EIP-7612 Bucket switch via an overlay tree (Verkle state transition via an overlay tree)
No call decision · Scaling & data · EIP status Stagnant · created 2024-01-25
A stopgap approach that freezes the existing MPT state as is while deferring the state transition work, recording all subsequent state write changes on top of it in an overlay Verkle Tree.
Why it is needed
Ethereum's state keeps growing, and Verkle Trees are considered a means of capping state size and enabling weak statelessness. However, a full migration of the entire existing MPT state to a Verkle Tree is complex, since contracts with large storage are hard to handle, and each client needs lengthy code changes. The larger the state, the longer the migration takes, and a longer migration slows down the fullsync that core dev teams use for performance testing, disrupts client release schedules (typically on a monthly cadence), delays recovery for nodes that fall behind during migration, and slows reorg handling. This EIP proposes immediately halting state growth by routing only new state writes to a Verkle Tree, instead of doing a full migration.
What changes
Today
- All state reads and writes currently happen in a single Hexary Merkle Patricia Trie (MPT).
- As Ethereum's state keeps growing, the full migration work to switch to a Verkle Tree takes longer and longer.
- A longer migration affects fullsync, client release schedules, and reorg handling speed, all at once.
After EIP-7612
- All new state writes after FORK_TIME are recorded in an overlay Verkle Tree (VKT).
- Reads first check the overlay VKT, and if not found there, fall back to the frozen existing MPT.
- The block header's state root switches from the MPT root to the VKT root.
- Once the block where the MPT was frozen is finalized, the MPT's internal node data can be deleted to free up disk space.
Who is affected
- Client teams: Execution clients must implement dual-read logic that queries the overlay VKT first and falls back to the existing MPT if not found, as well as logic to write accounts, storage, and code in Verkle Tree format.
- Full node and validator operators: Deleting internal node data after the block where the MPT was frozen is finalized can reduce disk usage.
- Core dev teams: This EIP does not cover migrating the existing MPT state itself into a Verkle Tree; that work is deferred to a separate follow-up EIP.
- Newly syncing nodes: Because the state transition period is shorter than with a full migration, impact from fullsync delays or new node join delays may be reduced.
In depth
How to view the state as split across an overlay tree
In addition to the existing _main_trie and _storage_tries, execution clients add an _overlay_tree (a Verkle Tree) to the State object. get_account_optional, which reads an account, first looks for the value in _overlay_tree and if not found looks in the existing _main_trie (MPT). get_storage, which reads storage, works in the same order. Conversely, the write functions set_account and set_storage write only to _overlay_tree without touching the MPT. As a result, after FORK_TIME the MPT remains only as a read-only reference, while all actual state changes accumulate on the Verkle Tree side.
FORK_TIME and determining the fork block
The transition point is defined by a constant called FORK_TIME, which is still marked TBD in the original text. The is_fork_block function determines a block to be the fork activation block when the parent block's timestamp is earlier than FORK_TIME and that block's own timestamp is at or after FORK_TIME. Starting from this block, the overlay Verkle Tree is activated and the block header's state root also switches to the VKT root.
The format for writing account data to the Verkle Tree
verkle_set_account encodes account information into a byte string called basicdata and stores it. Its layout is, in order, version (1 byte), reserved (4 bytes), code length (3 bytes), nonce (8 bytes), and balance (16 bytes). The code hash is stored in a separate leaf at the same key but with the last byte replaced by CODEHASH_LEAF_KEY. verkle_get_account parses this basicdata to recover balance, nonce, and code length, and additionally reads the code hash and code size via CODEHASH_LEAF_KEY and CODE_SIZE_LEAF_KEY to construct an Account object.
Storing contract code
To store contract code in the Verkle Tree, the state_set_codechunk function is used. This function computes the tree key for the address and chunk number (chunk_num) via get_tree_key_for_code_chunk and records the code chunk in the overlay tree.
Block header state root transition
Once FORK_TIME is reached, the state root carried in the block header is the Verkle Tree (VKT) root rather than the existing MPT root. Aside from this change, the block header structure itself does not change.
What this EIP does not cover
This proposal does not cover actually migrating (converting) the historical state accumulated in the existing MPT into a Verkle Tree. The original text describes this as a stopgap that defers that work to a follow-up EIP, citing simplicity as the benefit. It notes that this simplicity allows the Verge fork to be bundled and shipped first together with other simple EIPs, and also cites the fact that no consensus layer changes are required as a rationale.
Implementation status and remaining work
The text states that the reference implementation can be tested on go-ethereum's transition-post-genesis branch with the --override.overlay-stride=0 option. This EIP requires EIP-4762, 6800, and 7545 as prerequisites, and its Security Considerations section is still marked only as 'Needs discussion' with no content filled in. Its current status is listed as Stagnant.