How xOne snapshots and backups are made and verified

What is a chain snapshot made of?

A snapshot is one .xsnap file: the bytes XSNP, a format version, chunks and a trailer (format). The first chunk is the manifest. The next chunks hold accounts, storage, codes, side data, headers, bodies and receipts.

• Each chunk ends with a CRC-32C checksum. The trailer lists every chunk and its checksum.
• The trailer also holds the keccak256 of the manifest chunk.
• The manifest is the anchor: chain id, genesis hash, checkpoint number and hash, state root, created_at, max_age, the validator provenance and the proof headers.
• The same state gives the same bytes, so a publisher can name a file by its hash.

The exporter rebuilds the state root from the stored rows and compares it with the header. A mismatch writes nothing. It writes <out>.part and renames it when complete.

What does xone snapshot verify check?

It runs every check of import and installs nothing. It touches no datadir. Exit code 0 means every check passed (operator page).

xone snapshot verify --in snap.xsnap --pins pins.txt --network apothem

The first failure is the error. The order is (import order):

1. Pins. No pins file gives NoPins, before the file is opened.
2. Manifest. Format, chain, genesis, freshness, pin, binding, then certificates (V2) or seals (V1).
3. Chunks. The CRC-32C of each chunk. The trailer must name exactly the chunks read.
4. Content. Headers link to the checkpoint. Each body and receipt list matches its header. Each code hashes to its name. The rebuilt state root equals the manifest's.

What are the pins file and the anchor proof?

The pins file is the trust root. It lists <block number> <block hash> pairs from a source you trust. The importer refuses a file whose checkpoint or provenance header is not listed.

The anchor proof is made of chain signatures. On V2, it is a quorum certificate for the checkpoint plus a 3-chain above it. On V1, it is seals from at least ceil(2n/3) distinct listed sealers (anchor spec). These signatures belong to the chain. They are not a signature by the publisher of the file.

A chain built with its own keys passes every manifest check. Only the pin, which comes from outside the manifest, catches it. Three items are not authenticated: the V1 signer snapshot, the sign transactions and the gap pools. A forged item makes the node refuse a true block. It does not make the node accept a false block.

Is a snapshot signed?

No. The xone snapshot subcommands are export, import and verify (CLI definition). None has a flag that signs a file, checks a signature, or checks a hash of the whole file.

ADR-006 has the status Proposed, dated 2026-11-14. It says:

• The manifest "holds the hash of every part".
• The file travels over plain HTTPS from any mirror, and "trust does not come from the mirror".
• The manifest is bound to an anchor, and the operator gives one pin.

The ADR defines no signature, key or signature check for snapshot files. Its owner acceptance table has a row named "Signed" with an empty proposed value and an empty owner entry. Only the owner changes the status line. The ADR lists the HTTPS fetch and the published pin list as open work:

• #185: import from an HTTPS URL with a checksum, resume and pins. Today --in reads a local file.
• #14: the authenticated anchor. The source of the pins is an owner decision.
• #587: record ADR-006 and collect owner acceptance.

How does xone-datadir.py make a backup?

The tool backs up a stopped follower datadir. It writes chain data only: xone/, state/, xone-chain.json and the MDBX files. It leaves out nodekey, keystore/, safety/, miner.password, jwt.hex and *.toml. It refuses a datadir that has a safety record (tool).

ops/tools/xone-datadir.py backup <datadir> <backup.tar.gz>
ops/tools/xone-datadir.py rehearse <backup.tar.gz> <new-datadir>

• backup records the SHA-256 of every file in MANIFEST.json, the last member of the archive.
• The archive goes to <backup.tar.gz>.part and is renamed when complete.
• It then writes <backup.tar.gz>.sha256: the SHA-256 of the whole archive, and nothing else. The file is not in sha256sum -c format.

How does the rehearsal verify a backup?

rehearse restores into a new, empty directory. It never touches a live datadir. It restores nothing if the archive digest differs from the .sha256 file or the archive cannot be read.

• A missing .sha256 file skips that check.
• A MANIFEST.json that is not the last member means a truncated or foreign archive.
• After extraction, it recomputes every digest in the manifest. A missing or changed file gives digest mismatch.
• On success, it prints the file count and xone/head.json.

It does not start a node and does not check the chain. The digests find a damaged or cut archive. They do not show who made it. The tests (test_ops_datadir.py) cover a restore without custody files, a truncated archive and a digest mismatch. Automating the rehearsal before upgrades is open in #693. The upgrade guide still copies the whole datadir in step A3.

What is hashed and what is signed?

Frequently asked questions

Does the hash of a snapshot file prove it is the XDC chain?

No. A file hash proves the bytes. The anchor proof and the pin bind the file to the chain. The .xsnap file holds no hash of itself.

Is ADR-006 accepted?

No. Its status is Proposed, dated 2026-11-14. The owner changes the status line.

Can I use sha256sum -c on the backup .sha256 file?

Not directly. The file holds only the digest. Compare it with the output of sha256sum <backup.tar.gz>.

Does the backup include my validator key?

No. The tool excludes nodekey, keystore/ and safety/, and refuses a datadir that has a safety record.