EIPs/EIPS/eip-1167.md

---
eip: 1167
title: Minimal Proxy Contract
author: Peter Murray (@yarrumretep), Nate Welch (@flygoing), Joe Messerman (@JAMesserman)
discussions-to: https://github.com/optionality/clone-factory/issues/10
status: Draft
type: Standards Track
category: ERC
created: 2018-06-22
---

<!--You can leave these HTML comments in your merged EIP and delete the visible duplicate text guides, they will not appear and may be helpful to refer to if you edit it again. This is the suggested template for new EIPs. Note that an EIP number will be assigned by an editor. When opening a pull request to submit your EIP, please use an abbreviated title in the filename, `eip-draft_title_abbrev.md`. The title should be 44 characters or less.-->

## Simple Summary
<!--"If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the EIP.-->
To simply and cheaply clone contract functionality in an immutable way, we propose to standardize on a minimal bytecode implementation which delegates all calls to a known, fixed address.  
## Abstract
<!--A short (~200 word) description of the technical issue being addressed.-->
By standardizing on a known minimal bytecode redirect implementation, this standard will allow 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
<!--The motivation is critical for EIPs that want to change the Ethereum protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the EIP solves. EIP submissions without sufficient motivation may be rejected outright.-->
This standard is desireable to allow for use-cases wherein it is desireable to clone exact contract functionality with a minimum of side effects (e.g. memory slot stomping) and with super-cheap deployment of duplicate proxies.

