Skip to content

wallet: Add deriveHDKey interface - #36070

Open
PraneethGunas wants to merge 5 commits into
bitcoin:masterfrom
PraneethGunas:derivehdkey-interface
Open

PraneethGunas wants to merge 5 commits into
bitcoin:masterfrom
PraneethGunas:derivehdkey-interface

Conversation

@PraneethGunas

@PraneethGunas PraneethGunas commented Aug 24, 2026 •

Copy link
Copy Markdown

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:

  • Move the key selection and derivation logic from the RPC into CWallet::DeriveHDKey, including the wallet and argument checks.
  • Have the RPC call CWallet::DeriveHDKey and translate its WalletError using HandleWalletErrorCode.
  • Add interfaces::Wallet::deriveHDKey, which returns the derived xpub and key origin. Private materials are not exposed through the interface.
  • Add interface tests for derivation and error forwarding. Update the functional tests for the changed error codes and unlock message.

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

DrahtBot commented Aug 24, 2026 •

Copy link
Copy Markdown
Contributor

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

External sites

Reviews

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

Type Reviewers
Concept ACK polespinasa, jeanpablojp, pseudoramdom, vicjuma
Approach ACK w0xlt

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:

  • #36444 (wallet: Store information about created and imported multipath descriptors by achow101)
  • #36443 (descriptor: Reconstruct a multipath descriptor from its expansion by achow101)
  • #36442 (descriptor: Represent multipath descriptors in a single Descriptor object by achow101)
  • #35377 (wallet: Allow importing of descriptors without private keys when the wallet has the private keys by achow101)
  • #33112 (wallet: relax external_signer flag constraints 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.

@pseudoramdom pseudoramdom mentioned this pull request Aug 24, 2026
4 of 12 tasks
@polespinasa

polespinasa commented Aug 25, 2026 •

Copy link
Copy Markdown
Member

concept ACK

will review soon :)

@jeanpablojp jeanpablojp left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Concept ACK

Left some comments.

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

@polespinasa polespinasa left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

did a first swift review

Comment thread src/wallet/rpc/wallet.cpp Resolved
Comment thread src/wallet/wallet.h Resolved
Comment thread src/wallet/wallet.cpp Outdated
return *xprv;
}

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

@polespinasa polespinasa Aug 28, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 :)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@jeanpablojp jeanpablojp left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread src/wallet/test/wallet_tests.cpp Resolved
@DrahtBot

DrahtBot commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

🚧 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

hebasto commented Sep 2, 2026

Copy link
Copy Markdown
Member

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

achow101 commented Sep 9, 2026 •

Copy link
Copy Markdown
Member

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

Copy link
Copy Markdown
Author

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

Copy link
Copy Markdown
Author

Rebased on master and rebuilt the history

@pseudoramdom pseudoramdom left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Concept ACK. Left some comments

Comment thread src/wallet/wallet.cpp Resolved
Comment thread test/functional/wallet_derivehdkey.py Outdated
master_xpub_2 = wallet.addhdkey()['xpub']
assert_raises_rpc_error(
-5,
-4,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At this point we should add an invalid parameter error code to at least distinguish caller problems from wallet problems. I'm fine with collapsing INVALID_ADDRESS_OR_KEY with INVALID_PARAMETER, but collapsing those into WALLET_ERROR makes the error code to the user too vague. WALLET_ERROR is really for "something bad happened in the wallet internally", as opposed to "the user gave us a bad argument".

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree, after importdescriptors was merged this should be easy.
Those errors already exist now:

enum class WalletErrorCode {
//! Generic wallet error. Callers may present the accompanying message to
//! the user.
GenericError,
//! The wallet is locked and the operation requires access to private keys.
//! Callers may ask the user to unlock the wallet and retry the operation.
UnlockNeeded,
//! The passphrase does not decrypt the wallet. Callers may ask the user to enter it again.
PassphraseIncorrect,
//! TODO Add correct descriptions to each error.
//! At the moment only used by ImportDescriptors.
InvalidDescriptor,
InvalidParameter,
MiscError,
};

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll remap them based on invalid param or wallet error

@w0xlt

w0xlt commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

Approach ACK. Will review soon.

@polespinasa

Copy link
Copy Markdown
Member

What do you think about #36070 (comment) ?

Move the HD key selection, private key lookup, and derivation out of
the derivehdkey RPC into a static DeriveHDKey function in the same file.
Move the watch-only, hardened-path, unlock and xpub-validity checks into
DeriveHDKey in their existing order, retaining the v32 RPC codes and
messages. The RPC still decodes its inputs and holds the wallet lock.

Input parsing now precedes the watch-only check, so a malformed path
supplied to a watch-only wallet reports the path error first.
Return WalletError from the helper instead of throwing RPC errors. Keep
the checks in the same order. The locked-wallet error now uses the
common wallet unlock message.

Argument errors use InvalidParameter and map to RPC_INVALID_PARAMETER,
including cases previously reported as RPC_INVALID_ADDRESS_OR_KEY.
Use HandleWalletErrorCode to translate wallet errors back to RPC codes.
Move DeriveHDKey from the derivehdkey RPC into CWallet so that it is
not tied to the RPC.
Only the xpub is returned, since interfaces::Wallet is not
authenticated and should not pass private keys.
@PraneethGunas

Copy link
Copy Markdown
Author

What do you think about #36070 (comment) ?

Thanks for the proposal. I’ve reworked the history along those lines, separating the check moves, error changes, and move into CWallet

@vicjuma vicjuma left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Concept ACK

Comment thread src/wallet/wallet.cpp
return xpubs;
}

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Derivation functionality works as expected

