EIPs/EIPS/eip-3448.md

---
eip: 3448
title: Meta Proxy Factory
author: pinkiebell (@pinkiebell)
discussions-to: https://ethereum-magicians.org/t/erc-3448-metaproxy-factory/5834
status: Draft
type: Standards Track
category: ERC
created: 2021-03-29
---

## 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
```
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](https://github.com/pinkiebell/MetaProxy) 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](https://github.com/pinkiebell/MetaProxy) GitHub repo.

### Deployment bytecode
An annotated version of the deploy bytecode:
```
// PUSH1 11;
// CODESIZE;
// SUB;
// DUP1;
// PUSH1 11;
// RETURNDATASIZE;
// CODECOPY;
// RETURNDATASIZE;
// RETURN;
```

### 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)
```

## 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.

## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).