status-im/EIPs
2
0
Fork 0
mirror of https://github.com/status-im/EIPs.git synced 2025-03-04 00:20:54 +00:00
Code Issues Projects Releases Wiki Activity

Automatically merged updates to draft EIP(s) 1167

Browse Source 
Hi, I'm a bot! This change was automatically merged because:

 - It only modifies existing Draft or Last Call EIP(s)
 - The PR was approved or written by at least one author of each modified EIP
 - The build is passing
This commit is contained in:
yarrumretep 2018-08-13 18:55:59 -04:00 committed by EIP Automerge Bot
parent 46d1ba6452
commit 3354ea2b2c
1 changed files with 72 additions and 174 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

246
EIPS/eip-1167.md
View File

@ -13,21 +13,21 @@ created: 2018-06-22
## 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.
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
<!--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).
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
<!--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.
This standard supports use-cases wherein it is desireable 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 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.
The exact bytecode of the standard clone contract is this: `363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf3` wherein the bytes at idices 10 - 29 (inclusive) are replaced with the 20 byte address of the master functionality contract.
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).
A reference implementation of this can be found at the [optionality/clone-factory](https://github.com/optionality/clone-factory) github repo.
## 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.-->
@ -41,187 +41,85 @@ The goals of this effort have been the following:
## 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.
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 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.
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
<!--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`.
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)
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);
}
}
| 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
```
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.
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*`.
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));
}
}
}
}
### 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:
```
The ContractProbe contract is deployed on Kovan at `0x8b98e65e0e8bce0f71a2a22f3d2666591e4cc857`, Ropsten at `0x75f09888af7c9bdfe15317c411dfb03636179a6d` and on Mainnet at `0x0c953133aa046965b83a3de1215ed4285414537c`
| 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
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).