On Master

ratedg@0xratedg:~/projects/contributions/bitcoin/build/bin$ ./bitcoin-cli loadwallet testwallet
{
  "name": "testwallet"
}
ratedg@0xratedg:~/projects/contributions/bitcoin/build/bin$ ./bitcoin-cli -named derivehdkey path="m/84h/1h/0h"
{
  "origin": "[ce287f45/84h/1h/0h]",
  "xpub": "tpubDCGyDHJvhr4r2BMf47yvpTDvP2BM6GhsF1dETWpmXetF4zjMnpettacQYNdgdzYd8FTW6LS3UuPWpqPuZgWmDu1dDSYbXfgwSsKX8upwmE1"
}
ratedg@0xratedg:~/projects/contributions/bitcoin/build/bin$

PR Branch

ratedg@0xratedg:~/projects/contributions/bitcoin/build2/bin$ ./bitcoin-cli restorewallet testwallet ~/Desktop/testwallet.dat
{
  "name": "testwallet"
}
ratedg@0xratedg:~/projects/contributions/bitcoin/build2/bin$ ./bitcoin-cli -named derivehdkey path="m/84h/1h/0h"
{
  "origin": "[ce287f45/84h/1h/0h]",
  "xpub": "tpubDCGyDHJvhr4r2BMf47yvpTDvP2BM6GhsF1dETWpmXetF4zjMnpettacQYNdgdzYd8FTW6LS3UuPWpqPuZgWmDu1dDSYbXfgwSsKX8upwmE1"
}
ratedg@0xratedg:~/projects/contributions/bitcoin/build2/bin$ 

Comment thread src/wallet/wallet.cpp

if (IsWalletFlagSet(WALLET_FLAG_DISABLE_PRIVATE_KEYS)) {
// Watch-only wallets can't contain unused(KEY) descriptors
return util::Unexpected{WalletError{WalletErrorCode::GenericError, _("derivehdkey is not available for watch-only wallets")}};

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any difference between the error message substring derivehdkey and the current RPC derivehdkey "path" ( {"private":bool,"hdkey":"str",...} )? Wouldn't a universal message work best if the functionality should be exposed to the GUI too?

Comment thread src/wallet/wallet.cpp
HDPubKeyMap wallet_xpubs{GetHDPubKeys(HDKeyFilter::UnusedKey)};

if (wallet_xpubs.size() > 1) {
return util::Unexpected{WalletError{WalletErrorCode::InvalidParameter, _("Unable to determine which HD key to use. Please specify with 'hdkey'")}};

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same case here. Is the hdkey used here different from the named argument of derivehdkey RPC? A universal message would probably work better for the GUI users too

Comment thread src/wallet/wallet.cpp
}

if (active_xpubs.size() > 1) {
return util::Unexpected{WalletError{WalletErrorCode::InvalidParameter, _("Unable to determine which HD key to use from active descriptors. Please specify with 'hdkey'")}};

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same case here. Is the hdkey used here different from the named argument of derivehdkey RPC? A universal message would probably work better for the GUI users too

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants