BitcoinTechnicalIntermediate

One Hash Written in the Source Code

A new full node spends days validating every block from genesis. AssumeUTXO loads a snapshot of the UTXO set at a fixed height so the node is usable first, and finishes validation from scratch in the background. Why the snapshot file can come from anywhere, what the one hash you trust for a while actually is, how it differs from assumevalid, and the conditions you hit in practice, checked against the Bitcoin Core source and release notes.

·9min·Updated

The first thing you meet when you start a full node is a wait. Initial Block Download (IBD) fetches every block from the genesis block to today and validates each one, and depending on hardware it takes days. Until it finishes, a wallet connected to that node can do nothing. This is where many people give up and go back to someone else's node.

Since Bitcoin Core 28 (October 2024), mainnet has had another path. You load the UTXO set as of block 840,000, the block of the fourth halving, from a file and start from there. The feature is called AssumeUTXO. The word "assume" in its name invites suspicion: is this asking you to trust instead of verify? Bitcoin Core's source and documentation spell out exactly what it assumes and when and how that assumption goes away.

What a node actually needs

To validate a new transaction a node does not need every past block. It needs the UTXO set, the list of outputs not yet spent. If the coins a transaction's inputs point to are in that set and the signatures check out, the transaction is valid. IBD takes days because it builds this set by hand. It applies every transaction in order from genesis, adding and removing coins, until it arrives at the set as it stands right now.

So why not take the set another synced node already built? The problem is knowing the file is right. Slip in one extra output and a coin that never existed appears. Drop one and somebody's coin vanishes. The moment you trust the file you were handed, there is no point running your own node.

The file can come from anywhere

Bitcoin Core's answer is to distribute a hash instead of the file. The mainnet entry in src/kernel/chainparams.cpp lists snapshot hashes by height. The entry for 840,000 reads:

.height = 840'000,
.hash_serialized = AssumeutxoHash{uint256{"a2a5521b1b5ab65f67818e5e8eccabb7171a517f9e2382208f77687310768f96"}},
.m_chain_tx_count = 991032194,
.blockhash = uint256{"0000000000000000000320283a032748cef8227873ff4872689bf23f1cda83a5"},

When you load a snapshot file with loadtxoutset, the node reads in the coins one by one, computes a hash over the whole set and compares it with this value. If a single bit differs it rejects the file with "Bad snapshot content hash". That is why Core's usage document can say there is no canonical source for snapshots and, in the same breath, that any downloaded snapshot will be checked against a hash hardcoded in the source. The Core 26 release notes call getting snapshots from third-party sources such as HTTP or torrents reasonable, because their contents are always checked by hash. You do not need to trust whoever handed you the file.

There is one more condition. The header of the block the snapshot is based on must be in the header chain the node has already downloaded. If a forked header chain with more work exists that does not contain that block, the node refuses and tells you to sync without AssumeUTXO. The snapshot has to sit on the chain with the most proof of work.

So what do you trust?

You trust one line of hash instead of a file. Core developers put that value in through a pull request, and it was reviewed and merged. The mainnet 840,000 value went in with PR #28553 on August 14, 2024.

The value can be computed, so anyone can reproduce it. Run dumptxoutset in rollback mode on a node that is already synced, and it rebuilds the snapshot at that height and returns its hash. Core's usage document gives exactly this as the way to verify the hardcoded hash.

Nor is this a new kind of trust. The moment you download and run Bitcoin Core you already trust that its code implements the consensus rules correctly. The hash is part of that same code and goes through the same review. The difference is that this trust has an expiry date.

Starting over, in the background

A node that has loaded a snapshot holds two chainstates. One starts from the snapshot and follows the chain from 840,000 to the tip. Once the snapshot has been read in and its hash matches, this one becomes active right away, and the wallet and RPC use it. The other does an ordinary IBD, from genesis. According to Core's design document, the snapshot side gets priority for block downloads and most of the cache until it reaches the tip, after which the cache shifts to the background validation.

