HomeEIPsNewsletter
EIPsERC-1167
ERC-1167

Minimal Proxy Contract

FinalStandards Track: ERC
Created: 2018-06-22
Requires: EIP-211
Peter Murray (@yarrumretep), Nate Welch (@flygoing), Joe Messerman (@JAMesserman)
DiscussionsOriginal linkEdit
1 min read

The ERC-1167: Minimal Proxy Contract is a standard for cloning contract functionality in a simple and cost-effective way. It specifies a minimal bytecode implementation that delegates all calls to a fixed address, allowing users and third-party tools to easily discover and depend on the behavior of the code at the destination contract. This implementation forwards all calls and gas to the implementation contract and relays the return value back to the caller. The standard clone contract bytecode is provided, with the bytes at indices 10-29 replaced with the 20 byte address of the master functionality contract. The goals of this effort have been to support inexpensive deployment and clone initialization in creation transactions, as well as to maintain a private reputation of contracts and keep track of which tokens and gas prices are used for deploying transactions. A reference implementation of the standard clone contract can be found on the optionality/clone-factory GitHub repository.

Video
Anyone may contribute to propose contents.
Go propose
Original

Simple Summary

To simply and cheaply clone contract functionality in an immutable way, this standard specifies a minimal bytecode implementation that delegates all calls to a known, fixed address.

Abstract

By standardizing on a known minimal bytecode redirect implementation, this standard allows users and third party tools (e.g. Etherscan) to (a) simply discover that a contract will always redirect in a known manner and (b) depend on the behavior of the code at the destination contract as the behavior of the redirecting contract. Specifically, tooling can interrogate the bytecode at a redirecting address to determine the location of the code that will run - and can depend on representations about that code (verified source, third-party audits, etc). This implementation forwards all calls and 100% of the gas to the implementation contract and then relays the return value back to the caller. In the case where the implementation reverts, the revert is passed back along with the payload data (for revert with message).

Motivation

This standard supports use-cases wherein it is desirable to clone exact contract functionality with a minimum of side effects (e.g. memory slot stomping) and with low gas cost deployment of duplicate proxies.

Specification

The exact bytecode of the standard clone contract is this: 363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf3 wherein the bytes at indices 10 - 29 (inclusive) are replaced with the 20 byte address of the master functionality contract.

A reference implementation of this can be found at the optionality/clone-factory github repo.

Rationale

The goals of this effort have been the following:

  • inexpensive deployment (low gas to deploy clones)
  • support clone initialization in creation transaction (through factory contract model)
  • simple clone bytecode to encourage directly bytecode interrogation (see CloneProbe.sol in the clone-factory project)
  • dependable, locked-down behavior - this is not designed to handle upgradability, nor should it as the representation we are seeking is stronger.
  • small operational overhead - adds a single call cost to each call
  • handles error return bubbling for revert messages

Backwards Compatibility

There are no backwards compatibility issues. There may be some systems that are using earlier versions of the proxy contract bytecode. They will not be compliant with this standard.

Test Cases

Test cases include:

  • invocation with no arguments
  • invocation with arguments
  • invocation with fixed length return values
  • invocation with variable length return values
  • invocation with revert (confirming reverted payload is transferred)

Tests for these cases are included in the reference implementation project.

Implementation

Deployment bytecode is not included in this specification. One approach is defined in the proxy-contract reference implementation.

Standard Proxy

The disassembly of the standard deployed proxy contract code (from r2 and edited to include stack visualization)

|           0x00000000      36             calldatasize          cds
|           0x00000001      3d             returndatasize        0 cds
|           0x00000002      3d             returndatasize        0 0 cds
|           0x00000003      37             calldatacopy          
|           0x00000004      3d             returndatasize        0
|           0x00000005      3d             returndatasize        0 0 
|           0x00000006      3d             returndatasize        0 0 0
|           0x00000007      36             calldatasize          cds 0 0 0
|           0x00000008      3d             returndatasize        0 cds 0 0 0
|           0x00000009      73bebebebebe.  push20 0xbebebebe     0xbebe 0 cds 0 0 0
|           0x0000001e      5a             gas                   gas 0xbebe 0 cds 0 0 0
|           0x0000001f      f4             delegatecall          suc 0
|           0x00000020      3d             returndatasize        rds suc 0
|           0x00000021      82             dup3                  0 rds suc 0
|           0x00000022      80             dup1                  0 0 rds suc 0
|           0x00000023      3e             returndatacopy        suc 0
|           0x00000024      90             swap1                 0 suc
|           0x00000025      3d             returndatasize        rds 0 suc
|           0x00000026      91             swap2                 suc 0 rds
|           0x00000027      602b           push1 0x2b            0x2b suc 0 rds
|       ,=< 0x00000029      57             jumpi                 0 rds
|       |   0x0000002a      fd             revert
|       `-> 0x0000002b      5b             jumpdest              0 rds
\           0x0000002c      f3             return

NOTE: as an effort to reduce gas costs as much as possible, the above bytecode depends on EIP-211 specification that returndatasize returns zero prior to any calls within the call-frame. returndatasize uses 1 less gas than dup*.

Vanity Address Optimization

Proxy deployment can be further optimized by installing the master contract at a vanity contract deployment address with leading zero-bytes. By generating a master contract vanity address that includes Z leading 0 bytes in its address, you can shorten the proxy bytecode by replacing the push20 opcode with pushN (where N is 20 - Z) followed by the N non-zero address bytes. The revert jump address is decremented by Z in this case. Here is an example where Z = 4:

|           0x00000000      36             calldatasize          cds
|           0x00000001      3d             returndatasize        0 cds
|           0x00000002      3d             returndatasize        0 0 cds
|           0x00000003      37             calldatacopy          
|           0x00000004      3d             returndatasize        0
|           0x00000005      3d             returndatasize        0 0 
|           0x00000006      3d             returndatasize        0 0 0
|           0x00000007      36             calldatasize          cds 0 0 0
|           0x00000008      3d             returndatasize        0 cds 0 0 0
|           0x00000009      6fbebebebebe.  push16 0xbebebebe     0xbebe 0 cds 0 0 0
|           0x0000001a      5a             gas                   gas 0xbebe 0 cds 0 0 0
|           0x0000001b      f4             delegatecall          suc 0
|           0x0000001c      3d             returndatasize        rds suc 0
|           0x0000001d      82             dup3                  0 rds suc 0
|           0x0000001e      80             dup1                  0 0 rds suc 0
|           0x0000001f      3e             returndatacopy        suc 0
|           0x00000020      90             swap1                 0 suc
|           0x00000021      3d             returndatasize        rds 0 suc
|           0x00000022      91             swap2                 suc 0 rds
|           0x00000023      6027           push1 0x27            0x27 suc 0 rds
|       ,=< 0x00000025      57             jumpi                 0 rds
|       |   0x00000026      fd             revert
|       `-> 0x00000027      5b             jumpdest              0 rds
\           0x00000028      f3             return

This saves 4 bytes of proxy contract size (savings on each deployment) and has zero impact on runtime gas costs.

Copyright and related rights waived via CC0.

Related EIPs
ERC-6551
ERC-6551
ERC-6551: Non-fungible Token Bound Accounts
Learn more
Further reading
Adopted by projects
Anyone may contribute to propose contents.
Go propose

Not miss a beat of EIPs' update?

Subscribe EIPs Fun to receive the latest updates of EIPs Good for Buidlers to follow up.

View all
Serve Ethereum Builders, Scale the Community.
Resources
GitHub
Supported by