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

ReviewabilityReviewsAgreementSize
#32861 Sjors Have createwalletdescriptor auto-detect an unused(KEY)Ready0Strong49 + 25 tests
  • Auto-detect unused HD keys during descriptor creation so users do not need to copy-paste xpubs
  • Streamlines scripted blank wallet setups and prevents importing duplicate HD keys
  • Ready to review
  • Substantive support after testing (adyshimony)
  • Concept approval without stated reasons (w0xlt, jeanpablojp)
  • Resolved objections about duplicate key checks and code reuse (adyshimony, jeanpablojp)
  • Answered concern regarding whether to delete unused descriptors in this change (rkrux)
  • 49 lines added or modified outside tests
  • 25 lines added or modified in tests
  • 9 lines removed in total
  • 7 files, 5 commits
Wallet#56 of 92
P3 · new feature
  • P3 because it improves RPC ergonomics for automated and scripted descriptor wallet setups
  • Offers moderate usability gains for wallet configuration without affecting fund safety
Ranking notes
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.

Goal

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.

Reviewability

Ready

Nothing known that would invalidate a review now.

Agreement

Strong

substantive support, no open objection (adyshimony)

Thread notes: First read of PR 32861. All concerns raised (rkrux regarding unused descriptor deletion, adyshimony on duplicate xprv checks, and jeanpablojp regarding code deduplication) were resolved.

Objections, suggestions, and questions:

ReviewerTypeHarm, request, or questionStatusMust beAuthor repliedQuote
rkrux (member)objection, scopeleaving unused(KEY) descriptors in the wallet after they have been used is confusing and violates the intended workflowanswered · v1, not yet re-checkedansweredyes2025-07-18: 'Shouldn't we add the deletion of the unused descriptor in this PR itself?'
Status from: 2025-07-25: Sjors: 'That should be done in #29136 which introduces createwalletdescriptor, or in a followup, but not in this PR'
adyshimony (none)objection, correctnessallows adding the same private key twice if the wallet already has it through an active descriptorfixed · fix pushed · v1, not yet re-checkedansweredyes2026-02-21: 'A check is needed here to prevent adding the same private key twice.'
Status from: 2026-05-14: Sjors: 'Rebased after #29136 landed and included suggestions from @adyshimony.'
jeanpablojp (contributor)objection, maintenanceintroduces redundant helper GetScriptlessSPKMs() instead of reusing existing GetHDPubKeys(HDKeyFilter::UnusedKey)fixed · fix pushed · v1, not yet re-checkedansweredyes2026-08-24: 'GetHDPubKeys(HDKeyFilter::UnusedKey) already returns this set, and derivehdkey uses it further down in this same file.'
Status from: 2026-08-25: Sjors: 'I dropped f336199336f619f6c361e56da06e36aa46f776c8, as it's indeed superseded by GetHDPubKeys(HDKeyFilter::UnusedKey)'

Support:

  • adyshimony (none) (Approach ACK, 2026-02-21): Reviewed and tested c8b6d4ee2abbd1271e44aa66da6079cee6323529
  • w0xlt (contributor) (Concept ACK, 2026-06-08): Concept ACK [not substantive]
  • jeanpablojp (contributor) (Concept ACK, 2026-08-24): Concept ACK [not substantive]

Participants:

  • rkrux (member, objection, 3 statements 2025-07-18 to 2025-07-18): argued unused descriptors should be deleted once used
  • adyshimony (none, support, 4 statements 2026-02-21 to 2026-02-21): Concept and Approach ACK; noted missing duplicate check when calling addhdkey with existing xprv
  • w0xlt (contributor, support, 1 statements 2026-06-08 to 2026-06-08): Concept ACK
  • jeanpablojp (contributor, support, 2 statements 2026-08-24 to 2026-08-24): Concept ACK; suggested reusing GetHDPubKeys(HDKeyFilter::UnusedKey) and asked about lookup behavior

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

The short text the ranking pass compares across PRs.

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 ledger, generated 2026-09-18T03:44, confidence high, input hash e8f3ae3191ad7dd9
thread read through 2026-09-14 (19 statements), head bf0af8ae29
Discussion read under schema 1 rules: suggestions and questions may be missing, and an objection may combine several harms (schema history).
labels: none

Categories

Wallet

P3 · new feature

Improves RPC ergonomics by allowing createwalletdescriptor to auto-detect an unused HD key instead of requiring manual copy-pasting from gethdkeys. This provides a clear usability improvement for scripted descriptor wallet setups, but does not impact fund safety or fix a critical bug.

Membership: Modifies src/wallet/rpc/wallet.cpp and src/wallet/wallet.cpp to improve descriptor and HD key management.

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