ERC-7613 Puppet Proxy Contract
Draft · Other · created 2024-02-04
A 66-byte minimal proxy that delegates execution only to the address embedded in the calldata, and only when called by its deployer. It makes it cheap to create per-user deposit addresses and lets funds be deposited into a protocol via a plain transfer, with no approval process needed.
Why it is needed
To deposit tokens into a smart contract protocol, a separate transaction called approve is usually required first, granting the protocol permission to take the tokens. This requires one extra transaction, forces the user to sign call data whose meaning is hard to understand, and makes it effectively impossible to participate using a wallet that only supports plain transfers. In addition, if a protocol wants a separate address to hold each user's assets, it must deploy a contract for every address; typical proxy approaches require either an initialization step that first deploys an implementation contract, or an additional mechanism like a beacon to change logic later, which adds complexity and cost. If the bytecode varies with the compiler version, predicting the deployment address in advance with CREATE2 also becomes difficult.
What to implement
function deploy() internal returns (address instance): A function in the reference implementation library that deploys a new puppet via CREATE and returns its address.function deployDeterministic(bytes32 salt) internal returns (address instance): Deploys a puppet via CREATE2 using a salt. The address can be predicted in advance.function predictDeterministicAddress(bytes32 salt) internal view returns (address predicted): Computes the address of the puppet that this contract will deploy with the given salt.function predictDeterministicAddress(bytes32 salt, address deployer) internal pure returns (address predicted): Computes the address of the puppet that the specified deployer will deploy with the given salt.function delegationCalldata(address delegateTo, bytes memory data) internal pure returns (bytes memory payload): Builds calldata for calling the puppet by encoding the delegate target address as 32 bytes and prepending it to the data.
In depth
Calling rule: deployer only, address first
For the deployer to make the puppet delegate, it must prepend the ABI-encoded delegate target address (32 bytes, zero-left-padded) to the front of the calldata. Everything after that is passed through unchanged as the calldata of the delegatecall. If the caller is not the deployer, the calldata is shorter than 32 bytes, or the first word is not in zero-padded address form, the puppet does nothing. Thanks to this rule, if the deployer sends only the native token with no data, the calldata is empty and the transfer is simply accepted without any delegation.
Fixed 66-byte bytecode and deployment cost
The deployed bytecode is 66 bytes and the init code is 62 bytes. Deployment costs 45K gas, only 4K more than a clone proxy, and like a clone it can be deployed using only Solidity's scratch space memory. Because the standard defines the puppet as a fixed init code byte blob, the same puppet is produced regardless of language or framework, and since no compilation step is involved, the CREATE2 address can be predicted reliably regardless of compiler version. It also avoids the PUSH0 opcode, so it works on chains that do not yet support it.
Loading funds without an approval transaction
Any contract or wallet can send funds to a user's assigned puppet address without an approval and without calling the protocol contract. Funds can also be sent in multiple transactions from multiple sources. When pulling funds from other protocols, as long as a plain transfer to an arbitrary address is possible, there is no need to add integration code to third-party contracts. Once funds have accumulated in the puppet, someone must call the protocol to report the deposit, and if this call is permissionless, gasless transactions or third-party gas sponsorship can make the UX more convenient. The source states that most protocols that currently receive funds via approved transfers could benefit from puppets.
Changing behavior without an upgrade
The puppet's logic never needs to be upgraded. To change its behavior, the deployer simply changes the address or calldata it passes as the delegation target. All puppets deployed by a single contract change behavior together whenever that deployer contract is upgraded, with no need for a beacon. If the deployer delegates the puppet to an address holding its own logic, this technique can encapsulate the puppet's logic inside the deployer's code. Because puppets are deployed to predictable addresses without any fixed logic, they can in some cases serve as an alternative to CREATE3, and if a puppet deployed via CREATE2 is made to deploy arbitrary code via a plain CREATE, it can replace a CREATE3 factory entirely.
Design rationale: comparison with Solidity implementations, clones, and beacons
The same behavior could be implemented in Solidity or inline Yul, but the bytecode would be much larger, making deployment more expensive, and the result would vary with compiler version and settings, which complicates predictable CREATE2 deployment. Deploying copies of a puppet implementation via clone proxies has a slightly lower per-deployment cost, but each call incurs an extra delegatecall and its gas cost, requires an initialization step to deploy the implementation first, and limits address predictability because the implementation address is embedded in the clone's init code. Beacon proxies require large code to safely call the Solidity API, so they end up being used together with clones anyway, and changing the delegation address requires updating the beacon's state, which is less flexible than passing the address through calldata.
Limitation: cannot expose an API to third parties
A puppet cannot expose an API to any caller other than its deployer. For a third party to run logic on a puppet, it must not call the puppet directly but must go through a function exposed by the deployer. When that function is called, the deployer in turn calls the puppet to execute the desired logic. As a result, mechanisms that expect a contract to expose a specific API, such as the safeTransfer family in ERC-721, do not work with puppets.
A proposal still in Draft stage
This proposal has been in Draft status since February 2024. Its content may change or progress may stall, so it is best to check its latest status before implementing it.
Things to watch out for
- Bytecode designed to resemble a clone proxy: To simplify auditing, the bytecode was made to resemble a clone proxy's bytecode wherever it made sense.
- Protective effect of ABI-encoding the delegate address: Receiving the delegate address as ABI-encoded data prevents a scenario where a third party tricks the deployer into calling the puppet in a way that delegates to an arbitrary address. This attack is only possible if the deployer calls the puppet with a function whose selector is 0x00000000, and no reasonably named function currently produces that selector.