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.

14,257 bytes · SHA-256 56ad30ce3e8127d0… · View upstream ↗

1// Copyright (c) 2017-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#include <addresstype.h>
6#include <chain.h>
7#include <chainparams.h>
8#include <common/args.h>
9#include <consensus/amount.h>
10#include <consensus/validation.h>
11#include <crypto/hex_base.h>
12#include <dbwrapper.h>
13#include <flatfile.h>
14#include <index/disktxpos.h>
15#include <index/txindex.h>
16#include <index/txindex_key.h>
17#include <interfaces/chain.h>
18#include <key.h>
19#include <node/blockstorage.h>
20#include <primitives/block.h>
21#include <script/script.h>
22#include <streams.h>
23#include <sync.h>
24#include <test/util/setup_common.h>
25#include <util/byte_units.h>
26#include <util/check.h>
27#include <util/strencodings.h>
28#include <validation.h>
29
30#include <cstdint>
31#include <memory>
32#include <string>
33#include <string_view>
34#include <utility>
35#include <vector>
36
37#include <boost/test/unit_test.hpp>
38
39BOOST_AUTO_TEST_SUITE(txindex_tests)
40
41// Grants tests access to the otherwise non-public txindex database handle.
42class TxIndexTest
43{
44public:
45    static CDBWrapper& GetDB(const TxIndex& txindex) { return txindex.GetDB(); }
46    static CBlockLocator ReadBestBlock(const TxIndex& txindex) { return txindex.GetDB().ReadBestBlock(); }
47    static void WriteBestBlock(const TxIndex& txindex, const CBlockLocator& locator)
48    {
49        auto& db{txindex.GetDB()};
50        CDBBatch batch{db};
51        db.WriteBestBlock(batch, locator);
52        db.WriteBatch(batch);
53    }
54};
55
56namespace {
57
58SipHasher13UJ ReadHasher(const CDBWrapper& db)
59{
60    std::pair<uint64_t, uint64_t> salt;
61    BOOST_REQUIRE(db.Read(txindex::DB_TXID_HASH_SALT, salt));
62    return SipHasher13UJ{salt.first, salt.second};
63}
64
65std::vector<txindex::BlockTxPosition> BucketPositions(CDBWrapper& db, txindex::TxHashKeyPrefix prefix)
66{
67    std::vector<txindex::BlockTxPosition> positions;
68    std::unique_ptr<CDBIterator> it{db.NewIterator()};
69    txindex::DBKey key{prefix, {}};
70    for (it->Seek(key); it->Valid() && it->GetKey(key) && key.hash_prefix == prefix; it->Next()) {
71        positions.push_back(key.pos);
72    }
73    return positions;
74}
75
76FlatFilePos BlockFilePos(const ChainstateManager& chainman, uint32_t height)
77{
78    LOCK(cs_main);
79    const CBlockIndex* block_index{chainman.ActiveChain()[height]};
80    BOOST_REQUIRE(block_index);
81    return {block_index->nFile, block_index->nDataPos};
82}
83
84uint256 LookupTx(const TxIndex& txindex, const Txid& txid)
85{
86    const auto result{txindex.FindTx(txid)};
87    BOOST_REQUIRE(result);
88    BOOST_CHECK(result->tx->GetHash() == txid);
89    return result->block_hash;
90}
91
92void InvalidateBlock(ChainstateManager& chainman, const uint256& block_hash)
93{
94    CBlockIndex* block_index{WITH_LOCK(cs_main, return chainman.m_blockman.LookupBlockIndex(block_hash))};
95    BOOST_REQUIRE(block_index);
96    BlockValidationState state;
97    BOOST_REQUIRE(chainman.ActiveChainstate().InvalidateBlock(state, block_index));
98}
99
100} // namespace
101
102BOOST_AUTO_TEST_CASE(txindex_position_encoding)
103{
104    constexpr struct { txindex::BlockTxPosition position; std::string_view encoded; } test_vectors[]{
105        {{0, 0}, "00000000"},
106        {{1, 2}, "01000002"},
107        {{10'000'000, 123}, "83e1ac0000007b"},
108        {{456, 3'999'999}, "82483d08ff"},
109    };
110
111    for (const auto& [position, encoded] : test_vectors) {
112        BOOST_CHECK_EQUAL(HexStr(DataStream{} << position), encoded);
113
114        txindex::BlockTxPosition decoded;
115        BOOST_CHECK((DataStream{ParseHex(encoded)} >> decoded).empty());
116        BOOST_CHECK(decoded == position);
117    }
118
119    // Pin the full key encodings, including the type prefixes.
120    BOOST_CHECK_EQUAL(HexStr(DataStream{} << txindex::BlockSeqKey{1}), "7301");
121    BOOST_CHECK_EQUAL(HexStr(DataStream{} << txindex::DBKey{0x0102030405, {1, 2}}),
122                      "78010203040501000002");
123
124    BOOST_CHECK_EQUAL(txindex::BLOCK_HEADER_SIZE, GetSerializeSize(CBlockHeader{}));
125}
126
127BOOST_AUTO_TEST_CASE(txindex_hash_prefix)
128{
129    BOOST_CHECK_EQUAL(
130        txindex::CreateKeyPrefix(
131            SipHasher13UJ{0x0706050403020100ULL, 0x0F0E0D0C0B0A0908ULL},
132            Txid{"1f1e1d1c1b1a191817161514131211100f0e0d0c0b0a09080706050403020100"}),
133        0xc67d87b08cULL);
134}
135
136BOOST_FIXTURE_TEST_CASE(txindex_initial_sync, TestChain100Setup)
137{
138    TxIndex txindex(interfaces::MakeChain(m_node), /*n_cache_size=*/1_MiB, /*f_memory=*/true);
139    BOOST_REQUIRE(txindex.Init());
140
141    // Transaction should not be found in the index before it is started.
142    for (const auto& txn : m_coinbase_txns) {
143        BOOST_CHECK(!txindex.FindTx(txn->GetHash()));
144    }
145
146    // BlockUntilSyncedToCurrentChain should return false before txindex is started.
147    BOOST_CHECK(!txindex.BlockUntilSyncedToCurrentChain());
148
149    txindex.Sync();
150
151    // Check that txindex excludes genesis block transactions.
152    const CBlock& genesis_block = Params().GenesisBlock();
153    for (const auto& txn : genesis_block.vtx) {
154        BOOST_CHECK(!txindex.FindTx(txn->GetHash()));
155    }
156
157    // Check that txindex has all txs that were in the chain before it started.
158    for (const auto& txn : m_coinbase_txns) {
159        LookupTx(txindex, txn->GetHash());
160    }
161
162    // Check that new transactions in new blocks make it into the index.
163    for (int i = 0; i < 10; i++) {
164        CScript coinbase_script_pub_key = GetScriptForDestination(PKHash(coinbaseKey.GetPubKey()));
165        std::vector<CMutableTransaction> no_txns;
166        const CBlock& block = CreateAndProcessBlock(no_txns, coinbase_script_pub_key);
167        const CTransaction& txn = *block.vtx[0];
168
169        BOOST_CHECK(txindex.BlockUntilSyncedToCurrentChain());
170        LookupTx(txindex, txn.GetHash());
171    }
172
173    // shutdown sequence (c.f. Shutdown() in init.cpp)
174    txindex.Stop();
175}
176
177BOOST_FIXTURE_TEST_CASE(txindex_collision_scan_path, TestChain100Setup)
178{
179    // On-disk, so the legacy-entry probe at construction runs against a fresh
180    // database, as it would on a node whose index was created by this version.
181    TxIndex txindex(interfaces::MakeChain(m_node), /*n_cache_size=*/1_MiB, /*f_memory=*/false);
182    BOOST_REQUIRE(txindex.Init());
183    txindex.Sync();
184
185    CDBWrapper& db{TxIndexTest::GetDB(txindex)};
186    const SipHasher13UJ hasher{ReadHasher(db)};
187
188    // Lookups scan candidates in descending sequence order, so entries of
189    // later-connected blocks are tried first. Forge a colliding entry under the
190    // first coinbase's prefix pointing at the last coinbase, so looking up the
191    // first tx must scan that false positive first.
192    const Txid fake_txid{m_coinbase_txns.back()->GetHash()};
193    const Txid target_txid{m_coinbase_txns.front()->GetHash()};
194    const auto fake_prefix{txindex::CreateKeyPrefix(hasher, fake_txid)};
195    const auto target_prefix{txindex::CreateKeyPrefix(hasher, target_txid)};
196    // Distinct prefixes guarantee the target's bucket initially holds only the target.
197    BOOST_REQUIRE(fake_prefix != target_prefix);
198
199    // Read the last coinbase's encoded position straight from its bucket.
200    const auto fake_bucket{BucketPositions(db, fake_prefix)};
201    BOOST_REQUIRE_EQUAL(fake_bucket.size(), 1U);
202    const txindex::BlockTxPosition fake_pos{fake_bucket.front()};
203
204    db.Write(txindex::DBKey{target_prefix, fake_pos}, txindex::EMPTY_VALUE);
205
206    // The target's bucket now holds the real target first (lower sequence
207    // number), then the forged false positive, which the descending scan tries first.
208    const auto target_bucket{BucketPositions(db, target_prefix)};
209    BOOST_REQUIRE_EQUAL(target_bucket.size(), 2U);
210    BOOST_CHECK(target_bucket[0] != fake_pos);
211    BOOST_CHECK(target_bucket[1] == fake_pos);
212
213    LookupTx(txindex, target_txid);
214
215    // A database created fresh by this version cannot contain legacy entries, so
216    // lookups skip the legacy fallback: drop the last coinbase's hashed entry and
217    // re-add it under the old 't' + txid schema (a physical CDiskTxPos), then
218    // confirm the lookup misses even though the legacy row exists.
219    // BlockTxPosition offsets are from the block start (header included), while
220    // the legacy CDiskTxPos.nTxOffset is measured after the header.
221    const CDiskTxPos fake_physical{BlockFilePos(*m_node.chainman, fake_pos.block_seq + 1), fake_pos.tx_offset_in_block - txindex::BLOCK_HEADER_SIZE};
222    db.Erase(txindex::DBKey{fake_prefix, fake_pos});
223    db.Write(txindex::LegacyTxKey(fake_txid), fake_physical);
224    BOOST_CHECK(!txindex.FindTx(fake_txid));
225
226    txindex.Stop();
227}
228
229BOOST_FIXTURE_TEST_CASE(txindex_legacy_fallback, TestChain100Setup)
230{
231    // Seed the on-disk database with a legacy ('t' + txid) entry before the index
232    // is opened, as if it had been written by a pre-hashing version.
233    const Txid legacy_txid{m_coinbase_txns.front()->GetHash()};
234    // The block at height 1 holds only the coinbase, so the tx starts right after
235    // the header and the 1-byte tx count.
236    const CDiskTxPos legacy_pos{BlockFilePos(*m_node.chainman, 1), 1};
237    {
238        CDBWrapper db{DBParams{.path = gArgs.GetDataDirNet() / "indexes" / "txindex", .cache_bytes = 1_MiB}};
239        db.Write(txindex::LegacyTxKey(legacy_txid), legacy_pos);
240    }
241
242    TxIndex txindex(interfaces::MakeChain(m_node), /*n_cache_size=*/1_MiB, /*f_memory=*/false);
243    BOOST_REQUIRE(txindex.Init());
244    txindex.Sync();
245
246    // Drop the hashed entries so only the legacy row remains, then confirm the
247    // lookup succeeds through the fallback.
248    CDBWrapper& db{TxIndexTest::GetDB(txindex)};
249    const auto prefix{txindex::CreateKeyPrefix(ReadHasher(db), legacy_txid)};
250    const auto bucket{BucketPositions(db, prefix)};

src/wallet/receive.cpp

src/wallet/coinselection.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/init.cpp

src/crypto/sha256.cpp

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/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.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/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/rpc/util.h

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/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/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/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.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/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/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

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/key_io.h

src/logging/categories.h

src/logging/timer.h

src/mapport.h

src/musig.h

src/net_permissions.h

src/netgroup.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/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/pow.h

src/primitives/block.cpp

src/randomenv.h

src/rest.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/signet.h

src/span.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

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.