When the background validation reaches 840,000, the node hashes the UTXO set it built itself and compares that with the value in the source. If they match, the next restart deletes the background data and promotes the chainstate that started from the snapshot to the regular one. The design document says the result is indistinguishable from one built by traditional IBD. The only trace left is a base_blockhash file recording which block's snapshot it started from.

If they do not match, the node stops. The error message in validation.cpp attributes this case to a hardware problem, a software bug, or a bad software modification that let an invalid snapshot through. The node throws away all the state built on the snapshot, resets the chain height and shuts down. On the next start it continues syncing without any snapshot data. The discarded data is left on disk under a name ending in _INVALID so it can help diagnose the cause.

So the assumption in AssumeUTXO holds only until background validation finishes. Even in the meantime, every block after 840,000 is fully validated. What is borrowed for a while is only the history before it, and within days the node pays that back by recomputing it itself.

How it differs from assumevalid

Core already has a feature with a similar name: assumevalid, added in 0.14 in March 2017. Taking one block hash written in the source as a reference, it skips script (signature) checks for that block's ancestors. The UTXO set is still built by hand from genesis, and every other rule is still checked. The 0.14 release notes stressed that, unlike the old checkpoints, it does not force a particular chain. It only processes a chain consistent with that value faster, still accepts a different chain if it would otherwise be chosen as best, and can be switched off with -assumevalid=0.

The two skip along different axes. assumevalid goes through in order from start to finish, omits some signature checks, and never comes back to them. AssumeUTXO changes the order. It starts at the end and fills in the beginning behind itself. Background validation is the same process as an ordinary IBD, so under default settings assumevalid applies there too. A node that used AssumeUTXO does not validate less than one that did not. It does the same validation, and becomes usable sooner.

The height moves up with each release

Snapshot heights are tied to the Core version. When loadtxoutset first appeared in Core 26 (December 2023), the mainnet entry was empty, holding only the comment "TODO to be specified in a future patch". Mainnet use began with 28. Checking the source of each release since then gives this:

Core versionReleasedHeight added
28.0October 2024840,000
29.0April 2025880,000
30.0October 2025910,000
31.0April 2026935,000
32.0October 2026965,000

Old heights are kept, not removed. The more recent the snapshot height, the fewer blocks there are to catch up on after it. Load a snapshot for a height not in the source and the node refuses, listing the heights it does accept.

What you run into in practice

You have to find the snapshot file yourself. With no canonical source, you either get one from a third-party source such as the web or a torrent, or make one with dumptxoutset on another node that is already synced. You do not need to vet where the file came from. The hash check described above does that.

Loading it looks like this. It takes a while, so turn off the RPC client timeout.

bitcoin-cli -rpcclienttimeout=0 loadtxoutset /path/to/snapshot
bitcoin-cli getchainstates

getchainstates shows the progress of both chainstates. If headers have not been downloaded up to the snapshot's base block, you get an error saying the base block header must appear in the headers chain; wait for header sync and load it again. The node also refuses while the mempool is not empty.

While background validation runs there are two chainstate directories, so it uses more disk. Each is several gigabytes and can grow larger than the snapshot file you downloaded. A pruned node can load a snapshot too, but instead of the usual 550 MiB pruning minimum it uses at least 1100 MiB.

Wallets have a limit as well. A wallet that needs to rescan blocks below the snapshot height will not load until background validation reaches the height it needs, and the error message tells you which height that is. If you plan to attach a long-used wallet to a fresh node, you will end up waiting for background validation anyway. Indexes such as txindex gain nothing either, because they are only built in order from genesis.

The total amount of work does not shrink. CPU and disk end up doing the same job as an IBD, and slightly more, since two chainstates run side by side. What you gain is a node of your own that you can use during the days you would otherwise spend waiting.

Only the order changes

Running a full node means checking the rules yourself instead of taking someone's word for them. AssumeUTXO does not skip that check. It changes the order in which you do it. You borrow one line of hash from the source code for a few days, and in the meantime the node recomputes the same value with its own hands. Once that computation is done, the fact that you once trusted the hash no longer means anything.

Related