ERC-7546 Upgradeable clone proxy (Upgradeable Clone for Scalable Contracts)
Draft · Other · created 2023-10-25
A design in which per-function implementation addresses are registered in an external Dictionary contract that multiple proxies share. This allows mass cloning of proxies while still enabling upgrades at the granularity of individual functions.
Why it is needed
The Ethereum Virtual Machine (EVM) has structural limits, such as a 24.576kB cap on the code size of a single contract, and vulnerabilities discovered after deployment require an upgrade mechanism to fix. However, existing approaches were each only half a solution. ERC-1167 allows cheaply stamping out clones of the same logic, but they cannot be upgraded. ERC-1822 allows upgrades, but each clone must be fixed individually. The Beacon in ERC-1967 can upgrade clones simultaneously, but since there is only one implementation contract, function-level swapping is not possible. ERC-2535 Diamond allows function-level swapping, but because it keeps the list of implementation addresses inside the proxy itself, cloning and simultaneous upgrades are difficult. There was no standard that supported both function-level upgrades and factory-style cloning at the same time, and this proposal fills that gap.
What to implement
event DictionaryUpgraded(address dictionary);: An event emitted when the dictionary contract address that the proxy points to changes.event ImplementationUpgraded(bytes4 functionSelector, address implementation);: An event emitted when the mapping between a registered function selector and its implementation address changes in the dictionary.function getImplementation(bytes4 functionSelector) external view returns(address implementation);: Takes a function selector and returns the address of the implementation contract that handles that function. The dictionary contract MUST implement this.function setImplementation(bytes4 functionSelector, address implementation) external;: Registers or updates the mapping between a function selector and an implementation contract address.function supportsInterfaces() public view returns (bytes4[] memory);: Returns the list of interface IDs registered in the dictionary. Implementing this function is recommended.
In depth
Separating roles into three contracts
The components of an EVM account (nonce, balance, code, storage) are split across three types of contracts. The Proxy contract holds the account's state (nonce, balance, storage), the Dictionary contract acts as a dispatcher that takes a function selector and routes it to the appropriate implementation contract, and the Function implementation contracts hold the actual execution logic. Because the dictionary is separated outside the proxy, it becomes easy to clone via a factory and enables simultaneous upgrades.
Proxy contract rules
The proxy SHOULD store the dictionary address in storage slot 0x267691be3525af8a813d30db0c9e2bad08f63baecf6dceb85e2cf3676cff56f4 (the value of keccak256('erc7546.proxy.dictionary') minus 1) following the ERC-1967 convention. It MUST emit a DictionaryUpgraded event when the dictionary address changes, and for every call coming in via CALL or STATICCALL it MUST obtain the implementation address from the dictionary's getImplementation and delegatecall it. The proxy itself SHOULD NOT define external functions, to avoid conflicting with selectors registered in the dictionary.
Dictionary contract rules
The dictionary MUST maintain a mapping from function selectors to implementation contract addresses, and MUST implement getImplementation(bytes4). Implementing setImplementation to change or add to the mapping, and emitting an ImplementationUpgraded event on change, are SHOULD recommendations. Implementing ERC-165's supportsInterface(bytes4), and supportsInterfaces() which returns the list of registered interface IDs, are RECOMMENDED.
Function implementation contracts and storage management
Implementation contracts SHOULD NOT use their own storage, and SHOULD write to the proxy's storage via delegatecall. Since multiple implementation contracts share a single proxy's storage layout, allocating slots sequentially from slot 0 as compilers do by default can cause collisions. Storage management to prevent collisions is MUST, but since no standard technique has yet been established, this ERC does not mandate a specific method and instead recommends choosing whatever is most appropriate at the time, citing layout patterns like ERC-7201 as an example. Implementation contracts MUST also have the same function selectors registered in the dictionary, and implementing ERC-165's supportsInterface for verification at registration time is recommended.
Difference from the ERC-2535 Diamond
Both standards provide function-level upgrades, but ERC-2535 keeps the mapping of implementation contracts (facets) inside the proxy itself, whereas this ERC keeps the mapping in an external dictionary contract. Moving the mapping outside makes cloning the proxy easy and allows clones to be upgraded simultaneously. This is a similar idea to ERC-1967's beacon proxy, except that whereas a beacon swaps the implementation at the granularity of a single contract, this standard swaps at the granularity of individual function selectors.
When to use this standard
The source text distinguishes six cases. If neither upgrades nor a factory are needed, use a plain deployment; if only a factory is needed, use ERC-1167; if only contract-level upgrades are needed, use ERC-1822; if both contract-level upgrades and a factory are needed, use ERC-1967's beacon; if only function-level upgrades are needed, use ERC-2535. The last case, where both function-level upgrades and a factory are needed, is where this Upgradeable Clone Standard (UCS) fits. A reference implementation in the form of a Foundry project (Proxy.sol, Dictionary.sol) and tests are also provided.
Still in draft stage
This proposal was created in October 2023 and is currently in Draft status. Its content may change going forward, so implementers should check the latest status of the source text.
Things to watch out for
- Trust in the dictionary administrator: Because the structure delegates the implementation decision for every call to the dictionary contract, it relies on the assumption that the dictionary administrator acts in good faith and does not carelessly introduce vulnerabilities. A proxy should not be connected to the dictionary of an untrustworthy administrator, and it is recommended to provide an option to switch to a different administrator's dictionary. The dictionary address can also be hardcoded as immutable or constant, but if the dictionary administrator and the proxy administrator differ, the ability to change the implementation could be permanently lost, so careful design is needed.
- Storage collision: Since multiple function implementation contracts share a single proxy's storage, collisions must be prevented by using whatever storage management technique is judged most appropriate at the time.
- Function selector mismatch: If the selector registered in the dictionary does not match the selector actually held by the implementation contract, execution fails. It is recommended to verify, when registering an implementation address in the dictionary, that the implementation actually includes that selector (interface).
- Calling the proxy via DELEGATECALL: The proxy is designed to respond to CALL and STATICCALL. If another contract performs a DELEGATECALL on this proxy, the result may not be as intended if the caller's storage layout differs from what is expected. This is not a direct threat to the proxy itself, but DELEGATECALL is not an appropriate way to interact with this proxy.