EIP-7620 EOF contract creation

No call decision · EVM & execution · EIP status Stagnant · created 2024-02-12

Adds new instructions, EOFCREATE and RETURNCODE, for creating another contract from within a container of EOF (EVM Object Format), Ethereum's new code format, replacing the existing CREATE and CREATE2 creation methods.

Why it is needed

With the introduction of EOF, Ethereum's new code format, one goal is to make contract code non-observable and non-modifiable during execution (code opaqueness). However, the existing contract creation instructions CREATE and CREATE2 let the EVM directly inspect and manipulate the initcode used to create a contract as well as the code that actually gets stored, which conflicts with this goal. EOF also removes the code-copying instructions CODECOPY and EXTCODECOPY, which factory contracts (contracts that create other contracts) had previously relied on. As a result, a new creation procedure specific to EOF containers was needed so that factory contracts could still create other contracts in the EOF environment.

What changes

Today

After EIP-7620

Who is affected

In depth

Introducing New Instructions: EOFCREATE and RETURNCODE

Two new instructions, EOFCREATE (0xec) and RETURNCODE (0xee), are introduced in the same block where EIP-3540 is activated. Executing these two instructions inside legacy bytecode is treated as an exceptional halt, so existing behavior is unchanged. Conversely, inside EOF contracts, CREATE and CREATE2 are rejected at the validation stage, remaining legacy-only instructions.

EOFCREATE's Detailed Procedure

EOFCREATE first deducts TX_CREATE_COST (32000) gas, and fails immediately if the frame is in static mode. It uses the 8-bit immediate value initcontainer_index to select one subcontainer within the EOF container as the initcode, pops salt, input_offset, input_size, and value from the stack, expands memory, and writes it as calldata. If STACK_DEPTH_LIMIT (1024) is exceeded or the balance is insufficient for the value transfer, it pushes 0 onto the stack and consumes neither nonce nor gas. On success, it increments the sender's nonce and computes the address as new_address = keccak256(0xff || sender32 || salt)[12:]. The 63/64 rule from EIP-150 applies to initcode execution, and after deployment, GAS_CODE_DEPOSIT (200) * deployed_code_size gas is additionally deducted.

RETURNCODE's Behavior

RETURNCODE reads the 8-bit deploy_container_index and pops aux_data_offset and aux_data_size from the stack. Its gas cost is 0, with only memory expansion being charged. This instruction ends execution of the initcode frame and returns control to the EOFCREATE calling frame, constructing the contract to be deployed from the specified subcontainer and aux_data. If appending aux_data to the data section causes the total size to fall outside the declared range (overflow or underflow), it aborts exceptionally.

Changes to the Data Section Before and After Deployment

The data_section of an undeployed EOF container is called the pre_deploy_data_section, and the pre_deploy_data_size declared in the header is greater than or equal to its actual length, reserving space to be appended later. Once deployment is complete, the final data_section is concatenated in the order pre_deploy_data_section, static_aux_data, dynamic_aux_data. The size of static_aux_data, which is known even before RETURNCODE executes, is pre_deploy_data_size - len(pre_deploy_data_section), and the remainder is dynamic_aux_data. This structure affects the validation and behavior of the DATALOAD, DATALOADN, and DATACOPY instructions.

Changes to CREATE/CREATE2 and EF00 Initcode Handling

Inside EOF contracts, the CREATE and CREATE2 instructions themselves are rejected at the validation stage. When CREATE or CREATE2 in a legacy contract receives EOF initcode starting with the EF00 magic bytes, deployment fails early (returning 0), the caller's nonce is not incremented, and initcode execution gas is not consumed. Previously, code starting with EF would begin execution and then fail at an undefined instruction, but this behavior changes to an early failure.

Code Validation Rules

Nine rules are added to the EIP-3670 validation rules. EOFCREATE's initcontainer_index and RETURNCODE's deploy_container_index must be smaller than num_container_sections. The subcontainer referenced by EOFCREATE must have a data_section length exactly equal to the header's data_size, and must not contain RETURN or STOP. The subcontainer referenced by RETURNCODE must not contain RETURNCODE, and a single container is also forbidden from having both RETURNCODE and RETURN/STOP. Every subcontainer must be referenced by its parent container, and the same subcontainer cannot be referenced by both RETURNCODE and EOFCREATE at once. It is also invalid for a jump destination of RJUMP, RJUMPI, or RJUMPV to point to the byte immediately following EOFCREATE or RETURNCODE.

Why initcontainer Is Excluded from the new_address Hash

An earlier draft also considered a scheme similar to CREATE2, where new_address = keccak256(0xff || sender || salt || keccak256(initcontainer))[12:], including a hash of the initcontainer. However, this conflicts with the code non-observability principle, blocking later upgrades that change the initcontainer's contents, and it also increases cost since the hash would need to be recomputed every time EOFCREATE runs. The final design uses only sender and salt, minimizing the formula, and leaves it to the factory contract to embed a code witness directly in the salt if a commitment to specific code is needed. This approach also has the advantage of keeping new_address independent of any metadata section proposed separately in the future.

Current Status and Remaining Work

This EIP's status is Stagnant, meaning it is not currently being actively advanced. The specification is intertwined with EIP-7873, which defines the EOF InitcodeTransaction, and since InitcodeTransaction is the point where unverified external code first enters state, the security considerations specify that its complexity, gas charging, and scope of validation must be examined especially carefully.

Original EIP · ← EIPs