ERC-7760 Minimal upgradeable proxy (Minimal Upgradeable Proxies)
Draft · Other · created 2024-08-19
Standardizes the bytecode of upgradeable proxy contracts into a minimal form. It covers the transparent, UUPS, and beacon patterns, and supports attaching immutable arguments and querying the implementation address onchain.
Why it is needed
In Ethereum, to make a contract upgradable later, it is common to place a relay contract called a proxy in front and keep the actual logic in an implementation contract behind it. However, if the proxy's bytecode differs from project to project, it becomes hard for block explorers to automatically recognize and verify which proxy a given contract is. There is also no good way for other contracts to reliably verify the proxy's implementation address onchain, and where fixed values set at deployment (immutable arguments) are stored varies by implementation, making them hard to query. If the bytecode is unnecessarily large, deployment costs and the execution cost of every call also increase. This standard aims to solve all of these problems at once by fixing the bytecode of upgradeable proxies into a minimal form.
In depth
The three patterns and the ERC-1967 slot
This standard defines minimal bytecode for ERC-1967 proxies in three patterns: transparent, UUPS, and beacon. All patterns store the implementation address in the ERC-1967 implementation slot 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc. For UUPS and beacon proxies, which have no upgrade logic of their own, the initialization code must store the implementation address in this slot. Emitting ERC-1967 events during initialization is optional, and indexers should not assume that initialization code emits events. The PUSH0 opcode was deliberately avoided for broad EVM compatibility, and minimizing execution gas was prioritized over minimizing bytecode size.
How transparent proxy upgrades work
A transparent proxy bakes the factory address with upgrade authority directly into the runtime bytecode. This is to save one SLOAD that would otherwise read from storage on every call. When the factory performs an upgrade, it calls the proxy with the new implementation address padded to 32 bytes, the ERC-1967 implementation slot, and optional calldata to be delegatecalled to the implementation after configuration, appended together. The upgrade logic can write an arbitrary 32-byte value to an arbitrary 32-byte slot, which is intended for flexibility and bytecode compactness, and does not sacrifice security since the implementation contract can modify any slot anyway. The upgrade logic does not emit ERC-1967 events, so indexers should not rely on events. Custom authentication logic, such as authority transfer, can be placed in the factory, preserving flexibility.
The I-variant and onchain implementation address verification
The I-variant is a variant whose bytecode includes logic that returns the implementation address. When called with 1-byte-length calldata, instead of forwarding the calldata to the implementation, it returns the implementation address left-padded to 32 bytes with zeros. 1 byte was chosen because a plain ETH transfer uses 0 bytes of calldata and a normal Solidity function call uses 4 or more bytes, avoiding collisions. To trust the returned value, the bytecode must be verified: fetch the bytecode preceding the immutable arguments with EXTCODECOPY, zero out the factory address embedded within it, and check whether the hash matches the expected value. If the hash differs, the returned implementation address should not be trusted.
Handling immutable arguments
Every proxy can optionally append data (immutable arguments) at the end of its runtime bytecode. Since it is stored at the same offset following the standard bytecode, its location can be known and queried onchain. However, these arguments are not appended to the calldata passed to the implementation, in order to avoid compatibility and safety issues with other ERC standards that append extra data to the end of calldata. If immutable arguments are needed, they are read directly from the bytecode using the EXTCODECOPY opcode. In the reference implementation, deployment is rejected if the total length exceeds 0xffff.
The 14-byte factory address sub-variant
Transparent proxies come in a variant that embeds the full 20-byte factory address and a variant that shortens it to 14 bytes. The 14-byte variant can be used when the factory is deployed to a vanity address whose first 6 bytes are zero, which shortens the proxy bytecode accordingly. 14 bytes was chosen as a balance between the cost of mining the address and the bytecode size. The reference implementation automatically picks one of the two variants by checking whether the upper bits of the factory address are zero.
Out-of-scope topics and the minimalism principle
The factory used to deploy proxies, the logic for reading and verifying the implementation address in the I-variant, and the beacon itself that a beacon proxy points to may all contain custom logic, and are therefore out of scope for this standard. However, it explicitly states that careful implementation is needed for security and correctness. Initialization code is also left unfixed, since for UUPS and beacon it is enough to initialize only the ERC-1967 slot when needed. The bytecode is hand-crafted EVM code that could be further optimized, but for variants already used in production, the benefit of automatic block explorer verification is considered to outweigh small gas savings, so keeping the existing layout is preferred.
Standard status
This proposal is currently in Draft status. Since its content may still change, the latest original text should be checked before treating the bytecode and rules as finalized.
Things to watch out for
- Factory access control: The factory of a transparent proxy must implement appropriate access control so that only authorized accounts can upgrade the proxy.
- 1-byte calldata collision: The I-variant reserves all calldata of length 1 as a request to query the implementation address. If the underlying implementation contract actually uses 1-byte calldata for a special purpose, compatibility issues can arise.