EIP-2926 Chunk based code merkleization (Chunk-Based Code Merkleization)
No call decision · Scaling & data · EIP status Draft · created 2020-08-25
Splits contract code into 31 byte chunks and stores them in a Merkle tree. This lets a node verify a block after receiving only the chunks actually used by transaction execution, instead of the entire code.
Why it is needed
For Ethereum to move toward stateless execution, where a node can verify a block without holding the full state, the size of the witness sent along with each block must be shrunk. In the current witness, the largest share is proof hashes, followed by contract bytecode. Switching the trie from hexary to binary shrinks the hash portion threefold, making code the largest share this time. But under the current structure, even if only part of the code is executed, the entire code must be included in the witness. If code is split into fixed size chunks and each chunk is committed to a Merkle tree, a stateless client can fetch and execute only the chunks that a given transaction actually touched.
What changes
Today
- Contract code is stored as a whole, and the account records only a single hash of the entire code (codeHash)
- Even if only part of the code is executed, the entire code must be included in the witness
- The cost of storing code at contract creation is 200 gas per byte
After EIP-2926
- Code is split into 31 byte chunks and stored in a separate code tree (codeTrie), and codeSize and codeRoot fields are added to the account
- The witness only needs to include the chunks actually read during transaction execution
- The cost of storing code at contract creation rises to 500 gas per byte
Who is affected
- Client teams: The way code is stored changes significantly, and a transition process must be implemented to convert all existing contract code, over 10GB of it, into the new format.
- Contract and app developers: Contract deployment gas cost rises from 200 to 500 per byte. Apart from the gas cost change, the contract-facing interface stays the same.
- Node operators: Block proof size shrinks, making it easier to verify blocks via stateless or partial-stateless approaches.
- Ordinary users: Aside from the increase in contract deployment cost, there is almost no change the end user directly feels.
In depth
Account structure changes
The account record A gains two optional fields, A.codeSize and A.codeRoot. A.codeHash is kept unchanged to support EXTCODEHASH. If the code C is empty (an EOA), codeRoot and codeSize are omitted from the account RLP to reduce size overhead. If code exists, A.codeSize = len(code), and A.codeRoot holds the root of codeTrie. codeTrie contains a version leaf (key VERSION_KEY = max(u256), value BE(VERSION, 1), VERSION = 0) along with the chunk leaves. The root constant for empty code, EMPTY_CODE_ROOT, is keccak256(''). The trie format is kept the same as the account trie, and if the tree format changes later, the chunk tree must migrate along with it (see the EIP-6800, EIP-7864 approach).
Chunk-splitting rules and first instruction offset (FIO)
Code C is split so that code_0 || ... || code_n == C, where every chunk except the last has length CHUNK_SIZE (31 bytes) and the last chunk is at most 31 bytes. Each chunk's FIO_i is the offset at which the first instruction in that chunk begins. It is greater than 0 only when the last instruction of the preceding chunk is a multi-byte instruction like PUSHN that crosses the boundary, and is set to CHUNK_SIZE if the whole chunk is data. The i-th chunk is stored as key BE(i, 4), value BE(FIO_i, 1) || code_i. The FIO lets even a stateless client that does not hold all chunks safely perform jumpdest analysis. Edge cases where the trailing data bytes of the last chunk happen to look like a multi-byte instruction can be safely ignored.
Gas cost changes
When a contract is created via CREATE, CREATE2, or an external transaction, the per-byte cost of code stored in state rises from 200 gas to 500 gas. This reflects the cost of chunking and merkleization; the figure is taken from EIP-4762 and chosen with an eye toward future compatibility. On the read side, reading a chunk that has not yet been accessed incurs a 200-gas warming cost, and chunks used beyond the 24kb limit cost 500 gas rather than 200. This reflects the removal of the maximum code size limit and the fact that loading cost grows with code size. How the code is actually stored internally is left to client implementations.
Transition process for existing contracts
At the time this EIP was written, total code size exceeds 10GB and cannot be processed in a single block, so a gradual transition process similar to EIP-7612 is used. Once activated at HF_TIMESTAMP, newly created contracts and 7702 delegation updates both use the new format. Accounts whose balance or nonce alone changes are not migrated; migration happens via iterator sweep or at creation time. At the end of each block's processing, after all transactions have executed but before recomputing the tree root, the client walks ITERATOR_STRIDE accounts in the tree and rewrites legacy contracts into the new format. ITERATOR_STRIDE is To Be Confirmed (TBC), but based on Buckle's figures the first devnet uses 50,000, which at current state size and block time takes roughly 10,000 blocks, about a day and a half. Because multiple accounts can share the same code hash, the entire account tree must be walked, but chunking the same bytecode only needs to happen once, and codeSize and codeRoot can be cached during the transition. The overall migration is expected to take hours rather than days.
Handling 7702 delegated accounts and coordination with EIP-8032
For a 7702 delegated account, code size is treated as 23, and CODESIZE and CODECOPY are forwarded to the delegated account. EXTCODESIZE, EXTCODEHASH, and EXTCODECOPY behave exactly as they did before this EIP's activation. The transition process follows the approach in EIP-8032, storing progress pointers in a system contract, and is designed so that if both EIPs are activated at the same time, the two transition processes can be merged into one.
The 31-byte chunk size and alternative designs
Smaller chunks have higher utilization but deepen the trie, increasing the number of hashes included in proofs; larger chunks have the opposite tradeoff. 31 bytes is the current recommended value based on these observations, and a larger experiment comparing multiple chunk sizes is planned to determine a final recommendation. An alternative of prefixing each chunk with chunkLength and storing only complete instructions was also considered, but it was not adopted because storing a PUSH32 would require a chunk of at least 33 bytes, code like DUP1 PUSH32 would waste space across two chunks, and computing the chunk count is not straightforward, requiring it to be stored separately as metadata. Other approaches such as basic-block-based chunking, Solidity subroutines, and EIP-2315 subroutines were also considered, but this EIP focuses solely on chunk-based design.
Compatibility and current status
From a contract's perspective, this is designed to behave transparently aside from the gas cost change, but because it substantially alters how code is stored and changes Ethereum state, it can only be introduced via a hard fork. HF_TIMESTAMP has not yet been set, ITERATOR_STRIDE is also unconfirmed, and test cases and security considerations remain To Be Determined/Announced (TBD, TBA). This EIP is currently in Draft status, so the specification may change, and there is as yet no core developer call decision to include it in any specific fork.