EIP-3540 EOF - EVM Object Format v1

No call decision · EVM & execution · EIP status Stagnant · created 2021-03-16

EOF is an extensible container format that validates EVM bytecode once at deployment time, splitting code and data into sections.

Why it is needed

EVM bytecode deployed on-chain today has no fixed structure, so clients must repeat JUMPDEST analysis on every execution. This is both an execution overhead and an obstacle when trying to add new features or remove existing ones. In addition, because code and data (such as constructor arguments) are mixed together in one blob, on-chain code verifiers such as those used by L2s have difficulty telling the two apart. This has meant code had to be pre-processed before deployment, relied on fragile techniques, or required running expensive jump analysis. EOF aims to solve these problems by validating the structure once at deployment time.

What changes

Today

After EIP-3540

Who is affected

In depth

Overall container structure

An EOF container consists of magic (2 bytes, 0xEF00), version (1 byte), the section headers that follow, a 0x00 marking the end of the headers, and then the section bodies. In summary the structure is magic, version, (section_kind, section_size_or_sizes)+, 0, then the section bodies. Each section header consists of section_kind (1 byte) and either section_size or section_size_list, and section_kind cannot be 0, since 0 is reserved as the header terminator byte. A container must contain at least one section, and no stray bytes outside a section are allowed.

EOF1 header fields

The EOF version 1 header lists, in order: magic (0xEF00), version (0x01), kind_type (0x01) with type_size, kind_code (0x02) with num_code_sections and each code_size, optionally kind_container (0x03) with num_container_sections and each container_size, kind_data (0xFF) with data_size, and finally the terminator (0x00). type_size uses 4 bytes per code section, so it must be divisible by 4, and the number of code sections must equal type_size/4. The total container size cannot exceed MAX_INITCODE_SIZE as defined by EIP-3860.

Body composition: types/code/container/data sections

The body consists of exactly one types_section, one or more code_sections, zero or more container_sections, and one data_section. The types_section holds, for each code section, inputs (number of values consumed from the stack), outputs (number of values returned), and max_stack_increase (the maximum stack height the code section can add), each 4 bytes. The outputs value 0x80 is a special value, defined by a separate EIP, denoting a non-returning function. A container_section can hold an entire arbitrary EOF container, and a data_section is an arbitrary byte sequence; for a container that has not yet been deployed, data_size may be larger than the actual content.

Changes to execution semantics

An EOF contract always begins execution at the first byte of code section 0. CODESIZE, CODECOPY, EXTCODESIZE, EXTCODECOPY, EXTCODEHASH, and GAS are rejected at validation time with no replacement instructions. CALL, DELEGATECALL, and STATICCALL are also rejected, and replacement instructions are introduced by separate EIPs. An EOF contract calling a non-EOF contract (legacy, EOA, or empty account) via DELEGATECALL (or its replacement) is forbidden and fails the same way a call-depth check failure does. However, a legacy contract calling an EOF contract via DELEGATECALL is still allowed, so that existing proxy contracts can use an implementation upgraded to EOF.

How a legacy contract sees an EOF contract

If a legacy contract tries to copy an EOF contract's code with EXTCODECOPY, it behaves as if only the first 2 bytes of EF00 were copied. EXTCODEHASH returns 0x9dbf3648db8210552e9c4f75c6a1c3057c0ca432043bd648be15fe7be05646f5, the hash of EF00, and EXTCODESIZE returns 2. This rule does not apply to an EOF contract that is still being created, which is treated the same as an account with no code.

Choice of the MAGIC bytes

The EOF identifier is 0xEF00. The first byte, 0xEF, is the value EIP-3541 reserved for this purpose, and the second byte, 0x00, was chosen so as not to collide with three contracts already deployed on mainnet that start with 0xEF (EFF09f918bf09f9fa9, EF, EF). As of the London fork block, public testnets such as Goerli, Ropsten, Rinkeby, Kovan, and Sepolia have no contracts starting with 0xEF. This EIP must not be applied to a chain where bytecode already exists that starts with MAGIC but is not valid EOF.

EOF1 can only DELEGATECALL EOF1

A contract can currently be self-destructed via three paths: SELFDESTRUCT, CALLCODE, and DELEGATECALL. EIP-3670 blocks the first two paths, but the DELEGATECALL path remains. By restricting EOF1 contracts so they can only DELEGATECALL other EOF1 contracts, we get a strong guarantee that an EOF1 contract can never be destroyed, which eliminates attacks like the one on the Parity multisig caused by a destroyed library contract, for EOF1 contracts entirely.

Current status and prerequisites

This EIP's status is Stagnant: it has not yet been finalized or included in a hard fork, and it may still change or be discontinued. It builds on EIP-3541 (reserving the 0xEF byte) and EIP-3860 (MAX_INITCODE_SIZE). The actual contract creation instructions, replacement CALL-type instructions, EXTDATACOPY, and so on are all defined in separate EIPs. In other words, this EIP alone is not a complete feature; it is the base container specification for a format called EOF that is made up of multiple EIPs.

Original EIP · ← EIPs