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.

11,846 bytes · SHA-256 5cb4ec8e5839568f… · 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 tx status in case of reorgs while wallet being shutdown.
7
8Wallet txn status rely on block connection/disconnection for its
9accuracy. In case of reorgs happening while wallet being shutdown
10block updates are not going to be received. At wallet loading, we
11check against chain if confirmed txn are still in chain and change
12their status if block in which they have been included has been
13disconnected.
14"""
15
16from decimal import Decimal
17import shutil
18
19from test_framework.test_framework import BitcoinTestFramework
20from test_framework.util import (
21        assert_equal,
22        assert_greater_than,
23        assert_not_equal,
24        assert_raises_rpc_error
25)
26
27class ReorgsRestoreTest(BitcoinTestFramework):
28    def set_test_params(self):
29        self.num_nodes = 3
30
31    def skip_test_if_missing_module(self):
32        self.skip_if_no_wallet()
33
34    def test_coinbase_automatic_abandon_during_startup(self):
35        ##########################################################################################################
36        # Verify the wallet marks coinbase transactions, and their descendants, as abandoned during startup when #
37        # the block is no longer part of the best chain.                                                         #
38        ##########################################################################################################
39        self.log.info("Test automatic coinbase abandonment during startup")
40        # Test setup: Sync nodes for the coming test, ensuring both are at the same block, then disconnect them to
41        # generate two competing chains. After disconnection, verify no other peer connection exists.
42        self.connect_nodes(1, 0)
43        self.sync_blocks(self.nodes[:2])
44        self.disconnect_nodes(1, 0)
45        for node in self.nodes[:2]:
46            assert_equal(len(node.getpeerinfo()), 0)
47
48        # Create a new block in node0, coinbase going to wallet0
49        self.nodes[0].createwallet(wallet_name="w0", load_on_startup=True)
50        wallet0 = self.nodes[0].get_wallet_rpc("w0")
51        self.generatetoaddress(self.nodes[0], 1, wallet0.getnewaddress(), sync_fun=self.no_op)
52        node0_coinbase_tx_hash = wallet0.getblock(wallet0.getbestblockhash(), verbose=1)['tx'][0]
53
54        # Mine 100 blocks on top to mature the coinbase and create a descendant
55        self.generate(self.nodes[0], 101, sync_fun=self.no_op)
56        # Make descendant, send-to-self
57        descendant_tx_id = wallet0.sendtoaddress(wallet0.getnewaddress(), 1)
58
59        # Verify balance
60        wallet0.syncwithvalidationinterfacequeue()
61        assert(wallet0.getbalances()['mine']['trusted'] > 0)
62
63        # Now create a fork in node1. This will be used to replace node0's chain later.
64        self.nodes[1].createwallet(wallet_name="w1", load_on_startup=True)
65        wallet1 = self.nodes[1].get_wallet_rpc("w1")
66        self.generatetoaddress(self.nodes[1], 1, wallet1.getnewaddress(), sync_fun=self.no_op)
67        wallet1.syncwithvalidationinterfacequeue()
68
69        # Verify both nodes are on a different chain
70        block0_best_hash, block1_best_hash = wallet0.getbestblockhash(), wallet1.getbestblockhash()
71        assert(block0_best_hash != block1_best_hash)
72
73        # Stop both nodes and replace node0 chain entirely for the node1 chain
74        self.stop_nodes()
75        for path in ["chainstate", "blocks"]:
76            self.cleanup_folder(self.nodes[0].chain_path / path)
77            shutil.copytree(self.nodes[1].chain_path / path, self.nodes[0].chain_path / path)
78
79        # Start node0 and verify that now it has node1 chain and no info about its previous best block
80        self.start_node(0)
81        wallet0 = self.nodes[0].get_wallet_rpc("w0")
82        assert_equal(wallet0.getbestblockhash(), block1_best_hash)
83        assert_raises_rpc_error(-5, "Block not found", wallet0.getblock, block0_best_hash)
84
85        # Verify the coinbase tx was marked as abandoned and balance correctly computed
86        tx_info = wallet0.gettransaction(node0_coinbase_tx_hash)['details'][0]
87        assert_equal(tx_info['abandoned'], True)
88        assert_equal(tx_info['category'], 'orphan')
89        assert(wallet0.getbalances()['mine']['trusted'] == 0)
90        # Verify the coinbase descendant was also marked as abandoned
91        assert_equal(wallet0.gettransaction(descendant_tx_id)['details'][0]['abandoned'], True)
92
93    def test_reorg_handling_during_unclean_shutdown(self):
94        self.log.info("Test that wallet transactions are un-abandoned in case of temporarily invalidated blocks and wallet doesn't crash due to a duplicate block disconnection event after an unclean shutdown")
95        node = self.nodes[0]
96        # Receive coinbase reward on a new wallet
97        node.createwallet(wallet_name="reorg_crash", load_on_startup=True)
98        wallet = node.get_wallet_rpc("reorg_crash")
99        self.generatetoaddress(node, 1, wallet.getnewaddress(), sync_fun=self.no_op)
100
101        # Restart to ensure node and wallet are flushed
102        self.restart_node(0)
103        wallet = node.get_wallet_rpc("reorg_crash")
104        assert_greater_than(wallet.getbalances()["mine"]["immature"], 0)
105
106        # Disconnect tip and sync wallet state
107        tip = wallet.getbestblockhash()
108        tip_height = wallet.getblockstats(hash_or_height=tip)["height"]
109        wallet.invalidateblock(tip)
110        wallet.syncwithvalidationinterfacequeue()
111
112        # Tip was disconnected, ensure coinbase has been abandoned
113        assert_equal(wallet.getbalances()["mine"]["immature"], 0)
114        coinbase_tx_id = wallet.getblock(tip, verbose=1)["tx"][0]
115        assert_equal(wallet.gettransaction(coinbase_tx_id)['details'][0]['abandoned'], True)
116
117        # Abort process abruptly to mimic an unclean shutdown (no chain state flush to disk)
118        node.kill_process()
119
120        # Restart the node and confirm that it has not persisted the last chain state changes to disk
121        # that leads to a rescan by the wallet
122        with self.nodes[0].assert_debug_log(expected_msgs=[f"Rescanning last 1 blocks (from block {tip_height - 1})...\n"]):
123            self.start_node(0)
124        assert_equal(node.getbestblockhash(), tip)
125
126        # After disconnecting the block, the wallet should record the new best block.
127        # Upon reload after the crash, since the chainstate was not flushed, the tip contains the previously abandoned
128        # coinbase. This was rescanned and now un-abandoned.
129        wallet = node.get_wallet_rpc("reorg_crash")
130        assert_equal(wallet.gettransaction(coinbase_tx_id)['details'][0]['abandoned'], False)
131        assert_greater_than(wallet.getbalances()["mine"]["immature"], 0)
132
133        # Previously, a bug caused the node to crash if two block disconnection events occurred consecutively.
134        # Ensure this is no longer the case by simulating a new reorg.
135        node.invalidateblock(tip)
136        assert(node.getbestblockhash() != tip)
137        # Ensure wallet state is consistent now
138        assert_equal(wallet.gettransaction(coinbase_tx_id)['details'][0]['abandoned'], True)
139        assert_equal(wallet.getbalances()["mine"]["immature"], 0)
140
141        # And finally, verify the state if the block ends up being into the best chain again
142        node.reconsiderblock(tip)
143        assert_equal(wallet.gettransaction(coinbase_tx_id)['details'][0]['abandoned'], False)
144        assert_greater_than(wallet.getbalances()["mine"]["immature"], 0)
145
146    def run_test(self):
147        # Send a tx from which to conflict outputs later
148        txid_conflict_from = self.nodes[0].sendtoaddress(self.nodes[0].getnewaddress(), Decimal("10"))
149        self.generate(self.nodes[0], 1)
150
151        # Disconnect node1 from others to reorg its chain later
152        self.disconnect_nodes(0, 1)
153        self.disconnect_nodes(1, 2)
154        self.connect_nodes(0, 2)
155
156        # Send a tx to be unconfirmed later
157        txid = self.nodes[0].sendtoaddress(self.nodes[0].getnewaddress(), Decimal("10"))
158        tx = self.nodes[0].gettransaction(txid)
159        self.generate(self.nodes[0], 4, sync_fun=self.no_op)
160        self.sync_blocks([self.nodes[0], self.nodes[2]])
161        tx_before_reorg = self.nodes[0].gettransaction(txid)
162        assert_equal(tx_before_reorg["confirmations"], 4)
163
164        # Disconnect node0 from node2 to broadcast a conflict on their respective chains
165        self.disconnect_nodes(0, 2)
166        nA = next(tx_out["vout"] for tx_out in self.nodes[0].gettransaction(txid_conflict_from)["details"] if tx_out["amount"] == Decimal("10"))
167        inputs = []
168        inputs.append({"txid": txid_conflict_from, "vout": nA})
169        outputs_1 = {}
170        outputs_2 = {}
171
172        # Create a conflicted tx broadcast on node0 chain and conflicting tx broadcast on node1 chain. Both spend from txid_conflict_from
173        outputs_1[self.nodes[0].getnewaddress()] = Decimal("9.99998")
174        outputs_2[self.nodes[0].getnewaddress()] = Decimal("9.99998")
175        conflicted = self.nodes[0].signrawtransactionwithwallet(self.nodes[0].createrawtransaction(inputs, outputs_1))
176        conflicting = self.nodes[0].signrawtransactionwithwallet(self.nodes[0].createrawtransaction(inputs, outputs_2))
177
178        conflicted_txid = self.nodes[0].sendrawtransaction(conflicted["hex"])
179        self.generate(self.nodes[0], 1, sync_fun=self.no_op)
180        conflicting_txid = self.nodes[2].sendrawtransaction(conflicting["hex"])
181        self.generate(self.nodes[2], 9, sync_fun=self.no_op)
182
183        # Reconnect node0 and node2 and check that conflicted_txid is effectively conflicted
184        self.connect_nodes(0, 2)
185        self.sync_blocks([self.nodes[0], self.nodes[2]])
186        conflicted = self.nodes[0].gettransaction(conflicted_txid)
187        conflicting = self.nodes[0].gettransaction(conflicting_txid)
188        assert_equal(conflicted["confirmations"], -9)
189        assert_equal(conflicted["walletconflicts"][0], conflicting["txid"])
190
191        # Node0 wallet is shutdown
192        self.restart_node(0)
193
194        # The block chain re-orgs and the tx is included in a different block
195        self.generate(self.nodes[1], 9, sync_fun=self.no_op)
196        self.nodes[1].sendrawtransaction(tx["hex"])
197        self.generate(self.nodes[1], 1, sync_fun=self.no_op)
198        self.nodes[1].sendrawtransaction(conflicted["hex"])
199        self.generate(self.nodes[1], 1, sync_fun=self.no_op)
200
201        # Node0 wallet file is loaded on longest sync'ed node1
202        self.stop_node(1)
203        self.nodes[0].backupwallet(self.nodes[0].datadir_path / 'wallet.bak')
204        shutil.copyfile(self.nodes[0].datadir_path / 'wallet.bak', self.nodes[1].chain_path / self.default_wallet_name / self.wallet_data_filename)
205        self.start_node(1)
206        tx_after_reorg = self.nodes[1].gettransaction(txid)
207        # Check that normal confirmed tx is confirmed again but with different blockhash
208        assert_equal(tx_after_reorg["confirmations"], 2)
209        assert_not_equal(tx_before_reorg["blockhash"], tx_after_reorg["blockhash"])
210        conflicted_after_reorg = self.nodes[1].gettransaction(conflicted_txid)
211        # Check that conflicted tx is confirmed again with blockhash different than previously conflicting tx
212        assert_equal(conflicted_after_reorg["confirmations"], 1)
213        assert_not_equal(conflicting["blockhash"], conflicted_after_reorg["blockhash"])
214
215        # Verify we mark coinbase txs, and their descendants, as abandoned during startup
216        self.test_coinbase_automatic_abandon_during_startup()
217
218        # Verify reorg behavior during an unclean shutdown
219        self.test_reorg_handling_during_unclean_shutdown()
220
221
222if __name__ == '__main__':
223    ReorgsRestoreTest(__file__).main()
224

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.