wallet: derivehdkey RPC to get xpub at arbitrary path

[Sjors]

Adds a derivehdkey RPC that returns an xpub, or optionally the xprv, at an arbitrary BIP32 path (with at least one hardened step), derived from a wallet HD key.

The main use case is coordinating a multisig setup, where each participant shares an xpub derived at a hardened path (e.g. m/87h/0h/0h) distinct from their default single-signature descriptors. See the (updated) doc/multisig-tutorial.md and (updated) functional test to see how that workflow improves.

The first commits are some helpful helpers:

• key: add DeriveExtKey() helper - performs the actual derivation
• test: move parse_hd_keypath test to bip32_tests - from psbt_wallet_tests
• Have ParseHDKeypath handle h derivation marker
• util: reject out-of-range BIP32 keypath indices - ParseHDKeypath would previously map overflowing values without h to hardened.
• fuzz: check ParseHDKeypath/WriteHDKeypath round-trip
• rpc: ParsePathBIP32 helper
• refactor: add hardened derivation helper - HasHardenedDerivation(), to enforce the "at least one hardened step" rule
• wallet: generalize GetActiveHDPubKeys helper - extracts code from gethdkeys which derivehdkey needs
• wallet: add GetExtKey helper - reconstruct an xprv from a wallet xpub (analog of GetKey()); behavior-preserving prep, also simplifies gethdkeys.

Meat and potatoes:

• rpc: add derivehdkey - the RPC itself, plus the UnusedKey filter on GetHDPubKeys that drives key selection.
• test: use derivehdkey in M-of-N multisig demo - rewrites the functional multisig test to use the RPC and <0;1> syntax.
• doc: use derivehdkey in multisig tutorial - same for the prose tutorial.

[DrahtBot]

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/32784.

Reviews

See the guideline and AI policy for information on the review process.

Type	Reviewers
ACK	w0xlt, pseudoramdom, achow101
Concept ACK	rkrux

If your review is incorrectly listed, please copy-paste <!--meta-tag:bot-skip--> into the comment that the bot should ignore.

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #35747 (wallet: Fix FillPSBT failing to sign owned inputs when UTXOs disagree by nervana21)
• #35170 (test: Better test coverage for legacy ParseHDKeypath() by optout21)
• #35069 (Refactor keypath parser by pythcoiner)
• #34502 (wallet: remove most asserts of WALLET_FLAG_DESCRIPTORS flag by rkrux)
• #32861 (Have createwalletdescriptor auto-detect an unused(KEY) 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:

• # Get the activate wpkh() receive descriptor -> # Get the active wpkh() receive descriptor [“activate” is the wrong word here; “active” is intended.]

Possible places where comparison-specific test macros should replace generic comparisons:

• [test/functional/wallet_derivehdkey.py] assert xpub_info_1["xpub"] != xpub_info_2["xpub"] -> recommend assert_not_equal(xpub_info_1["xpub"], xpub_info_2["xpub"])

^{2026-08-07 13:13:06}

[DrahtBot]

🚧 At least one of the CI tasks failed.
_{Task lint: https://github.com/bitcoin/bitcoin/runs/44475268764
LLM reason (✨ experimental): The CI failure is caused by errors from the lint check 'py_lint', specifically due to unused imports flagged by ruff.}

Hints

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.

[DrahtBot]

In util.h: “@params[in] path” → “@param[in] path” [Doxygen tag typo]

[DrahtBot]

addressesd -> addresses [extra “d” makes “addresses” misspelled]

[rkrux]

Very nice, Concept ACK.
I will review this PR.

[Sjors]

Rebased after #35896, which should get rid of ci failures for test: move parse_hd_keypath test to bip32_tests. Took both @w0xlt's suggestions.

[w0xlt]

Code looks good. One question following up on the earlier parent-key leakage discussion #32784 (comment):

HasHardenedDerivation() accepts m/44h/1h/0h/0 because the path contains hardened steps. With private=true, the returned child xprv and public account xpub allow recovery of the account xprv.

Should private output require the final step to be hardened?

possible diff if so.

