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.

37,291 bytes · SHA-256 97d56ce4cca83ebd… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2024-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.
5from decimal import Decimal
6
7from test_framework.test_framework import BitcoinTestFramework
8from test_framework.util import (
9    assert_not_equal,
10    assert_equal,
11    assert_greater_than,
12    assert_greater_than_or_equal,
13    assert_raises_rpc_error,
14    get_fee,
15)
16from test_framework.wallet import (
17    COIN,
18    DEFAULT_FEE,
19    MiniWallet,
20)
21from test_framework.blocktools import (
22    create_empty_fork,
23)
24
25MAX_REPLACEMENT_CANDIDATES = 100
26TRUC_MAX_VSIZE = 10000
27TRUC_CHILD_MAX_VSIZE = 1000
28
29def cleanup(extra_args=None):
30    def decorator(func):
31        def wrapper(self):
32            if extra_args is not None:
33                self.restart_node(0, extra_args=extra_args)
34            func(self)
35
36            # Clear mempool again after test
37            self.generate(self.nodes[0], 1)
38            if extra_args is not None:
39                self.restart_node(0)
40        return wrapper
41    return decorator
42
43class MempoolTRUC(BitcoinTestFramework):
44    def set_test_params(self):
45        self.num_nodes = 1
46        self.extra_args = [[]]
47        self.setup_clean_chain = True
48
49    def check_mempool(self, txids):
50        """Assert exact contents of the node's mempool (by txid)."""
51        mempool_contents = self.nodes[0].getrawmempool()
52        assert_equal(len(txids), len(mempool_contents))
53        assert all([txid in txids for txid in mempool_contents])
54
55    def trigger_reorg(self, fork_blocks):
56        """Trigger reorg of the fork blocks."""
57        for block in fork_blocks:
58            self.nodes[0].submitblock(block.serialize().hex())
59        assert_equal(self.nodes[0].getbestblockhash(), fork_blocks[-1].hash_hex)
60
61    @cleanup()
62    def test_truc_max_vsize(self):
63        node = self.nodes[0]
64        self.log.info("Test TRUC-specific maximum transaction vsize")
65        tx_v3_heavy = self.wallet.create_self_transfer(target_vsize=TRUC_MAX_VSIZE + 1, version=3)
66        assert_greater_than_or_equal(tx_v3_heavy["tx"].get_vsize(), TRUC_MAX_VSIZE)
67        expected_error_heavy = f"TRUC-violation, version=3 tx {tx_v3_heavy['txid']} (wtxid={tx_v3_heavy['wtxid']}) is too big"
68        assert_raises_rpc_error(-26, expected_error_heavy, node.sendrawtransaction, tx_v3_heavy["hex"])
69        self.check_mempool([])
70
71        # Ensure we are hitting the TRUC-specific limit and not something else
72        tx_v2_heavy = self.wallet.send_self_transfer(from_node=node, target_vsize=TRUC_MAX_VSIZE + 1, version=2)
73        self.check_mempool([tx_v2_heavy["txid"]])
74
75    @cleanup()
76    def test_truc_acceptance(self):
77        node = self.nodes[0]
78        self.log.info("Test a child of a TRUC transaction cannot be more than 1000vB")
79        tx_v3_parent_normal = self.wallet.send_self_transfer(from_node=node, version=3)
80        self.check_mempool([tx_v3_parent_normal["txid"]])
81        tx_v3_child_heavy = self.wallet.create_self_transfer(
82            utxo_to_spend=tx_v3_parent_normal["new_utxo"],
83            target_vsize=TRUC_CHILD_MAX_VSIZE + 1,
84            version=3
85        )
86        assert_greater_than_or_equal(tx_v3_child_heavy["tx"].get_vsize(), TRUC_CHILD_MAX_VSIZE)
87        expected_error_child_heavy = f"TRUC-violation, version=3 child tx {tx_v3_child_heavy['txid']} (wtxid={tx_v3_child_heavy['wtxid']}) is too big"
88        assert_raises_rpc_error(-26, expected_error_child_heavy, node.sendrawtransaction, tx_v3_child_heavy["hex"])
89        self.check_mempool([tx_v3_parent_normal["txid"]])
90        # tx has no descendants
91        assert_equal(node.getmempoolentry(tx_v3_parent_normal["txid"])["descendantcount"], 1)
92
93        self.log.info("Test that, during replacements, only the new transaction counts for TRUC descendant limit")
94        tx_v3_child_almost_heavy = self.wallet.send_self_transfer(
95            from_node=node,
96            fee_rate=DEFAULT_FEE,
97            utxo_to_spend=tx_v3_parent_normal["new_utxo"],
98            target_vsize=TRUC_CHILD_MAX_VSIZE - 3,
99            version=3
100        )
101        assert_greater_than_or_equal(TRUC_CHILD_MAX_VSIZE, tx_v3_child_almost_heavy["tx"].get_vsize())
102        self.check_mempool([tx_v3_parent_normal["txid"], tx_v3_child_almost_heavy["txid"]])
103        assert_equal(node.getmempoolentry(tx_v3_parent_normal["txid"])["descendantcount"], 2)
104        tx_v3_child_almost_heavy_rbf = self.wallet.send_self_transfer(
105            from_node=node,
106            fee_rate=DEFAULT_FEE * 2,
107            utxo_to_spend=tx_v3_parent_normal["new_utxo"],
108            target_vsize=875,
109            version=3
110        )
111        assert_greater_than_or_equal(tx_v3_child_almost_heavy["tx"].get_vsize() + tx_v3_child_almost_heavy_rbf["tx"].get_vsize(),
112                                     TRUC_CHILD_MAX_VSIZE)
113        self.check_mempool([tx_v3_parent_normal["txid"], tx_v3_child_almost_heavy_rbf["txid"]])
114        assert_equal(node.getmempoolentry(tx_v3_parent_normal["txid"])["descendantcount"], 2)
115
116    @cleanup(extra_args=None)
117    def test_truc_replacement(self):
118        node = self.nodes[0]
119        self.log.info("Test TRUC transactions may be replaced by TRUC transactions")
120        utxo_v3_bip125 = self.wallet.get_utxo()
121        tx_v3_bip125 = self.wallet.send_self_transfer(
122            from_node=node,
123            fee_rate=DEFAULT_FEE,
124            utxo_to_spend=utxo_v3_bip125,
125            version=3
126        )
127        self.check_mempool([tx_v3_bip125["txid"]])
128
129        tx_v3_bip125_rbf = self.wallet.send_self_transfer(
130            from_node=node,
131            fee_rate=DEFAULT_FEE * 2,
132            utxo_to_spend=utxo_v3_bip125,
133            version=3
134        )
135        self.check_mempool([tx_v3_bip125_rbf["txid"]])
136
137        self.log.info("Test TRUC transactions may be replaced by non-TRUC (BIP125) transactions")
138        tx_v3_bip125_rbf_v2 = self.wallet.send_self_transfer(
139            from_node=node,
140            fee_rate=DEFAULT_FEE * 3,
141            utxo_to_spend=utxo_v3_bip125,
142            version=2
143        )
144        self.check_mempool([tx_v3_bip125_rbf_v2["txid"]])
145
146        self.log.info("Test that replacements cannot cause violation of inherited TRUC")
147        utxo_v3_parent = self.wallet.get_utxo()
148        tx_v3_parent = self.wallet.send_self_transfer(
149            from_node=node,
150            fee_rate=DEFAULT_FEE,
151            utxo_to_spend=utxo_v3_parent,
152            version=3
153        )
154        tx_v3_child = self.wallet.send_self_transfer(
155            from_node=node,
156            fee_rate=DEFAULT_FEE,
157            utxo_to_spend=tx_v3_parent["new_utxo"],
158            version=3
159        )
160        self.check_mempool([tx_v3_bip125_rbf_v2["txid"], tx_v3_parent["txid"], tx_v3_child["txid"]])
161
162        tx_v3_child_rbf_v2 = self.wallet.create_self_transfer(
163            fee_rate=DEFAULT_FEE * 2,
164            utxo_to_spend=tx_v3_parent["new_utxo"],
165            version=2
166        )
167        expected_error_v2_v3 = f"TRUC-violation, non-version=3 tx {tx_v3_child_rbf_v2['txid']} (wtxid={tx_v3_child_rbf_v2['wtxid']}) cannot spend from version=3 tx {tx_v3_parent['txid']} (wtxid={tx_v3_parent['wtxid']})"
168        assert_raises_rpc_error(-26, expected_error_v2_v3, node.sendrawtransaction, tx_v3_child_rbf_v2["hex"])
169        self.check_mempool([tx_v3_bip125_rbf_v2["txid"], tx_v3_parent["txid"], tx_v3_child["txid"]])
170
171
172    @cleanup()
173    def test_truc_reorg(self):
174        node = self.nodes[0]
175
176        # Prep for fork
177        fork_blocks = create_empty_fork(node)
178        self.log.info("Test that, during a reorg, TRUC rules are not enforced")
179        self.check_mempool([])
180
181        # Testing 2<-3 versions allowed
182        tx_v2_block = self.wallet.create_self_transfer(version=2)
183
184        # Testing 3<-2 versions allowed
185        tx_v3_block = self.wallet.create_self_transfer(version=3)
186
187        # Testing overly-large child size
188        tx_v3_block2 = self.wallet.create_self_transfer(version=3)
189
190        # Also create a linear chain of 3 TRUC transactions that will be directly mined, followed by one v2 in-mempool after block is made
191        tx_chain_1 = self.wallet.create_self_transfer(version=3)
192        tx_chain_2 = self.wallet.create_self_transfer(utxo_to_spend=tx_chain_1["new_utxo"], version=3)
193        tx_chain_3 = self.wallet.create_self_transfer(utxo_to_spend=tx_chain_2["new_utxo"], version=3)
194
195        tx_to_mine = [tx_v3_block["hex"], tx_v2_block["hex"], tx_v3_block2["hex"], tx_chain_1["hex"], tx_chain_2["hex"], tx_chain_3["hex"]]
196        self.generateblock(node, output="raw(42)", transactions=tx_to_mine)
197
198        self.check_mempool([])
199
200        tx_v2_from_v3 = self.wallet.send_self_transfer(from_node=node, utxo_to_spend=tx_v3_block["new_utxo"], version=2)
201        tx_v3_from_v2 = self.wallet.send_self_transfer(from_node=node, utxo_to_spend=tx_v2_block["new_utxo"], version=3)
202        tx_v3_child_large = self.wallet.send_self_transfer(from_node=node, utxo_to_spend=tx_v3_block2["new_utxo"], target_vsize=1250, version=3)
203        assert_greater_than(node.getmempoolentry(tx_v3_child_large["txid"])["vsize"], TRUC_CHILD_MAX_VSIZE)
204        tx_chain_4 = self.wallet.send_self_transfer(from_node=node, utxo_to_spend=tx_chain_3["new_utxo"], version=2)
205        self.check_mempool([tx_v2_from_v3["txid"], tx_v3_from_v2["txid"], tx_v3_child_large["txid"], tx_chain_4["txid"]])
206
207        # Reorg should have all block transactions re-accepted, ignoring TRUC enforcement
208        self.trigger_reorg(fork_blocks)
209        self.check_mempool([tx_v3_block["txid"], tx_v2_block["txid"], tx_v3_block2["txid"], tx_v2_from_v3["txid"], tx_v3_from_v2["txid"], tx_v3_child_large["txid"], tx_chain_1["txid"], tx_chain_2["txid"], tx_chain_3["txid"], tx_chain_4["txid"]])
210
211    @cleanup(extra_args=["-limitclustercount=1"])
212    def test_nondefault_package_limits(self):
213        """
214        Max standard tx size + TRUC rules imply the cluster rules (at their default
215        values), but those checks must not be skipped. Ensure both sets of checks are done by
216        changing the cluster limit configurations.
217        """
218        node = self.nodes[0]
219        self.log.info("Test that a decreased cluster count limit also applies to TRUC child")
220        parent_target_vsize = 9990
221        child_target_vsize = 500
222        tx_v3_parent_large1 = self.wallet.send_self_transfer(
223            from_node=node,
224            target_vsize=parent_target_vsize,
225            version=3
226        )
227        tx_v3_child_large1 = self.wallet.create_self_transfer(
228            utxo_to_spend=tx_v3_parent_large1["new_utxo"],
229            target_vsize=child_target_vsize,
230            version=3
231        )
232
233        # Parent and child are within v3 limits, but cluster count limit is exceeded.
234        assert_greater_than_or_equal(TRUC_MAX_VSIZE, tx_v3_parent_large1["tx"].get_vsize())
235        assert_greater_than_or_equal(TRUC_CHILD_MAX_VSIZE, tx_v3_child_large1["tx"].get_vsize())
236
237        assert_raises_rpc_error(-26, "too-large-cluster", node.sendrawtransaction, tx_v3_child_large1["hex"])
238        self.check_mempool([tx_v3_parent_large1["txid"]])
239        assert_equal(node.getmempoolentry(tx_v3_parent_large1["txid"])["descendantcount"], 1)
240        self.generate(node, 1)
241
242        self.log.info("Test that a decreased limitclustersize also applies to TRUC child")
243        self.restart_node(0, extra_args=["-limitclustersize=10", "-acceptnonstdtxn=1"])
244        tx_v3_parent_large2 = self.wallet.send_self_transfer(from_node=node, target_vsize=parent_target_vsize, version=3)
245        tx_v3_child_large2 = self.wallet.create_self_transfer(utxo_to_spend=tx_v3_parent_large2["new_utxo"], target_vsize=child_target_vsize, version=3)
246        # Parent and child are within TRUC limits
247        assert_greater_than_or_equal(TRUC_MAX_VSIZE, tx_v3_parent_large2["tx"].get_vsize())
248        assert_greater_than_or_equal(TRUC_CHILD_MAX_VSIZE, tx_v3_child_large2["tx"].get_vsize())
249        assert_raises_rpc_error(-26, "too-large-cluster", node.sendrawtransaction, tx_v3_child_large2["hex"])
250        self.log.info("Test that a decreased limitclustercount also applies to TRUC transactions")

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.