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
- Because metadata is mixed in after the execution code or within the data section, telling it apart relies on heuristic logic
- When the metadata size changes, the execution code's data-read offsets shift, changing the code itself
- Code can in theory access the metadata bytes
- For factory contracts with multiple nested bytecodes, locating each one's metadata is even trickier
After EIP-7834
- Metadata goes into a dedicated section whose size is specified in the header, making its location clear
- Execution code stays the same even when metadata changes, so it can be easily excluded during verification
- The metadata section cannot be accessed from code
- If metadata is not needed, the section can be omitted entirely to reduce container size
Who is affected
- Source code verification services: Can skip the metadata section and compare only the execution code, without heuristic logic.
- Compiler teams (Solidity, Vyper): Can change their output format to write metadata into the dedicated section instead of the data section.
- Client and tooling teams: Need to reflect the new section kind (0x05) in their EOF container processing logic.
- Ordinary users: It becomes easier to confirm that the contract they are using matches the published source.
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.