What happens when a snap pivot moves in xOne on XDC

How does xOne choose a snap pivot?

The pivot is the block head - 64, lowered to the first block whose anchor verifies. The anchor is the epoch-switch header's masternode list, the quorum certificates of the next three blocks, and the 3-chain that commits the pivot (pivot rule).

• The switch header is pinned by --snap.pins <file>, or by at least two peers that serve the same hash. A peer on another chain is outvoted and logged.
• A pivot on a branch that fails --eth.requiredblocks is refused before state is requested (peer chain checks).

Why does the pivot move?

The pivot moves because peers keep state for recent roots only. The spec says a geth path-scheme node serves about the last 128 blocks, about 4 minutes on a 2-second chain. A longer download gets "no data" from every peer.

In the client, two empty answers in a row give up the root (max_empty: 2 in Config::default). The error is SyncError::Unavailable. Before PR #143, this error ended the sync and the node restarted from an empty datadir.

What does xOneRS do when the pivot moves?

xOneRS re-pivots. The driver in snapsync.rs runs three steps, up to 64 times (MAX_REPIVOTS):

1. Pick a fresh pivot by the same rules: new tip, head - 64, anchor verified, switch header pinned again. Fetch the header window, bodies, receipts and gap pools again for it.
2. Call StateStore::set_root(new root). The downloaded accounts, storage and codes stay. The cursors go on.
3. Run client::sync again. It reconciles, downloads the rest, heals and checks the root.

Each move logs pivot moved to root ... (move n). After 64 moves the sync fails with the last error.

Does xOneRS heal the state trie?

Yes. The heal pass is part of client::sync in crates/xone-snap. It uses the snap/1 message GetTrieNodes (code 0x06), which asks for a node by its path (messages.md).

• Reconcile first. After a move, the client walks the account trie at the new root. An account that is gone is dropped with its storage. An account whose storage root changed starts its storage over. geth answers a storage request for an unknown account with an empty reply, so this step comes first.
• Walk and fetch. The client walks the tries from the new root over the nodes it can build from local rows plus fetched nodes. It asks for each missing node by path, 1,024 paths a request (Config::default).
• Check by hash. A node is kept only if its hash is the one the walk needs. An empty string in the answer is a gap.
• Stop. The walk ends when no node is missing. Its leaves replace the local rows. Rounds are bounded by max_heal_rounds (128).

A storage trie whose root the local slots already hash to is left alone. The net2040 docs show runs with 0 trie nodes (heal) (net2040-sync-modes.md).

What does xOneRS not do?

The code names its own limit. Each heal round walks and rebuilds from the whole store. Geth keeps a persistent frontier of paths. xOneRS does not, and it does not keep fetched nodes across runs (code comment above heal in client.rs).

How is a moved pivot still checked?

Every range is proven against the root with verify_range, and a range with no proof is refused unless its leaves alone rebuild the whole trie (range-proofs.md). The root rebuilt from the hashed rows must equal the pivot's state root.

The sync is not done when the state is done. The first block after the pivot can be an epoch switch, and its reward hook reads data below the pivot. client::finish refuses with SyncError::Incomplete until every range of the plan is held (completeness.md). The anchor, window and state of the installed datadir belong to one pivot.

What do the other xOne clients do?

xOneTS and xOneC each have a moving-pivot step. Details differ.

The xOneC doc records a net2040 run of 2026-11-13 from two geth-XDC peers: pivot 820125, 109 trie nodes fetched, 12 requests, root verified.

How do other clients describe it?

ethrex describes the same problem. Network and units differ, so the numbers below are not like for like.

The Apothem run stopped before the install: that PR comment records that the install and tip were not reached, because the store was held in memory. A disk-backed download (--syncmode snap --state.disk, PR #148) was merged later. This post claims no Apothem result for it.

Frequently asked questions

Does xOneRS heal state after a snap pivot moves?

Yes. After set_root, the client reconciles the downloaded accounts with the new root, then fetches missing trie nodes with GetTrieNodes and checks each by its hash.

Does a moved pivot throw away the downloaded state?

No. StateStore::set_root keeps the downloaded accounts, storage and codes. An account that is gone is dropped, and an account whose storage root changed starts its storage over.

How many times can the pivot move?

At most 64 times in one sync. The heal is bounded to 128 rounds. Nothing is installed unless the rebuilt root equals the pivot's state root.