EIP-8347 PBT offline state migration (Offline State Migration to the PBT)
No call decision · Networking & nodes · EIP status Draft · created 2026-07-23
Defines a migration procedure that converts Ethereum's full state from the existing MPT to a new PBT outside the consensus path, ships it as a verifiable snapshot, and swaps only the state commitment in a single hard fork.
Why it is needed
EIP-8297 proposes changing Ethereum's state storage structure from the existing hexary Merkle Patricia Trie (MPT) to a Partitioned Binary Tree (PBT). The problem is how to move the enormous state of an already-running mainnet to the new structure without splitting the chain. One path is an online overlay approach that converts gradually, inside consensus, while the chain keeps running, but then every client must match the conversion's progress bit-for-bit block by block, state proofs become complicated by spanning two trees until conversion finishes, and a zkEVM prover would have to prove the conversion process itself. This EIP instead takes an offline approach that finishes the conversion outside consensus. The consensus change shrinks to a single block changing how one header field is computed, and the state root always commits to the full state. In exchange, it pays the disk and compute cost of maintaining both trees during the transition period, and recovers correctness for the conversion, now invisible on-chain, through dual verification and shadow-root observation.
What changes
Today
- State is committed to a single hexary MPT, and the block header's stateRoot is the MPT root
- Changing the state tree has mainly been discussed as an overlay approach that converts gradually, block by block, inside consensus
- Nodes maintain only one tree, and state proofs are likewise built against the MPT alone
After EIP-8347
- The state of a finalized anchor block is converted to PBT outside consensus and shipped as a snapshot that anyone can receive and verify using only their own header chain
- After catching the snapshot up to the chain's latest block by BAL replay, the chain goes through a shadow-commitment period in which validators sign and publish the PBT root for every block
- In a single hard fork, PBT_ACTIVATION_FORK, stateRoot switches to the PBT root, and nothing else about execution changes
- Nodes keep maintaining both trees until the fork is finalized, and only then can they drop the MPT
Who is affected
- Node operators: Nodes must receive and verify a PBT snapshot or convert it themselves, state storage roughly doubles (about 300GB more on mainnet) while both trees are maintained during the transition period, and per-block tree-update work roughly doubles as well
- Validators: Adds an observation-only duty during the shadow-commitment period: signing and publishing the PBT root for every block with a validator key. This is a recommendation, not a consensus rule
- Bridges and light clients: Because the per-account storage_root disappears and the tree hashes change, every contract and service that verifies Merkle proofs of Ethereum state needs to be upgraded. The source text calls this out as the dependency with the longest lead time in the migration process
- zkEVM provers: They prove MPT execution as usual before the swap and commit to the PBT root after it, so they never have to prove the conversion step itself
In depth
Parameters and overall structure
Three parameters are defined. ANCHOR_BLOCK is the block that commits the state to be converted; it must be finalized, is identified by block hash, and its value is set after a mainnet rehearsal. PBT_ACTIVATION_FORK is the simultaneous EL+CL hard fork at which PBT becomes the official state commitment; this EIP fixes only the name, and the schedule is set by the hard-fork meta-EIP that includes this proposal, after the shadow-commitment period. REANCHOR_CADENCE is the re-anchoring interval for nodes that join late, set to 50400 blocks (about one week at 12-second slots). The migration proceeds through five stages: conversion, distribution and verification, catch-up, shadow commitment, and the swap and transition window, and consensus runs on the MPT at every stage before the swap. Conversion and distribution are permissionless and trustless. Since the conversion result is a pure function of the state committed by the ANCHOR_BLOCK stateRoot, and dual verification can reject bad outputs, who produces and who serves it has no bearing on correctness.
Preimage files
Because both MPT and PBT write keys as hashes, holding the tree gives you no way to recover the original account addresses and slot keys. Keccak cannot be inverted, so preimages can only come from what a client has kept on hand, from the EIP-7928 BAL, or from re-executing the chain. The BAL only gives keys touched after activation, so a complete set including long-dormant keys needs either a preimage store or a full re-execution. The file format is a sequence of fixed-width records, each being address[20] | slotCount[4, big-endian] | slotKey[32] * slotCount. Records are sorted ascending by keccak256(address), and the slotKeys within a record ascending by keccak256(slotKey), with no duplicates allowed. This sort key is exactly the MPT path, so both consensus anchoring rehashing and self-conversion can read the tree and the file with a single sequential merge. There is no terminator or padding after the last record, and the file is invalid if any bytes remain.
The converter's six stages
The converter is a deterministic function from MPT state to PBT state. 1) It scans MPT leaves and reconstructs the full hash path of each leaf. 2) It matches preimages against leaf paths via keccak256 so the two sets correspond exactly in both directions, rejecting any leaf path without a preimage or any preimage without a leaf. 3) It derives PBT keys as specified in EIP-8297. Most account state goes into the header stem of the ACCOUNT_ZONE, with slots 0-63 placed at sub-indices starting from HEADER_STORAGE_OFFSET, and only slots 64 and above receive storage zone keys. 4) Code is content-addressed by code_hash and emitted as chunks into the CODE_ZONE; the same code leaf is emitted exactly once, and chunks whose 32 bytes are all zero are not emitted. Delegated accounts have only a single header leaf at DELEGATION_LEAF_KEY. 5) An external merge sort is performed in PBT key order. 6) The tree is built bottom-up in a single sequential pass. For the same anchor state, any correct converter must produce a bitwise-identical root and snapshot.
Snapshot artifact format
A snapshot is a sequence of tagged records, terminated by an end tag (0x07) and a pbtRoot[32] trailer. Tags 0x00-0x02 are ACCOUNT_ZONE header records (codeless, contract code, EIP-7702 delegation), 0x03 is a CODE_ZONE code group, and 0x04-0x06 are STORAGE_ZONE storage account and group records. Records must preserve zone order; header records are sorted by addressHash, code groups by stemHash, and storage records by ascending addressHash. All integers are big-endian, and variable-width integers forbid leading zero bytes so the encoding is unique. The snapshot contains only PBT leaves and no intermediate nodes, so every node must hash the tree directly during verification, with no deployed intermediate hash ever trusted. snapshotDigest and preimageDigest, the keccak256 of the entire byte stream, are not a basis for trust but a way to cheaply cross-check multiple sources with 32 bytes before an expensive download.
Dual verification
Any node, even a new node with no prior state, must be able to verify a snapshot without trusting its source. There are two checks. First, internal consistency: reconstruct the PBT from the snapshot leaves, hash all intermediate nodes directly, and check that the root matches the claimed PBT root. Second, consensus anchoring: rehash the same leaves under the MPT schema using the preimages, and check that the result matches the stateRoot of the ANCHOR_BLOCK header. Because the root of trust is the stateRoot obtained from the node's own header chain, a tampered package with fake leaves and a fake pbtRoot that is only internally self-consistent will be caught by the second check. Since the MPT does not hold code, code leaves are anchored separately via code_hash. For each code_hash, the 31-byte fragments of the chunk leaves are concatenated to reconstruct the bytecode, its keccak256 is checked against that code_hash, and the reconstructed code is re-chunked per EIP-8297 and checked byte-for-byte against the code leaves in the artifact. A snapshot that fails either check must be rejected and re-fetched or re-converted.
BAL replay, deletion, and reorgs
From the anchor to the latest block, catch-up is done by applying the writes recorded in each block's BAL to the PBT without re-execution. The BAL lives outside the block body and is fetched from peers via the eth/71 protocol of EIP-8159 (GetBlockAccessLists / BlockAccessLists). Replay must be faster than block production, and ranges can be batched so repeated writes to the same key collapse into a single final value. The invariant to preserve is that the PBT obtained by replaying from the anchor to block B is bitwise identical to the PBT obtained by directly converting B's MPT. Since the BAL carries no deletion markers, deletions are read off from the recorded post-values: a zero write is a deletion of that key, and an account is deleted if its nonce, balance, and code_size are all zero after the block is applied. Reorg recovery must work by discarding state rather than by reverting writes, because the BAL holds only post-values and cannot be run backward. Re-anchoring emits a new snapshot every REANCHOR_CADENCE to keep the replay range within the EIP-7928 retention period (3,533 epochs, about 113,000 blocks); with a 50,400-block cadence, two cycles fit within that period.
Shadow commitments and residual risk
The weakness of the offline approach is that consensus never observes the correctness of the conversion. To address this, it is recommended that during the pre-swap period attesters sign and publish, with their validator keys, the shadow root, the PBT root of each block's post-state. The shadow root is delivered through an out-of-consensus telemetry sidecar and is not a block validity condition; omissions or delays are not treated as mismatches and count only toward a coverage metric. Enforcing it as a validity rule would require every validator to compute a PBT root for every block, reviving the on-consensus-path PBT construction that the offline model was meant to avoid. The wire format and aggregation method are deferred to a companion EIP that has not yet been published. Shadow roots must be keyed by block hash rather than height, so that normal root differences on either side of a reorg are not misread as mismatches. The residual risk is a converter bug affecting only the last blocks before a fork, whose PBT roots go live without ever having been validated by consensus. The source text lists two mitigations limited to those final blocks: enforcing shadow roots specifically for them, and relying on cross-client agreement accumulated during the shadow period.
Activation, the transition window, and current status
At PBT_ACTIVATION_FORK, the only thing that changes is which tree the existing stateRoot header field's value is computed from. No header field is added or changed, the boundary is a single block rather than a range, and since the consensus layer treats state_root only as an opaque 32 bytes, the CL-side change is purely fork scheduling. During the transition window from activation to finality, nodes must maintain both trees and preserve the ability to recover via the MPT, and can only drop the MPT after finality. Gas costs are not changed in this fork and are handled by a separate, unpublished repricing EIP; the only settled direction is that if PBT access is more expensive than MPT access it should be activated before the fork as an increase, and if cheaper, after the fork as a decrease. Upgrades for consumers of state proofs (bridges, light clients) also remain separate work. This EIP is currently in Draft status, so details of the specification may still change; the ANCHOR_BLOCK value and fork schedule are undecided, and no core developer call to date has decided on inclusion in a fork.