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.

13,176 bytes · SHA-256 3b7d2bb4ac628a40… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2019-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
6""" Test node outbound peer eviction logic
7
8A subset of our outbound peers are subject to eviction logic if they cannot keep up
9with our vision of the best chain. This criteria applies only to non-protected peers,
10and can be triggered by either not learning about any blocks from an outbound peer after
11a certain deadline, or by them not being able to catch up fast enough (under the same deadline).
12
13This tests the different eviction paths based on the peer's behavior and on whether they are protected
14or not.
15"""
16import time
17
18from test_framework.messages import (
19    from_hex,
20    msg_headers,
21    CBlockHeader,
22)
23from test_framework.p2p import P2PInterface
24from test_framework.test_framework import BitcoinTestFramework
25
26# Timeouts (in seconds)
27CHAIN_SYNC_TIMEOUT = 20 * 60
28HEADERS_RESPONSE_TIME = 2 * 60
29
30
31class P2POutEvict(BitcoinTestFramework):
32    def set_test_params(self):
33        self.num_nodes = 1
34
35    def test_outbound_eviction_unprotected(self):
36        # This tests the eviction logic for **unprotected** outbound peers (that is, PeerManagerImpl::ConsiderEviction)
37        node = self.nodes[0]
38        cur_mock_time = node.mocktime
39
40        # Get our tip header and its parent
41        tip_header = from_hex(CBlockHeader(), node.getblockheader(node.getbestblockhash(), False))
42        prev_header = from_hex(CBlockHeader(), node.getblockheader(f"{tip_header.hashPrevBlock:064x}", False))
43
44        self.log.info("Create an outbound connection and don't send any headers")
45        # Test disconnect due to no block being announced in 22+ minutes (headers are not even exchanged)
46        peer = node.add_outbound_p2p_connection(P2PInterface(), p2p_idx=0, connection_type="outbound-full-relay")
47        # Wait for over 20 min to trigger the first eviction timeout. This sets the last call past 2 min in the future.
48        cur_mock_time += (CHAIN_SYNC_TIMEOUT + 1)
49        node.setmocktime(cur_mock_time)
50        peer.sync_with_ping()
51        # Wait for over 2 more min to trigger the disconnection
52        peer.wait_for_getheaders(block_hash=tip_header.hashPrevBlock)
53        cur_mock_time += (HEADERS_RESPONSE_TIME + 1)
54        node.setmocktime(cur_mock_time)
55        self.log.info("Test that the peer gets evicted")
56        peer.wait_for_disconnect()
57
58        self.log.info("Create an outbound connection and send header but the peer never catches up")
59        # Mimic a node that just falls behind for long enough
60        # This should also apply for a node doing IBD that does not catch up in time
61        # Connect a peer and make it send us headers ending in our tip's parent
62        peer = node.add_outbound_p2p_connection(P2PInterface(), p2p_idx=0, connection_type="outbound-full-relay")
63        peer.send_and_ping(msg_headers([prev_header]))
64
65        # Trigger the timeouts
66        cur_mock_time += (CHAIN_SYNC_TIMEOUT + 1)
67        node.setmocktime(cur_mock_time)
68        peer.sync_with_ping()
69        peer.wait_for_getheaders(block_hash=tip_header.hashPrevBlock)
70        cur_mock_time += (HEADERS_RESPONSE_TIME + 1)
71        node.setmocktime(cur_mock_time)
72        self.log.info("Test that the peer gets evicted")
73        peer.wait_for_disconnect()
74
75        self.log.info("Create an outbound connection and keep lagging behind, but not too much")
76        # Test that if the peer never catches up with our current tip, but it does with the
77        # expected work that we set when setting the timer (that is, our tip at the time)
78        # the node does not disconnect the peer
79        peer = node.add_outbound_p2p_connection(P2PInterface(), p2p_idx=0, connection_type="outbound-full-relay")
80
81        self.log.info("Mine a block so our peer starts lagging")
82        prev_prev_hash = tip_header.hashPrevBlock
83        best_block_hash = self.generateblock(node, output="raw(42)", transactions=[])["hash"]
84        peer.sync_with_ping()
85
86        self.log.info("The peer keeps catching up with the old tip; check that the node does not evict the peer")
87        for i in range(10):
88            # Generate an additional block so the peers is 2 blocks behind
89            prev_header = from_hex(CBlockHeader(), node.getblockheader(best_block_hash, False))
90            best_block_hash = self.generateblock(node, output="raw(42)", transactions=[])["hash"]
91            tip_header = from_hex(CBlockHeader(), node.getblockheader(best_block_hash, False))
92            peer.sync_with_ping()
93
94            # Advance time but not enough to evict the peer
95            cur_mock_time += (CHAIN_SYNC_TIMEOUT + 1)
96            node.setmocktime(cur_mock_time)
97            peer.sync_with_ping()
98
99            # Make the peer wait until it gets node's last call (by receiving a getheaders)
100            peer.wait_for_getheaders(block_hash=prev_prev_hash)
101
102            # The peer sends a header with the previous tip (so the peer goes back to 1 block behind)
103            peer.send_and_ping(msg_headers([prev_header]))
104            prev_prev_hash = tip_header.hashPrevBlock
105
106        self.log.info("Create an outbound connection and take some time to catch up, but do it in time")
107        # Check that if the peer manages to catch up within time, the timeouts are removed (and the peer is not disconnected)
108        # We are reusing the peer from the previous case which already sent the node a valid (but old) block and whose timer is ticking
109
110        # Make the peer send an updated headers message matching our tip
111        peer.send_and_ping(msg_headers([from_hex(CBlockHeader(), node.getblockheader(best_block_hash, False))]))
112
113        # Wait for long enough for the timeouts to have triggered and check that the peer is still connected
114        cur_mock_time += (CHAIN_SYNC_TIMEOUT + 1)
115        node.setmocktime(cur_mock_time)
116        peer.sync_with_ping()
117        cur_mock_time += (HEADERS_RESPONSE_TIME + 1)
118        node.setmocktime(cur_mock_time)
119        self.log.info("Test that the peer does not get evicted")
120        peer.sync_with_ping()
121
122        node.disconnect_p2ps()
123
124    def test_outbound_eviction_protected(self):
125        # This tests the eviction logic for **protected** outbound peers (that is, PeerManagerImpl::ConsiderEviction)
126        # Outbound connections are flagged as protected if:
127        #   - The peer sends a connecting block with at least as much work as our current tip.
128        #   - There are still available slots in the node's protected_peers list.
129        # This test ensures that such protected outbound peers are not disconnected even after chain sync and headers timeouts.
130        node = self.nodes[0]
131        cur_mock_time = node.mocktime
132        tip_header = from_hex(CBlockHeader(), node.getblockheader(node.getbestblockhash(), False))
133
134        self.log.info("Create an outbound connection to a peer that shares our tip so it gets granted protection")
135        peer = node.add_outbound_p2p_connection(P2PInterface(), p2p_idx=0, connection_type="outbound-full-relay")
136        peer.send_and_ping(msg_headers([tip_header]))
137
138        self.log.info("Mine a new block and sync with our peer")
139        self.generateblock(node, output="raw(42)", transactions=[])
140        peer.sync_with_ping()
141
142        self.log.info("Let enough time pass for the timeouts to go off")
143        # Trigger the timeouts and check how we are still connected
144        cur_mock_time += (CHAIN_SYNC_TIMEOUT + 1)
145        node.setmocktime(cur_mock_time)
146        peer.sync_with_ping()
147        peer.wait_for_getheaders(block_hash=tip_header.hashPrevBlock)
148        cur_mock_time += (HEADERS_RESPONSE_TIME + 1)
149        node.setmocktime(cur_mock_time)
150        self.log.info("Test that the peer does not get evicted")
151        peer.sync_with_ping()
152
153        node.disconnect_p2ps()
154
155    def test_outbound_eviction_mixed(self):
156        # This tests the outbound eviction logic for a mix of protected and unprotected peers.
157        node = self.nodes[0]
158        cur_mock_time = node.mocktime
159
160        self.log.info("Create a mix of protected and unprotected outbound connections to check against eviction")
161
162        # Let's try this logic having multiple peers, some protected and some unprotected
163        # We protect up to 4 peers as long as they have provided a block with the same amount of work as our tip
164        self.log.info("The first 4 peers are protected by sending us a valid block with enough work")
165        tip_header = from_hex(CBlockHeader(), node.getblockheader(node.getbestblockhash(), False))
166        headers_message = msg_headers([tip_header])
167        protected_peers = []
168        for i in range(4):
169            peer = node.add_outbound_p2p_connection(P2PInterface(), p2p_idx=i, connection_type="outbound-full-relay")
170            peer.send_and_ping(headers_message)
171            protected_peers.append(peer)
172
173        # We can create 4 additional outbound connections to peers that are unprotected. 2 of them will be well behaved,
174        # whereas the other 2 will misbehave (1 sending no headers, 1 sending old ones)
175        self.log.info("The remaining 4 peers will be mixed between honest (2) and misbehaving peers (2)")
176        prev_header = from_hex(CBlockHeader(), node.getblockheader(f"{tip_header.hashPrevBlock:064x}", False))
177        headers_message = msg_headers([prev_header])
178        honest_unprotected_peers = []
179        for i in range(2):
180            peer = node.add_outbound_p2p_connection(P2PInterface(), p2p_idx=4+i, connection_type="outbound-full-relay")
181            peer.send_and_ping(headers_message)
182            honest_unprotected_peers.append(peer)
183
184        misbehaving_unprotected_peers = []
185        for i in range(2):
186            peer = node.add_outbound_p2p_connection(P2PInterface(), p2p_idx=6+i, connection_type="outbound-full-relay")
187            if i%2==0:
188                peer.send_and_ping(headers_message)
189            misbehaving_unprotected_peers.append(peer)
190
191        self.log.info("Mine a new block and keep the unprotected honest peer on sync, all the rest off-sync")
192        # Mine a block so all peers become outdated
193        target_hash = prev_header.hash_int
194        tip_hash = self.generateblock(node, output="raw(42)", transactions=[])["hash"]
195        tip_header = from_hex(CBlockHeader(), node.getblockheader(tip_hash, False))
196        tip_headers_message = msg_headers([tip_header])
197
198        # Let the timeouts hit and check back
199        cur_mock_time += (CHAIN_SYNC_TIMEOUT + 1)
200        node.setmocktime(cur_mock_time)
201        for peer in protected_peers + misbehaving_unprotected_peers:
202            peer.sync_with_ping()
203            peer.wait_for_getheaders(block_hash=target_hash)
204        for peer in honest_unprotected_peers:
205            peer.send_and_ping(tip_headers_message)
206            peer.wait_for_getheaders(block_hash=target_hash)
207
208        cur_mock_time += (HEADERS_RESPONSE_TIME + 1)
209        node.setmocktime(cur_mock_time)
210        self.log.info("Check that none of the honest or protected peers were evicted, but all misbehaving unprotected peers were")
211        for peer in protected_peers + honest_unprotected_peers:
212            peer.sync_with_ping()
213        for peer in misbehaving_unprotected_peers:
214            peer.wait_for_disconnect()
215
216        node.disconnect_p2ps()
217
218    def test_outbound_eviction_blocks_relay_only(self):
219        # The logic for outbound eviction protection only applies to outbound-full-relay peers
220        # This tests that other types of peers (blocks-relay-only for instance) are not granted protection
221        node = self.nodes[0]
222        cur_mock_time = node.mocktime
223        tip_header = from_hex(CBlockHeader(), node.getblockheader(node.getbestblockhash(), False))
224
225        self.log.info("Create an blocks-only outbound connection to a peer that shares our tip. This would usually grant protection")
226        peer = node.add_outbound_p2p_connection(P2PInterface(), p2p_idx=0, connection_type="block-relay-only")
227        peer.send_and_ping(msg_headers([tip_header]))
228
229        self.log.info("Mine a new block and sync with our peer")
230        self.generateblock(node, output="raw(42)", transactions=[])
231        peer.sync_with_ping()
232
233        self.log.info("Let enough time pass for the timeouts to go off")
234        # Trigger the timeouts and check how the peer gets evicted, since protection is only given to outbound-full-relay peers
235        cur_mock_time += (CHAIN_SYNC_TIMEOUT + 1)
236        node.setmocktime(cur_mock_time)
237        peer.sync_with_ping()
238        peer.wait_for_getheaders(block_hash=tip_header.hash_int)
239        cur_mock_time += (HEADERS_RESPONSE_TIME + 1)
240        node.setmocktime(cur_mock_time)
241        self.log.info("Test that the peer gets evicted")
242        peer.wait_for_disconnect()
243
244        node.disconnect_p2ps()
245
246
247    def run_test(self):
248        self.nodes[0].setmocktime(int(time.time()))
249        self.test_outbound_eviction_unprotected()
250        self.test_outbound_eviction_protected()

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.