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.

28,648 bytes · SHA-256 ad75fbbb0901ed46… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2018-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"""Backwards compatibility functional test
6
7Test various backwards compatibility scenarios. Requires previous releases binaries,
8see test/README.md.
9
10Due to RPC changes introduced in various versions the below tests
11won't work for older versions without some patches or workarounds.
12
13Use only the latest patch version of each release, unless a test specifically
14needs an older patch version.
15"""
16
17import json
18import os
19import shutil
20
21from test_framework.blocktools import COINBASE_MATURITY
22from test_framework.extendedkey import ExtendedPrivateKey
23from test_framework.test_framework import BitcoinTestFramework
24from test_framework.descriptors import descsum_create
25from test_framework.messages import ser_string
26
27from test_framework.util import (
28    assert_equal,
29    assert_greater_than,
30    assert_not_equal,
31    assert_raises_rpc_error,
32)
33
34LAST_KEYPOOL_INDEX = 9 # Index of the last derived address with the keypool size of 10
35
36class BackwardsCompatibilityTest(BitcoinTestFramework):
37    def set_test_params(self):
38        self.setup_clean_chain = True
39        self.num_nodes = 11
40        # Add new version after each release:
41        self.extra_args = [
42            ["-addresstype=bech32", "[email protected]"], # Pre-release: use to mine blocks. noban for immediate tx relay
43            ["-nowallet", "-addresstype=bech32", "[email protected]"], # Pre-release: use to receive coins, swap wallets, etc
44            ["-nowallet", "-addresstype=bech32", "[email protected]"], # v31.1
45            ["-nowallet", "-addresstype=bech32", "[email protected]"], # v31.0
46            ["-nowallet", "-addresstype=bech32", "[email protected]"], # v30.2
47            ["-nowallet", "-addresstype=bech32", "[email protected]"], # v25.0
48            ["-nowallet", "-addresstype=bech32", "[email protected]"], # v24.0.1
49            ["-nowallet", "-addresstype=bech32", "[email protected]"], # v23.0
50            ["-nowallet", "-addresstype=bech32", "[email protected]", f"-keypool={LAST_KEYPOOL_INDEX + 1}"], # v22.0
51            ["-nowallet", "-addresstype=bech32", "[email protected]"], # v0.21.0
52            ["-nowallet", "-addresstype=bech32", "[email protected]"], # v0.20.1
53        ]
54        self.wallet_names = [self.default_wallet_name]
55
56    def skip_test_if_missing_module(self):
57        self.skip_if_no_wallet()
58        self.skip_if_no_previous_releases()
59
60    def setup_nodes(self):
61        self.add_nodes(self.num_nodes, extra_args=self.extra_args, versions=[
62            None,
63            None,
64            310100,
65            310000,
66            300200,
67            250000,
68            240001,
69            230000,
70            220000,
71            210000,
72            200100,
73        ])
74
75        self.start_nodes()
76        self.import_deterministic_coinbase_privkeys()
77
78    def split_version(self, node):
79        major = node.version // 10000
80        minor = (node.version % 10000) // 100
81        patch = (node.version % 100)
82        return (major, minor, patch)
83
84    def major_version_equals(self, node, major):
85        node_major, _, _ = self.split_version(node)
86        return node_major == major
87
88    def major_version_less_than(self, node, major):
89        node_major, _, _ = self.split_version(node)
90        return node_major < major
91
92    def major_version_at_least(self, node, major):
93        node_major, _, _ = self.split_version(node)
94        return node_major >= major
95
96    def test_v22_inactivehdchain_path(self):
97        self.log.info("Testing inactive hd chain bad derivation path cleanup")
98        # 0.21.x and 22.x would both produce bad derivation paths when topping up an inactive hd chain
99        # Make sure that this is being automatically cleaned up by migration
100        node_master = self.nodes[1]
101        node_v22 = self.nodes[self.num_nodes - 3]
102        wallet_name = "bad_deriv_path"
103        node_v22.createwallet(wallet_name=wallet_name, descriptors=False)
104        bad_deriv_wallet = node_v22.get_wallet_rpc(wallet_name)
105
106        # Make a dump of the wallet to get an unused address
107        dump_path = node_v22.wallets_path / f"{wallet_name}.dump"
108        bad_deriv_wallet.dumpwallet(dump_path)
109        addr = None
110        seed = None
111        with open(dump_path) as f:
112            for line in f:
113                if f"hdkeypath=m/0'/0'/{LAST_KEYPOOL_INDEX}'" in line:
114                    addr = line.split(" ")[4].split("=")[1]
115                elif " hdseed=1 " in line:
116                    seed = line.split(" ")[0]
117        assert addr is not None
118        assert seed is not None
119        # Rotate seed and unload
120        bad_deriv_wallet.sethdseed()
121        bad_deriv_wallet.unloadwallet()
122        # Receive at addr to trigger inactive chain topup on next load
123        self.nodes[0].sendtoaddress(addr, 1)
124        self.generate(self.nodes[0], 1, sync_fun=self.no_op)
125        self.sync_all(nodes=[self.nodes[0], node_master, node_v22])
126        node_v22.loadwallet(wallet_name)
127
128        # Dump again to find bad hd keypath
129        bad_deriv_path = f"m/0'/0'/{LAST_KEYPOOL_INDEX}'/0'/0'/{LAST_KEYPOOL_INDEX + 1}'"
130        good_deriv_path = f"m/0h/0h/{LAST_KEYPOOL_INDEX + 1}h"
131        os.unlink(dump_path)
132        bad_deriv_wallet.dumpwallet(dump_path)
133        bad_path_addr = None
134        with open(dump_path) as f:
135            for line in f:
136                if f"hdkeypath={bad_deriv_path}" in line:
137                    bad_path_addr = line.split(" ")[4].split("=")[1]
138        assert bad_path_addr is not None
139        assert_equal(bad_deriv_wallet.getaddressinfo(bad_path_addr)["hdkeypath"], bad_deriv_path)
140
141        # Verify that this bad derivation path addr is actually at m/0'/0'/10' by making a new wallet with the same seed but larger keypool
142        node_v22.createwallet(wallet_name="path_verify", descriptors=False, blank=True)
143        verify_wallet = node_v22.get_wallet_rpc("path_verify")
144        verify_wallet.sethdseed(True, seed)
145        # Bad addr is after keypool, so need to generate it by refilling
146        verify_wallet.keypoolrefill(LAST_KEYPOOL_INDEX + 2)
147        assert_equal(verify_wallet.getaddressinfo(bad_path_addr)["hdkeypath"], good_deriv_path.replace("h", "'"))
148
149        # Migrate with master
150        # Since all keymeta records are now deleted after migration, the derivation path
151        # should now be correct as it is derived on-the-fly from the inactive hd chain's descriptor
152        backup_path = node_v22.wallets_path / f"{wallet_name}.bak"
153        bad_deriv_wallet.backupwallet(backup_path)
154        wallet_dir_master = os.path.join(node_master.wallets_path, wallet_name)
155        os.makedirs(wallet_dir_master, exist_ok=True)
156        shutil.copy(backup_path, os.path.join(wallet_dir_master, "wallet.dat"))
157        node_master.migratewallet(wallet_name)
158        bad_deriv_wallet_master = node_master.get_wallet_rpc(wallet_name)
159        assert_equal(bad_deriv_wallet_master.getaddressinfo(bad_path_addr)["hdkeypath"], good_deriv_path)
160        bad_deriv_wallet_master.unloadwallet()
161
162        def check_keymeta(conn):
163            # Retrieve all records that have the "keymeta" prefix. The remaining key data varies for each record.
164            keymeta_rec = conn.execute(f"SELECT value FROM main where key >= x'{ser_string(b'keymeta').hex()}' AND key < x'{ser_string(b'keymetb').hex()}'").fetchone()
165            assert_equal(keymeta_rec, None)
166
167        wallet_db = node_master.wallets_path / wallet_name / "wallet.dat"
168        self.inspect_sqlite_db(wallet_db, check_keymeta)
169
170    def test_ignore_legacy_during_startup(self, legacy_nodes, node_master):
171        self.log.info("Test that legacy wallets are ignored during startup on v29+")
172
173        legacy_node = legacy_nodes[0]
174        wallet_name = f"legacy_up_{legacy_node.version}"
175        legacy_node.loadwallet(wallet_name)
176        legacy_wallet = legacy_node.get_wallet_rpc(wallet_name)
177
178        # Move legacy wallet to latest node
179        wallet_path = node_master.wallets_path / wallet_name
180        wallet_path.mkdir()
181        legacy_wallet.backupwallet(wallet_path / "wallet.dat")
182        legacy_wallet.unloadwallet()
183
184        # Write wallet so it is automatically loaded during init
185        settings_path = node_master.chain_path / "settings.json"
186        with settings_path.open("w") as fp:
187            json.dump({"wallet": [wallet_name]}, fp)
188
189        # Restart latest node and verify that the legacy wallet load is skipped without exiting early during init.
190        self.restart_node(node_master.index, extra_args=[])
191        # Ensure we receive the warning message and clear the stderr pipe.
192        node_master.stderr.seek(0)
193        warning_msg = node_master.stderr.read().decode('utf-8').strip()
194        assert "The wallet appears to be a Legacy wallet, please use the wallet migration tool (migratewallet RPC or the GUI option)" in warning_msg
195        node_master.stderr.truncate(0), node_master.stderr.seek(0) # reset buffer
196
197        # Verify the node is still running (no shutdown occurred during startup)
198        node_master.getblockcount()
199        # Reset settings for any subsequent test
200        os.remove(settings_path)
201
202    def test_downgrade_preserves_witness_variants(self, node_master, node_miner, node_old):
203        # Ensure the wallet keeps every witness variant of a tx during a downgrade. An old
204        # release updating the tx record must not drop them.
205        self.log.info("Test that witness variants survive a downgrade that rewrites the tx record")
206
207        # Earlier tests may have restarted node_master or dropped its peers
208        self.connect_nodes(node_miner.index, node_master.index)
209        self.connect_nodes(node_master.index, node_old.index)
210        self.sync_blocks([node_miner, node_master, node_old])
211
212        wallet_name = "altwit_downgrade"
213        node_master.createwallet(wallet_name)
214        wallet = node_master.get_wallet_rpc(wallet_name)
215
216        xprvs = [ExtendedPrivateKey.generate() for _ in range(0, 2)]
217        xpubs = [xprv.pubkey() for xprv in xprvs]
218
219        # Taproot descriptor with a public-only internal key: the wallet can only
220        # spend via the script path, so the key path is signed separately below.
221        script_path_desc = descsum_create(f"tr({xpubs[0].to_string()}/*,pk({xprvs[1].to_string()}/*))")
222        assert_equal(wallet.importdescriptors([{"desc": script_path_desc, "active": True, "timestamp": "now"}])[0]["success"], True)
223
224        # Fund tr output owned by the wallet
225        node_miner.sendtoaddress(wallet.getnewaddress(address_type="bech32m"), 1)
226        self.sync_mempools([node_miner, node_master])
227        self.generate(node_miner, 1, sync_fun=self.no_op)
228        self.sync_blocks([node_miner, node_master, node_old])
229        wallet.syncwithvalidationinterfacequeue()
230
231        # Two witness variants of the same spend: same txid, different wtxid
232        psbt = wallet.walletcreatefundedpsbt(outputs=[{node_miner.getnewaddress(): 0.5}])["psbt"]
233        script_path_tx = wallet.finalizepsbt(wallet.walletprocesspsbt(psbt=psbt, finalize=False)["psbt"])["hex"]
234        script_path_wtxid = node_master.decoderawtransaction(script_path_tx)["hash"]
235
236        key_path_desc = descsum_create(f"tr({xprvs[0].to_string()}/*,pk({xpubs[1].to_string()}/*))")
237        key_path_psbt = node_master.descriptorprocesspsbt(psbt=psbt, descriptors=[{"desc": key_path_desc}], finalize=False)["psbt"]
238        key_path_tx = wallet.finalizepsbt(key_path_psbt)["hex"]
239        key_path_wtxid = node_master.decoderawtransaction(key_path_tx)["hash"]
240        assert_not_equal(script_path_wtxid, key_path_wtxid)
241
242        # Store variant A through the mempool; store variant B by mining it. The
243        # confirmed (key path) variant becomes canonical, the script path an alternate.
244        txid = node_master.sendrawtransaction(script_path_tx)
245        wallet.syncwithvalidationinterfacequeue()
246        block_hash = self.generateblock(node_master, node_miner.getnewaddress(), [key_path_tx], sync_fun=self.no_op)["hash"]
247        self.sync_blocks([node_miner, node_master, node_old])
248        wallet.syncwithvalidationinterfacequeue()
249        assert_equal(wallet.gettransaction(txid)["alternate_wtxids"], [script_path_wtxid])
250        wallet.unloadwallet()

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.