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

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

Original ERC · ← ERCs