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.

7,730 bytes · SHA-256 e3e083d5b1d58136… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2022-present The Bitcoin Core developers
3# Distributed under the MIT software license, see the accompanying
4# file COPYING or http://www.opensource.org/licenses/mit-license.php.
5"""Test initial headers download and timeout behavior
6
7Test that we only try to initially sync headers from one peer (until our chain
8is close to caught up), and that each block announcement results in only one
9additional peer receiving a getheaders message.
10
11Also test peer timeout during initial headers sync, including normal peer
12disconnection vs noban peer behavior.
13"""
14
15from test_framework.test_framework import BitcoinTestFramework
16from test_framework.messages import (
17    CInv,
18    MSG_BLOCK,
19    msg_headers,
20    msg_inv,
21)
22from test_framework.p2p import (
23    p2p_lock,
24    P2PInterface,
25)
26from test_framework.util import (
27    assert_equal,
28)
29import math
30import random
31import time
32
33# Constants from net_processing
34HEADERS_DOWNLOAD_TIMEOUT_BASE_SEC = 15 * 60
35HEADERS_DOWNLOAD_TIMEOUT_PER_HEADER_MS = 1
36POW_TARGET_SPACING_SEC = 10 * 60
37
38
39def calculate_headers_timeout(best_header_time, current_time):
40    seconds_since_best_header = current_time - best_header_time
41    # Using ceil ensures the calculated timeout is >= actual timeout and not lower
42    # because of precision loss from conversion to seconds
43    variable_timeout_sec = math.ceil(HEADERS_DOWNLOAD_TIMEOUT_PER_HEADER_MS / 1_000 *
44                                     seconds_since_best_header / POW_TARGET_SPACING_SEC)
45    return int(current_time + HEADERS_DOWNLOAD_TIMEOUT_BASE_SEC + variable_timeout_sec)
46
47
48class HeadersSyncTest(BitcoinTestFramework):
49    def set_test_params(self):
50        self.setup_clean_chain = True
51        self.num_nodes = 1
52
53    def announce_random_block(self, peers):
54        new_block_announcement = msg_inv(inv=[CInv(MSG_BLOCK, random.randrange(1<<256))])
55        for p in peers:
56            p.send_and_ping(new_block_announcement)
57
58    def assert_single_getheaders_recipient(self, peers):
59        count = 0
60        receiving_peer = None
61        for p in peers:
62            with p2p_lock:
63                if "getheaders" in p.last_message:
64                    count += 1
65                    receiving_peer = p
66        assert_equal(count, 1)
67        return receiving_peer
68
69    def test_initial_headers_sync(self):
70        self.log.info("Test initial headers sync")
71
72        self.log.info("Adding a peer to node0")
73        peer1 = self.nodes[0].add_p2p_connection(P2PInterface())
74        best_block_hash = int(self.nodes[0].getbestblockhash(), 16)
75
76        # Wait for peer1 to receive a getheaders
77        peer1.wait_for_getheaders(block_hash=best_block_hash)
78        # An empty reply will clear the outstanding getheaders request,
79        # allowing additional getheaders requests to be sent to this peer in
80        # the future.
81        peer1.send_without_ping(msg_headers())
82
83        self.log.info("Connecting two more peers to node0")
84        # Connect 2 more peers; they should not receive a getheaders yet
85        peer2 = self.nodes[0].add_p2p_connection(P2PInterface())
86        peer3 = self.nodes[0].add_p2p_connection(P2PInterface())
87
88        all_peers = [peer1, peer2, peer3]
89
90        self.log.info("Verify that peer2 and peer3 don't receive a getheaders after connecting")
91        for p in all_peers:
92            p.sync_with_ping()
93        with p2p_lock:
94            assert "getheaders" not in peer2.last_message
95            assert "getheaders" not in peer3.last_message
96
97        self.log.info("Have all peers announce a new block")
98        self.announce_random_block(all_peers)
99
100        self.log.info("Check that peer1 receives a getheaders in response")
101        peer1.wait_for_getheaders(block_hash=best_block_hash)
102        peer1.send_without_ping(msg_headers()) # Send empty response, see above
103
104        self.log.info("Check that exactly 1 of {peer2, peer3} received a getheaders in response")
105        peer_receiving_getheaders = self.assert_single_getheaders_recipient([peer2, peer3])
106        peer_receiving_getheaders.send_without_ping(msg_headers()) # Send empty response, see above
107
108        self.log.info("Announce another new block, from all peers")
109        self.announce_random_block(all_peers)
110
111        self.log.info("Check that peer1 receives a getheaders in response")
112        peer1.wait_for_getheaders(block_hash=best_block_hash)
113
114        self.log.info("Check that the remaining peer received a getheaders as well")
115        expected_peer = peer2
116        if peer2 == peer_receiving_getheaders:
117            expected_peer = peer3
118
119        expected_peer.wait_for_getheaders(block_hash=best_block_hash)
120
121    def setup_timeout_test_peers(self):
122        self.log.info("Add peer1 and check it receives an initial getheaders request")
123        node = self.nodes[0]
124        with node.assert_debug_log(expected_msgs=["initial getheaders (0) to peer=0"]):
125            peer1 = node.add_p2p_connection(P2PInterface())
126            peer1.wait_for_getheaders(block_hash=int(node.getbestblockhash(), 16))
127
128        self.log.info("Add outbound peer2")
129        # This peer has to be outbound otherwise the stalling peer is
130        # protected from disconnection
131        peer2 = node.add_outbound_p2p_connection(P2PInterface(), p2p_idx=1, connection_type="outbound-full-relay")
132
133        assert_equal(node.num_test_p2p_connections(), 2)
134        return peer1, peer2
135
136    def trigger_headers_timeout(self):
137        self.log.info("Trigger the headers download timeout by advancing mock time")
138        # The node has not received any headers from peers yet
139        # So the best header time is the genesis block time
140        best_header_time = self.nodes[0].getblockchaininfo()["time"]
141        current_time = self.nodes[0].mocktime
142        timeout = calculate_headers_timeout(best_header_time, current_time)
143        # The calculated timeout above is always >= actual timeout, but we still need
144        # +1 to trigger the timeout when both values are equal
145        self.nodes[0].setmocktime(timeout + 1)
146
147    def test_normal_peer_timeout(self):
148        self.log.info("Test peer disconnection on header timeout")
149        self.restart_node(0)
150        self.nodes[0].setmocktime(int(time.time()))
151        peer1, peer2 = self.setup_timeout_test_peers()
152
153        with self.nodes[0].assert_debug_log(["Timeout downloading headers, disconnecting peer=0"]):
154            self.trigger_headers_timeout()
155
156            self.log.info("Check that stalling peer1 is disconnected")
157            peer1.wait_for_disconnect()
158            assert_equal(self.nodes[0].num_test_p2p_connections(), 1)
159
160        self.log.info("Check that peer2 receives a getheaders request")
161        peer2.wait_for_getheaders(block_hash=int(self.nodes[0].getbestblockhash(), 16))
162
163    def test_noban_peer_timeout(self):
164        self.log.info("Test noban peer on header timeout")
165        self.restart_node(0, extra_args=['[email protected]'])
166        self.nodes[0].setmocktime(int(time.time()))
167        peer1, peer2 = self.setup_timeout_test_peers()
168
169        with self.nodes[0].assert_debug_log(["Timeout downloading headers from noban peer, not disconnecting peer=0"]):
170            self.trigger_headers_timeout()
171
172            self.log.info("Check that noban peer1 is not disconnected")
173            peer1.sync_with_ping()
174            assert_equal(self.nodes[0].num_test_p2p_connections(), 2)
175
176        self.log.info("Check that exactly 1 of {peer1, peer2} receives a getheaders")
177        self.assert_single_getheaders_recipient([peer1, peer2])
178
179    def run_test(self):
180        self.test_initial_headers_sync()
181        self.test_normal_peer_timeout()
182        self.test_noban_peer_timeout()
183
184
185if __name__ == '__main__':
186    HeadersSyncTest(__file__).main()
187

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.