wallet: Add deriveHDKey interface by PraneethGunas · Pull Request #36070 · bitcoin/bitcoin

PraneethGunas · 2026-08-24T17:59:33Z

This PR adds a wallet interface for derivehdkey.

The motivation is the same as #35436 and #34861. The derivehdkey RPC exists
(#32784), but the GUI does not go through RPC, so the logic is currently out of
its reach. A dedicated wallet interface makes it available for multisig setup.
Alongside the addhdkey interface, this lets the GUI add an HD key and derive a
shareable xpub from it. Tracked as the deriveHDKey item in #35645.

Key changes:

Add CWallet::DeriveHDKey(), which selects the HD key and derives it at the
requested path.
Update the derivehdkey RPC to call it, rather than repeating the hardened path check, the key selection and the derivation. The watch-only and unlock checks stay in the RPC, along with the xpub argument parsing.
Add interfaces::Wallet::deriveHDKey(), which returns the derived xpub and its
key origin. Private key material does not cross the interface.
Add unit test coverage for interfaces::Wallet::deriveHDKey().

The RPC maps every WalletError to -4, moving the unhardened path and failed derivation cases from -8 and the key selection cases from -5. The watch-only -4 and locked wallet -13 are unchanged.

DrahtBot · 2026-08-24T17:59:41Z

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

Reviews

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

Type	Reviewers
Concept ACK	polespinasa, jeanpablojp, pseudoramdom

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

Conflicts

No conflicts as of last run.

polespinasa · 2026-08-25T07:54:27Z

concept ACK

will review soon :)

jeanpablojp

Concept ACK

Left some comments.

polespinasa

did a first swift review

polespinasa · 2026-08-28T11:28:20Z

    return *xprv;
 }

+util::Expected<std::pair<CExtKey, KeyOriginInfo>, WalletError> CWallet::DeriveHDKey(const std::vector<uint32_t>& path, const std::optional<CExtPubKey>& hdkey) const


in a1250d2 wallet: Add deriveHDKey interface

All this is duplicated from RPC code. Why not just make both the interface and the RPC rely on the same code? Because of both using different code functions, they both return different error codes for same errors.

Also probably this commit could be split in different commits. First a preparatory commit that creates the DeriveHDKey function + testing, then a commit rebasing the RPC to use it, then a commit creating the interface. You can check #34861 for a commit structure idea :)

Done. Split into "Add CWallet::DeriveHDKey" and "Add deriveHDKey interface".

On sharing code with the RPC: it already calls SelectHDKey(). What's left is the watch-only, hardened-path and unlock guards, which pin the error codes wallet_derivehdkey.py asserts (-4, -8, -13).

DeriveHDKey() returns GenericError for every failure, so routing the rest through it would turn "Unable to derive HD key at the requested path" from -8 into -5. Keeping -8 would need a new WalletErrorCode just so one caller can pick a different number, which src/wallet/types.h:48-50 warns against.

Now both the interface and the RPC rely on the same CWallet::DeriveHDKey

jeanpablojp

Reviewed again. Left one more comment on the new test.

DrahtBot · 2026-09-01T12:54:06Z

