EIPs/EIPS/eip-3540.md

eip	title	description	author	discussions-to	status	type	category	created	requires
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.	Alex Beregszaszi (@axic), Paweł Bylica (@chfast), Andrei Maiboroda (@gumb0), Matt Garnett (@lightclient)	https://ethereum-magicians.org/t/evm-object-format-eof/5727	Review	Standards Track	Core	2021-03-16	3541, 3860, 4750, 5450

Abstract

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>

Motivation

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 JUMPDESTs entirely.
• 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.

Specification

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.

Remarks

The initcode is the code executed in the context of the create transaction, CREATE, or 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.

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

Code validation

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.

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

For the CREATE and 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.

Container specification

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:

description	length	value
magic	2-bytes	0xEF00
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 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.

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.

Container validation rules

1. version MUST NOT be 0.^1
2. section_kind MUST NOT be 0. The value 0 is reserved for section headers terminator byte.
3. There MUST be at least one section (and therefore section header).
4. Section content size MUST be equal to size declared in its header.
5. 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.

Container

The EOF version 1 container consists of a header and body.

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)+

note: , is a concatenation operator and + should be interpreted as "one or more" of the preceding item

Header

name	length	value	description
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

Body

name	length	value	description
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
code_section	variable	n/a	arbitrary bytecode
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

1. 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.
2. Any version other than 0x01 is invalid.

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

1. Execution starts at the first byte of the first code section, and PC is set to 0.
2. Execution stops if PC goes outside the code section bounds.
3. PC returns the current position within the code.
4. CODECOPY/CODESIZE/EXTCODECOPY/EXTCODESIZE/EXTCODEHASH keeps operating on the entire container.
5. The input to CREATE/CREATE2 is still the entire container.
6. 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 initcode_cost.

(Remark: Due to EIP-4750, JUMP and 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.

1. If initcode's container has EOF1 prefix it MUST be valid EOF1 code.
2. If code's container has EOF1 prefix it MUST be valid EOF1 code.
3. 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).
4. If CREATE or CREATE2 instruction 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.

Rationale

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 JUMPDEST map in the EOF container and eliminate the need of implicit JUMPDEST analysis required before execution.
• Or to completely remove the need for JUMPDEST instructions.
• 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 0xEF byte 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 MAGIC

1. The first byte 0xEF was chosen because it is reserved for this purpose by EIP-3541.

2. The second byte 0x00 was chosen to avoid clashes with three contracts which were deployed on Mainnet:

   • 0xca7bf67ab492b49806e24b6e2e4ec105183caa01: EFF09f918bf09f9fa9
   • 0x897da0f23ccc5e939ec7a53032c5e80fd1a947ec: EF
   • 0x6e51d4d9be52b623a3d3a2fa8d3c5e3e01175cd0: EF

3. No contracts starting with 0xEF bytes 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.

Section structure

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 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.
• Whether to encode section_size as 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.

Data-only contracts

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 DATACOPY or 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 CODECOPY/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 CODECOPY instruction).

Backwards Compatibility

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.

Test Cases

Contract creation

All cases should be checked for creation transaction, CREATE and CREATE2.

• 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

Contract execution

• EOF code containing PC opcode - offset inside code section is returned
• EOF code containing CODECOPY/CODESIZE - works as in legacy code
  • CODESIZE returns the size of entire container
  • CODECOPY can copy from code section
  • CODECOPY can copy from data section
  • CODECOPY can copy from the EOF header
  • CODECOPY can copy entire container
• EXTCODECOPY/EXTCODESIZE/EXTCODEHASH with the EOF target contract - works as with legacy target contract
  • EXTCODESIZE returns the size of entire target container
  • EXTCODEHASH returns the hash of entire target container
  • EXTCODECOPY can copy from target's code section
  • EXTCODECOPY can copy from target's data section
  • EXTCODECOPY can copy from target's EOF header
  • EXTCODECOPY can copy entire target container
  • Results don't differ when executed inside legacy or EOF contract

Security Considerations

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

Copyright and related rights waived via CC0.