Skip to content

BITCOIN MAINNETLive explorer status

₿MyBitcoinExplorer

Explorer Mempool Feed Forum Visualizer Receipts Tools Learn Code

Inside Bitcoin

Opening the selected file…

₿MyBitcoinExplorer

Bitcoin, in focus.
Explore the network. Understand the connections.

Explore Bitcoin with clarity.

Explore

Block explorer Mempool Bitcoin message feed Fee estimates Transaction graph

Build & learn

Developer tools API documentation Bitcoin guides Inside Bitcoin source Our methodology

MyBitcoinExplorer

Watchlists & alerts About the project Network status Address monitoring

© 2026 MyBitcoinExplorer. Bitcoin, in focus.Privacy Terms Contact Bitcoin mainnet

READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server440 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

bitcoin / bitcoinstable

Find a file

▤ assumeutxo.md

▤ libraries.md

▤ multiprocess.md

▤ AI_POLICY.md

▤ asmap-data.md

▤ assets-attribution.md

▤ assumeutxo.md

▤ benchmarking.md

▤ bitcoin_logo_doxygen.png

▤ bitcoin-conf.md

▤ build-freebsd.md

▤ build-netbsd.md

▤ build-openbsd.md

▤ build-osx.md

▤ build-unix.md

▤ build-windows-msvc.md

▤ build-windows.md

▤ CMakeLists.txt

▤ dependencies.md

▤ descriptors.md

▤ developer-notes.md

▤ dnsseed-policy.md

▤ Doxyfile.in

▤ external-signer.md

▤ INSTALL_linux.md

▤ JSON-RPC-interface.md

▤ managing-wallets.md

▤ multiprocess.md

▤ multisig-tutorial.md

▤ offline-signing-tutorial.md

▤ p2p-bad-ports.md

▤ productivity.md

▤ README_doxygen.md

▤ README_windows.txt

▤ reduce-memory.md

▤ reduce-traffic.md

▤ release-notes.md

▤ release-process.md

▤ REST-interface.md

▤ translation_process.md

▤ translation_strings_policy.md

▤ .editorconfig

▤ .gitattributes

▤ .python-version

▤ .style.yapf

▤ CMakeLists.txtGuide

▤ CMakePresets.json

▤ CONTRIBUTING.md

▤ COPYINGGuide

▤ CTestConfig.cmake

▤ libbitcoinkernel.pc.in

▤ README.mdGuide

▤ SECURITY.md

bitcoin / doc / design / assumeutxo.md

Download source ↓

5,398 bytes · SHA-256 11614fe8c73513bc… · View upstream ↗

