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.

20,768 bytes · SHA-256 ea2dfb7826e7907a… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2017-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 the listsinceblock RPC."""
6
7from test_framework.address import key_to_p2wpkh
8from test_framework.blocktools import COINBASE_MATURITY
9from test_framework.descriptors import descsum_create
10from test_framework.test_framework import BitcoinTestFramework
11from test_framework.messages import MAX_BIP125_RBF_SEQUENCE
12from test_framework.util import (
13    assert_array_result,
14    assert_equal,
15    assert_raises_rpc_error,
16    wallet_importprivkey,
17)
18from test_framework.wallet_util import generate_keypair
19
20from decimal import Decimal
21
22class ListSinceBlockTest(BitcoinTestFramework):
23    def set_test_params(self):
24        self.num_nodes = 4
25        self.setup_clean_chain = True
26        # whitelist peers to speed up tx relay / mempool sync
27        self.noban_tx_relay = True
28
29    def skip_test_if_missing_module(self):
30        self.skip_if_no_wallet()
31
32    def run_test(self):
33        # All nodes are in IBD from genesis, so they'll need the miner (node2) to be an outbound connection, or have
34        # only one connection. (See fPreferredDownload in net_processing)
35        self.connect_nodes(1, 2)
36        self.generate(self.nodes[2], COINBASE_MATURITY + 1)
37
38        self.test_no_blockhash()
39        self.test_invalid_blockhash()
40        self.test_reorg()
41        self.test_cant_read_block()
42        self.test_double_spend()
43        self.test_double_send()
44        self.double_spends_filtered()
45        self.test_targetconfirmations()
46        self.test_desc()
47        self.test_send_to_self()
48        self.test_op_return()
49        self.test_label()
50
51    def test_no_blockhash(self):
52        self.log.info("Test no blockhash")
53        txid = self.nodes[2].sendtoaddress(self.nodes[0].getnewaddress(), 1)
54        self.sync_all()
55        assert_array_result(self.nodes[0].listtransactions(), {"txid": txid}, {
56            "category": "receive",
57            "amount": 1,
58            "confirmations": 0,
59            "trusted": False,
60        })
61
62        blockhash, = self.generate(self.nodes[2], 1)
63        blockheight = self.nodes[2].getblockheader(blockhash)['height']
64
65        txs = self.nodes[0].listtransactions()
66        assert_array_result(txs, {"txid": txid}, {
67            "category": "receive",
68            "amount": 1,
69            "blockhash": blockhash,
70            "blockheight": blockheight,
71            "confirmations": 1,
72        })
73        assert_equal(len(txs), 1)
74        assert "trusted" not in txs[0]
75
76        assert_equal(
77            self.nodes[0].listsinceblock(),
78            {"lastblock": blockhash,
79             "removed": [],
80             "transactions": txs})
81        assert_equal(
82            self.nodes[0].listsinceblock(""),
83            {"lastblock": blockhash,
84             "removed": [],
85             "transactions": txs})
86
87    def test_invalid_blockhash(self):
88        self.log.info("Test invalid blockhash")
89        assert_raises_rpc_error(-5, "Block not found", self.nodes[0].listsinceblock,
90                                "42759cde25462784395a337460bde75f58e73d3f08bd31fdc3507cbac856a2c4")
91        assert_raises_rpc_error(-5, "Block not found", self.nodes[0].listsinceblock,
92                                "0000000000000000000000000000000000000000000000000000000000000000")
93        assert_raises_rpc_error(-8, "blockhash must be of length 64 (not 11, for 'invalid-hex')", self.nodes[0].listsinceblock,
94                                "invalid-hex")
95        assert_raises_rpc_error(-8, "blockhash must be hexadecimal string (not 'Z000000000000000000000000000000000000000000000000000000000000000')", self.nodes[0].listsinceblock,
96                                "Z000000000000000000000000000000000000000000000000000000000000000")
97
98    def test_targetconfirmations(self):
99        '''
100        This tests when the value of target_confirmations exceeds the number of
101        blocks in the main chain. In this case, the genesis block hash should be
102        given for the `lastblock` property. If target_confirmations is < 1, then
103        a -8 invalid parameter error is thrown.
104        '''
105        self.log.info("Test target_confirmations")
106        blockhash, = self.generate(self.nodes[2], 1)
107        blockheight = self.nodes[2].getblockheader(blockhash)['height']
108
109        assert_equal(
110            self.nodes[0].getblockhash(0),
111            self.nodes[0].listsinceblock(blockhash, blockheight + 1)['lastblock'])
112        assert_equal(
113            self.nodes[0].getblockhash(0),
114            self.nodes[0].listsinceblock(blockhash, blockheight + 1000)['lastblock'])
115        assert_raises_rpc_error(-8, "Invalid parameter",
116            self.nodes[0].listsinceblock, blockhash, 0)
117
118    def test_reorg(self):
119        '''
120        `listsinceblock` did not behave correctly when handed a block that was
121        no longer in the main chain:
122
123             ab0
124          /       \
125        aa1 [tx0]   bb1
126         |           |
127        aa2         bb2
128         |           |
129        aa3         bb3
130                     |
131                    bb4
132
133        Consider a client that has only seen block `aa3` above. It asks the node
134        to `listsinceblock aa3`. But at some point prior the main chain switched
135        to the bb chain.
136
137        Previously: listsinceblock would find height=4 for block aa3 and compare
138        this to height=5 for the tip of the chain (bb4). It would then return
139        results restricted to bb3-bb4.
140
141        Now: listsinceblock finds the fork at ab0 and returns results in the
142        range bb1-bb4.
143
144        This test only checks that [tx0] is present.
145        '''
146        self.log.info("Test reorg")
147
148        # Split network into two
149        self.split_network()
150
151        # send to nodes[0] from nodes[2]
152        senttx = self.nodes[2].sendtoaddress(self.nodes[0].getnewaddress(), 1)
153
154        # generate on both sides
155        nodes1_last_blockhash = self.generate(self.nodes[1], 6, sync_fun=lambda: self.sync_all(self.nodes[:2]))[-1]
156        nodes2_first_blockhash = self.generate(self.nodes[2], 7, sync_fun=lambda: self.sync_all(self.nodes[2:]))[0]
157        self.log.debug("nodes[1] last blockhash = {}".format(nodes1_last_blockhash))
158        self.log.debug("nodes[2] first blockhash = {}".format(nodes2_first_blockhash))
159
160        self.join_network()
161
162        # listsinceblock(nodes1_last_blockhash) should now include tx as seen from nodes[0]
163        # and return the block height which listsinceblock now exposes since a5e7795.
164        transactions = self.nodes[0].listsinceblock(nodes1_last_blockhash)['transactions']
165        found = next(tx for tx in transactions if tx['txid'] == senttx)
166        assert_equal(found['blockheight'], self.nodes[0].getblockheader(nodes2_first_blockhash)['height'])
167
168    def test_cant_read_block(self):
169        self.log.info('Test the RPC error "Can\'t read block from disk"')
170
171        # Split network into two
172        self.split_network()
173
174        # generate on both sides
175        nodes1_last_blockhash = self.generate(self.nodes[1], 6, sync_fun=lambda: self.sync_all(self.nodes[:2]))[-1]
176        self.generate(self.nodes[2], 7, sync_fun=lambda: self.sync_all(self.nodes[2:]))[0]
177
178        self.join_network()
179
180        # Renaming the block file to induce unsuccessful block read
181        blk_dat = (self.nodes[0].blocks_path / "blk00000.dat")
182        blk_dat_moved = blk_dat.rename(self.nodes[0].blocks_path / "blk00000.dat.moved")
183        assert not blk_dat.exists()
184
185        # listsinceblock(nodes1_last_blockhash) should now fail as blocks are not accessible
186        assert_raises_rpc_error(-32603, "Can't read block from disk",
187            self.nodes[0].listsinceblock, nodes1_last_blockhash)
188
189        # Restoring block file
190        blk_dat_moved.rename(self.nodes[0].blocks_path / "blk00000.dat")
191        assert blk_dat.exists()
192
193    def test_double_spend(self):
194        '''
195        This tests the case where the same UTXO is spent twice on two separate
196        blocks as part of a reorg.
197
198             ab0
199          /       \
200        aa1 [tx1]   bb1 [tx2]
201         |           |
202        aa2         bb2
203         |           |
204        aa3         bb3
205                     |
206                    bb4
207
208        Problematic case:
209
210        1. User 1 receives BTC in tx1 from utxo1 in block aa1.
211        2. User 2 receives BTC in tx2 from utxo1 (same) in block bb1
212        3. User 1 sees 2 confirmations at block aa3.
213        4. Reorg into bb chain.
214        5. User 1 asks `listsinceblock aa3` and does not see that tx1 is now
215           invalidated.
216
217        Currently the solution to this is to detect that a reorg'd block is
218        asked for in listsinceblock, and to iterate back over existing blocks up
219        until the fork point, and to include all transactions that relate to the
220        node wallet.
221        '''
222        self.log.info("Test double spend")
223
224        self.sync_all()
225
226        # share utxo between nodes[1] and nodes[2]
227        privkey, pubkey = generate_keypair(wif=True)
228        address = key_to_p2wpkh(pubkey)
229        self.nodes[2].sendtoaddress(address, 10)
230        self.generate(self.nodes[2], 6)
231        wallet_importprivkey(self.nodes[2], privkey, "now")
232        utxos = self.nodes[2].listunspent()
233        utxo = [u for u in utxos if u["address"] == address][0]
234        wallet_importprivkey(self.nodes[1], privkey, "now")
235
236        # Split network into two
237        self.split_network()
238
239        # send from nodes[1] using utxo to nodes[0]
240        change = '%.8f' % (float(utxo['amount']) - 1.0003)
241        recipient_dict = {
242            self.nodes[0].getnewaddress(): 1,
243            self.nodes[1].getnewaddress(): change,
244        }
245        utxo_dicts = [{
246            'txid': utxo['txid'],
247            'vout': utxo['vout'],
248        }]
249        txid1 = self.nodes[1].sendrawtransaction(
250            self.nodes[1].signrawtransactionwithwallet(

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.