We introduce an extensible and versioned container format for the EVM with a once-off validation at deploy time. The version described here brings the tangible benefit of code and data separation, and allows for easy introduction of a variety of changes in the future. This change relies on the reserved byte introduced by EIP-3541.
To summarise, EOF bytecode has the following layout:
On-chain deployed EVM bytecode contains no pre-defined structure today. Code is typically validated in clients to the extent of JUMPDEST analysis at runtime, every single time prior to execution. This poses not only an overhead, but also a challenge for introducing new or deprecating existing features.
Validating code during the contract creation process allows code versioning without an additional version field in the account. Versioning is a useful tool for introducing or deprecating features, especially for larger changes (such as significant changes to control flow, or features like account abstraction).
The format described in this EIP introduces a simple and extensible container with a minimal set of changes required to both clients and languages, and introduces validation.
The first tangible feature it provides is separation of code and data. This separation is especially beneficial for on-chain code validators (like those utilised by layer-2 scaling tools, such as Optimism), because they can distinguish code and data (this includes deployment code and constructor arguments too). Currently, they a) require changes prior to contract deployment; b) implement a fragile method; or c) implement an expensive and restrictive jump analysis. Code and data separation can result in ease of use and significant gas savings for such use cases. Additionally, various (static) analysis tools can also benefit, though off-chain tools can already deal with existing code, so the impact is smaller.
A non-exhaustive list of proposed changes which could benefit from this format:
JUMPDEST-table (to avoid analysis at execution time) and/or removing JUMPDESTs entirely.The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.
In order to guarantee that every EOF-formatted contract in the state is valid, we need to prevent already deployed (and not validated) contracts from being recognized as such format. This is achieved by choosing a byte sequence for the magic that doesn't exist in any of the already deployed contracts.
If code starts with the MAGIC, it is considered to be EOF formatted, otherwise it is considered to be legacy code. For clarity, the MAGIC together with a version number n is denoted as the EOFn prefix, e.g. EOF1 prefix.
EOF-formatted contracts are created using new instructions which are introduced in a separate EIP.
The opcode 0xEF is currently an undefined instruction, therefore: It pops no stack items and pushes no stack items, and it causes an exceptional abort when executed. This means legacy initcode or already deployed legacy code starting with this instruction will continue to abort execution.
Unless otherwise specified, all integers are encoded in big-endian byte order.
We introduce code validation for new contract creation. To achieve this, we define a format called EVM Object Format (EOF), containing a version indicator, and a ruleset of validity tied to a given version.
Legacy code is not affected by EOF code validation.
Code validation is performed during contract creation, and is elaborated on in separate EIPs. The EOF format itself and its formal validation are described in the following sections.
EOF container is a binary format with the capability of providing the EOF version number and a list of EOF sections.
The container starts with the EOF prefix:
| description | length | value | |
|---|---|---|---|
| magic | 2-bytes | 0xEF00 | |
| version | 1-byte | 0x01–0xFF | EOF version number |
The EOF prefix is followed by at least one section header. Each section header contains two fields, section_kind and either section_size or section_size_list, depending on the kind. section_size_list is a list of size values when multiple sections of this kind are allowed, encoded as a count of items followed by the items.
| description | length | value | |
|---|---|---|---|
| section_kind | 1-byte | 0x01–0xFF | uint8 |
| section_size | 2-bytes | 0x0000–0xFFFF | uint16 |
| section_size_list | dynamic | n/a | uint16, uint16+ |
The list of section headers is terminated with the section headers terminator byte 0x00. The body content follows immediately after.
version MUST NOT be 0.section_kind MUST NOT be 0. The value 0 is reserved for section headers terminator byte.EOF version 1 is made up of several EIPs, including this one. Some values in this specification are only discussed briefly. To understand the full scope of EOF, it is necessary to review each EIP in-depth.
The EOF version 1 container consists of a header and body.
note: , is a concatenation operator, + should be interpreted as "one or more" of the preceding item, * should be interpreted as "zero or more" of the preceding item, and [item] should be interpreted as an optional item.
| name | length | value | description |
|---|---|---|---|
| magic | 2 bytes | 0xEF00 | |
| version | 1 byte | 0x01 | EOF version |
| kind_type | 1 byte | 0x01 | kind marker for type section |
| type_size | 2 bytes | 0x0004-0x1000 | 16-bit unsigned big-endian integer denoting the length of the type section content, 4 bytes per code section |
| kind_code | 1 byte | 0x02 | kind marker for code size section |
| num_code_sections | 2 bytes | 0x0001-0x0400 | 16-bit unsigned big-endian integer denoting the number of the code sections |
| code_size | 2 bytes | 0x0001-0xFFFF | 16-bit unsigned big-endian integer denoting the length of the code section content |
| kind_container | 1 byte | 0x03 | kind marker for container size section |
| num_container_sections | 2 bytes | 0x0001-0x0100 | 16-bit unsigned big-endian integer denoting the number of the container sections |
| container_size | 4 bytes | 0x00000001-0xFFFFFFFF | 32-bit unsigned big-endian integer denoting the length of the container section content |
| kind_data | 1 byte | 0xFF | kind marker for data size section |
| data_size | 2 bytes | 0x0000-0xFFFF | 16-bit unsigned big-endian integer denoting the length of the data section content (*) |
| terminator | 1 byte | 0x00 | marks the end of the header |
(*) For not yet deployed containers this can be greater than the actual content length.
| name | length | value | description |
|---|---|---|---|
| types_section | variable | n/a | stores code section metadata |
| inputs | 1 byte | 0x00-0x7F | number of stack elements the code section consumes |
| outputs | 1 byte | 0x00-0x7F | number of stack elements the code section returns |
| max_stack_increase | 2 bytes | 0x0000-0x03FF | maximum increase of the operand stack height by the code section |
| code_section | variable | n/a | arbitrary bytecode |
| container_section | variable | n/a | arbitrary EOF-formatted container |
| data_section | variable | n/a | arbitrary sequence of bytes |
NOTE: A special value of outputs being 0x80 is designated to denote non-returning functions as defined in a separate EIP.
The following validity constraints are placed on the container format:
types_size is divisible by 4types_size / 4data_size for a not yet deployed containerMAX_INITCODE_SIZE (as defined in EIP-3860)For an EOF contract:
CODESIZE, CODECOPY, EXTCODESIZE, EXTCODECOPY, EXTCODEHASH, GAS are rejected by validation in EOF contracts, with no replacementsCALL, DELEGATECALL, STATICCALL are rejected by validation in EOF contracts, replacement instructions to be introduced in a separate EIP.DELEGATECALL (or any replacement instruction for EOF) from an EOF contract to a non-EOF contract (legacy contract, EOA, empty account) is disallowed, and it should fail in the same mode as if the call depth check failed. We allow legacy to EOF path for existing proxy contracts to be able to use EOF upgrades.For a legacy contract:
EXTCODECOPY is an EOF contract, then it will copy up to 2 bytes from EF00, as if that would be the code.EXTCODEHASH is an EOF contract, then it will return 0x9dbf3648db8210552e9c4f75c6a1c3057c0ca432043bd648be15fe7be05646f5 (the hash of EF00, as if that would be the code).EXTCODESIZE is an EOF contract, then it will return 2.NOTE Like for legacy targets, the aforementioned behavior of EXTCODECOPY, EXTCODEHASH and EXTCODESIZE does not apply to EOF contract targets mid-creation, i.e. those report same as accounts without code.
EVM and/or account versioning has been discussed numerous times over the past years. This proposal aims to learn from them. See "Ethereum account versioning" on the Fellowship of Ethereum Magicians Forum for a good starting point.
This specification introduces creation time validation, which means:
JUMPDEST map in the EOF container and eliminate the need of implicit JUMPDEST analysis required before execution.JUMPDEST instructions.The alternative is to have execution time validation for EOF. This is performed every single time a contract is executed, however clients may be able to cache validation results. This alternative approach has the following properties:
0xEF byte or the EOF prefix can be deployed. This is a dubious benefit, however.The first byte 0xEF was chosen because it is reserved for this purpose by EIP-3541.
The second byte 0x00 was chosen to avoid clashes with three contracts which were deployed on Mainnet:
0xca7bf67ab492b49806e24b6e2e4ec105183caa01: EFF09f918bf09f9fa90x897da0f23ccc5e939ec7a53032c5e80fd1a947ec: EF0x6e51d4d9be52b623a3d3a2fa8d3c5e3e01175cd0: EFNo contracts starting with 0xEF bytes exist on public testnets: Goerli, Ropsten, Rinkeby, Kovan and Sepolia at their London fork block.
NOTE: This EIP MUST NOT be enabled on chains which contain bytecodes starting with MAGIC and not being valid EOF.
The version number 0 will never be used in EOF, so we can call legacy code EOF0. Also, implementations may use APIs where 0 version number denotes legacy code.
We have considered different questions for the sections:
section_header, section_data, section_header, section_data, ...) are used in some other formats (such as WebAssembly). They are handy for formats which are subject to editing (adding/removing sections). That is not a useful feature for EVM. One minor benefit applicable to our case is that they do not require a specific "header terminator". On the other hand they seem to play worse with code chunking / merkleization, as it is better to have all section headers in a single chunk.number_of_sections or total_size_of_headers. Both raise the question of how large of a value these fields should be able to hold. A terminator byte seems to avoid the problem of choosing a size which is too small without any perceptible downside, so it is the path taken.See section Lack of EXTDATACOPY in EIP-7480.
DELEGATECALL EOF1 contractsCurrently contracts can selfdestruct in three different ways (directly through SELFDESTRUCT, indirectly through CALLCODE and indirectly through DELEGATECALL). EIP-3670 disables the first two possibilities, however the third possibility remains. Allowing EOF1 contracts to only DELEGATECALL other EOF1 contracts allows the following strong statement: EOF1 contract can never be destructed. Attacks based on SELFDESTRUCT completely disappear for EOF1 contracts. These include destructed library contracts (e.g. Parity Multisig).
Imposing an EOF-validation time limit for the size of EOF containers provides a reference limit of how large the containers should EVM implementations be able to handle when validating and processing containers. MAX_INITCODE_SIZE was chosen for EOF1, as it is what contract creation currently allows for.
Given one of the main reasons for the limit is to avoid attack vectors on JUMPDEST-analysis, and EOF removes the need for JUMPDEST-analysis and introduces a cost structure for deploy-time analysis, in the future this limit could be increased or even lifted for EOF.
kind_data could be 0x04 not 0xffPutting the data section last as 0xff has the advantage of aligning with the fact that it always comes last. We're avoiding a situation that a new section kind would need to go before the data section and break the section kind ordering. At the same time, data section being last is advantageous because it is the section which gets data appended to during contract deployment.
This is a breaking change given that any code starting with 0xEF was not deployable before (and resulted in exceptional abort if executed), but now some subset of such codes can be deployed and executed successfully.
The choice of MAGIC guarantees that none of the contracts existing on the chain are affected by the new rules.
With the anticipated EOF extensions, the validation is expected to have linear computational and space complexity. We think that the validation cost is sufficiently covered by:
Copyright and related rights waived via CC0.