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.

25,377 bytes · SHA-256 c78eb820c5979df9… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2014-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 behavior of headers messages to announce blocks.
6
7Setup:
8
9- Two nodes:
10    - node0 is the node-under-test. We create two p2p connections to it. The
11      first p2p connection is a control and should only ever receive inv's. The
12      second p2p connection tests the headers sending logic.
13    - node1 is used to create reorgs.
14
15test_null_locators
16==================
17
18Sends two getheaders requests with null locator values. First request's hashstop
19value refers to validated block, while second request's hashstop value refers to
20a block which hasn't been validated. Verifies only the first request returns
21headers.
22
23test_nonnull_locators
24=====================
25
26Part 1: No headers announcements before "sendheaders"
27a. node mines a block [expect: inv]
28   send getdata for the block [expect: block]
29b. node mines another block [expect: inv]
30   send getheaders and getdata [expect: headers, then block]
31c. node mines another block [expect: inv]
32   peer mines a block, announces with header [expect: getdata]
33d. node mines another block [expect: inv]
34
35Part 2: After "sendheaders", headers announcements should generally work.
36a. peer sends sendheaders [expect: no response]
37   peer sends getheaders with current tip [expect: no response]
38b. node mines a block [expect: tip header]
39c. for N in 1, ..., 10:
40   * for announce-type in {inv, header}
41     - peer mines N blocks, announces with announce-type
42       [ expect: getheaders/getdata or getdata, deliver block(s) ]
43     - node mines a block [ expect: 1 header ]
44
45Part 3: Headers announcements stop after large reorg and resume after getheaders or inv from peer.
46- For response-type in {inv, getheaders}
47  * node mines a 7 block reorg [ expect: headers announcement of 8 blocks ]
48  * node mines an 8-block reorg [ expect: inv at tip ]
49  * peer responds with getblocks/getdata [expect: inv, blocks ]
50  * node mines another block [ expect: inv at tip, peer sends getdata, expect: block ]
51  * node mines another block at tip [ expect: inv ]
52  * peer responds with getheaders with an old hashstop more than 8 blocks back [expect: headers]
53  * peer requests block [ expect: block ]
54  * node mines another block at tip [ expect: inv, peer sends getdata, expect: block ]
55  * peer sends response-type [expect headers if getheaders, getheaders/getdata if mining new block]
56  * node mines 1 block [expect: 1 header, peer responds with getdata]
57
58Part 4: Test direct fetch behavior
59a. Announce 2 old block headers.
60   Expect: no getdata requests.
61b. Announce 3 new blocks via 1 headers message.
62   Expect: one getdata request for all 3 blocks.
63   (Send blocks.)
64c. Announce 1 header that forks off the last two blocks.
65   Expect: no response.
66d. Announce 1 more header that builds on that fork.
67   Expect: one getdata request for two blocks.
68e. Announce 16 more headers that build on that fork.
69   Expect: getdata request for 14 more blocks.
70f. Announce 1 more header that builds on that fork.
71   Expect: no response.
72
73Part 5: Test handling of headers that don't connect.
74a. Repeat 100 times:
75   1. Announce a header that doesn't connect.
76      Expect: getheaders message
77   2. Send headers chain.
78      Expect: getdata for the missing blocks, tip update.
79b. Then send 99 more headers that don't connect.
80   Expect: getheaders message each time.
81"""
82from test_framework.blocktools import create_block
83from test_framework.messages import CInv
84from test_framework.p2p import (
85    CBlockHeader,
86    NODE_WITNESS,
87    P2PInterface,
88    p2p_lock,
89    MSG_BLOCK,
90    msg_block,
91    msg_getblocks,
92    msg_getdata,
93    msg_getheaders,
94    msg_headers,
95    msg_inv,
96    msg_sendheaders,
97)
98from test_framework.test_framework import BitcoinTestFramework
99from test_framework.util import (
100    assert_equal,
101)
102
103DIRECT_FETCH_RESPONSE_TIME = 0.05
104
105class BaseNode(P2PInterface):
106    def __init__(self):
107        super().__init__()
108
109        self.block_announced = False
110        self.last_blockhash_announced = None
111        self.recent_headers_announced = []
112
113    def send_get_data(self, block_hashes):
114        """Request data for a list of block hashes."""
115        msg = msg_getdata()
116        for x in block_hashes:
117            msg.inv.append(CInv(MSG_BLOCK, x))
118        self.send_without_ping(msg)
119
120    def send_get_headers(self, locator, hashstop):
121        msg = msg_getheaders()
122        msg.locator.vHave = locator
123        msg.hashstop = hashstop
124        self.send_without_ping(msg)
125
126    def send_block_inv(self, blockhash):
127        msg = msg_inv()
128        msg.inv = [CInv(MSG_BLOCK, blockhash)]
129        self.send_without_ping(msg)
130
131    def send_header_for_blocks(self, new_blocks):
132        headers_message = msg_headers()
133        headers_message.headers = [CBlockHeader(b) for b in new_blocks]
134        self.send_without_ping(headers_message)
135
136    def send_getblocks(self, locator):
137        getblocks_message = msg_getblocks()
138        getblocks_message.locator.vHave = locator
139        self.send_without_ping(getblocks_message)
140
141    def wait_for_block_announcement(self, block_hash, timeout=60):
142        def test_function():
143            return self.last_blockhash_announced == block_hash
144
145        self.wait_until(test_function, timeout=timeout)
146
147    def on_inv(self, message):
148        self.block_announced = True
149        self.last_blockhash_announced = message.inv[-1].hash
150
151    def on_headers(self, message):
152        if len(message.headers):
153            self.block_announced = True
154            for x in message.headers:
155                # append because headers may be announced over multiple messages.
156                self.recent_headers_announced.append(x.hash_int)
157            self.last_blockhash_announced = message.headers[-1].hash_int
158
159    def clear_block_announcements(self):
160        with p2p_lock:
161            self.block_announced = False
162            self.last_message.pop("inv", None)
163            self.last_message.pop("headers", None)
164            self.recent_headers_announced = []
165
166
167    def check_last_headers_announcement(self, headers):
168        """Test whether the last headers announcements received are right.
169           Headers may be announced across more than one message."""
170        def test_function():
171            return len(self.recent_headers_announced) >= len(headers)
172
173        self.wait_until(test_function)
174        with p2p_lock:
175            assert_equal(self.recent_headers_announced, headers)
176            self.block_announced = False
177            self.last_message.pop("headers", None)
178            self.recent_headers_announced = []
179
180    def check_last_inv_announcement(self, inv):
181        """Test whether the last announcement received had the right inv.
182        inv should be a list of block hashes."""
183
184        def test_function():
185            return self.block_announced
186
187        self.wait_until(test_function)
188
189        with p2p_lock:
190            compare_inv = []
191            if "inv" in self.last_message:
192                compare_inv = [x.hash for x in self.last_message["inv"].inv]
193            assert_equal(compare_inv, inv)
194            self.block_announced = False
195            self.last_message.pop("inv", None)
196
197class SendHeadersTest(BitcoinTestFramework):
198    def set_test_params(self):
199        self.setup_clean_chain = True
200        self.num_nodes = 2
201
202    def mine_blocks(self, count):
203        """Mine count blocks and return the new tip."""
204
205        # Clear out block announcements from each p2p listener
206        [x.clear_block_announcements() for x in self.nodes[0].p2ps]
207        self.generatetoaddress(self.nodes[0], count, self.nodes[0].get_deterministic_priv_key().address)
208        return int(self.nodes[0].getbestblockhash(), 16)
209
210    def mine_reorg(self, length):
211        """Mine a reorg that invalidates length blocks (replacing them with # length+1 blocks).
212
213        Note: we clear the state of our p2p connections after the
214        to-be-reorged-out blocks are mined, so that we don't break later tests.
215        return the list of block hashes newly mined."""
216
217        # make sure all invalidated blocks are node0's
218        self.generatetoaddress(self.nodes[0], length, self.nodes[0].get_deterministic_priv_key().address)
219        for x in self.nodes[0].p2ps:
220            x.wait_for_block_announcement(int(self.nodes[0].getbestblockhash(), 16))
221            x.clear_block_announcements()
222
223        tip_height = self.nodes[1].getblockcount()
224        hash_to_invalidate = self.nodes[1].getblockhash(tip_height - (length - 1))
225        self.nodes[1].invalidateblock(hash_to_invalidate)
226        all_hashes = self.generatetoaddress(self.nodes[1], length + 1, self.nodes[1].get_deterministic_priv_key().address)  # Must be longer than the orig chain
227        return [int(x, 16) for x in all_hashes]
228
229    def run_test(self):
230        # Setup the p2p connections
231        inv_node = self.nodes[0].add_p2p_connection(BaseNode())
232        # Make sure NODE_NETWORK is not set for test_node, so no block download
233        # will occur outside of direct fetching
234        test_node = self.nodes[0].add_p2p_connection(BaseNode(), services=NODE_WITNESS)
235
236        self.test_null_locators(test_node, inv_node)
237        self.test_nonnull_locators(test_node, inv_node)
238
239    def test_null_locators(self, test_node, inv_node):
240        tip = self.nodes[0].getblockheader(self.generatetoaddress(self.nodes[0], 1, self.nodes[0].get_deterministic_priv_key().address)[0])
241        tip_hash = int(tip["hash"], 16)
242
243        inv_node.check_last_inv_announcement(inv=[tip_hash])
244        test_node.check_last_inv_announcement(inv=[tip_hash])
245
246        self.log.info("Verify getheaders with null locator and valid hashstop returns headers.")
247        test_node.clear_block_announcements()
248        test_node.send_get_headers(locator=[], hashstop=tip_hash)
249        test_node.check_last_headers_announcement(headers=[tip_hash])
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.