EIP-7834 EOF-exclusive metadata section (Separate Metadata Section for EOF)

No call decision · EVM & execution · EIP status Review · created 2024-12-06

Adds a metadata section to the EOF container that is exclusively off-limits to code access. Because execution code stays the same even when metadata changes, source code verification becomes easier.

Why it is needed

Smart contract bytecode carries metadata alongside the execution code, such as the compiler version or a hash of the source files. Currently, the Solidity and Vyper compilers encode this information in a format called CBOR and simply append it after the execution code. Because the bytecode has no structure, it is hard to tell where the execution code ends and the metadata begins. In source code verification, which compares the bytecode deployed on chain against the result of compiling the source, every verification service has to build its own heuristic logic to pick out the metadata. Even once EOF (Ethereum Object Format), which structures bytecode, is introduced, without a dedicated spot for metadata it would have to go into the data section, and then whenever the metadata size changes, the offset values of instructions reading that data would shift, changing the execution code itself and potentially letting code access the metadata. To prevent two contracts compiled from the same source from failing verification merely because of a metadata size difference, a separate section is needed.

What changes

Today

After EIP-7834

Who is affected

In depth

kind_metadata and metadata_size added to the header

Adds two OPTIONAL fields to the EIP-3540 container header. kind_metadata is 1 byte with value 0x05, marking it as the metadata section's kind indicator. metadata_size is a 2-byte big-endian unsigned integer with a value range of 0x0001-0xFFFF, indicating the length of the metadata section's content. Both fields are placed before kind_data (value 0xff) and data_size, and after the container-section-related fields. Unlike data_size, which allows 0x0000, metadata_size has a minimum of 0x0001, so a section cannot be declared with empty content.

Position and content of metadata_section in the body

The body's order becomes types_section, code_section(s), container_section(s), metadata_section, data_section. metadata_section is placed as OPTIONAL right before data_section. Its content is an arbitrary byte sequence, and this EIP does not define its structure or encoding. That is left to compilers, tooling, and contract developers to decide, and the current practice for the Solidity and Vyper compilers is CBOR encoding.

Why the metadata section is OPTIONAL

metadata_section and the header's kind_metadata and metadata_size fields are all OPTIONAL. This lets compilers that do not want to use metadata build a container without any extra bytes. By contrast, data_section is REQUIRED even when its data is empty, since its size and content can change during deployment. metadata_section is assumed not to change during deployment.

Placement before data_section and the choice of value 0x05

The reason metadata_section is placed before data_section rather than after it is that if it were placed after, the position of metadata_section would shift whenever data_section changes at deployment time. Placing it before avoids this problem. The value 0x05 rather than 0x04 was chosen for the kind value so that existing EOF tooling can accept the change more easily.

Three problems with putting metadata in the data section

In pre-EOF, Solidity appends CBOR-encoded metadata plus its 2-byte length to the end of the runtime bytecode, including an IPFS or Swarm hash and an experimental flag. Vyper, from 0.4.1, appends an integrity hash to the initcode using CBOR. Without a dedicated section, putting metadata into EOF's data_section creates three problems the source raises. First, it is hard to distinguish the metadata portion within data_section, repeating the same problem as pre-EOF. Second, when the metadata size changes, the execution bytecode changes as well, for example by shifting the DATALOADN offset, so two otherwise identical contracts differing only in metadata size would fail to match in source code verification. Third, by manipulating the DATALOADN instruction, code could in theory access the metadata.

Compatibility, security, and current status

Since EIP-3540 has not yet been implemented, there are expected to be no backward compatibility issues. Because the metadata section is a region that is never executed, the source states there are no separate security considerations. This EIP is currently in Review status, so the specification may still change.

Original EIP · ← EIPs