wallet: Allow importing of descriptors without private keys when the wallet has the private keys #35377

pull achow101 wants to merge 7 commits into bitcoin:master from achow101:importdescriptors-without-priv changing 12 files +622 −277

achow101 commented at 11:55 PM on May 25, 2026: member

Currently importing a descriptor to a wallet that has private keys requires the descriptor to include the private keys. This is not ideal as it means exposing private key material. This PR makes it so that the wallet will lookup and substitute the private keys for their respective public keys in such descriptors, thus enabling importing of public descriptors into wallets with private keys.

The underlying mechanism is that the wallet retrieves all of the pubkeys from the descriptor and checks to see if any of them have private keys in any ScriptPubKeyMan. Additionally, if the descriptor has a xpub with key origin info, we will check if any xprvs known to the wallet have a matching fingerprint and derive to the specified xpub. If so, the origin + xpub are replaced with the single xprv with the origin derivation path prepended to the key expression's derivation path.

Possible future work is to allow the xpub substitution to work when the wallet has some child in the key origin, i.e. the wallet xprv has a key origin that is a prefix of the key origin specified for an xpub in the descriptor. Currently this kind of substitution is not being done, only root master xprvs will be substituted.

If a wallet does not have the private keys for a public descriptor, the import is still disallowed.

This PR is based on #34861 to avoid an annoying rebase.

Closes #27336
DrahtBot added the label Wallet on May 25, 2026
DrahtBot commented at 11:55 PM on May 25, 2026: contributor


The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.



Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35377.



Reviews

See the guideline for information on the review process.

Type Reviewers

Concept ACK rkrux, polespinasa

If your review is incorrectly listed, please copy-paste <code></code> into the comment that the bot should ignore.



Conflicts

Reviewers, this pull request conflicts with the following ones:
- #35493 (wallet, descriptor: Fix MuSig private key completeness checks on importdescriptors by w0xlt)
- #35436 (wallet: Add addHDkey interface by pseudoramdom)
- #34861 (wallet: Add importdescriptors interface by polespinasa)
- #34681 (wallet: move rescan logic into ChainScanner and wallet/scan by Eunovo)
- #34520 (refactor: Add [[nodiscard]] to functions returning bool+mutable ref by maflcko)
- #33392 (wallet, rpc: add UTXO set check and incremental rescan to importdescriptors by musaHaruna)
If you consider this pull request important, please also help to review the conflicting pull requests. Ideally, start with the one that should be merged first.



LLM Linter (✨ experimental)

Possible typos and grammar issues:
- // Whether ' or h is used in harded derivation -> // Whether ' or h is used in hardened derivation [misspelled word]
- self.log.info("Test import of descriptors without private keys that the wallet has the privkeys for") / xpub substition -> xpub substitution [misspelled word]
2026-06-13 02:22:27
DrahtBot added the label Needs rebase on May 26, 2026
achow101 force-pushed on May 26, 2026
DrahtBot removed the label Needs rebase on May 26, 2026
rkrux commented at 10:28 AM on June 5, 2026: contributor

Definite Concept ACK 2e6d8d0 because it allows the users to not deal with private keys manually.
polespinasa commented at 10:15 AM on June 8, 2026: member

seems like a good idea, concept ACK

Will review after #34861 is merged
DrahtBot added the label Needs rebase on Jun 12, 2026

Type	Reviewers
Concept ACK	rkrux, polespinasa

wallet: Add ImportDescriptorRequest and ImportDescriptorResult structs

Add two new structs used for creating requests and getting response when importing descriptors.

These structs replace the UniValue-based interface of ProcessDescriptorImport()
in a subsequent commit.

12f5d18b8c

wallet: refactor importdescriptors RPC

Rename ProcessDescriptorImport() to ImportDescriptor() and replace its
UniValue-based arguments and return value with the ImportDescriptorRequest
and ImportDescriptorResult structs introduced in the previous commit.

Add ProcessDescriptorsImport() to handle wallet locking and rescanning
over a vector of ImportDescriptorRequest items.

Add ProcessUniValueDescriptor() to translat from the UniValue arguments
used by the importdescriptors RPC into ImportDescriptorRequest.

This allows a next commit to extract ImportDescriptor() and
ProcessDescriptorsImport() out of the RPC code so they can be used by
other future interfaces.

Lowers the minimum timestamps to 0 instead of 1.

d86e01c601

wallet: Move ImportDescriptor and ProcessDescriptorsImport to imports.cpp

Extract ImportDescriptor() and ProcessDescriptorsImport() out of backup.cpp and move it into imports.cpp so other future interfaces
can use them without needing to know about RPC code.

The commit can be reviewed with the --color-moved=dimmed-zebra option for an easier review.

0931e32700

wallet: Add an importDescriptors() interface for the wallet 2e47806f2e

descriptor: Implement SubstituteMasterExtPubs

SubstituteMasterExtPubs replaces Origin + BIP32 inside of a descriptor
when a master xprv is provided that matches the origin and derives the
BIP32 xpub.

c99f2e7f2a

wallet: Substitute known keys when importing a descriptor

When an imported descriptor contains pubkeys for which the wallet knows
the private keys, substitute those pubkeys for the privkeys so that the
descriptor can be imported. This allows such descriptors without private keys
to be imported into wallets with private keys enabled.

956bb1ee6b

test: Test importdescriptors with descriptors without privkeys

Test that importdescriptors can import descriptors that don't have
private keys, but the wallet already has the private key for them.

726006c447

achow101 force-pushed on Jun 13, 2026
DrahtBot added the label CI failed on Jun 13, 2026
DrahtBot commented at 3:24 AM on June 13, 2026: contributor


🚧 At least one of the CI tasks failed. Task iwyu: https://github.com/bitcoin/bitcoin/actions/runs/27453755862/job/81154189319 LLM reason (✨ experimental): CI failed because IWYU reported a header include issue (it modified src/script/descriptor.h and deliberately exited with “Failure generated from IWYU”).

<details><summary>Hints</summary>

Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:
- Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.
- A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.
- An intermittent issue.
Leave a comment here, if you need help tracking down a confusing failure.

</details>
DrahtBot removed the label Needs rebase on Jun 13, 2026

Contributors

Labels

Linked (view graph)

#27336 Should be able to import an xpub descriptor to a privkey-enabled wallet if the wallet has the privkeys #34861 wallet: Add importdescriptors interface

wallet: Allow importing of descriptors without private keys when the wallet has the private keys #35377

Code Coverage & Benchmarks

Reviews

Conflicts

LLM Linter (✨ experimental)