Abstract
This EIP adds a code_hash field to the AccountChanges entry of the EIP-7928 block access list (BAL). For every account whose pre-block bytecode is executed, copied, sized or checked for a delegation indicator during the block, the field holds the Keccak-256 hash of that bytecode. For every other account the field is empty. The BAL then names every piece of pre-block state that a block reads. When EIP-7709 is also active, a stateless or proving input for the block can be assembled from the block, its BAL and a state snapshot, without executing the block.
Motivation
EIP-7928 records every account and storage slot a block touches. A stateless verifier or a zkVM prover can use the BAL as the index of the pre-state it has to load: the account leaves of every listed address and the storage leaves of every listed key. Bytecode is the one state exception. The BAL records bytecode only when it changes, in code_changes. An address that is only called, or whose code is only copied or sized, appears with empty change lists, indistinguishable from an address whose balance was read. Which bytecode a block needs can today only be learned by executing the block, or by over-approximating and shipping the code of every listed address.
A witness is therefore still gathered the way it was before BALs existed: execute the block, record what it reads, then prove. This EIP removes the last state read that the BAL does not name. EIP-7709 removes the only non-state read, by serving BLOCKHASH from the storage of the EIP-2935 history contract so that it appears in storage_reads. With both, the block, its BAL and a state snapshot are a complete proving input. A prover assembles the witness by lookup alone, with no execution ahead of proving, and can start collecting it as soon as the BAL arrives, which under EIP-8146 is before the transactions.
Clients already diverge on this point. A witness generator that answers EXTCODESIZE from a code size cached by code hash never loads the bytes and omits the code from its witness, while a guest built on the reference implementation reads the code and fails without it. A normative definition of "code read" in the BAL removes that class of interoperability bug and gives witness formats such as EIP-8025 a complete and checkable definition of their code list.
Recording the code hash lets consumers without state, such as witness services or peers exchanging BALs, resolve the bytecode from a hash-keyed code store, deduplicates shared code across accounts, and matches the hash form that EIP-8298 uses for adopted code.
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.
Definitions
- Pre-block code of an account is its bytecode at the start of block execution, before the pre-execution system contract calls at
block_access_index = 0. For an EIP-7702 delegated account it is the delegation indicator, not the delegate's code.
Data Structure
AccountChanges gains a seventh element, code_hash:
CodeHash = bytes # 32-byte Keccak-256 hash of bytecode, or empty
# AccountChanges: [address, storage_changes, storage_reads, balance_changes, nonce_changes, code_changes, code_hash]
AccountChanges = [
Address, # address
List[SlotChanges], # storage_changes
List[StorageKey], # storage_reads
List[BalanceChange], # balance_changes
List[NonceChange], # nonce_changes
List[CodeChange], # code_changes
CodeHash # code_hash (hash of the pre-block code if it was loaded, else empty)
]code_hash MUST be RLP-encoded as a 32-byte string when set and as the empty byte string (0x80) when not set. All other encoding rules of EIP-7928 are unchanged.
Code Loads
A code load of address A is any of the following events, and only these:
- A message frame is dispatched with
Aas its code address. This includes the recipient of a transaction with a non-emptyto, the code address ofCALL,CALLCODE,DELEGATECALLandSTATICCALLafter EIP-7702 delegation resolution, the targets of pre- and post-execution system contract calls, and the resolved target of every EIP-8141 frame. The frame counts even if it reverts, halts exceptionally, or is not started because the call fails a post-state gas charge, its sender-balance check or its call-stack-depth check. A call or transaction to a delegated account loads the account under this rule to resolve the delegation, and loads the delegate under this rule when EIP-7928 includes it. EXTCODESIZEorEXTCODECOPYexecutes withAas its target.- An EIP-7702 authorization names
Aas its authority and the authority account is loaded, whether or not the authorization then succeeds. - Transaction validation checks the code of sender
Aunder the EIP-7702 transaction-origination rule. This loads only the sender's own code, not its delegate's code. - When EIP-8298 is active,
SETCODEFROMtargets sourceAand passes itsSETCODEFROM_SOURCE_GAScheck. This loads only the source's own code, without resolving delegation, whether or not the source is valid, the instruction subsequently runs out of gas, or the enclosing execution reverts.
An event is a code load only when EIP-7928 records the corresponding address access. In particular an operation that fails its pre-state gas validation of EIP-7928, which includes the EIP-2929 access costs, loads no code, and code_hash can never be set on an address that is absent from the BAL. Bytecode reads that a client performs for other reasons, such as prefetching, tracing or computing EXTCODEHASH from the bytes, are not code loads.
The following are not code loads: BALANCE, EXTCODEHASH, the collision check of CREATE and CREATE2, the execution of initcode by a creation frame, the delegation target named by an EIP-7702 authorization, SELFDESTRUCT beneficiaries, withdrawal recipients, and the fee recipient.
Recording Rule
For every AccountChanges entry of address A:
code_hashMUST bekeccak256(pre_block_code(A))if the pre-block code ofAis non-empty and at least one code load ofAoccurs in the block.- Otherwise
code_hashMUST be empty.
Validation
The EIP-7928 rule that the BAL MUST be complete and accurate extends to code_hash. A BAL whose code_hash values differ from those produced by execution invalidates the block.
The reference pseudocode of EIP-7928 changes as follows. new_account_entry creates the dictionary that track_state_changes creates for a new address, with an additional code_hash key initialized to b"". EMPTY_CODE_HASH is the Keccak-256 hash of the empty byte string. get_pre_block_code_hash reads the code hash from the pre-block account leaf and returns EMPTY_CODE_HASH for an absent account; it does not load bytecode.
def track_code_load(addr, accesses):
"""Called for every code load of addr"""
entry = accesses.setdefault(addr, new_account_entry())
if entry['code_hash'] != b"":
return
code_hash = get_pre_block_code_hash(addr)
if code_hash != EMPTY_CODE_HASH:
entry['code_hash'] = code_hashbuild_bal appends data['code_hash'] as the seventh element of each account entry.
Rationale
Hash rather than bytecode
Recording the full bytecode would make the BAL self-contained but would add the code of every executed contract to a consensus object that is gossiped with every block. A mainnet block loads a few hundred distinct contracts, so this adds on the order of megabytes per block, against a BAL of roughly 72 KiB at a 60M gas limit per the size analysis of EIP-7928.
Each populated code_hash costs 33 bytes, roughly 13 KiB for 400 populated fields, plus one byte for every empty field and any growth in enclosing RLP length prefixes. It lets a consumer without state resolve the bytecode from a hash-keyed store, deduplicates code shared by many accounts, lets a verifier check witness completeness against the BAL alone, and uses the same form as the new_code_hash element that EIP-8298 adds to CodeChange.
Fixed arity rather than an optional element
EIP-8298 adds its hash as an optional trailing element of CodeChange, so an entry has two or three elements. code_hash is instead always present, empty or 32 bytes. The cost is one byte per account entry, about 2 KiB for a block that touches 2000 accounts. The benefit is a single shape for AccountChanges: decoders need no arity check, and the position of the field never depends on the value of another field.
Pre-block code only
The field identifies pre-block bytecode needed during execution. Code introduced during the block can be reconstructed as execution proceeds, even when it is later overwritten or reverted and therefore absent from code_changes. Code that is loaded only while empty needs no bytes: the account leaf, or its absence, already proves that the code is empty. Both conditions depend only on the account's state and on instruction semantics, never on whether a client chose to read the bytes or to answer from the code hash, so independent implementations produce the same value.
The rule does not order loads against code changes. Every operation that changes the code of an account with non-empty code first loads that code: EIP-7702 authorization processing reads the authority's code before it writes the indicator, and code-changing instructions such as SETCODEFROM run in the frame of the account they change. Contract creation and EIP-6780 self-destruct only touch accounts whose pre-block code is empty. A load that follows an in-block code change therefore never records a hash that an earlier load has not already recorded, so the field does not depend on the order of loads and changes.
EXTCODEHASH is not a code load
EXTCODEHASH is answered by the account leaf. EXTCODESIZE is a code load because the account leaf does not carry the code size.
Block-level, not per block access index
EIP-7928 records storage reads without a block access index, and a stateless input is assembled per block, so one value per account suffices. A per-index list would only serve transaction-level proof sharding and would cost a few bytes per transaction that loads the account.
Interaction with EIP-8298
SETCODEFROM in EIP-8298 inspects the source's own code to determine whether it is valid regular deployed code before copying its code hash. The source bytes are therefore needed even when validation rejects a delegation indicator or a later gas charge fails. Rule 5 records this access once the source-access gas check passes, independently of success or reversion. It also makes pre-block source code available to an adopter called later in the block, whose code_changes entry contains only the adopted hash.
Witness construction
A witness builder with access to the pre-state includes, for every account entry with a non-empty code_hash, the bytecode with that hash, deduplicated by hash. A verifier binds each bytecode to the account leaf by hashing it on first use. The codes list of an EIP-8025 witness is complete and minimal exactly when the set of Keccak-256 hashes of its entries equals the set of non-empty code_hash values in the BAL. Together with the storage reads that EIP-7709 records for BLOCKHASH, this makes the BAL a complete index of the pre-state a block reads. Without EIP-7709, a proving input still needs the historical block data required to resolve BLOCKHASH; EIP-2935 alone does not change the opcode's access recording.
Backwards Compatibility
This EIP requires a hard fork. It changes the RLP encoding of AccountChanges and therefore the value of block_access_list_hash. A client implementing only EIP-7928 rejects blocks produced under this EIP, and vice versa. The Engine API is unchanged: the BAL is opaque RLP bytes to the consensus layer and to the engine methods that carry it.
No gas cost changes. Contracts are unaffected.
Test Cases
For each case, pre describes the pre-block state and expect the code_hash value of the named account.
CALLto contractCfrom a frame that later reverts.pre:Chas code.expect:C.code_hash = keccak256(C.code).CALLto contractCwith too little gas for the cold access cost, and no other access toC.expect:Cis absent from the BAL.EXTCODEHASHof contractC, no other access.expect:C.code_hashempty,Cpresent with empty change lists.EXTCODESIZEof an EOAEwith no code.expect:E.code_hashempty.EXTCODESIZEof contractC.expect:C.code_hash = keccak256(C.code).CALLto a delegated EOAEwith delegateD.pre:Dhas code.expect:E.code_hash = keccak256(0xef0100 || D)andD.code_hash = keccak256(D.code).CALLto a delegated EOAEfrom a frame at the call-stack depth limit.expect: as case 6, since the delegation is resolved before the depth check.- Transaction with an authorization whose authority
Ealready holds a delegation indicator, then aCALLtoEin the same transaction.expect:E.code_hash = keccak256(old indicator)by rule 3; the new indicator appears inE.code_changes. - Authorization whose authority
Ehas empty code, followed by aCALLtoE.expect:E.code_hashempty; the indicator appears inE.code_changes. - Contract
Ncreated at index 2 and called at index 5.expect:N.code_hashempty;N.code_changesholds the deployed code. - Contract
Ncreated and called in the same transaction.expect: as case 10. - Delegated EOA
Ehas its delegation updated by an authorization at index 3 and is called only at index 5.pre:Eholds the old delegation indicator.expect:E.code_hash = keccak256(old indicator)because authorization processing loads it before the update; the new indicator appears inE.code_changesat index 3. - Block with transactions.
expect: the account entries of the EIP-2935 and EIP-4788 system contracts, called at index0, and of the EIP-7002 and EIP-7251 system contracts, called at indexlen(transactions) + 1, each havecode_hash = keccak256(code). CALLto a precompile.expect:code_hashempty.- Value transfer from an EOA with no code to another EOA with no code.
expect:code_hashempty for sender and recipient. - Ordinary transaction from a delegated sender
Eto an EOA with no code, with no authorizations or other accesses toEor its delegateD.pre:E.code = 0xef0100 || D.expect:E.code_hash = keccak256(E.code);Dis absent from the BAL. - A parent frame creates contract
N, calls its deployed code, then reverts.pre:Ndoes not exist.expect:Nremains in the BAL with an emptycode_hashand nocode_changesentry. The executed runtime code is reconstructed by executing the initcode, despite the deployment being reverted. CALLto a delegated EOAEwith enough gas for the access cost ofEbut not for the access cost of its delegateD.expect:E.code_hash = keccak256(0xef0100 || D);Dis absent from the BAL.CALLto a delegated EOAEwhose delegateE2itself holds a delegation indicator toD.expect:E.code_hash = keccak256(0xef0100 || E2)andE2.code_hash = keccak256(0xef0100 || D), since the indicator ofE2is loaded and executed, halting on its invalid0xEFopcode;Dis absent from the BAL unless independently accessed.EXTCODESIZEorEXTCODECOPYof a delegated EOAEwith delegateD.expect:E.code_hash = keccak256(0xef0100 || D);Dis absent from the BAL unless independently accessed.- Transaction whose
tois a delegated EOAEwith delegateD.pre:Dhas code.expect: as case 6.
The following cases additionally activate EIP-8298. The source has no other accesses or code changes in the block:
SETCODEFROM(S)with sufficient gas, followed by a call to the adopter.pre:Shas regular deployed code.expect:S.code_hash = keccak256(S.code); the adopter'scode_changesentry records the adopted hash.SETCODEFROM(E)rejects a delegated source.pre:E.code = 0xef0100 || D.expect:E.code_hash = keccak256(E.code);Dis absent from the BAL unless independently accessed.SETCODEFROM(S)passes the source-access gas check but fails a subsequent gas charge.pre:Shas regular deployed code.expect:S.code_hash = keccak256(S.code)despite the exceptional halt.- Successful
SETCODEFROM(S)in a frame that later reverts.pre:Shas regular deployed code.expect:S.code_hash = keccak256(S.code); the reverted adoption contributes nocode_changesentry. SETCODEFROM(S)fails its source-access gas check.expect:Sis absent from the BAL.SETCODEFROM(E)with an empty-code source.expect:Eis included with an emptycode_hash.
Reference Implementation
See the pseudocode under Validation. A client that already tracks state accesses for EIP-7928 records one additional value per account entry, set at the first code load of an account whose pre-block code is non-empty.
A client without a pre-block snapshot can use the account's current code hash. When code_hash is still empty at a load and the account's code has not changed in the block, the current code hash is the pre-block code hash. When the code has changed, the pre-block code was empty, as shown under Pre-block code only, and nothing is recorded. The client already tracks code changes to produce code_changes.
Security Considerations
Size
For A account entries and R populated code_hash fields, the fields add A + 32 * R bytes before growth in enclosing RLP length prefixes: one byte per empty field and 33 bytes per populated field. This includes accounts accessed by system calls and other accesses that do not pay a cold-account access cost. The overhead is bounded by the EIP-7928 size constraint on the number of account entries.
Validation overhead
Recording the field requires checking whether a hash has already been recorded, then reading the code hash of the account when needed. Clients keep code hashes with the account and already track code changes for code_changes, so deriving the field requires no pre-state lookup, bytecode load or hashing. The hash of a bytecode deployed in the block is never recorded.
Completeness
As with every other BAL field, a wrong code_hash makes the block invalid. The field is derived from execution, so a block producer cannot use it to force a verifier to load bytecode that the block does not read.
Copyright
Copyright and related rights waived via CC0.
