xone snapshot import is built so that a failed or interrupted import leaves no half-usable datadir. The manifest is checked before anything is written; checked chunks go to a separate buffer file that the next run resumes from; and the datadir counts as present only when its last file, head.json, exists. Since PR #1010 (merged 2026-11-15), --staging DIR puts that buffer on another directory or filesystem.

The step-by-step bootstrap is in how to bootstrap from a snapshot, and what is hashed and checked is in how snapshots are made and verified.

What does the command look like?

xone snapshot import --datadir D2 --in snap.xsnap --pins pins.txt [--max-age-cap SECONDS] [--staging DIR] [--network apothem]

D2 must hold no chain. --max-age-cap (default 7 days) is your limit on how old a manifest may be, whatever the manifest says about itself (docs/ops/snapshot.md).

What is checked before anything is written?

The manifest: chain, genesis, state root, age, the certificates or seals, and the pin. A snapshot that fails any of these is refused and nothing is written. A snapshot whose history window is shorter than the binary needs is refused with ShortWindow.

What happens if the import stops halfway?

Run the same command again. Whole chunks that were already checked are kept in a buffer file, and the read continues after them. The Truncated and Incomplete errors name the byte where the file ends, which tells you that a download was cut.

Without --staging the buffer is D2/xone/snapshot.part. With --staging DIR it is DIR/snapshot-<id>.part, named for the datadir. A later run with the same --staging resumes from it, and a successful install removes it. The install reads the verified rows from memory, never from the buffer, so the buffer can be on a different filesystem from the datadir (PR #1010; test import_staging_sits_in_the_given_directory_and_resumes_from_it).

When does the datadir count as installed?

The import spec writes head.json last: "the datadir exists when head.json does". A kill before that write leaves no datadir, only a valid prefix (spec/bootstrap/import.md).

Can I check a snapshot without installing it?

Yes:

xone snapshot verify --in snap.xsnap --pins pins.txt --network apothem [--staging DIR] [--max-age-cap SECONDS]

It runs every check of import and installs nothing; it reads and writes no datadir. The chunks it reads go to a temporary file in --staging (default: the system temporary directory), which is removed on every path. Exit 0 means every check passed.

Where do snapshots come from?

ops/xone-snapshot-catalog.py list --catalog catalog.json --network apothem lists catalog entries with block, age, size, digest and source. A catalog read by URL must be pinned with --catalog-sha256. fetch --id ID --out snap.xsnap downloads to snap.xsnap.part, checks size and sha256, and only then renames the file. The pin still comes from a source you trust; nothing is imported automatically.

What PR #1010 leaves out: staging for the datadir tables of a snap download.

The collected competitor articles state no claim about staged snapshot import, so this post has no comparison table.

Frequently asked questions

What does --staging do in xone snapshot import?

It puts the buffer of checked chunks in another directory, as snapshot-<id>.part, instead of inside the datadir. A run with the same --staging resumes from it, and a successful install removes it.

Is a failed import left half-written?

No. The manifest is checked first and nothing is written on failure. The datadir counts as installed only when head.json, written last, exists.

How do I resume an interrupted import?

Run the same command with the same arguments, including the same --staging. Checked chunks are kept and the read continues after them.

Is --staging in the v0.1.0 release?

No. It came in PR #1010 on 2026-11-15.

Sources