EIP-3540: EOF - EVM Object Format v1
EOF is an extensible and versioned container format for EVM bytecode with a once-off validation at deploy time.
|Authors||Alex Beregszaszi (@axic), Paweł Bylica (@chfast), Andrei Maiboroda (@gumb0), Matt Garnett (@lightclient)|
|Requires||EIP-3541, EIP-3860, EIP-4750, EIP-5450|
Table of Contents
- Backwards Compatibility
- Test Cases
- Security Considerations
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:
magic, version, (section_kind, section_size)+, 0, <section contents>
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:
- Including a
JUMPDEST-table (to avoid analysis at execution time) and/or removing
- Introducing static jumps (with relative addresses) and jump tables, and disallowing dynamic jumps at the same time.
- Requiring the execution of a code section ends with a terminating instruction. (Assumptions like this can provide significant speed improvements in interpreters, such as a speed-up of ~7% seen in evmone (ethereum/evmone#295).
- Multibyte opcodes without any workarounds.
- Representing functions as individual code sections instead of subroutines.
- Introducing special sections for different use cases, notably Account Abstraction.
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.
The initcode is the code executed in the context of the create transaction,
CREATE2 instructions. The initcode returns code (via the
RETURN instruction), which is inserted into the account. See section 7 (“Contract Creation”) in the Yellow Paper for more information.
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 initcode or already deployed code starting with this instruction will continue to abort execution.
Unless otherwised 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.
block.number == HF_BLOCK new contract creation is modified:
- if initcode or code starts with the
MAGIC, it is considered to be EOF formatted and will undergo validation specified in the following sections,
- else if code starts with
0xEF, creation continues to result in an exceptional abort (the rule introduced in EIP-3541),
- otherwise code is considered legacy code and the following rules do not apply to it.
For a create transaction, if initcode or code is invalid, the contract creation results in an exceptional abort. Such a transaction is valid and may be included in a block. Therefore, the transaction sender’s nonce is increased.
CREATE2 instructions, if initcode or code is invalid, instructions’ execution ends with the result
0 pushed on stack. The initcode validation happens just before its execution and validation failure is observable as if execution results in an exceptional abort. I.e. in case initcode or returned code is invalid the caller’s nonce remains increased and all creation gas is deducted.
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 header:
|version||1-byte||0x01–0xFF||EOF version number|
The EOF header is followed by at least one section header. Each section header contains two fields,
section_kind and either
section_size_list, depending on the kind.
section_size_list is a list of size values when multiple sections of this kind are allowed.
The list of section headers is terminated with the section headers terminator byte
0x00. The body content follows immediately after.
Container validation rules
versionMUST NOT be
section_kindMUST NOT be
0. The value
0is reserved for section headers terminator byte.
- There MUST be at least one section (and therefore section header).
- Section content size MUST be equal to size declared in its header.
- Stray bytes outside of sections MUST NOT be present. This includes trailing bytes after the last section.
EOF version 1
EOF version 1 is made up of 5 EIPs, including this one: EIP-3540, EIP-3670, EIP-4200, EIP-4750, and EIP-5450. 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
container := header, body header := magic, version, kind_type, type_size, kind_code, num_code_sections, code_size+, kind_data, data_size, terminator body := type_section, code_section+, data_section type_section := (inputs, outputs, max_stack_height)+
, is a concatenation operator and
+ should be interpreted as “one or more” of the preceding item
|magic||2 bytes||0xEF00||EOF prefix|
|version||1 byte||0x01||EOF version|
|kind_type||1 byte||0x01||kind marker for EIP-4750 type section header|
|type_size||2 bytes||0x0004-0xFFFC||uint16 denoting the length of the type section content, 4 bytes per code segment|
|kind_code||1 byte||0x02||kind marker for code size section|
|num_code_sections||2 bytes||0x0001-0x0400||uint16 denoting the number of the code sections|
|code_size||2 bytes||0x0001-0xFFFF||uint16 denoting the length of the code section content|
|kind_data||1 byte||0x03||kind marker for data size section|
|data_size||2 bytes||0x0000-0xFFFF||uint16 integer denoting the length of the data section content|
|terminator||1 byte||0x00||marks the end of the header|
|type_section||variable||n/a||stores EIP-4750 and EIP-5450 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_height||2 bytes||0x0000-0x3FF||max height of operand stack during execution|
|data_section||variable||n/a||arbitrary sequence of bytes|
See EIP-4750 for more information on the type section content.
EOF version 1 validation rules
- In addition to general validation rules above, EOF version 1 bytecode conforms to the rules specified below:
- Exactly one type section header MUST be present immediately following the EOF version. Each code section MUST have a specified type signature in the type body.
- Exactly one code section header MUST be present immediately following the type section. A maximum of 1024 individual code sections are allowed.
- Exactly one data section header MUST be present immediately following the code section.
- Any version other than
(Remark: Contract creation code SHOULD set the section size of the data section so that the constructor arguments fit it.)
Changes to execution semantics
For clarity, the container refers to the complete account code, while code refers to the contents of the code section only.
- Execution starts at the first byte of the first code section, and PC is set to 0.
- Execution stops if
PCgoes outside the code section bounds.
PCreturns the current position within the code.
EXTCODEHASHkeeps operating on the entire container.
- The input to
CREATE2is still the entire container.
- The size limit for deployed code as specified in EIP-170 and for initcode as specified in EIP-3860 is applied to the entire container size, not to the code size. This also means if initcode validation fails, it is still charged the EIP-3860
(Remark: Due to EIP-4750,
JUMPI are disabled and therefore are not discussed in relation to EOF.)
Changes to contract creation semantics
For clarity, the EOF prefix together with a version number n is denoted as the EOFn prefix, e.g. EOF1 prefix.
- If initcode’s container has EOF1 prefix it MUST be valid EOF1 code.
- If code’s container has EOF1 prefix it MUST be valid EOF1 code.
- If initcode’s container is valid EOF1 code the resulting code’s container MUST be valid EOF1 code (i.e. it MUST NOT be empty and MUST NOT produce legacy code).
CREATE2instruction is executed in an EOF1 code the instruction’s initcode MUST be valid EOF1 code (i.e. EOF1 contracts MUST NOT produce legacy code).
See Code validation above for specification of behaviour in case one of these conditions is not satisfied.
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.
Execution vs. creation time validation
This specification introduces creation time validation, which means:
- All created contracts with EOFn prefix are valid according to version n rules. This is very strong and useful property. The client can trust that the deployed code is well-formed.
- In the future, this allows to serialize
JUMPDESTmap in the EOF container and eliminate the need of implicit
JUMPDESTanalysis required before execution.
- Or to completely remove the need for
- This helps with deprecating EVM instructions and/or features.
- The biggest disadvantage is that deploy-time validation of EOF code must be enabled in two hard-forks. However, the first step (EIP-3541) is already deployed in London.
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:
- Because the validation is consensus-level execution step, it means the execution always requires the entire code. This makes code merkleization impractical.
- Can be enabled via a single hard-fork.
- Better backwards compatibility: data contracts starting with the
0xEFbyte or the EOF prefix can be deployed. This is a dubious benefit, however.
Contract creation restrictions
The Changes to contact creation semantics section defines minimal set of restrictions related to the contract creation: if initcode or code has the EOF1 container prefix it must be validated. This adds two validation steps in the contract creation, any of it failing will result in contract creation failure.
Moreover, it is not allowed to create legacy contracts from EOF1 ones. And the EOF version of initcode must match the EOF version of the produced code. The rule can be generalized in the future: EOFn contract must only create EOFm contracts, where m ≥ n.
This guarantees that a cluster of EOF contracts will never spawn new legacy contracts. Furthermore, some exotic contract creation combinations are eliminated (e.g. EOF1 contract creating new EOF1 contract with legacy initcode).
Finally, create transaction must be allowed to contain legacy initcode and deploy legacy code because otherwise there is no transition period allowing upgrading transaction signing tools. Deprecating such transactions may be considered in the future.
The first byte
0xEFwas chosen because it is reserved for this purpose by EIP-3541.
- The second byte
0x00was chosen to avoid clashes with three contracts which were deployed on Mainnet:
- No contracts starting with
0xEFbytes exist on public testnets: Goerli, Ropsten, Rinkeby, Kovan and Sepolia at their London fork block.
EOF version range start with 1
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:
- Streaming headers (i.e.
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.
- Whether to have a header terminator or to encode
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.
- Whether to encode
section_sizeas a fixed 16-bit value or some kind of variable length field (e.g. LEB128). We have opted for fixed size, because it simplifies client implementations, and 16-bit seems enough, because of the currently exposed code size limit of 24576 bytes (see EIP-170 and EIP-3860). Should this be limiting in the future, a new EOF version could change the format. Besides simplifying client implementations, not using LEB128 also greatly simplifies on-chain parsing.
The EOF prevents deploying contracts with arbitrary bytes (data-only contracts: their purpose is to store data not execution). EOF1 requires presence of a code section therefore the minimal overhead EOF data contract consist of a data section and one code section with single instruction. We recommend to use
INVALID instruction in this case. In total there are 20 additional bytes required.
EF0001 010004 020001 0001 03 <data size (2 bytes)> 00 00000000 FE <data>
It is possible in the future that this data will be accessible with data-specific opcodes, such as
EXTDATACOPY. Until then, callers will need to determine the data offset manually.
PC starts with 0 at the code section
The value for
PC is specified to start at 0 and to be within the active code section. We considered keeping
PC to operate on the whole container and be consistent with
EXTCODECOPY but in the end decided otherwise. This also feels more natural and easier to implement in EVM: the new EOF EVM should only care about traversing code and accessing other parts of the container only on special occasions (e.g. in
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.
All cases should be checked for creation transaction,
- Legacy init code
- Returns legacy code
- Returns valid EOF1 code
- Returns invalid EOF1 code, contract creation fails
- Returns 0xEF not followed by EOF1 code, contract creation fails
- Valid EOF1 init code
- Returns legacy code, contract creation fails
- Returns valid EOF1 code
- Returns invalid EOF1 code, contract creation fails
- Returns 0xEF not followed by EOF1 code, contract creation fails
- Invalid EOF1 init code
- EOF code containing
PCopcode - offset inside code section is returned
- EOF code containing
CODECOPY/CODESIZE- works as in legacy code
CODESIZEreturns the size of entire container
CODECOPYcan copy from code section
CODECOPYcan copy from data section
CODECOPYcan copy from the EOF header
CODECOPYcan copy entire container
EXTCODECOPY/EXTCODESIZE/EXTCODEHASHwith the EOF target contract - works as with legacy target contract
EXTCODESIZEreturns the size of entire target container
EXTCODEHASHreturns the hash of entire target container
EXTCODECOPYcan copy from target’s code section
EXTCODECOPYcan copy from target’s data section
EXTCODECOPYcan copy from target’s EOF header
EXTCODECOPYcan copy entire target container
- Results don’t differ when executed inside legacy or EOF contract
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:
- EIP-3860 for initcode,
- high per-byte cost of deploying code.
Copyright and related rights waived via CC0.
Please cite this document as:
Alex Beregszaszi (@axic), Paweł Bylica (@chfast), Andrei Maiboroda (@gumb0), Matt Garnett (@lightclient), "EIP-3540: EOF - EVM Object Format v1 [DRAFT]," Ethereum Improvement Proposals, no. 3540, March 2021. [Online serial]. Available: https://eips.ethereum.org/EIPS/eip-3540.