wallet: support bip388 policy with external signer #33008

1. 
   Sjors commented at 3:31 pm on July 18, 2025: member

   External signers such as Ledger, BitBox02 and Jade, when used with multisig, use BIP388 to display (and constrain) descriptor policies to their users.

   At least in the case of Ledger (haven’t tested the others) this requires us to hold on to an hmac, which proves to the device that the user previously reviewed and approved it.

   This PR adds a new RPC call registerpolicy which converts our descriptor(s) into a BIP388 policy (TODO), calls a new HWI method register (implemented) and stores the resulting HMAC (implemented).

   When signing a transaction using HWI’s signtx it passes the HMAC along with the PSBT (TODO). Ditto for displayaddress (TODO).

   For convenience the HMAC can be retrieved via getwalletinfo (implemented). This is useful for scenario’s where we can’t (yet) complete a transaction via HWI calls.

   Note that the HMAC itself is not specified in BIP388 and may be different for different hardware vendors. So we’ll store and echo any hex string the device gives us.

   Testing:

   • make a multisig wallet with a Ledger or other supported device
     • try https://github.com/Sjors/bitcoin/pull/91 if you’re feeling adventurous, it includes this PR
   • modify devices/ledger.py in HWI to print registered_hmac.hex() (to verify correctness later)
   • install https://github.com/bitcoin-core/HWI/pull/791 HWI branch
   • edit src/wallet/external_signer_scriptppubkeyman.cpp and change the hardcoded descriptor_template and keys_info to your own wallet (this step will go away, see TODO below)
   • call bitcoin rpc registerpolicy
   • check that the result contains the hmac from before

   TODO:

   • derive BIP388 descriptor template from descriptor
   • pass hmac along when signing

   Depends on:

   • HWI register command: https://github.com/bitcoin-core/HWI/pull/791
   • HWI optional --hmac argument for signtx (if set, bypass the current auto-registration workaround)

   Potential followups:

   • pass hmac along when displaying an address. This provides some extra assurance to the user. See https://github.com/bitcoin-core/HWI/pull/647
2. DrahtBot added the label Wallet on Jul 18, 2025
3. 
   DrahtBot commented at 3:31 pm on July 18, 2025: contributor

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

   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:

   • #33034 (wallet: Store transactions in a separate sqlite table by achow101)
   • #32958 (wallet/refactor: change PSBTError to PSBTResult and remove std::optionalcommon::PSBTResult and return common::PSBTResult by kevkevinpal)
   • #32895 (wallet: Prepare for future upgrades by recording versions of last client to open and decrypt by achow101)
   • #32876 (refactor: use options struct for signing and PSBT operations by Sjors)
   • #32861 (Have createwalletdescriptor auto-detect an unused(KEY) by Sjors)
   • #32857 (wallet: allow skipping script paths by Sjors)
   • #32784 (wallet: derivehdkey RPC to get xpub at arbitrary path by Sjors)
   • #32652 (wallet: add codex32 argument to addhdkey by roconnor-blockstream)
   • #32489 (wallet: Add exportwatchonlywallet RPC to export a watchonly version of a wallet by achow101)
   • #29136 (wallet: addhdkey RPC to add just keys to wallets via new unused(KEY) descriptor by achow101)

   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:

   • “ExternalSignerScriptPubKeyMananager” -> “ExternalSignerScriptPubKeyManager” [typo in class name, extra “an”] No other typos were found.

   drahtbot_id_4_m

4. DrahtBot added the label CI failed on Jul 18, 2025
5. 
   DrahtBot commented at 4:31 pm on July 18, 2025: contributor

   🚧 At least one of the CI tasks failed. Task previous releases, depends DEBUG: https://github.com/bitcoin/bitcoin/runs/46270694515 LLM reason (✨ experimental): The CI failure is caused by a compilation error due to a redundant declaration of ‘RPCHelpMan wallet::registerpolicy()’ which is treated as an error because all warnings are enabled as errors.

   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.

6. Sjors force-pushed on Jul 21, 2025
7. Sjors force-pushed on Jul 21, 2025
8. DrahtBot removed the label CI failed on Jul 21, 2025
9. wallet: add bip388_hmac record a96279b253
10. wallet: add RegisterPolicy to external signer 4c798156a8
11. wallet: add RegisterPolicy to signer SPKM d8c345e324
12. wallet: add registerPolicy() 9a65e047cf
13. rpc: add registerpolicy a551603eff
14. Sjors force-pushed on Jul 24, 2025

Contributors
Sjors DrahtBot

Labels
Wallet