UTXO snapshots
Start a node from a file of the unspent coins instead of replaying the chain: how to get, check, load and serve a snapshot, and what you trust.
A UTXO snapshot is a file that holds every unspent coin as it was after one block, the base. A node that loads it has the chain state of the base at once and follows the tip from there, without first validating every block since genesis. By default it then downloads and validates that history in the background and stops if the history disagrees with the snapshot.
A snapshot is identified by the height and hash of its base and by the MuHash3072 digest of its coin set. The digest does not depend on the file format, and it is the same value as the one committed in the coinbase by the UTXO commitment.
Requirements #
A node can load a snapshot only when:
- the explorer index is off (
-explorerindex=0) and no chain module is loaded (-modules=none): both need the whole history; -txindexand block filter indexes are off;- it does not already run on a snapshot;
- it knows the header of the base block, and its tip is below the base.
Once the background validation has finished, every block is on disk. You can then restart with the modules enabled (they are rebuilt from genesis) and rebuild the explorer with -explorerindex=1 -reindex.
Get a snapshot #
Full nodes on mainnet and testnet write a snapshot at every height that is a multiple of 100, once the tip is 110 blocks above it, and keep the newest one. They serve it over the REST API.
Download the newest snapshot of a node you choose (height 0 means the newest one it serves):
lotus-cli downloadutxosnapshot "node.example:10604" 0 utxo-latest.datThe file is fetched in chunks checked against the node's manifest, a partial file of the same snapshot is resumed, and the SHA-256 of the whole file is checked at the end.
Or write one on a node you run, at the tip or at an earlier height (at most 10,000 blocks back):
lotus-cli dumptxoutset utxo-1425000.dat 1425000dumptxoutset returns coins_written, base_hash, base_height, nchaintx, muhash, sha256, bytes, seconds and path. The format is deterministic: two nodes with the same set write the same bytes. A relative path is taken from the data directory.
Read the metadata of a file, and with true parse it all and check its trailer:
lotus-cli readutxosnapshot utxo-latest.dat trueCheck a snapshot against the chain #
From Napoleon, block H + 10 commits to the coin set after block H. Check the MuHash of a snapshot against that commitment, buried at least 100 blocks deep:
curl -s "http://127.0.0.1:10604/api/v1/chain/utxo-commitment/1800000?muhash=<muhash>&minconf=100"lotus-cli verifyutxocommitment "<muhash>" 1800000 100Blocks carry the UTXO commitment only from the Napoleon activation (median time past 1797886200, 21 December 2026, 20:50 UTC). Before it, no block vouches for a snapshot: use a quorum of nodes.
Load a snapshot #
On a running node:
lotus-cli -rpcclienttimeout=0 loadtxoutset utxo-latest.dat '{"source":"commitment","expected_muhash":"<muhash>"}'loadtxoutset "path" ( options ) takes one optional object:
| Option | Meaning |
|---|---|
source | What vouches for the hash: release (default), commitment or quorum. |
expected_muhash | The MuHash you expect the set to have. |
quorum | At least 3 "host:port" REST endpoints that must all report this MuHash at the base height. |
It returns coins_loaded, base_hash, base_height, muhash, seconds_build and seconds_swap. A file that fails any check is refused before the node's chain state changes.
To start a new node from a snapshot, pass the file at start-up. It is loaded as soon as the header of its base block is known:
lotusd -explorerindex=0 -modules=none -loadutxosnapshot=utxo-latest.datLoad with a quorum:
lotus-cli -rpcclienttimeout=0 loadtxoutset utxo-latest.dat '{"source":"quorum","quorum":["node-a:10604","node-b:10604","node-c:10604"]}'The release source needs a snapshot hash compiled into the node for that base block. Release 12.4.15 pins none for mainnet or testnet, so use commitment or quorum there.
Follow the background validation #
curl -s http://127.0.0.1:10604/api/v1/chain/utxo-snapshotlotus-cli getutxosnapshotinfoBoth return the state of the snapshot this node runs on and of its background validation. On a node that loaded a snapshot, getblockchaininfo carries the same object as utxo_snapshot.
Until the validation has finished, the base acts as a checkpoint: a chain that forks below it is refused (bad-fork-prior-to-utxo-snapshot). Reorganizations above the base work normally.
If the history does not reproduce the snapshot, the node logs the error, stops, and refuses to start again until you rebuild the chain state with -reindex.
Trust model #
What you trust depends on the source, until the background validation has replayed the history:
| Source | You trust |
|---|---|
release | The hash compiled into the release you run, the same trust as in the binary. |
commitment | Proof of work: the commitment in block base + 10, buried at least 100 blocks deep. |
quorum | At least 3 nodes, on distinct /16 networks on mainnet and testnet, that all report the same hash. One different or missing answer refuses the load. |
Blocks above the base are always fully validated. The background validation replays blocks 1 to the base with the normal block validation and compares the resulting set hash with the snapshot's. After it agrees, the node holds the same history as one that synced from genesis.
-snapshotverify=0 turns the background validation off: the node never downloads the history and keeps trusting the snapshot's source. It is refused for a quorum snapshot. From Napoleon, a wrong snapshot is still caught when block base + 10 connects: its commitment is compared with the loaded set and the node stops on a mismatch.
Do not open a wallet that needs a rescan on a snapshot node before the background validation is done: the blocks below the base are not there yet.
Serve and tune periodic snapshots #
| Option | Default | Meaning |
|---|---|---|
-utxosnapshotinterval=<n> | 100 (0 on regtest) | Mainnet and testnet accept only 0 (off): the heights are a network convention. |
-utxosnapshotkeep=<k> | 1 | Snapshots kept, plus the one being written (1 to 4). |
-utxosnapshotdir=<dir> | <datadir>/utxosnapshots | Where they are written. |
-utxosnapshotminfree=<MiB> | 8192 | Skip a snapshot when less than this would stay free. |
-utxosnapshotserve | 1 when the interval is set | Serve them on /api/v1/utxo-snapshots. |
-utxosnapshotservekbps=<n> | 8192 | Byte-rate budget for all clients together, in KB/s. |
-utxohash | 1 when the interval is set | Keep the set hash of every block for getutxohash and the quorum. |
List what a node holds:
curl -s http://127.0.0.1:10604/api/v1/utxo-snapshotslotus-cli listutxosnapshotsGET /api/v1/utxo-snapshots/<height> with a Range: bytes=a-b header returns at most 8 MiB of the file per request; beyond the byte-rate budget the node answers 429 with Retry-After.
The set hash after any recent block is available with lotus-cli getutxohash <height> and GET /api/v1/chain/utxo-hash/<height>. Compare it between nodes to check that they hold the same coins.
In the dashboard #
The page Developers > UTXO snapshots shows the commitment of recent blocks, the snapshots this node holds, and the commands above filled in with this node's values.