## Specification
<!--The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Ethereum platforms (go-ethereum, parity, cpp-ethereum, ethereumj, ethereumjs, and [others](https://github.com/ethereum/wiki/wiki/Clients)).-->
The exact bytecode of the standard clone contract is this: `6000368180378080368173bebebebebebebebebebebebebebebebebebebebe5af43d82803e15602c573d90f35b3d90fd` wherein the bytes at idices 10 - 29 (inclusive) are replaced with the 20 byte address of the master functionality contract.  The reference implementation of this is found at the [optionality/clone-factory](https://github.com/optionality/clone-factory) github repo. 

Detection of clone and redirection is implemented in the clone-factory repo with a contract deployed on both Kovan and Mainnet that detects the presence of a clone and returns the destination address if the interrogated contract is a clone (handles shortened addresses as well).

## Rationale
<!--The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.-->
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
<!--All EIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The EIP must explain how the author proposes to deal with these incompatibilities. EIP submissions without a sufficient backwards compatibility treatise may be rejected outright.-->
There are no backwards compatibility issues.

## Test Cases
<!--Test cases for an implementation are mandatory for EIPs that are affecting consensus changes. Other EIPs can choose to include links to test cases if applicable.-->
We have included some simple test cases in the clone-factory project that demonstrate the function of this contract including the error handling and error message propagation.

## Implementation
<!--The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.-->
The exact bytecode for deploying the clone instances is `600034603b57603080600f833981f36000368180378080368173bebebebebebebebebebebebebebebebebebebebe5af43d82803e15602c573d90f35b3d90fd` with the 20 'be' bytes at offset 26 replaced with the address of the implementation contract.  This deployment bytecode results in a deployed contract of `6000368180378080368173bebebebebebebebebebebebebebebebebebebebe5af43d82803e15602c573d90f35b3d90fd`.

The disassembly of the full deployment code (from r2, then edited to account for deployment offset changes)
```
            0x00000000      6000           push1 0x0
            0x00000002      34             callvalue
            0x00000003      603b           push1 0x3b
        ,=< 0x00000005      57             jumpi
        |   0x00000006      6030           push1 0x30
        |   0x00000008      80             dup1
        |   0x00000009      600f           push1 0xf
        |   0x0000000b      83             dup4
        |   0x0000000c      39             codecopy
        |   0x0000000d      81             dup2
        |   0x0000000e      f3             return
        |   0x0000000f      6000           push1 0x0
        |   0x00000011      36             calldatasize
        |   0x00000012      81             dup2
        |   0x00000013      80             dup1
        |   0x00000014      37             calldatacopy
        |   0x00000015      80             dup1
        |   0x00000016      80             dup1
        |   0x00000017      36             calldatasize
        |   0x00000018      81             dup2
        |   0x00000019      73bebebebebe.  push20 0xbebebebe
        |   0x0000002e      5a             gas
        |   0x0000002f      f4             delegatecall
        |   0x00000030      3d             returndatasize
        |   0x00000031      82             dup3
        |   0x00000032      80             dup1
        |   0x00000033      3e             returndatacopy
        |   0x00000034      15             iszero
        |   0x00000035      602c           push1 0x2c    // note that this offset is post deployment the following jumpi "arrow" on the left was hand edited
       ,==< 0x00000037      57             jumpi
       :|   0x00000038      3d             returndatasize
       :|   0x00000039      90             swap1
       :|   0x0000003a      f3             return
       ``-> 0x0000003b      5b             jumpdest
            0x0000003c      3d             returndatasize
            0x0000003d      90             swap1
            0x0000003e      fd             revert
```

Disassembly of only the deployed contract bytecode is (straight from r2): 
```
|           0x00000000      6000           push1 0x0
|           0x00000002      36             calldatasize
|           0x00000003      81             dup2
|           0x00000004      80             dup1
|           0x00000005      37             calldatacopy
|           0x00000006      80             dup1
|           0x00000007      80             dup1
|           0x00000008      36             calldatasize
|           0x00000009      81             dup2
|           0x0000000a      73bebebebebe.  push20 0xbebebebe
|           0x0000001f      5a             gas
|           0x00000020      f4             delegatecall
|           0x00000021      3d             returndatasize
|           0x00000022      82             dup3
|           0x00000023      80             dup1
|           0x00000024      3e             returndatacopy
|           0x00000025      15             iszero
|           0x00000026      602c           push1 0x2c
|       ,=< 0x00000028      57             jumpi
|       |   0x00000029      3d             returndatasize
|       |   0x0000002a      90             swap1
|       |   0x0000002b      f3             return
|       `-> 0x0000002c      5b             jumpdest
|           0x0000002d      3d             returndatasize
|           0x0000002e      90             swap1
\           0x0000002f      fd             revert
```

The typical deployment pattern would be to deploy a Factory contract that can easily create clones.  Here is the reference implementation of the clone-factory pattern:
```solidity
contract CloneFactory {

  event CloneCreated(address indexed target, address clone);

  function createClone(address target) internal returns (address result) {
    bytes memory clone = hex"600034603b57603080600f833981f36000368180378080368173bebebebebebebebebebebebebebebebebebebebe5af43d82803e15602c573d90f35b3d90fd";
    bytes20 targetBytes = bytes20(target);
    for (uint i = 0; i < 20; i++) {
      clone[26 + i] = targetBytes[i];
    }
    assembly {
      let len := mload(clone)
      let data := add(clone, 0x20)
      result := create(0, data, len)
    }
  }
}
```

To utilize the above implementation, you would extend the contract like this:
```solidity
import "./Thing.sol";
import "../contracts/CloneFactory.sol";


contract ThingFactory is CloneFactory {

  address public libraryAddress;

  event ThingCreated(address newThingAddress, address libraryAddress);

  constructor (address _libraryAddress) public {
    libraryAddress = _libraryAddress;
  }

  function createThing(string _name, uint _value) public {
    address clone = createClone(libraryAddress);
    Thing(clone).init(_name, _value);
    emit ThingCreated(clone, libraryAddress);
  }
}

```

IMPORANT NOTE: When implementing, it is important to ensure that the master implementation contract cannot be 'initialized' and that it cannot in any way be selfdestructed.  

Clones can be detected using the following contract
```solidity

contract ContractProbe {

    function probe(address _addr) public view returns (bool isContract, address forwardedTo) {
        bytes memory clone = hex"6000368180378080368173bebebebebebebebebebebebebebebebebebebebe5af43d82803e15602c573d90f35b3d90fd";
        uint size;
        bytes memory code;

        assembly {  //solhint-disable-line
            size := extcodesize(_addr)
        }

        isContract = size > 0;
        forwardedTo = _addr;

        if (size <= 48 && size >= 44) {
            bool matches = true;
            uint i;

            assembly { //solhint-disable-line
                code := mload(0x40)
                mstore(0x40, add(code, and(add(add(size, 0x20), 0x1f), not(0x1f))))
                mstore(code, size)
                extcodecopy(_addr, add(code, 0x20), 0, size)
            }
            for (i = 0; matches && i < 10; i++) { 
                matches = code[i] == clone[i];
            }
            for (i = 0; matches && i < 17; i++) {
                if (i == 8) {
                    matches = code[code.length - i - 1] == byte(uint(clone[48 - i - 1]) - (48 - size));
                } else {
                    matches = code[code.length - i - 1] == clone[48 - i - 1];
                }
            }
            if (code[10] != byte(0x73 - (48 - size))) {
                matches = false;
            }
            uint forwardedToBuffer;
            if (matches) {
                assembly { //solhint-disable-line
                    forwardedToBuffer := mload(add(code, 31))
                }
                forwardedToBuffer &= (0x1 << 20 * 8) - 1;
                forwardedTo = address(forwardedToBuffer >> ((48 - size) * 8));
            }
        }
    }
}
```
The ContractProbe contract is deployed on Kovan at `0x8b98e65e0e8bce0f71a2a22f3d2666591e4cc857` and on Mainnet at `0x0c953133aa046965b83a3de1215ed4285414537c`
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).