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.

11,877 bytes · SHA-256 60485439e8fcee7a… · View upstream ↗

1// Copyright (c) 2022-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#ifndef BITCOIN_HEADERSSYNC_H
6#define BITCOIN_HEADERSSYNC_H
7
8#include <arith_uint256.h>
9#include <chain.h>
10#include <consensus/params.h>
11#include <net.h>
12#include <primitives/block.h>
13#include <uint256.h>
14#include <util/bitdeque.h>
15#include <util/hasher.h>
16
17#include <deque>
18#include <stdexcept>
19#include <vector>
20
21// A compressed CBlockHeader, which leaves out the prevhash
22struct CompressedHeader {
23    // header
24    int32_t nVersion{0};
25    uint256 hashMerkleRoot;
26    uint32_t nTime{0};
27    uint32_t nBits{0};
28    uint32_t nNonce{0};
29
30    CompressedHeader()
31    {
32        hashMerkleRoot.SetNull();
33    }
34
35    explicit CompressedHeader(const CBlockHeader& header)
36        : nVersion{header.nVersion},
37          hashMerkleRoot{header.hashMerkleRoot},
38          nTime{header.nTime},
39          nBits{header.nBits},
40          nNonce{header.nNonce}
41    {
42    }
43
44    CBlockHeader GetFullHeader(const uint256& hash_prev_block) const
45    {
46        CBlockHeader ret;
47        ret.nVersion = nVersion;
48        ret.hashPrevBlock = hash_prev_block;
49        ret.hashMerkleRoot = hashMerkleRoot;
50        ret.nTime = nTime;
51        ret.nBits = nBits;
52        ret.nNonce = nNonce;
53        return ret;
54    };
55};
56
57/** HeadersSyncState:
58 *
59 * We wish to download a peer's headers chain in a DoS-resistant way.
60 *
61 * The Bitcoin protocol does not offer an easy way to determine the work on a
62 * peer's chain. Currently, we can query a peer's headers by using a GETHEADERS
63 * message, and our peer can return a set of up to 2000 headers that connect to
64 * something we know. If a peer's chain has more than 2000 blocks, then we need
65 * a way to verify that the chain actually has enough work on it to be useful to
66 * us -- by being above our anti-DoS minimum-chain-work threshold -- before we
67 * commit to storing those headers in memory. Otherwise, it would be cheap for
68 * an attacker to waste all our memory by serving us low-work headers
69 * (particularly for a new node coming online for the first time).
70 *
71 * To prevent memory-DoS with low-work headers, while still always being
72 * able to reorg to whatever the most-work chain is, we require that a chain
73 * meet a work threshold before committing it to memory. We can do this by
74 * downloading a peer's headers twice, whenever we are not sure that the chain
75 * has sufficient work:
76 *
77 * - In the first download phase, called pre-synchronization, we can calculate
78 * the work on the chain as we go (just by checking the nBits value on each
79 * header, and validating the proof-of-work).
80 *
81 * - Once we have reached a header where the cumulative chain work is
82 * sufficient, we switch to downloading the headers a second time, this time
83 * processing them fully, and possibly storing them in memory.
84 *
85 * To prevent an attacker from using (eg) the honest chain to convince us that
86 * they have a high-work chain, but then feeding us an alternate set of
87 * low-difficulty headers in the second phase, we store commitments to the
88 * chain we see in the first download phase that we check in the second phase,
89 * as follows:
90 *
91 * - In phase 1 (presync), store 1 bit (using a salted hash function) for every
92 * N headers that we see. With a reasonable choice of N, this uses relatively
93 * little memory even for a very long chain.
94 *
95 * - In phase 2 (redownload), keep a lookahead buffer and only accept headers
96 * from that buffer into the block index (permanent memory usage) once they
97 * have some target number of verified commitments on top of them. With this
98 * parametrization, we can achieve a given security target for potential
99 * permanent memory usage, while choosing N to minimize memory use during the
100 * sync (temporary, per-peer storage).
101 */
102
103class HeadersSyncState
104{
105public:
106    struct SystemClockError : std::runtime_error {
107        using std::runtime_error::runtime_error;
108    };
109
110    ~HeadersSyncState() = default;
111
112    enum class State {
113        /** PRESYNC means the peer has not yet demonstrated their chain has
114         * sufficient work and we're only building commitments to the chain they
115         * serve us. */
116        PRESYNC,
117        /** REDOWNLOAD means the peer has given us a high-enough-work chain,
118         * and now we're redownloading the headers we saw before and trying to
119         * accept them */
120        REDOWNLOAD,
121        /** We're done syncing with this peer and can discard any remaining state */
122        FINAL
123    };
124
125    /** Return the current state of our download */
126    State GetState() const { return m_download_state; }
127
128    /** Return the height reached during the PRESYNC phase */
129    int64_t GetPresyncHeight() const { return m_current_height; }
130
131    /** Return the block timestamp of the last header received during the PRESYNC phase. */
132    uint32_t GetPresyncTime() const { return m_last_header_received.nTime; }
133
134    /** Return the amount of work in the chain received during the PRESYNC phase. */
135    arith_uint256 GetPresyncWork() const { return m_current_chain_work; }
136
137    /** Construct a HeadersSyncState object representing a headers sync via this
138     *  download-twice mechanism).
139     *
140     * id: node id (for logging)
141     * consensus_params: parameters needed for difficulty adjustment validation
142     * chain_start: best known fork point that the peer's headers branch from
143     * minimum_required_work: amount of chain work required to accept the chain
144     *
145     * @throws SystemClockError if system clock is too far behind chain_start MTP.
146     */
147    HeadersSyncState(NodeId id, const Consensus::Params& consensus_params,
148                     const HeadersSyncParams& params, const CBlockIndex& chain_start,
149                     const arith_uint256& minimum_required_work);
150
151    /** Result data structure for ProcessNextHeaders. */
152    struct ProcessingResult {
153        std::vector<CBlockHeader> pow_validated_headers;
154        bool success{false};
155        bool request_more{false};
156    };
157
158    /** Process a batch of headers, once a sync via this mechanism has started
159     *
160     * received_headers: headers that were received over the network for processing.
161     *                   Assumes the caller has already verified the headers
162     *                   are continuous, and has checked that each header
163     *                   satisfies the proof-of-work target included in the
164     *                   header (but not necessarily verified that the
165     *                   proof-of-work target is correct and passes consensus
166     *                   rules).
167     * full_headers_message: true if the message was at max capacity,
168     *                       indicating more headers may be available
169     * ProcessingResult.pow_validated_headers: will be filled in with any
170     *                       headers that the caller can fully process and
171     *                       validate now (because these returned headers are
172     *                       on a chain with sufficient work)
173     * ProcessingResult.success: set to false if an error is detected and the sync is
174     *                       aborted; true otherwise.
175     * ProcessingResult.request_more: if true, the caller is suggested to call
176     *                       NextHeadersRequestLocator and send a getheaders message using it.
177     */
178    ProcessingResult ProcessNextHeaders(std::span<const CBlockHeader>
179            received_headers, bool full_headers_message);
180
181    /** Issue the next GETHEADERS message to our peer.
182     *
183     * This will return a locator appropriate for the current sync object, to continue the
184     * synchronization phase it is in.
185     */
186    CBlockLocator NextHeadersRequestLocator() const;
187
188protected:
189    /** The (secret) offset on the heights for which to create commitments.
190     *
191     * m_header_commitments entries are created at any height h for which
192     * (h % m_params.commitment_period) == m_commit_offset. */
193    const size_t m_commit_offset;
194
195private:
196    /** Clear out all download state that might be in progress (freeing any used
197     * memory), and mark this object as no longer usable.
198     */
199    void Finalize();
200
201    /**
202     *  Only called in PRESYNC.
203     *  Validate the work on the headers we received from the network, and
204     *  store commitments for later. Update overall state with successfully
205     *  processed headers.
206     *  On failure, this invokes Finalize() and returns false.
207     */
208    bool ValidateAndStoreHeadersCommitments(std::span<const CBlockHeader> headers);
209
210    /** In PRESYNC, process and update state for a single header */
211    bool ValidateAndProcessSingleHeader(const CBlockHeader& current);
212
213    /** In REDOWNLOAD, check a header's commitment (if applicable) and add to
214     * buffer for later processing */
215    bool ValidateAndStoreRedownloadedHeader(const CBlockHeader& header);
216
217    /** Return a set of headers that satisfy our proof-of-work threshold */
218    std::vector<CBlockHeader> PopHeadersReadyForAcceptance();
219
220private:
221    /** NodeId of the peer (used for log messages) **/
222    const NodeId m_id;
223
224    /** We use the consensus params in our anti-DoS calculations */
225    const Consensus::Params& m_consensus_params;
226
227    /** Parameters that impact memory usage for a given chain, especially when attacked. */
228    const HeadersSyncParams m_params;
229
230    /** Store the last block in our block index that the peer's chain builds from */
231    const CBlockIndex& m_chain_start;
232
233    /** Minimum work that we're looking for on this chain. */
234    const arith_uint256 m_minimum_required_work;
235
236    /** Work that we've seen so far on the peer's chain */
237    arith_uint256 m_current_chain_work;
238
239    /** m_hasher is a salted hasher for making our 1-bit commitments to headers we've seen. */
240    const SaltedUint256Hasher m_hasher;
241
242    /** A queue of commitment bits, created during the 1st phase, and verified during the 2nd. */
243    bitdeque<> m_header_commitments;
244
245    /** m_max_commitments is a bound we calculate on how long an honest peer's chain could be,
246     * given the MTP rule.
247     *
248     * Any peer giving us more headers than this will have its sync aborted. This serves as a
249     * memory bound on m_header_commitments. */
250    uint64_t m_max_commitments{0};

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.