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.

90,523 bytes · SHA-256 77b23d80831dc6f5… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2020-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 Migrating a wallet from legacy to descriptor."""
6from contextlib import suppress
7from pathlib import Path
8import json
9import os.path
10import random
11import shutil
12import struct
13import time
14from decimal import Decimal
15
16from test_framework.address import (
17    key_to_p2pkh,
18    key_to_p2wpkh,
19    script_to_p2sh,
20    script_to_p2wsh,
21)
22from test_framework.descriptors import descsum_create
23from test_framework.key import ECPubKey
24from test_framework.test_framework import BitcoinTestFramework
25from test_framework.messages import COIN, CTransaction, CTxOut, ser_string
26from test_framework.script import hash160
27from test_framework.script_util import key_to_p2pkh_script, key_to_p2pk_script, script_to_p2sh_script, script_to_p2wsh_script
28from test_framework.util import (
29    assert_equal,
30    assert_greater_than,
31    assert_raises_rpc_error,
32    find_vout_for_address,
33    sha256sum_file,
34)
35from test_framework.wallet_util import (
36    get_generate_key,
37    generate_keypair,
38)
39
40BTREE_MAGIC = 0x053162
41
42
43class WalletMigrationTest(BitcoinTestFramework):
44    def set_test_params(self):
45        self.setup_clean_chain = True
46        self.num_nodes = 2
47        self.supports_cli = False
48        self.extra_args = [[], ["-deprecatedrpc=create_bdb"]]
49
50    def skip_test_if_missing_module(self):
51        self.skip_if_no_wallet()
52        self.skip_if_no_previous_releases()
53
54    def setup_nodes(self):
55        self.add_nodes(
56            self.num_nodes,
57            extra_args=self.extra_args,
58            versions=[
59                None,
60                280200,
61            ],
62        )
63        self.start_nodes()
64        self.init_wallet(node=0)
65
66    def assert_is_sqlite(self, wallet_name, wallet_loaded = True):
67        wallet_file_path = self.master_node.wallets_path / wallet_name / self.wallet_data_filename
68        with open(wallet_file_path, 'rb') as f:
69            file_magic = f.read(16)
70            assert_equal(file_magic, b'SQLite format 3\x00')
71        # if the wallet is not loaded we can't ask the node about it
72        if wallet_loaded:
73            assert_equal(self.master_node.get_wallet_rpc(wallet_name).getwalletinfo()["format"], "sqlite")
74
75    def assert_is_bdb(self, wallet_name):
76        with open(self.master_node.wallets_path / wallet_name / self.wallet_data_filename, "rb") as f:
77            data = f.read(16)
78            _, _, magic = struct.unpack("QII", data)
79            assert_equal(magic, BTREE_MAGIC)
80
81    def create_legacy_wallet(self, wallet_name, **kwargs):
82        self.old_node.createwallet(wallet_name=wallet_name, descriptors=False, **kwargs)
83        wallet = self.old_node.get_wallet_rpc(wallet_name)
84        info = wallet.getwalletinfo()
85        assert_equal(info["descriptors"], False)
86        assert_equal(info["format"], "bdb")
87        return wallet
88
89    def assert_addr_info_equal(self, addr_info, addr_info_old):
90        assert_equal(addr_info["address"], addr_info_old["address"])
91        assert_equal(addr_info["scriptPubKey"], addr_info_old["scriptPubKey"])
92        assert_equal(addr_info["ismine"], addr_info_old["ismine"])
93        assert_equal(addr_info["hdkeypath"], addr_info_old["hdkeypath"].replace("'","h"))
94        assert_equal(addr_info["solvable"], addr_info_old["solvable"])
95        assert_equal(addr_info["ischange"], addr_info_old["ischange"])
96        assert_equal(addr_info["hdmasterfingerprint"], addr_info_old["hdmasterfingerprint"])
97
98    def assert_list_txs_equal(self, received_list_txs, expected_list_txs):
99        for d in received_list_txs:
100            if "parent_descs" in d:
101                del d["parent_descs"]
102        for d in expected_list_txs:
103            if "parent_descs" in d:
104                del d["parent_descs"]
105        assert_equal(received_list_txs, expected_list_txs)
106
107    def check_address(self, wallet, addr, is_mine, is_change, label):
108        addr_info = wallet.getaddressinfo(addr)
109        assert_equal(addr_info['ismine'], is_mine)
110        assert_equal(addr_info['ischange'], is_change)
111        if label is not None:
112            assert_equal(addr_info['labels'], [label]),
113        else:
114            assert_equal(addr_info['labels'], []),
115
116    def migrate_and_get_rpc(self, wallet_name, **kwargs):
117        # Since we may rescan on loading of a wallet, make sure that the best block
118        # is written before beginning migration
119        # Reload to force write that record
120        self.old_node.unloadwallet(wallet_name)
121        self.old_node.loadwallet(wallet_name)
122        assert_equal(self.old_node.get_wallet_rpc(wallet_name).getwalletinfo()["descriptors"], False)
123        # Now unload so we can copy it to the master node for the migration test
124        self.old_node.unloadwallet(wallet_name)
125        if wallet_name == "":
126            shutil.copyfile(self.old_node.wallets_path / "wallet.dat", self.master_node.wallets_path / "wallet.dat")
127        else:
128            src = os.path.abspath(self.old_node.wallets_path / wallet_name)
129            dst = os.path.abspath(self.master_node.wallets_path / wallet_name)
130            if src != dst :
131                shutil.copytree(self.old_node.wallets_path / wallet_name, self.master_node.wallets_path / wallet_name, dirs_exist_ok=True)
132        # Check that the wallet shows up in listwalletdir with a warning about migration
133        wallets = self.master_node.listwalletdir()
134        for w in wallets["wallets"]:
135            if w["name"] == wallet_name:
136                assert_equal(w["warnings"], ["This wallet is a legacy wallet and will need to be migrated with migratewallet before it can be loaded"])
137
138        # migratewallet uses current time in naming the backup file, set a mock time
139        # to check that this works correctly.
140        mocked_time = int(time.time())
141        self.master_node.setmocktime(mocked_time)
142        # Migrate, checking that rescan does not occur
143        with self.master_node.assert_debug_log(expected_msgs=[], unexpected_msgs=["Rescanning"]):
144            migrate_info = self.master_node.migratewallet(wallet_name=wallet_name, **kwargs)
145        self.master_node.setmocktime(0)
146        # Update wallet name in case the initial wallet was completely migrated to a watch-only wallet
147        # (in which case the wallet name would be suffixed by the 'watchonly' term)
148        migrated_wallet_name = migrate_info['wallet_name']
149        wallet = self.master_node.get_wallet_rpc(migrated_wallet_name)
150        wallet_info = wallet.getwalletinfo()
151        assert_equal(wallet_info["descriptors"], True)
152        self.assert_is_sqlite(migrated_wallet_name)
153        # Always verify the backup path exist after migration
154        assert os.path.exists(migrate_info['backup_path'])
155        if wallet_name == "":
156            backup_prefix = "default_wallet"
157        else:
158            backup_prefix = os.path.basename(os.path.realpath(self.old_node.wallets_path / wallet_name))
159
160        backup_filename = f"{backup_prefix}_{mocked_time}.legacy.bak"
161        expected_backup_path = self.master_node.wallets_path / backup_filename
162        assert_equal(str(expected_backup_path), migrate_info['backup_path'])
163        assert {"name": backup_filename} not in self.master_node.listwalletdir()["wallets"]
164
165        # Open the wallet with sqlite and verify that the wallet has the last hardened cache flag
166        # set and the last hardened cache entries
167        def check_last_hardened(conn):
168            flags_rec = conn.execute(f"SELECT value FROM main WHERE key = x'{ser_string(b'flags').hex()}'").fetchone()
169            flags = int.from_bytes(flags_rec[0], byteorder="little")
170
171            # All wallets should have the upgrade flag set
172            assert_equal(bool(flags & (1 << 2)), True)
173
174            # Fetch all records with the walletdescriptorlhcache prefix
175            # if the wallet has private keys and is not blank
176            if wallet_info["private_keys_enabled"] and not wallet_info["blank"]:
177                lh_cache_recs = conn.execute(f"SELECT value FROM main where key >= x'{ser_string(b'walletdescriptorlhcache').hex()}' AND key < x'{ser_string(b'walletdescriptorlhcachf').hex()}'").fetchall()
178                assert_greater_than(len(lh_cache_recs), 0)
179
180        inspect_path = os.path.join(self.options.tmpdir, os.path.basename(f"{migrated_wallet_name}_inspect.dat"))
181        wallet.backupwallet(inspect_path)
182        self.inspect_sqlite_db(inspect_path, check_last_hardened)
183
184        return migrate_info, wallet
185
186    def test_basic(self):
187        # Update listtransctions' output from old nodes to be compatible
188        def listtransactions_compatibility(list):
189            deprecated_keys = {"bip125-replaceable"}
190            for obj in list:
191                for key in deprecated_keys:
192                    obj.pop(key)
193                obj["alternate_wtxids"] = []
194            return list
195
196        default = self.master_node.get_wallet_rpc(self.default_wallet_name)
197
198        self.log.info("Test migration of a basic keys only wallet without balance")
199        basic0 = self.create_legacy_wallet("basic0")
200
201        addr = basic0.getnewaddress()
202        change = basic0.getrawchangeaddress()
203
204        old_addr_info = basic0.getaddressinfo(addr)
205        old_change_addr_info = basic0.getaddressinfo(change)
206        assert_equal(old_addr_info["ismine"], True)
207        assert_equal(old_addr_info["hdkeypath"], "m/0'/0'/0'")
208        assert_equal(old_change_addr_info["ismine"], True)
209        assert_equal(old_change_addr_info["hdkeypath"], "m/0'/1'/0'")
210
211        # Note: migration could take a while.
212        _, basic0 = self.migrate_and_get_rpc("basic0")
213
214        # The wallet should create the following descriptors:
215        # * BIP32 descriptors in the form of "0h/0h/*" and "0h/1h/*" (2 descriptors)
216        # * BIP44 descriptors in the form of "44h/1h/0h/0/*" and "44h/1h/0h/1/*" (2 descriptors)
217        # * BIP49 descriptors, P2SH(P2WPKH), in the form of "86h/1h/0h/0/*" and "86h/1h/0h/1/*" (2 descriptors)
218        # * BIP84 descriptors, P2WPKH, in the form of "84h/1h/0h/1/*" and "84h/1h/0h/1/*" (2 descriptors)
219        # * BIP86 descriptors, P2TR, in the form of "86h/1h/0h/0/*" and "86h/1h/0h/1/*" (2 descriptors)
220        # * A combo(PK) descriptor for the wallet master key.
221        # So, should have a total of 11 descriptors on it.
222        assert_equal(len(basic0.listdescriptors()["descriptors"]), 11)
223
224        # Compare addresses info
225        addr_info = basic0.getaddressinfo(addr)
226        change_addr_info = basic0.getaddressinfo(change)
227        self.assert_addr_info_equal(addr_info, old_addr_info)
228        self.assert_addr_info_equal(change_addr_info, old_change_addr_info)
229
230        addr_info = basic0.getaddressinfo(basic0.getnewaddress("", "bech32"))
231        assert_equal(addr_info["hdkeypath"], "m/84h/1h/0h/0/0")
232
233        self.log.info("Test migration of a basic keys only wallet with a balance")
234        basic1 = self.create_legacy_wallet("basic1")
235
236        for _ in range(0, 10):
237            default.sendtoaddress(basic1.getnewaddress(), 1)
238
239        self.generate(self.master_node, 1)
240
241        for _ in range(0, 5):
242            basic1.sendtoaddress(default.getnewaddress(), 0.5)
243
244        self.generate(self.master_node, 1)
245        bal = basic1.getbalance()
246        txs = basic1.listtransactions()
247        addr_gps = basic1.listaddressgroupings()
248
249        basic1_migrate, basic1 = self.migrate_and_get_rpc("basic1")
250        assert_equal(basic1.getbalance(), bal)

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.