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

After EIP-8347

Who is affected

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.

Original EIP · ← EIPs