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 server340 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.

15,260 bytes · SHA-256 bc61319b39e993d0… · 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#include <headerssync.h>
6
7#include <pow.h>
8#include <util/check.h>
9#include <util/log.h>
10#include <util/time.h>
11#include <util/vector.h>
12
13// Our memory analysis in headerssync-params.py assumes this many bytes for a
14// CompressedHeader (we should re-calculate parameters if we compress further).
15static_assert(sizeof(CompressedHeader) == 48);
16
17HeadersSyncState::HeadersSyncState(NodeId id,
18                                   const Consensus::Params& consensus_params,
19                                   const HeadersSyncParams& params,
20                                   const CBlockIndex& chain_start,
21                                   const arith_uint256& minimum_required_work)
22    : m_commit_offset((assert(params.commitment_period > 0), // HeadersSyncParams field must be initialized to non-zero.
23                       FastRandomContext().randrange(params.commitment_period))),
24      m_id(id),
25      m_consensus_params(consensus_params),
26      m_params(params),
27      m_chain_start(chain_start),
28      m_minimum_required_work(minimum_required_work),
29      m_current_chain_work(chain_start.nChainWork),
30      m_last_header_received(m_chain_start.GetBlockHeader()),
31      m_current_height(chain_start.nHeight)
32{
33    // Estimate the number of blocks that could possibly exist on the peer's
34    // chain *right now* using 6 blocks/second (fastest blockrate given the MTP
35    // rule) times the number of seconds from the last allowed block until
36    // today. This serves as a memory bound on how many commitments we might
37    // store from this peer, and we can safely give up syncing if the peer
38    // exceeds this bound, because it's not possible for a consensus-valid
39    // chain to be longer than this (at the current time -- in the future we
40    // could try again, if necessary, to sync a longer chain).
41    const auto now{NodeClock::now()};
42    const int64_t max_seconds_since_start{Ticks<std::chrono::seconds>(now - NodeSeconds{std::chrono::seconds{chain_start.GetMedianTimePast()}})
43                                          + MAX_FUTURE_BLOCK_TIME};
44    if (max_seconds_since_start < 0) {
45        throw SystemClockError{strprintf(
46            "System clock is more than %d minutes behind chain start MTP (%s vs %s).",
47            MAX_FUTURE_BLOCK_TIME / 60,
48            FormatISO8601DateTime(TicksSinceEpoch<std::chrono::seconds>(now)),
49            FormatISO8601DateTime(chain_start.GetMedianTimePast()))};
50    }
51    m_max_commitments = 6 * max_seconds_since_start / m_params.commitment_period;
52
53    LogDebug(BCLog::NET, "Initial headers sync started with peer=%d: height=%i, max_commitments=%i, min_work=%s\n", m_id, m_current_height, m_max_commitments, m_minimum_required_work.ToString());
54}
55
56/** Free any memory in use, and mark this object as no longer usable. This is
57 * required to guarantee that we won't reuse this object with the same
58 * SaltedUint256Hasher for another sync. */
59void HeadersSyncState::Finalize()
60{
61    Assume(m_download_state != State::FINAL);
62    ClearShrink(m_header_commitments);
63    m_last_header_received.SetNull();
64    ClearShrink(m_redownloaded_headers);
65    m_redownload_buffer_last_hash.SetNull();
66    m_redownload_buffer_first_prev_hash.SetNull();
67    m_process_all_remaining_headers = false;
68    m_current_height = 0;
69
70    m_download_state = State::FINAL;
71}
72
73/** Process the next batch of headers received from our peer.
74 *  Validate and store commitments, and compare total chainwork to our target to
75 *  see if we can switch to REDOWNLOAD mode.  */
76HeadersSyncState::ProcessingResult HeadersSyncState::ProcessNextHeaders(
77        std::span<const CBlockHeader> received_headers, const bool full_headers_message)
78{
79    ProcessingResult ret;
80
81    Assume(!received_headers.empty());
82    if (received_headers.empty()) return ret;
83
84    Assume(m_download_state != State::FINAL);
85    if (m_download_state == State::FINAL) return ret;
86
87    if (m_download_state == State::PRESYNC) {
88        // During PRESYNC, we minimally validate block headers and
89        // occasionally add commitments to them, until we reach our work
90        // threshold (at which point m_download_state is updated to REDOWNLOAD).
91        ret.success = ValidateAndStoreHeadersCommitments(received_headers);
92        if (ret.success) {
93            if (full_headers_message || m_download_state == State::REDOWNLOAD) {
94                // A full headers message means the peer may have more to give us;
95                // also if we just switched to REDOWNLOAD then we need to re-request
96                // headers from the beginning.
97                ret.request_more = true;
98            } else {
99                Assume(m_download_state == State::PRESYNC);
100                // If we're in PRESYNC and we get a non-full headers
101                // message, then the peer's chain has ended and definitely doesn't
102                // have enough work, so we can stop our sync.
103                LogDebug(BCLog::NET, "Initial headers sync aborted with peer=%d: incomplete headers message at height=%i (presync phase)\n", m_id, m_current_height);
104            }
105        }
106    } else if (m_download_state == State::REDOWNLOAD) {
107        // During REDOWNLOAD, we compare our stored commitments to what we
108        // receive, and add headers to our redownload buffer. When the buffer
109        // gets big enough (meaning that we've checked enough commitments),
110        // we'll return a batch of headers to the caller for processing.
111        ret.success = true;
112        for (const auto& hdr : received_headers) {
113            if (!ValidateAndStoreRedownloadedHeader(hdr)) {
114                // Something went wrong -- the peer gave us an unexpected chain.
115                // We could consider looking at the reason for failure and
116                // punishing the peer, but for now just give up on sync.
117                ret.success = false;
118                break;
119            }
120        }
121
122        if (ret.success) {
123            // Return any headers that are ready for acceptance.
124            ret.pow_validated_headers = PopHeadersReadyForAcceptance();
125
126            // If we hit our target blockhash, then all remaining headers will be
127            // returned and we can clear any leftover internal state.
128            if (m_redownloaded_headers.empty() && m_process_all_remaining_headers) {
129                LogDebug(BCLog::NET, "Initial headers sync complete with peer=%d: releasing all at height=%i (redownload phase)\n", m_id, m_redownload_buffer_last_height);
130            } else if (full_headers_message) {
131                // If the headers message is full, we need to request more.
132                ret.request_more = true;
133            } else {
134                // For some reason our peer gave us a high-work chain, but is now
135                // declining to serve us that full chain again. Give up.
136                // Note that there's no more processing to be done with these
137                // headers, so we can still return success.
138                LogDebug(BCLog::NET, "Initial headers sync aborted with peer=%d: incomplete headers message at height=%i (redownload phase)\n", m_id, m_redownload_buffer_last_height);
139            }
140        }
141    }
142
143    if (!(ret.success && ret.request_more)) Finalize();
144    return ret;
145}
146
147bool HeadersSyncState::ValidateAndStoreHeadersCommitments(std::span<const CBlockHeader> headers)
148{
149    // The caller should not give us an empty set of headers.
150    Assume(headers.size() > 0);
151    if (headers.size() == 0) return true;
152
153    Assume(m_download_state == State::PRESYNC);
154    if (m_download_state != State::PRESYNC) return false;
155
156    if (headers[0].hashPrevBlock != m_last_header_received.GetHash()) {
157        // Somehow our peer gave us a header that doesn't connect.
158        // This might be benign -- perhaps our peer reorged away from the chain
159        // they were on. Give up on this sync for now (likely we will start a
160        // new sync with a new starting point).
161        LogDebug(BCLog::NET, "Initial headers sync aborted with peer=%d: non-continuous headers at height=%i (presync phase)\n", m_id, m_current_height);
162        return false;
163    }
164
165    // If it does connect, (minimally) validate and occasionally store
166    // commitments.
167    for (const auto& hdr : headers) {
168        if (!ValidateAndProcessSingleHeader(hdr)) {
169            return false;
170        }
171    }
172
173    if (m_current_chain_work >= m_minimum_required_work) {
174        m_redownloaded_headers.clear();
175        m_redownload_buffer_last_height = m_chain_start.nHeight;
176        m_redownload_buffer_first_prev_hash = m_chain_start.GetBlockHash();
177        m_redownload_buffer_last_hash = m_chain_start.GetBlockHash();
178        m_redownload_chain_work = m_chain_start.nChainWork;
179        m_download_state = State::REDOWNLOAD;
180        LogDebug(BCLog::NET, "Initial headers sync transition with peer=%d: reached sufficient work at height=%i, redownloading from height=%i\n", m_id, m_current_height, m_redownload_buffer_last_height);
181    }
182    return true;
183}
184
185bool HeadersSyncState::ValidateAndProcessSingleHeader(const CBlockHeader& current)
186{
187    Assume(m_download_state == State::PRESYNC);
188    if (m_download_state != State::PRESYNC) return false;
189
190    int next_height = m_current_height + 1;
191
192    // Verify that the difficulty isn't growing too fast; an adversary with
193    // limited hashing capability has a greater chance of producing a high
194    // work chain if they compress the work into as few blocks as possible,
195    // so don't let anyone give a chain that would violate the difficulty
196    // adjustment maximum.
197    if (!PermittedDifficultyTransition(m_consensus_params, next_height,
198                m_last_header_received.nBits, current.nBits)) {
199        LogDebug(BCLog::NET, "Initial headers sync aborted with peer=%d: invalid difficulty transition at height=%i (presync phase)\n", m_id, next_height);
200        return false;
201    }
202
203    if (next_height % m_params.commitment_period == m_commit_offset) {
204        // Add a commitment.
205        m_header_commitments.push_back(m_hasher(current.GetHash()) & 1);
206        if (m_header_commitments.size() > m_max_commitments) {
207            // The peer's chain is too long; give up.
208            // It's possible the chain grew since we started the sync; so
209            // potentially we could succeed in syncing the peer's chain if we
210            // try again later.
211            LogDebug(BCLog::NET, "Initial headers sync aborted with peer=%d: exceeded max commitments at height=%i (presync phase)\n", m_id, next_height);
212            return false;
213        }
214    }
215
216    m_current_chain_work += GetBlockProof(current);
217    m_last_header_received = current;
218    m_current_height = next_height;
219
220    return true;
221}
222
223bool HeadersSyncState::ValidateAndStoreRedownloadedHeader(const CBlockHeader& header)
224{
225    Assume(m_download_state == State::REDOWNLOAD);
226    if (m_download_state != State::REDOWNLOAD) return false;
227
228    int64_t next_height = m_redownload_buffer_last_height + 1;
229
230    // Ensure that we're working on a header that connects to the chain we're
231    // downloading.
232    if (header.hashPrevBlock != m_redownload_buffer_last_hash) {
233        LogDebug(BCLog::NET, "Initial headers sync aborted with peer=%d: non-continuous headers at height=%i (redownload phase)\n", m_id, next_height);
234        return false;
235    }
236
237    // Check that the difficulty adjustments are within our tolerance:
238    uint32_t previous_nBits{0};
239    if (!m_redownloaded_headers.empty()) {
240        previous_nBits = m_redownloaded_headers.back().nBits;
241    } else {
242        previous_nBits = m_chain_start.nBits;
243    }
244
245    if (!PermittedDifficultyTransition(m_consensus_params, next_height,
246                previous_nBits, header.nBits)) {
247        LogDebug(BCLog::NET, "Initial headers sync aborted with peer=%d: invalid difficulty transition at height=%i (redownload phase)\n", m_id, next_height);
248        return false;
249    }
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

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.