wallet: add gethdkey RPC for BIP 32 key derivation #34438

1. 
   w0xlt commented at 2:21 am on January 29, 2026: contributor

   Revives #22341 (marked “up for grabs”).

   Add gethdkey RPC to derive an extended key at any BIP 32 path from the wallet’s active HD key. This enables exporting xpubs/xprvs for external setups (e.g., BIP 87 multisig) without modifying the wallet’s keypool.

    0$ bitcoin-cli gethdkey "m/87'/0'/0'"
    1{
    2    "xpub": "xpub6...",
    3    "fingerprint": "1a2b3c4d",
    4    "origin": "[1a2b3c4d/87'/0'/0']" 
    5}                                                                                                                                     
    6                                                                                                                                        
    7$ bitcoin-cli gethdkey "m/87'/0'/0'" '{"private": true}' 
    8{
    9    "xpub": "xpub6...",
   10    "xprv": "xprv9...",
   11    .. 
   12}
   

   Use case: Users setting up multisig (e.g., with hardware wallets or other software) need xpubs at specific derivation paths. Currently this there is no way to extract a specific path from wallets in Bitcoin Core.

   Design: Intentionally simple, only exports key info. To sign with derived keys, users import the returned xprv via importdescriptors. This keeps all signing through the normal keypool mechanism.

2. util: support 'h' as hardened marker in ParseHDKeypath

   Allow paths like "m/84h/0h/0h" in addition to "m/84'/0'/0'".
   This aligns with descriptor notation where both markers are valid.
   
   Co-Authored-By: Sjors Provoost <sjors@sprovoost.nl>

   16d2695a8e
3. wallet: add gethdkey RPC for BIP 32 key derivation

   Add a new RPC that derives an extended key at any BIP 32 path from the
   wallet's active HD key. This enables exporting xpubs for use in external
   setups (e.g., BIP 87 multisig) without modifying the wallet's keypool.
   
   The RPC returns the xpub, master fingerprint, and origin info in
   descriptor format. With the "private" option, it also returns the xprv.
   Hardened derivation requires the wallet to be unlocked.
   
   This RPC is intentionally simple: it only exports key information.
   Users who want to sign with keys at custom derivation paths
   should use the returned xprv with importdescriptors to add the
   descriptor to their wallet's keypool. This ensures all signing goes
   through the normal keypool mechanism.
   
   Co-Authored-By: Sjors Provoost <sjors@sprovoost.nl>

   d2ba62fa90
4. test: add functional tests for gethdkey RPC

   Cover BIP 32 derivation correctness, basic functionality, path format
   validation, error cases, and a 2-of-3 multisig workflow using keys
   derived at the BIP 87 path.
   
   Co-Authored-By: Sjors Provoost <sjors@sprovoost.nl>

   bb657f9d96
5. doc: update multisig tutorial to use gethdkey RPC

   Replace the listdescriptors-based xpub extraction with gethdkey,
   enabling proper BIP 87 multisig derivation path (m/87'/1'/0').
   
   Changes:
   - Use gethdkey to derive keys at the standard multisig path
   - Add section 1.4 explaining how to import the multisig descriptor
     with private keys into participant wallets for signing
   - Simplify xpub extraction (no more jq/grep/sed pipeline)
   - Update section numbering (1.4 Fund -> 1.5, etc.)
   
   Co-Authored-By: Sjors Provoost <sjors@sprovoost.nl>

   b4dbab25bf
6. DrahtBot renamed this:
   wallet: add `gethdkey` RPC for BIP 32 key derivation
   wallet: add `gethdkey` RPC for BIP 32 key derivation
   on Jan 29, 2026
7. DrahtBot added the label Wallet on Jan 29, 2026
8. 
   DrahtBot commented at 2:22 am on January 29, 2026: contributor

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

   Reviews

   See the guideline for information on the review process. A summary of reviews will appear here.

   Conflicts

   Reviewers, this pull request conflicts with the following ones:

   • #34049 (rpc: Disallow captures in RPCMethodImpl by ajtowns)
   • #32784 (wallet: derivehdkey RPC to get xpub at arbitrary path by Sjors)

   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:

   • One signed by participant_1 wallet and other, by the participant_2 wallet. -> One signed by the participant_1 wallet and the other by the participant_2 wallet. [Fixes missing articles and word order to make the sentence grammatical and clear]

   2026-01-29 02:22:54

9. 
   rkrux commented at 2:19 pm on February 6, 2026: contributor

   This seems quite similar to #32784, possibly a subset of the functionality provided by it.

   Like in the other PR, the name derivehdkey seems more appropriate to me - gethdkey gives the impression that something is being gotten from the wallet storage (read database).

10. 
    w0xlt commented at 2:51 pm on February 6, 2026: contributor

    I wasn’t aware of #32784. Thanks for letting me know. Closing this in favor of that PR.
11. w0xlt closed this on Feb 6, 2026

    ---

12. w0xlt deleted the branch on Feb 6, 2026

Contributors
w0xlt DrahtBot rkrux

Labels
Wallet