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.

59,055 bytes · SHA-256 4fd93963fa03f237… · 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"""Test the importdescriptors RPC.
6
7Test importdescriptors by generating keys on node0, importing the corresponding
8descriptors on node1 and then testing the address info for the different address
9variants.
10
11- `get_generate_key()` is called to generate keys and return the privkeys,
12  pubkeys and all variants of scriptPubKey and address.
13- `test_importdesc()` is called to send an importdescriptors call to node1, test
14  success, and (if unsuccessful) test the error code and error message returned.
15- `test_address()` is called to call getaddressinfo for an address on node1
16  and test the values returned."""
17
18import concurrent.futures
19import threading
20import time
21
22from test_framework.address import key_to_p2sh_p2wpkh, key_to_p2wpkh, script_to_p2wsh
23from test_framework.blocktools import COINBASE_MATURITY
24from test_framework.test_framework import BitcoinTestFramework
25from test_framework.descriptors import descsum_create
26from test_framework.extendedkey import ExtendedPrivateKey
27from test_framework.script import SEQUENCE_LOCKTIME_TYPE_FLAG
28from test_framework.script_util import keys_to_multisig_script
29from test_framework.util import (
30    assert_equal,
31    assert_raises_rpc_error,
32    JSONRPCException,
33)
34from test_framework.wallet_util import (
35    get_generate_key,
36    test_address,
37)
38
39MISSING_KEYS_WARNING = "Not all private keys provided. Some wallet functionality may return unexpected errors"
40
41class ImportDescriptorsTest(BitcoinTestFramework):
42    def set_test_params(self):
43        self.num_nodes = 2
44        # whitelist peers to speed up tx relay / mempool sync
45        self.noban_tx_relay = True
46        self.extra_args = [["-addresstype=legacy"],
47                           ["-addresstype=bech32", "-keypool=5"]
48                          ]
49        self.setup_clean_chain = True
50        self.wallet_names = []
51
52    def skip_test_if_missing_module(self):
53        self.skip_if_no_wallet()
54
55    def test_importdesc(self, req, success, global_error=False, error_code=None, error_message=None, warnings=None, wallet=None):
56        """Run importdescriptors and assert success"""
57        if warnings is None:
58            warnings = []
59        wrpc = self.nodes[1].get_wallet_rpc('w1')
60        if wallet is not None:
61            wrpc = wallet
62
63        if global_error and not success:
64            try:
65                result = wrpc.importdescriptors([req])
66            except JSONRPCException as e:
67                assert_equal(e.error["code"], error_code)
68                assert_equal(e.error["message"], error_message)
69                return
70
71        result = wrpc.importdescriptors([req])
72        observed_warnings = []
73        if 'warnings' in result[0]:
74            observed_warnings = result[0]['warnings']
75        assert_equal("\n".join(sorted(warnings)), "\n".join(sorted(observed_warnings)))
76        self.log.debug(result)
77        assert_equal(result[0]['success'], success)
78        if error_code is not None:
79            assert_equal(result[0]['error']['code'], error_code)
80            assert_equal(result[0]['error']['message'], error_message)
81
82    def test_import_unused_key(self):
83        self.log.info("Test import of unused(KEY)")
84        self.nodes[0].createwallet(wallet_name="import_unused", blank=True)
85        wallet = self.nodes[0].get_wallet_rpc("import_unused")
86
87        assert_equal(len(wallet.gethdkeys()), 0)
88
89        extended_key = ExtendedPrivateKey.generate()
90        xprv = extended_key.to_string()
91        xpub = extended_key.pubkey().to_string()
92        self.test_importdesc({"desc":descsum_create(f"unused({xpub})"),
93                              "timestamp": "now"},
94                              success=False,
95                              error_code=-4,
96                              error_message='Cannot import descriptor without private keys to a wallet with private keys enabled',
97                              wallet=wallet)
98        self.test_importdesc({"timestamp": "now", "desc": descsum_create(f"unused({xprv})")},
99                             success=True,
100                             wallet=wallet)
101        hdkeys = wallet.gethdkeys()
102        assert_equal(len(hdkeys), 1)
103        assert_equal(hdkeys[0]["xpub"], xpub)
104        wallet.unloadwallet()
105
106    def test_import_unused_key_existing(self):
107        self.log.info("Test import of unused(KEY) with existing KEY")
108        self.nodes[0].createwallet(wallet_name="import_existing_unused")
109        wallet = self.nodes[0].get_wallet_rpc("import_existing_unused")
110
111        hdkeys = wallet.gethdkeys(private=True)
112        assert_equal(len(hdkeys), 1)
113        xprv = hdkeys[0]["xprv"]
114
115        self.test_importdesc({"timestamp": "now", "desc": descsum_create(f"unused({xprv})")},
116                             success=False,
117                             error_code=-4,
118                             error_message="Cannot import an unused() descriptor when its private key is already in the wallet",
119                             wallet=wallet)
120        wallet.unloadwallet()
121
122    def test_import_unused_noprivs(self):
123        self.log.info("Test import of unused(KEY) to wallet without privkeys")
124        self.nodes[0].createwallet(wallet_name="import_unused_noprivs", disable_private_keys=True)
125        wallet = self.nodes[0].get_wallet_rpc("import_unused_noprivs")
126
127        xpub = ExtendedPrivateKey.generate().pubkey().to_string()
128        self.test_importdesc({"timestamp": "now", "desc": descsum_create(f"unused({xpub})")},
129                             success=False,
130                             error_code=-4,
131                             error_message="Cannot import unused() to wallet without private keys enabled",
132                             wallet=wallet)
133        wallet.unloadwallet()
134
135    def test_per_item_errors_are_reported_in_order(self):
136        self.log.info("Test that import results are in the same order as the original request")
137        self.nodes[0].createwallet(wallet_name="test_order_import", blank=True)
138        wallet = self.nodes[0].get_wallet_rpc('test_order_import')
139        whitespace_pubkey = f" {get_generate_key().pubkey}"
140        cases = [
141            ({
142                "timestamp": "now"
143            }, [False, "Descriptor not found."]),
144            ({
145                "desc": descsum_create(f"pkh({get_generate_key().privkey})"),
146                "timestamp": 1,
147                "label": "Valid descriptor 1",
148            }, [True]),
149            ({
150                "desc": descsum_create(f"pkh({get_generate_key().privkey})"),
151                "timestamp": "now",
152                "internal": True,
153            }, [True]),
154            ({
155                "desc": descsum_create(f"pkh({get_generate_key().pubkey})"),
156                "timestamp": "now",
157                "label": "Invalid descriptor 2",
158                "internal": True,
159            }, [False, "Internal addresses should not have a label"]),
160            ({
161                "desc": descsum_create(f"pkh({whitespace_pubkey})"),
162                "timestamp": "now",
163                "internal": True,
164            }, [False, f"pkh(): Key '{whitespace_pubkey}' is invalid due to whitespace"]),
165        ]
166
167        descriptors, expected = map(list, zip(*cases))
168        results = wallet.importdescriptors(descriptors)
169        for i, result in enumerate(results):
170            assert_equal(result["success"], expected[i][0])
171            if not result["success"]:
172                assert_equal(result["error"]["message"], expected[i][1])
173
174    def test_rescan_fails_import(self):
175        xpriv = ExtendedPrivateKey.generate().to_string()
176
177        self.log.info("Test importdescriptors fails when wallet is already rescanning")
178        wallet_name = "rescan_wallet"
179        self.nodes[0].createwallet(wallet_name=wallet_name, blank=True)
180        other_desc = descsum_create("pkh(" + get_generate_key().privkey + ")")
181
182        w_import = self.nodes[0].create_new_rpc_connection(mode="AUTHPROXY") / f"wallet/{wallet_name}"
183
184        with concurrent.futures.ThreadPoolExecutor(max_workers=2) as thread:
185            w_rescan = self.nodes[0].create_new_rpc_connection(mode="AUTHPROXY") / f"wallet/{wallet_name}"
186            w_conflict = self.nodes[0].create_new_rpc_connection(mode="AUTHPROXY") / f"wallet/{wallet_name}"
187            # Use an xprv with timestamp=0 and a large key-range to trigger a slow full rescan that stays in-flight
188            slow_desc = [{"desc": descsum_create("pkh(" + xpriv + "/0h/*h)"),
189            "timestamp": 0, "range": [0, 10000]}]
190            conflicting_desc = [{"desc": descsum_create("pkh(" + xpriv + "/1h/*h)"),
191            "timestamp": 0, "range": [0, 10000]}]
192            num_relevant_blocks = 1000
193            self.generatetoaddress(self.nodes[0], num_relevant_blocks, self.nodes[0].deriveaddresses(slow_desc[0]['desc'], [0, 0])[0])
194            self.generatetoaddress(self.nodes[0], num_relevant_blocks, self.nodes[0].deriveaddresses(conflicting_desc[0]['desc'], [0, 0])[0])
195
196            start = threading.Barrier(3)
197
198            def import_after_barrier(wallet, descriptors):
199                start.wait(timeout=10)
200                return wallet.importdescriptors(descriptors)
201
202            imports = [
203                thread.submit(import_after_barrier, w_rescan, slow_desc),
204                thread.submit(import_after_barrier, w_conflict, conflicting_desc),
205            ]
206            start.wait(timeout=10)
207
208            # One importdescriptor call must hold WalletRescanReserver while the other fails immediately.
209            num_errors = 0
210            num_success = 0
211            for future in concurrent.futures.as_completed(imports, timeout=30 * self.options.timeout_factor):
212                try:
213                    assert_equal(future.result(), [{'success': True}])
214                    num_success += 1
215                except JSONRPCException as e:
216                    assert_equal(e.error["code"], -4)
217                    assert_equal(e.error["message"], "Wallet is currently rescanning. Abort existing rescan or wait.")
218                    num_errors += 1
219
220            assert_equal(num_success, 1)
221            assert_equal(num_errors, 1)
222
223        # After the rescan finishes, any importdescriptors should succeed.
224        result = w_import.importdescriptors([{"desc": other_desc, "timestamp": "now"}])
225        assert_equal(result[0]['success'], True)
226
227        self.log.info("Aborting an importdescriptors rescan should fail the RPC call")
228        wallet_name = "abort_import_wallet"
229        self.nodes[0].createwallet(wallet_name, blank=True)
230
231        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as thread:
232            w_import = self.nodes[0].create_new_rpc_connection(mode="AUTHPROXY") / f"wallet/{wallet_name}"
233            abort_rpc = self.nodes[0].create_new_rpc_connection(mode="AUTHPROXY") / f"wallet/{wallet_name}"
234            descriptor = [{"desc": descsum_create("pkh(" + xpriv + "/2h/*h)"),
235            "timestamp": 0, "range": [0, 4000]}]
236
237            importing = thread.submit(w_import.importdescriptors, descriptor)
238
239            # Keep trying because an abort before ScanForWalletTransactions starts
240            # is reset when the scan loop begins.
241            abort_succeeded = False
242            abort_deadline = time.time() + 30 * self.options.timeout_factor
243            while not importing.done() and time.time() < abort_deadline:
244                abort_succeeded = abort_rpc.abortrescan() or abort_succeeded
245
246            assert_equal(abort_succeeded, True)
247            try:
248                importing.result(timeout=30 * self.options.timeout_factor)
249                raise AssertionError("importdescriptors unexpectedly succeeded")
250            except JSONRPCException as e:

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.