EIP3448 - Meta Proxy Factory

# Simple Summary

This standard specifies a minimal bytecode implementation to create children of a parent contract with a set of immutable metadata for each child. Also known as a Proxy Contract but with the additional twist to store metadata or immutable arguments for the cloned contract at the end of the proxy bytecode.

# Abstract

By standardizing on a known minimal bytecode proxy implementation with support for immutable metadata, 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 and (c) verify/view the attached metadata.

Tooling can interrogate the bytecode at a redirecting address to determine the location of the code that will run along with the associated metadata - and can depend on representations about that code (verified source, third-party audits, etc). This implementation forwards all calls via DELEGATECALL and any (calldata) input plus the metadata at the end of the bytecode 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.

# Motivation

This standard supports use-cases wherein it is desirable to clone exact contract functionality with different parameters at another address.

# Specification

The exact bytecode of the MetaProxy contract is:

                                              20 bytes target contract address
                                          ----------------------------------------
363d3d373d3d3d3d60368038038091363936013d7300000000000000000000000000000000000000005af43d3d93803e603457fd5bf3

1
2
3

wherein the bytes at indices 21 - 41 (inclusive) are replaced with the 20 byte address of the master functionality contract. Additionally, everything after the MetaProxy bytecode can be arbitrary metadata and the last 32 bytes (one word) of the bytecode must indicate the length of the metadata in bytes.

<54 bytes metaproxy> <arbitrary data> <length in bytes of arbitrary data (uint256)>

A reference implementation of this can be found at the pinkiebell/MetaProxy (opens new window) GitHub repo.

# Rationale

The goals of this effort have been the following:

a cheap way of storing immutable metadata for each child instead of using storage slots
inexpensive deployment of clones
handles error return bubbling for revert messages

# Backwards Compatibility

There are no backwards compatibility issues.

# Test Cases

Test cases include:

invocation with no arguments
invocation with arguments
invocation with return values
invocation with revert (confirming reverted payload is transferred)

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

# Implementation

A reference implementation can be found at the pinkiebell/MetaProxy (opens new window) GitHub repo.

# Deployment bytecode

An annotated version of the deploy bytecode:

// PUSH1 11;
// CODESIZE;
// SUB;
// DUP1;
// PUSH1 11;
// RETURNDATASIZE;
// CODECOPY;
// RETURNDATASIZE;
// RETURN;

1
2
3
4
5
6
7
8
9

# MetaProxy

An annotated version of the MetaProxy bytecode:

// copy args
// CALLDATASIZE;   calldatasize
// RETURNDATASIZE; 0, calldatasize
// RETURNDATASIZE; 0, 0, calldatasize
// CALLDATACOPY;

// RETURNDATASIZE; 0
// RETURNDATASIZE; 0, 0
// RETURNDATASIZE; 0, 0, 0
// RETURNDATASIZE; 0, 0, 0, 0

// PUSH1 54;       54, 0, 0, 0, 0
// DUP1;           54, 54, 0, 0, 0, 0
// CODESIZE;       codesize, 54, 54, 0, 0, 0, 0
// SUB;            codesize-54, 54, 0, 0, 0, 0
// DUP1;           codesize-54, codesize-54, 54, 0, 0, 0, 0
// SWAP2;          54, codesize-54, codesize-54, 0, 0, 0, 0
// CALLDATASIZE;   calldatasize, 54, codesize-54, codesize-54, 0, 0, 0, 0
// CODECOPY;       codesize-54, 0, 0, 0, 0

// CALLDATASIZE;   calldatasize, codesize-54, 0, 0, 0, 0
// ADD;            calldatasize+codesize-54, 0, 0, 0, 0
// RETURNDATASIZE; 0, calldatasize+codesize-54, 0, 0, 0, 0
// PUSH20 0;       addr, 0, calldatasize+codesize-54, 0, 0, 0, 0 - zero is replaced with shl(96, address())
// GAS;            gas, addr, 0, calldatasize+codesize-54, 0, 0, 0, 0
// DELEGATECALL;   (gas, addr, 0, calldatasize() + metadata, 0, 0) delegatecall to the target contract;
//
// RETURNDATASIZE; returndatasize, retcode, 0, 0
// RETURNDATASIZE; returndatasize, returndatasize, retcode, 0, 0
// SWAP4;          0, returndatasize, retcode, 0, returndatasize
// DUP1;           0, 0, returndatasize, retcode, 0, returndatasize
// RETURNDATACOPY; (0, 0, returndatasize) - Copy everything into memory that the call returned

// stack = retcode, 0, returndatasize # this is for either revert(0, returndatasize()) or return (0, returndatasize())

// PUSH1 _SUCCESS_; push jumpdest of _SUCCESS_
// JUMPI;          jump if delegatecall returned `1`
// REVERT;         (0, returndatasize()) if delegatecall returned `0`
// JUMPDEST _SUCCESS_;
// RETURN;         (0, returndatasize()) if delegatecall returned non-zero (1)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

# Security Considerations

This standard only covers the bytecode implementation and does not include any serious side effects of itself. The reference implementation includes some examples how to make use of it, but it is highly recommended to research side effects depending on how the functionaliy is used and implemented in any project.