#32861 Have createwalletdescriptor auto-detect an unused(KEY)

full analysis

https://github.com/bitcoin/bitcoin/pull/32861 · Sjors · +74/-9 in 7 files, 5 commits · labels: none

Goal

  • Automatically detect unused keys when creating wallet descriptors
  • Avoid requiring users to manually copy-paste xpubs when configuring blank descriptor wallets

Updates `createwalletdescriptor` to inspect `unused(KEY)` descriptors when no active descriptors exist, removing the need to manually pass the `hdkey` parameter. Also prevents `addhdkey` from importing duplicate HD keys and updates `doc/multisig-tutorial.md` to use blank wallets.

Problem: Setting up a blank wallet with `addhdkey` previously forced users to call `gethdkeys` and copy-paste the xpub into `createwalletdescriptor`, making automated or scripted setups unnecessarily clunky.

Category: Wallet (#45 of 84)

P3 · new feature

  • P3 because it is an incremental workflow improvement for descriptor wallets
  • Smooths blank wallet scripting without altering critical wallet safety mechanisms

P3 because this is a worthwhile RPC workflow enhancement for descriptor wallets. As Sjors noted, 'Before this PR the last line would fail, requiring the user to call gethdkeys and copy-paste the xpub', smoothing blank wallet setup without changing consensus or critical wallet safety mechanisms.

Membership: Modifies wallet RPC createwalletdescriptor and CWallet::AddHDKey logic in src/wallet/

Factors: security/stability 1, bug 0, performance 0, user value 2, leverage 1

Reviewability: Ready

  • Ready to review with CI passing and prior reviewer suggestions already incorporated

The code is rebased on master, CI is passing, and prior review suggestions have been implemented.

Author status: active

Resolved concerns:

  • rkrux questioned whether unused descriptors should be deleted once used; Sjors clarified this belongs to #29136 or a followup
  • adyshimony noted missing duplicate check when calling addhdkey with an existing xprv; Sjors added a check and functional test
  • jeanpablojp noted that GetHDPubKeys(HDKeyFilter::UnusedKey) should be reused rather than adding a separate helper; Sjors adopted it

Agreement: Strong

  • Strong support across reviewers with suggestions incorporated
  • Concept and approach approval proposing a duplicate key check that was added (adyshimony)
  • Concept approval suggesting existing helper reuse that was adopted (jeanpablojp)
  • Concept approval without stated reasons (w0xlt)

Strong: Concept and Approach ACKs with all reviewer suggestions incorporated

Multiple reviewers provided Concept and Approach ACKs. Suggestions regarding duplicate key checking and RPC help text were incorporated in subsequent pushes.

  • adyshimony gave Concept ACK and Approach ACK, proposing a duplicate check for addhdkey which was implemented in commit 6d668f0ba2
  • w0xlt provided Concept ACK
  • jeanpablojp gave Concept ACK and suggested reusing GetHDPubKeys(HDKeyFilter::UnusedKey), which Sjors adopted

Review verdicts (DrahtBot): 0

Files

27 lines under test/bench/ci.

  • test/functional/wallet_createwalletdescriptor.py +22/-1
  • doc/multisig-tutorial.md +17/-4
  • src/wallet/rpc/wallet.cpp +16/-3
  • doc/release-notes-32861.md +9/-0
  • src/wallet/wallet.cpp +7/-0
  • src/test/descriptor_tests.cpp +1/-1
  • test/functional/wallet_hd.py +2/-0

Card

This PR improves the wallet RPC workflow by allowing createwalletdescriptor to auto-detect an unused HD key created by addhdkey when no active descriptors exist in the wallet. It also prevents addhdkey from importing duplicate HD keys and updates the multisig tutorial to follow this safer blank-wallet approach. The change is primarily a quality-of-life UX improvement for users and developers configuring descriptor wallets. Review is active and positive with Approach ACKs and suggestions already integrated.

Data

dossier JSON · extract JSON · model openrouter/google/gemini-3.8-flash, generated 2026-09-17T17:11, confidence high, input hash b413aff1c7e9aba0