1# Assumeutxo Design
2
3For notes on the usage of Assumeutxo, please refer to [the usage doc](/doc/assumeutxo.md).
4
5## General background
6
7- [assumeutxo proposal](https://github.com/jamesob/assumeutxo-docs/tree/2019-04-proposal/proposal)
8- [Github issue](https://github.com/bitcoin/bitcoin/issues/15605)
9- [draft PR](https://github.com/bitcoin/bitcoin/pull/15606)
10
11## Design notes
12
13- The concept of UTXO snapshots is treated as an implementation detail that lives
14  behind the ChainstateManager interface. The external presentation of the changes
15  required to facilitate the use of UTXO snapshots is the understanding that there are
16  now certain regions of the chain that can be temporarily assumed to be valid.
17  In certain cases, e.g. wallet rescanning, this is very similar to dealing with
18  a pruned chain.
19
20  Logic outside ChainstateManager should try not to know about snapshots, instead
21  preferring to work in terms of more general states like assumed-valid.
22
23
24## Chainstate phases
25
26Chainstate within the system goes through a number of phases when UTXO snapshots are
27used, as managed by `ChainstateManager`. At various points there can be multiple
28`Chainstate` objects in existence to facilitate both maintaining the network tip and
29performing historical validation of the assumed-valid chain.
30
31It is worth noting that though there are multiple separate chainstates, those
32chainstates share use of a common block index (i.e. they hold the same `BlockManager`
33reference).
34
35The subheadings below outline the phases and the corresponding changes to chainstate
36data.
37
38### "Normal" operation via initial block download
39
40`ChainstateManager` manages a single Chainstate object, for which
41`m_from_snapshot_blockhash` is `std::nullopt`. This chainstate is (maybe obviously)
42considered active. This is the "traditional" mode of operation for bitcoind.
43
44|    |    |
45| ---------- | ----------- |
46| number of chainstates | 1 |
47| active chainstate | ibd |
48
49### User loads a UTXO snapshot via `loadtxoutset` RPC
50
51`ChainstateManager` initializes a new chainstate (see `ActivateSnapshot()`) to load the
52snapshot contents into. During snapshot load and validation (see
53`PopulateAndValidateSnapshot()`), the new chainstate is not considered active and the
54original chainstate remains in use as active.
55
56|    |    |
57| ---------- | ----------- |
58| number of chainstates | 2 |
59| active chainstate | ibd |
60
61Once the snapshot chainstate is loaded and validated, it is promoted to active
62chainstate and a sync to tip begins. A new chainstate directory is created in the
63datadir for the snapshot chainstate called `chainstate_snapshot`.
64
65When this directory is present in the datadir, the snapshot chainstate will be detected
66and loaded as active on node startup (via `LoadAssumeutxoChainstate()`).
67
68A special file is created within that directory, `base_blockhash`, which contains the
69serialized `uint256` of the base block of the snapshot. This is used to reinitialize
70the snapshot chainstate on subsequent inits. Otherwise, the directory is a normal
71leveldb database.
72
73|    |    |
74| ---------- | ----------- |
75| number of chainstates | 2 |
76| active chainstate | snapshot |
77
78The snapshot begins to sync to tip from its base block, technically in parallel with
79the original chainstate, but it is given priority during block download and is
80allocated most of the cache (see `MaybeRebalanceCaches()` and usages) as our chief
81goal is getting to network tip.
82
83**Failure consideration:** if shutdown happens at any point during this phase, both
84chainstates will be detected during the next init and the process will resume.
85
86### Snapshot chainstate hits network tip
87
88Once the snapshot chainstate leaves IBD, caches are rebalanced
89(via `MaybeRebalanceCaches()` in `ActivateBestChain()`) and more cache is given
90to the background chainstate, which is responsible for doing full validation of the
91assumed-valid parts of the chain.
92
93**Note:** at this point, ValidationInterface callbacks will be coming in from both
94chainstates. Considerations here must be made for indexing, which may no longer be happening
95sequentially.
96
97### Background chainstate hits snapshot base block
98
99Once the tip of the background chainstate hits the base block of the snapshot
100chainstate, we hash the
101background chainstate's UTXO set contents and ensure it matches the compiled value in
102`CMainParams::m_assumeutxo_data`.
103
104|    |    |
105| ---------- | ----------- |
106| number of chainstates | 2 |
107| active chainstate | snapshot |
108
109The background chainstate data lingers on disk until the program is restarted.
110
111### Bitcoind restarts sometime after snapshot validation has completed
112
113After a shutdown and subsequent restart, `LoadChainstate()` cleans up the background
114chainstate with `ValidatedSnapshotCleanup()`, which renames the `chainstate_snapshot`
115datadir as `chainstate` and removes the now unnecessary background chainstate data.
116
117|    |    |
118| ---------- | ----------- |
119| number of chainstates | 1 |
120| active chainstate | ibd (was snapshot, but is now fully validated) |
121
122What began as the snapshot chainstate is now indistinguishable from a chainstate that
123has been built from the traditional IBD process, and will be initialized as such.
124
125A file will be left in `chainstate/base_blockhash`, which indicates that the
126chainstate, even though now fully validated, was originally started from a snapshot
127with the corresponding base blockhash.
128

A READING COMPANION

Source available. Guide coming next.

This file is included in the stable source snapshot. A file-specific guide has not been published yet.

440 guided files · 2,580 pending. Guides cover key sections, not every line.

cmake/bitcoin-build-config.h.in src/consensus/amount.h src/consensus/consensus.h src/primitives/block.h src/primitives/transaction.h src/crypto/sha256.h src/util/moneystr.h src/clientversion.h src/uint256.h src/script/script.h src/policy/policy.h CMakeLists.txt README.md COPYING src/consensus/tx_check.cpp src/consensus/tx_verify.cpp src/consensus/merkle.cpp src/pow.cpp src/validation.cpp src/script/interpreter.cpp src/script/solver.cpp src/script/sign.cpp src/key_io.cpp src/net.cpp src/net_processing.cpp src/netaddress.cpp src/protocol.h src/wallet/wallet.cpp src/wallet/spend.cpp

Code page 1

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/wallet/fees.cpp

src/wallet/load.cpp

src/txmempool.cpp

src/node/miner.cpp

src/chainparams.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/crypto/sha256.cpp

src/serialize.h

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/arith_uint256.h

src/blockencodings.h

src/blockfilter.h

src/crypto/siphash.h

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/compressor.h

src/compressor.cpp

src/flatfile.cpp

src/dbwrapper.h

src/util/chaintype.h

src/util/chaintype.cpp

src/scheduler.h

src/scheduler.cpp

src/checkqueue.h

src/threadsafety.h

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/blockfilter.cpp

src/merkleblock.cpp

src/merkleblock.h

src/addrman.cpp

src/netgroup.cpp

src/net_permissions.cpp

src/netbase.cpp

src/torcontrol.cpp

src/net_types.h

src/net_types.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/server.cpp

src/rpc/mempool.cpp

src/rpc/mining.cpp

src/rpc/net.cpp

src/rpc/node.cpp

src/rpc/blockchain.h

src/rpc/client.h

src/rpc/mempool.h

src/rpc/mining.h

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/abort.cpp

src/node/abort.h

src/node/caches.cpp

src/node/caches.h

src/kernel/caches.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/util/rbf.cpp

src/util/thread.h

src/common/netif.h

src/common/url.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/util/thread.cpp

src/kernel/types.h

src/interfaces/rpc.h

src/util/fees.cpp

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

src/attributes.h

src/chainparams.h

src/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/compat/cpuid.h

src/compat/endian.h

src/compat/stdin.cpp

src/compat/stdin.h

src/core_memusage.h

src/crypto/common.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

src/indirectmap.h

src/init/basic.cpp

src/init/bitcoin-gui.cpp

src/init/bitcoin-node.cpp

src/init/bitcoin-qt.cpp

src/init/bitcoin-wallet.cpp

src/init/bitcoind.cpp

src/init/common.h

src/interfaces/init.h

src/interfaces/ipc.h

src/logging/categories.h

src/logging/timer.h

src/net_permissions.h

src/netmessagemaker.h

src/node/chainstatemanager_args.cpp

src/node/connection_types.h

src/node/context.h

src/node/interface_ui.h

src/node/mempool_args.cpp

src/node/mining_args.cpp

src/node/minisketchwrapper.cpp

src/node/txreconciliation.h

src/node/warnings.h

src/outputtype.cpp

src/outputtype.h

src/policy/fees/estimator_args.cpp

src/policy/fees/estimator_args.h

src/policy/fees/estimator_man.cpp

src/policy/fees/estimator_man.h

src/policy/packages.h

src/policy/rbf.h

src/policy/truc_policy.h

src/primitives/block.cpp

src/randomenv.h

src/script/keyorigin.h

src/script/parsing.cpp

src/script/parsing.h

src/script/script_error.h

src/script/sigcache.cpp

src/script/sigcache.h

src/script/solver.h

src/script/verify_flags.h

src/semaphore_grant.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

src/uint256.cpp

src/util/bip32.cpp

src/util/fees.h

src/util/fs.cpp

src/util/result.h

src/util/string.cpp

src/util/tokenpipe.cpp

src/util/translation.h

src/util/vector.h

src/versionbits.h

src/versionbits_impl.h

src/wallet/external_signer_scriptpubkeyman.h

src/wallet/fees.h

src/wallet/load.h

src/wallet/receive.h

src/wallet/rpc/wallet.h

src/wallet/types.h

src/walletinitinterface.h

src/zmq/zmqabstractnotifier.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.