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.

21,231 bytes · SHA-256 b343f40f0058e63e… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2023-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"""
7Test that wallet correctly tracks transactions that have been conflicted by blocks, particularly during reorgs.
8"""
9
10from decimal import Decimal
11
12from test_framework.test_framework import BitcoinTestFramework
13from test_framework.util import (
14        assert_equal,
15)
16
17class TxConflicts(BitcoinTestFramework):
18    def set_test_params(self):
19        self.num_nodes = 3
20
21    def skip_test_if_missing_module(self):
22        self.skip_if_no_wallet()
23
24    def get_utxo_of_value(self, from_tx_id, search_value):
25        return next(tx_out["vout"] for tx_out in self.nodes[0].gettransaction(from_tx_id)["details"] if tx_out["amount"] == Decimal(f"{search_value}"))
26
27    def run_test(self):
28        """
29        The following tests check the behavior of the wallet when
30        transaction conflicts are created. These conflicts are created
31        using raw transaction RPCs that double-spend UTXOs and have more
32        fees, replacing the original transaction.
33        """
34
35        self.test_block_conflicts()
36        self.test_mempool_conflict()
37        self.test_mempool_and_block_conflicts()
38        self.test_descendants_with_mempool_conflicts()
39
40    def test_block_conflicts(self):
41        self.log.info("Send tx from which to conflict outputs later")
42        txid_conflict_from_1 = self.nodes[0].sendtoaddress(self.nodes[0].getnewaddress(), Decimal("10"))
43        txid_conflict_from_2 = self.nodes[0].sendtoaddress(self.nodes[0].getnewaddress(), Decimal("10"))
44        self.generate(self.nodes[0], 1)
45        self.sync_blocks()
46
47        self.log.info("Disconnect nodes to broadcast conflicts on their respective chains")
48        self.disconnect_nodes(0, 1)
49        self.disconnect_nodes(2, 1)
50
51        self.log.info("Create transactions that conflict with each other")
52        output_A = self.get_utxo_of_value(from_tx_id=txid_conflict_from_1, search_value=10)
53        output_B = self.get_utxo_of_value(from_tx_id=txid_conflict_from_2, search_value=10)
54
55        # First create a transaction that consumes both A and B outputs.
56        #
57        # | tx1 |  ----->  |                |         |               |
58        #                  |  AB_parent_tx  |  ---->  |   Child_Tx    |
59        # | tx2 |  ----->  |                |         |               |
60        #
61        inputs_tx_AB_parent = [{"txid": txid_conflict_from_1, "vout": output_A}, {"txid": txid_conflict_from_2, "vout": output_B}]
62        tx_AB_parent = self.nodes[0].signrawtransactionwithwallet(self.nodes[0].createrawtransaction(inputs_tx_AB_parent, {self.nodes[0].getnewaddress(): Decimal("19.99998")}))
63
64        # Secondly, create two transactions: One consuming output_A, and another one consuming output_B
65        #
66        # | tx1 |  ----->  |     Tx_A_1     |
67        #                   ----------------
68        # | tx2 |  ----->  |     Tx_B_1     |
69        #
70        inputs_tx_A_1 = [{"txid": txid_conflict_from_1, "vout": output_A}]
71        inputs_tx_B_1 = [{"txid": txid_conflict_from_2, "vout": output_B}]
72        tx_A_1 = self.nodes[0].signrawtransactionwithwallet(self.nodes[0].createrawtransaction(inputs_tx_A_1, {self.nodes[0].getnewaddress(): Decimal("9.99998")}))
73        tx_B_1 = self.nodes[0].signrawtransactionwithwallet(self.nodes[0].createrawtransaction(inputs_tx_B_1, {self.nodes[0].getnewaddress(): Decimal("9.99998")}))
74
75        self.log.info("Broadcast conflicted transaction")
76        txid_AB_parent = self.nodes[0].sendrawtransaction(tx_AB_parent["hex"])
77        self.generate(self.nodes[0], 1, sync_fun=self.no_op)
78
79        # Now that 'AB_parent_tx' was broadcast, build 'Child_Tx'
80        output_c = self.get_utxo_of_value(from_tx_id=txid_AB_parent, search_value=19.99998)
81        inputs_tx_C_child = [({"txid": txid_AB_parent, "vout": output_c})]
82
83        tx_C_child = self.nodes[0].signrawtransactionwithwallet(self.nodes[0].createrawtransaction(inputs_tx_C_child, {self.nodes[0].getnewaddress() : Decimal("19.99996")}))
84        tx_C_child_txid = self.nodes[0].sendrawtransaction(tx_C_child["hex"])
85        self.generate(self.nodes[0], 1, sync_fun=self.no_op)
86
87        self.log.info("Broadcast conflicting tx to node 1 and generate a longer chain")
88        conflicting_txid_A = self.nodes[1].sendrawtransaction(tx_A_1["hex"])
89        self.generate(self.nodes[1], 4, sync_fun=self.no_op)
90        conflicting_txid_B = self.nodes[1].sendrawtransaction(tx_B_1["hex"])
91        self.generate(self.nodes[1], 4, sync_fun=self.no_op)
92
93        self.log.info("Connect nodes 0 and 1, trigger reorg and ensure that the tx is effectively conflicted")
94        self.connect_nodes(0, 1)
95        self.sync_blocks([self.nodes[0], self.nodes[1]])
96        conflicted_AB_tx = self.nodes[0].gettransaction(txid_AB_parent)
97        tx_C_child = self.nodes[0].gettransaction(tx_C_child_txid)
98        conflicted_A_tx = self.nodes[0].gettransaction(conflicting_txid_A)
99
100        self.log.info("Verify, after the reorg, that Tx_A was accepted, and tx_AB and its Child_Tx are conflicting now")
101        # Tx A was accepted, Tx AB was not.
102        assert conflicted_AB_tx["confirmations"] < 0
103        assert conflicted_A_tx["confirmations"] > 0
104
105        # Conflicted tx should have confirmations set to the confirmations of the most conflicting tx
106        assert_equal(-conflicted_AB_tx["confirmations"], conflicted_A_tx["confirmations"])
107        # Child should inherit conflicted state from parent
108        assert_equal(-tx_C_child["confirmations"], conflicted_A_tx["confirmations"])
109        # Check the confirmations of the conflicting transactions
110        assert_equal(conflicted_A_tx["confirmations"], 8)
111        assert_equal(self.nodes[0].gettransaction(conflicting_txid_B)["confirmations"], 4)
112
113        self.log.info("Now generate a longer chain that does not contain any tx")
114        # Node2 chain without conflicts
115        self.generate(self.nodes[2], 15, sync_fun=self.no_op)
116
117        # Connect node0 and node2 and wait reorg
118        self.connect_nodes(0, 2)
119        self.sync_blocks()
120        conflicted = self.nodes[0].gettransaction(txid_AB_parent)
121        tx_C_child = self.nodes[0].gettransaction(tx_C_child_txid)
122
123        self.log.info("Test that formerly conflicted transaction are inactive after reorg")
124        # Former conflicted tx should be unconfirmed as it hasn't been yet rebroadcast
125        assert_equal(conflicted["confirmations"], 0)
126        # Former conflicted child tx should be unconfirmed as it hasn't been rebroadcast
127        assert_equal(tx_C_child["confirmations"], 0)
128        # Rebroadcast former conflicted tx and check it confirms smoothly
129        self.nodes[2].sendrawtransaction(conflicted["hex"])
130        self.generate(self.nodes[2], 1)
131        self.sync_blocks()
132        former_conflicted = self.nodes[0].gettransaction(txid_AB_parent)
133        assert_equal(former_conflicted["confirmations"], 1)
134        assert_equal(former_conflicted["blockheight"], 217)
135
136    def test_mempool_conflict(self):
137        self.nodes[0].createwallet("alice")
138        alice = self.nodes[0].get_wallet_rpc("alice")
139
140        bob = self.nodes[1]
141
142        self.nodes[2].send(outputs=[{alice.getnewaddress() : 25} for _ in range(3)])
143        self.generate(self.nodes[2], 1)
144
145        self.log.info("Test a scenario where a transaction has a mempool conflict")
146
147        unspents = alice.listunspent()
148        assert_equal(len(unspents), 3)
149        for tx in unspents:
150            assert_equal(tx["amount"], 25)
151
152        # tx1 spends unspent[0] and unspent[1]
153        raw_tx = alice.createrawtransaction(inputs=[unspents[0], unspents[1]], outputs=[{bob.getnewaddress() : 49.9999}])
154        tx1 = alice.signrawtransactionwithwallet(raw_tx)['hex']
155
156        # tx2 spends unspent[1] and unspent[2], conflicts with tx1
157        raw_tx = alice.createrawtransaction(inputs=[unspents[1], unspents[2]], outputs=[{bob.getnewaddress() : 49.99}])
158        tx2 = alice.signrawtransactionwithwallet(raw_tx)['hex']
159
160        # tx3 spends unspent[2], conflicts with tx2
161        raw_tx = alice.createrawtransaction(inputs=[unspents[2]], outputs=[{bob.getnewaddress() : 24.9899}])
162        tx3 = alice.signrawtransactionwithwallet(raw_tx)['hex']
163
164        # broadcast tx1
165        tx1_txid = alice.sendrawtransaction(tx1)
166
167        assert_equal(alice.listunspent(), [unspents[2]])
168        assert_equal(alice.getbalance(), 25)
169
170        # broadcast tx2, replaces tx1 in mempool
171        tx2_txid = alice.sendrawtransaction(tx2)
172
173        # Check that unspent[0] is now available because the transaction spending it has been replaced in the mempool
174        assert_equal(alice.listunspent(), [unspents[0]])
175        assert_equal(alice.getbalance(), 25)
176
177        assert_equal(alice.gettransaction(tx1_txid)["mempoolconflicts"], [tx2_txid])
178
179        self.log.info("Test scenario where a mempool conflict is removed")
180
181        # broadcast tx3, replaces tx2 in mempool
182        # Now that tx1's conflict has been removed, tx1 is now
183        # not conflicted, and instead is inactive until it is
184        # rebroadcasted. Now unspent[0] is not available, because
185        # tx1 is no longer conflicted.
186        alice.sendrawtransaction(tx3)
187
188        assert_equal(alice.gettransaction(tx1_txid)["mempoolconflicts"], [])
189        assert tx1_txid not in self.nodes[0].getrawmempool()
190
191        # now all of alice's outputs should be considered spent
192        # unspent[0]: spent by inactive tx1
193        # unspent[1]: spent by inactive tx1
194        # unspent[2]: spent by active tx3
195        assert_equal(alice.listunspent(), [])
196        assert_equal(alice.getbalance(), 0)
197
198        # Clean up for next test
199        bob.sendall([self.nodes[2].getnewaddress()])
200        self.generate(self.nodes[2], 1)
201
202        alice.unloadwallet()
203
204    def test_mempool_and_block_conflicts(self):
205        self.nodes[0].createwallet("alice_2")
206        alice = self.nodes[0].get_wallet_rpc("alice_2")
207        bob = self.nodes[1]
208
209        self.nodes[2].send(outputs=[{alice.getnewaddress() : 25} for _ in range(3)])
210        self.generate(self.nodes[2], 1)
211
212        self.log.info("Test a scenario where a transaction has both a block conflict and a mempool conflict")
213        unspents = [{"txid" : element["txid"], "vout" : element["vout"]} for element in alice.listunspent()]
214
215        assert_equal(bob.getbalances()["mine"]["untrusted_pending"], 0)
216
217        # alice and bob nodes are disconnected so that transactions can be
218        # created by alice, but broadcasted from bob so that alice's wallet
219        # doesn't know about them
220        self.disconnect_nodes(0, 1)
221
222        # Sends funds to bob
223        raw_tx = alice.createrawtransaction(inputs=[unspents[0]], outputs=[{bob.getnewaddress() : 24.99999}])
224        raw_tx1 = alice.signrawtransactionwithwallet(raw_tx)['hex']
225        tx1_txid = bob.sendrawtransaction(raw_tx1) # broadcast original tx spending unspents[0] only to bob
226
227        # create a conflict to previous tx (also spends unspents[0]), but don't broadcast, sends funds back to alice
228        raw_tx = alice.createrawtransaction(inputs=[unspents[0], unspents[2]], outputs=[{alice.getnewaddress() : 49.999}])
229        tx1_conflict = alice.signrawtransactionwithwallet(raw_tx)['hex']
230
231        # Sends funds to bob
232        raw_tx = alice.createrawtransaction(inputs=[unspents[1]], outputs=[{bob.getnewaddress() : 24.9999}])
233        raw_tx2 = alice.signrawtransactionwithwallet(raw_tx)['hex']
234        tx2_txid = bob.sendrawtransaction(raw_tx2) # broadcast another original tx spending unspents[1] only to bob
235
236        # create a conflict to previous tx (also spends unspents[1]), but don't broadcast, sends funds to alice
237        raw_tx = alice.createrawtransaction(inputs=[unspents[1]], outputs=[{alice.getnewaddress() : 24.9999}])
238        tx2_conflict = alice.signrawtransactionwithwallet(raw_tx)['hex']
239
240        bob_unspents = [{"txid" : element, "vout" : 0} for element in [tx1_txid, tx2_txid]]
241
242        # tx1 and tx2 are now in bob's mempool, and they are unconflicted, so bob has these funds
243        assert_equal(bob.getbalances()["mine"]["untrusted_pending"], Decimal("49.99989000"))
244
245        # spend both of bob's unspents, child tx of tx1 and tx2
246        raw_tx = bob.createrawtransaction(inputs=[bob_unspents[0], bob_unspents[1]], outputs=[{bob.getnewaddress() : 49.999}])
247        raw_tx3 = bob.signrawtransactionwithwallet(raw_tx)['hex']
248        tx3_txid = bob.sendrawtransaction(raw_tx3) # broadcast tx only to bob
249
250        # alice knows about 0 txs, bob knows about 3

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.