diff --git a/src/wallet/rpc/wallet.cpp b/src/wallet/rpc/wallet.cpp
index 054ab6b763..a98471c382 100644
--- a/src/wallet/rpc/wallet.cpp
+++ b/src/wallet/rpc/wallet.cpp
@@ -965,7 +965,7 @@ RPCMethod derivehdkey()
         {
             {"path", RPCArg::Type::STR, RPCArg::Optional::NO, "BIP 32 derivation path with at least one hardened step."},
             {"options", RPCArg::Type::OBJ_NAMED_PARAMS, RPCArg::Optional::OMITTED, "", {
-                {"private", RPCArg::Type::BOOL, RPCArg::Default{false}, "Show private key"},
+                {"private", RPCArg::Type::BOOL, RPCArg::Default{false}, "Show private key. The final derivation step must be hardened"},
                 {"hdkey", RPCArg::Type::STR, RPCArg::DefaultHint{"Either the HD key of an unused(KEY) descriptor, or any other active descriptor."}, "The HD key that the wallet knows the private key of, listed using 'gethdkeys', to use for derivation"},
             }},
         },
@@ -998,6 +998,9 @@ RPCMethod derivehdkey()
             if (!HasHardenedDerivation(path)) {
                 throw JSONRPCError(RPC_INVALID_PARAMETER, "Derivation path requires at least one hardened step");
             }
+            if (priv && !(path.back() >> 31)) {
+                throw JSONRPCError(RPC_INVALID_PARAMETER, "Private key output requires a hardened final derivation step");
+            }
 
             LOCK(wallet->cs_wallet);
 
diff --git a/test/functional/wallet_derivehdkey.py b/test/functional/wallet_derivehdkey.py
index 8905c55e68..6c741233bb 100755
--- a/test/functional/wallet_derivehdkey.py
+++ b/test/functional/wallet_derivehdkey.py
@@ -73,8 +73,8 @@ class WalletDeriveHDKeyTest(BitcoinTestFramework):
             too_deep_path,
         )
 
-        xpub_info = wallet.derivehdkey("m/87h/0h/0h/0")
-        xpub_priv_info = wallet.derivehdkey("m/87h/0h/0h/0", private=True)
+        xpub_info = wallet.derivehdkey("m/87h/0h/0h/0h")
+        xpub_priv_info = wallet.derivehdkey("m/87h/0h/0h/0h", private=True)
         xprv = xpub_priv_info["xprv"]
         assert_equal(xpub_priv_info["xpub"], xpub_info["xpub"])
 
@@ -99,11 +99,11 @@ class WalletDeriveHDKeyTest(BitcoinTestFramework):
             -13,
             "Error: Please enter the wallet passphrase with walletpassphrase first",
             wallet.derivehdkey,
-            "m/87h/0h/0h/0",
+            "m/87h/0h/0h/0h",
             private=True,
         )
         with WalletUnlock(wallet, "pass"):
-            xpub_info = wallet.derivehdkey("m/87h/0h/0h/0", private=True)
+            xpub_info = wallet.derivehdkey("m/87h/0h/0h/0h", private=True)
             # Unused(KEY) is preferred over active descriptors and is not
             # rotated on encryption.
             assert_equal(xpub_info["xprv"], prev_xprv)
@@ -140,6 +140,18 @@ class WalletDeriveHDKeyTest(BitcoinTestFramework):
         active_xpub = wallet.gethdkeys(active_only=True)[0]["xpub"]
         assert_equal(wallet.derivehdkey("m/44h/1h/0h", hdkey=active_xpub), xpub_info)
 
+        # An xprv at an unhardened child, together with its exposed parent
+        # xpub, would reveal the parent xprv. Public output remains allowed.
+        unhardened_path = "m/44h/1h/0h/0"
+        assert "xprv" not in wallet.derivehdkey(unhardened_path)
+        assert_raises_rpc_error(
+            -8,
+            "Private key output requires a hardened final derivation step",
+            wallet.derivehdkey,
+            unhardened_path,
+            private=True,
+        )
+
         # Get the activate wpkh() receive descriptor
         desc = list(filter(lambda d:
                            d["active"] and not d["internal"] and d["desc"][0:3] == "pkh",

[Sjors]

Should private output require the final step to be hardened?

I think anyone who obtains xprv's should be careful, not sure if adding restrictions makes sense.

[w0xlt]

I think anyone who obtains xprv's should be careful, not sure if adding restrictions makes sense.

That being the case, ACK c3945bf

[pseudoramdom]

This is in a good state IMO.
code review ACK c3945bf

[achow101]

ACK c3945bf

[davidgumberg]

This needs a release note!

[Sjors]

@davidgumberg it's in doc/release-notes-32784.md

[optout21]

Post-merge comment: the merge conflict on #35170 showed that it has overlap with this PR. I have updated #35170 accordingly. Reviews are welcome on it!

[davidgumberg]

@davidgumberg it's in doc/release-notes-32784.md

Oops, I looked at the commit list. My bad