🚧 At least one of the CI tasks failed.
_{Task iwyu: https://github.com/bitcoin/bitcoin/actions/runs/33223334574/job/99831020528}
_{LLM reason (✨ experimental): CI failed because the IWYU (include-what-you-use) check reported include issues and intentionally exited with a failure.}

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.

hebasto · 2026-09-02T09:21:26Z

From https://github.com/bitcoin/bitcoin/actions/runs/33532997440/job/100190403622?pr=36070:

--- a/src/interfaces/wallet.h
+++ b/src/interfaces/wallet.h
@@ -34,19 +34,16 @@
 #include <vector>
 
 class ArgsManager;
-class CKeyID;
-class CPubKey;
 class CScript;
 class PartiallySignedTransaction;
 class uint256;
 enum class FeeReason;
 enum class OutputType;
 struct bilingual_str;
+
 namespace wallet {
-struct CreatedTransactionResult;
 class CCoinControl;
 class CWallet;
-enum class AddressPurpose;
 struct CRecipient;
 struct WalletContext;
 } // namespace wallet

achow101 · 2026-09-09T23:03:19Z

Why is SelectHDKey being split into a separate function? This PR should only create one function: DeriveHDKey, and that should be called by RPC. There should not need to be a RPC that is essentially duplicating code of CWallet::DeriveHDKey. This also allows the unit tests to be dropped as the functional tests (can) cover those cases.

PraneethGunas · 2026-09-10T18:25:44Z

Why is SelectHDKey being split into a separate function? This PR should only create one function: DeriveHDKey, and that should be called by RPC. There should not need to be a RPC that is essentially duplicating code of CWallet::DeriveHDKey. This also allows the unit tests to be dropped as the functional tests (can) cover those cases.

It was done so that the the RPC error codes and messages are preserved. Also, looking at the discussions in #35436 (comment) it makes sense to collapse the error codes down based on how the errors are logged/displayed #35436 (comment)

PraneethGunas · 2026-09-10T20:46:44Z

Rebased on master and rebuilt the history

pseudoramdom

Concept ACK. Left some comments

pseudoramdom · 2026-09-14T19:23:53Z

        master_xpub_2 = wallet.addhdkey()['xpub']
        assert_raises_rpc_error(
-            -5,
+            -4,


In wallet: Add CWallet::DeriveHDKey

I'm not sure if we're okay with changing the error contract since derivehdkey will ship in v32.
If not, we likely have to duplicate the checks to retain the error codes.
@achow101

Restored the watch-only and unlock checks in the RPC, so -4 and -13 are unchanged from v32.

-8 and -5 are now collapsed to -4, or we can duplicate the checks in the RPC to preserve the v32 behaviour.

Haven't reviewed yet, but re changing error codes:
#35690 (comment)

The derivehdkey RPC selects the HD key and derives it inline, which the GUI cannot reach. Move both into the wallet.

The RPC now consumes CWallet::DeriveHDKey instead of repeating the hardened path check, the key selection and the derivation. Those errors now come from the wallet and are reported as -4.

Only the xpub is returned. interfaces::Wallet is not authenticated, so the private key is not passed over it.

DrahtBot changed the title ~~wallet: Add deriveHDKey interface~~ wallet: Add deriveHDKey interface Aug 24, 2026

DrahtBot added the Wallet label Aug 24, 2026

pseudoramdom mentioned this pull request Aug 24, 2026

Multisig Wizard tracking issue #35645

Open

12 tasks

This was referenced Aug 25, 2026

iwyu: Fix warnings in src/interfaces and treat them as errors #35900

Merged

wallet: Add addHDkey interface #35436

Merged

wallet: Handle or explicitly ignore WalletBatch write failures #35998

Draft

DrahtBot added the Needs rebase label Aug 27, 2026

jeanpablojp reviewed Aug 27, 2026

View reviewed changes

Comment thread src/wallet/test/wallet_interfaces_tests.cpp Outdated

Comment thread src/wallet/rpc/wallet.cpp Outdated

polespinasa reviewed Aug 28, 2026

View reviewed changes

PraneethGunas force-pushed the derivehdkey-interface branch from a1250d2 to 6131eab Compare August 29, 2026 00:22

DrahtBot removed the Needs rebase label Aug 29, 2026

jeanpablojp reviewed Aug 29, 2026

View reviewed changes

Comment thread src/wallet/test/wallet_tests.cpp Outdated

This was referenced Aug 29, 2026

wallet: move rescan logic into ChainScanner and wallet/scan #34681

Merged

Wallet: Add maxfeerate wallet startup option #29278

Open

DrahtBot added the CI failed label Sep 1, 2026

DrahtBot mentioned this pull request Sep 1, 2026

wallet, rpc: Implements set key label functionality #36126

Draft

PraneethGunas force-pushed the derivehdkey-interface branch from 6131eab to 32d7ebf Compare September 1, 2026 16:38

PraneethGunas force-pushed the derivehdkey-interface branch from 32d7ebf to 3c88685 Compare September 9, 2026 19:19

DrahtBot removed the CI failed label Sep 9, 2026

DrahtBot mentioned this pull request Sep 10, 2026

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

Draft

PraneethGunas force-pushed the derivehdkey-interface branch from 3c88685 to 431f0d9 Compare September 10, 2026 20:13

DrahtBot mentioned this pull request Sep 10, 2026

wallet: Add importdescriptors interface #34861

Merged

DrahtBot added the Needs rebase label Sep 14, 2026

pseudoramdom reviewed Sep 14, 2026

View reviewed changes

PraneethGunas added 3 commits September 15, 2026 14:34

wallet: Add CWallet::DeriveHDKey

132dd25

The derivehdkey RPC selects the HD key and derives it inline, which the GUI cannot reach. Move both into the wallet.

wallet: Have derivehdkey use CWallet::DeriveHDKey

c18cc35

The RPC now consumes CWallet::DeriveHDKey instead of repeating the hardened path check, the key selection and the derivation. Those errors now come from the wallet and are reported as -4.

wallet: Add deriveHDKey interface

462038a

Only the xpub is returned. interfaces::Wallet is not authenticated, so the private key is not passed over it.

PraneethGunas force-pushed the derivehdkey-interface branch from 431f0d9 to 462038a Compare September 15, 2026 22:35

DrahtBot added CI failed and removed Needs rebase labels Sep 16, 2026

DrahtBot closed this Sep 18, 2026

DrahtBot reopened this Sep 18, 2026

DrahtBot closed this Sep 19, 2026

DrahtBot reopened this Sep 19, 2026

DrahtBot added CI failed and removed CI failed labels Sep 19, 2026

Conversation

PraneethGunas commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DrahtBot commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage & Benchmarks

Reviews

Conflicts

Uh oh!

polespinasa commented Aug 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jeanpablojp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

polespinasa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

polespinasa Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PraneethGunas Aug 29, 2026

Choose a reason for hiding this comment

Uh oh!

PraneethGunas Sep 10, 2026

Choose a reason for hiding this comment

Uh oh!

jeanpablojp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DrahtBot commented Sep 1, 2026

Uh oh!

hebasto commented Sep 2, 2026

Uh oh!

achow101 commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

PraneethGunas commented Sep 10, 2026

Uh oh!

PraneethGunas commented Sep 10, 2026

Uh oh!

pseudoramdom left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

pseudoramdom Sep 14, 2026

Choose a reason for hiding this comment

Uh oh!

PraneethGunas Sep 15, 2026

Choose a reason for hiding this comment

Uh oh!

polespinasa Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

PraneethGunas commented Aug 24, 2026 •

edited

Loading

DrahtBot commented Aug 24, 2026 •

edited

Loading

polespinasa commented Aug 25, 2026 •

edited

Loading

polespinasa Aug 28, 2026 •

edited

Loading

achow101 commented Sep 9, 2026 •

edited

Loading