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.

36,118 bytes · SHA-256 fd2ced81edace3dc… · View upstream ↗

1// Copyright (c) 2020-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 <txrequest.h>
6
7#include <crypto/siphash.h>
8#include <net.h>
9#include <primitives/transaction.h>
10#include <random.h>
11#include <uint256.h>
12
13#include <boost/multi_index/indexed_by.hpp>
14#include <boost/multi_index/ordered_index.hpp>
15#include <boost/multi_index/sequenced_index.hpp>
16#include <boost/multi_index/tag.hpp>
17#include <boost/multi_index_container.hpp>
18#include <boost/tuple/tuple.hpp>
19
20#include <chrono>
21#include <unordered_map>
22#include <utility>
23
24#include <cassert>
25
26namespace {
27
28/** The various states a (txhash,peer) pair can be in.
29 *
30 * Note that CANDIDATE is split up into 3 substates (DELAYED, BEST, READY), allowing more efficient implementation.
31 * Also note that the sorting order of ByTxHashView relies on the specific order of values in this enum.
32 *
33 * Expected behaviour is:
34 *   - When first announced by a peer, the state is CANDIDATE_DELAYED until reqtime is reached.
35 *   - Announcements that have reached their reqtime but not been requested will be either CANDIDATE_READY or
36 *     CANDIDATE_BEST. Neither of those has an expiration time; they remain in that state until they're requested or
37 *     no longer needed. CANDIDATE_READY announcements are promoted to CANDIDATE_BEST when they're the best one left.
38 *   - When requested, an announcement will be in state REQUESTED until expiry is reached.
39 *   - If expiry is reached, or the peer replies to the request (either with NOTFOUND or the tx), the state becomes
40 *     COMPLETED.
41 */
42enum class State : uint8_t {
43    /** A CANDIDATE announcement whose reqtime is in the future. */
44    CANDIDATE_DELAYED,
45    /** A CANDIDATE announcement that's not CANDIDATE_DELAYED or CANDIDATE_BEST. */
46    CANDIDATE_READY,
47    /** The best CANDIDATE for a given txhash; only if there is no REQUESTED announcement already for that txhash.
48     *  The CANDIDATE_BEST is the highest-priority announcement among all CANDIDATE_READY (and _BEST) ones for that
49     *  txhash. */
50    CANDIDATE_BEST,
51    /** A REQUESTED announcement. */
52    REQUESTED,
53    /** A COMPLETED announcement. */
54    COMPLETED,
55};
56
57//! Type alias for sequence numbers.
58using SequenceNumber = uint64_t;
59
60/** An announcement. This is the data we track for each txid or wtxid that is announced to us by each peer. */
61struct Announcement {
62    /** Txid or wtxid that was announced. */
63    const GenTxid m_gtxid;
64    /** For CANDIDATE_{DELAYED,BEST,READY} the reqtime; for REQUESTED the expiry. */
65    std::chrono::microseconds m_time;
66    /** What peer the request was from. */
67    const NodeId m_peer;
68    /** What sequence number this announcement has. */
69    const SequenceNumber m_sequence : 59;
70    /** Whether the request is preferred. */
71    const bool m_preferred : 1;
72    /** What state this announcement is in. */
73    State m_state : 3 {State::CANDIDATE_DELAYED};
74    State GetState() const { return m_state; }
75    void SetState(State state) { m_state = state; }
76
77    /** Whether this announcement is selected. There can be at most 1 selected peer per txhash. */
78    bool IsSelected() const
79    {
80        return GetState() == State::CANDIDATE_BEST || GetState() == State::REQUESTED;
81    }
82
83    /** Whether this announcement is waiting for a certain time to pass. */
84    bool IsWaiting() const
85    {
86        return GetState() == State::REQUESTED || GetState() == State::CANDIDATE_DELAYED;
87    }
88
89    /** Whether this announcement can feasibly be selected if the current IsSelected() one disappears. */
90    bool IsSelectable() const
91    {
92        return GetState() == State::CANDIDATE_READY || GetState() == State::CANDIDATE_BEST;
93    }
94
95    /** Construct a new announcement from scratch, initially in CANDIDATE_DELAYED state. */
96    Announcement(const GenTxid& gtxid, NodeId peer, bool preferred, std::chrono::microseconds reqtime,
97                 SequenceNumber sequence)
98        : m_gtxid(gtxid), m_time(reqtime), m_peer(peer), m_sequence(sequence), m_preferred(preferred) {}
99};
100
101//! Type alias for priorities.
102using Priority = uint64_t;
103
104/** A functor with embedded salt that computes priority of an announcement.
105 *
106 * Higher priorities are selected first.
107 */
108class PriorityComputer {
109    const uint64_t m_k0, m_k1;
110public:
111    explicit PriorityComputer(bool deterministic) :
112        m_k0{deterministic ? 0 : FastRandomContext().rand64()},
113        m_k1{deterministic ? 0 : FastRandomContext().rand64()} {}
114
115    Priority operator()(const uint256& txhash, NodeId peer, bool preferred) const
116    {
117        uint64_t low_bits = CSipHasher(m_k0, m_k1).Write(txhash).Write(peer).Finalize() >> 1;
118        return low_bits | uint64_t{preferred} << 63;
119    }
120
121    Priority operator()(const Announcement& ann) const
122    {
123        return operator()(ann.m_gtxid.ToUint256(), ann.m_peer, ann.m_preferred);
124    }
125};
126
127// Definitions for the 3 indexes used in the main data structure.
128//
129// Each index has a By* type to identify it, a By*View data type to represent the view of announcement it is sorted
130// by, and an By*ViewExtractor type to convert an announcement into the By*View type.
131// See https://www.boost.org/doc/libs/1_58_0/libs/multi_index/doc/reference/key_extraction.html#key_extractors
132// for more information about the key extraction concept.
133
134// The ByPeer index is sorted by (peer, state == CANDIDATE_BEST, txhash)
135//
136// Uses:
137// * Looking up existing announcements by peer/txhash, by checking both (peer, false, txhash) and
138//   (peer, true, txhash).
139// * Finding all CANDIDATE_BEST announcements for a given peer in GetRequestable.
140struct ByPeer {};
141using ByPeerView = std::tuple<NodeId, bool, const uint256&>;
142struct ByPeerViewExtractor
143{
144    using result_type = ByPeerView;
145    result_type operator()(const Announcement& ann) const
146    {
147        return ByPeerView{ann.m_peer, ann.GetState() == State::CANDIDATE_BEST, ann.m_gtxid.ToUint256()};
148    }
149};
150
151// The ByTxHash index is sorted by (txhash, state, priority).
152//
153// Note: priority == 0 whenever state != CANDIDATE_READY.
154//
155// Uses:
156// * Deleting all announcements with a given txhash in ForgetTxHash.
157// * Finding the best CANDIDATE_READY to convert to CANDIDATE_BEST, when no other CANDIDATE_READY or REQUESTED
158//   announcement exists for that txhash.
159// * Determining when no more non-COMPLETED announcements for a given txhash exist, so the COMPLETED ones can be
160//   deleted.
161struct ByTxHash {};
162using ByTxHashView = std::tuple<const uint256&, State, Priority>;
163class ByTxHashViewExtractor {
164    const PriorityComputer& m_computer;
165public:
166    explicit ByTxHashViewExtractor(const PriorityComputer& computer) : m_computer(computer) {}
167    using result_type = ByTxHashView;
168    result_type operator()(const Announcement& ann) const
169    {
170        const Priority prio = (ann.GetState() == State::CANDIDATE_READY) ? m_computer(ann) : 0;
171        return ByTxHashView{ann.m_gtxid.ToUint256(), ann.GetState(), prio};
172    }
173};
174
175enum class WaitState {
176    //! Used for announcements that need efficient testing of "is their timestamp in the future?".
177    FUTURE_EVENT,
178    //! Used for announcements whose timestamp is not relevant.
179    NO_EVENT,
180    //! Used for announcements that need efficient testing of "is their timestamp in the past?".
181    PAST_EVENT,
182};
183
184WaitState GetWaitState(const Announcement& ann)
185{
186    if (ann.IsWaiting()) return WaitState::FUTURE_EVENT;
187    if (ann.IsSelectable()) return WaitState::PAST_EVENT;
188    return WaitState::NO_EVENT;
189}
190
191// The ByTime index is sorted by (wait_state, time).
192//
193// All announcements with a timestamp in the future can be found by iterating the index forward from the beginning.
194// All announcements with a timestamp in the past can be found by iterating the index backwards from the end.
195//
196// Uses:
197// * Finding CANDIDATE_DELAYED announcements whose reqtime has passed, and REQUESTED announcements whose expiry has
198//   passed.
199// * Finding CANDIDATE_READY/BEST announcements whose reqtime is in the future (when the clock time went backwards).
200struct ByTime {};
201using ByTimeView = std::pair<WaitState, std::chrono::microseconds>;
202struct ByTimeViewExtractor
203{
204    using result_type = ByTimeView;
205    result_type operator()(const Announcement& ann) const
206    {
207        return ByTimeView{GetWaitState(ann), ann.m_time};
208    }
209};
210
211
212/** Data type for the main data structure (Announcement objects with ByPeer/ByTxHash/ByTime indexes). */
213using Index = boost::multi_index_container<
214    Announcement,
215    boost::multi_index::indexed_by<
216        boost::multi_index::ordered_unique<boost::multi_index::tag<ByPeer>, ByPeerViewExtractor>,
217        boost::multi_index::ordered_non_unique<boost::multi_index::tag<ByTxHash>, ByTxHashViewExtractor>,
218        boost::multi_index::ordered_non_unique<boost::multi_index::tag<ByTime>, ByTimeViewExtractor>
219    >
220>;
221
222/** Helper type to simplify syntax of iterator types. */
223template<typename Tag>
224using Iter = typename Index::index<Tag>::type::iterator;
225
226/** Per-peer statistics object. */
227struct PeerInfo {
228    size_t m_total = 0; //!< Total number of announcements for this peer.
229    size_t m_completed = 0; //!< Number of COMPLETED announcements for this peer.
230    size_t m_requested = 0; //!< Number of REQUESTED announcements for this peer.
231};
232
233/** Per-txhash statistics object. Only used for sanity checking. */
234struct TxHashInfo
235{
236    //! Number of CANDIDATE_DELAYED announcements for this txhash.
237    size_t m_candidate_delayed = 0;
238    //! Number of CANDIDATE_READY announcements for this txhash.
239    size_t m_candidate_ready = 0;
240    //! Number of CANDIDATE_BEST announcements for this txhash (at most one).
241    size_t m_candidate_best = 0;
242    //! Number of REQUESTED announcements for this txhash (at most one; mutually exclusive with CANDIDATE_BEST).
243    size_t m_requested = 0;
244    //! The priority of the CANDIDATE_BEST announcement if one exists, or max() otherwise.
245    Priority m_priority_candidate_best = std::numeric_limits<Priority>::max();
246    //! The highest priority of all CANDIDATE_READY announcements (or min() if none exist).
247    Priority m_priority_best_candidate_ready = std::numeric_limits<Priority>::min();
248    //! All peers we have an announcement for this txhash for.
249    std::vector<NodeId> m_peers;
250};

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.