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

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

Original ERC · ← ERCs