wallet: support bip388 policy with external signer #33008

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 (no others so far, see #33008 (comment)) 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 (partially implemented), 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).

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.

An alternative approach to directly supporting BIP388 policies would be to pass the involved descriptors to HWI and have it figure out how to derive a policy.

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
• install https://github.com/bitcoin-core/HWI/pull/791 HWI branch
• call bitcoin rpc registerpolicy
• call bitcoin rpc getwalletinfo to see the hmac

TODO:

• derive policy using Descriptor class instead regex madness, implement all constraints
• 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

<!--e57a25ab6845829454e8d69fc972939a-->

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

<!--006a51241073e994b41acfe9ec718e94-->

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/33008.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

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

<!--174a7506f384e20aa4161008e828411d-->

Conflicts

Reviewers, this pull request conflicts with the following ones:

• #bitcoin-core/gui/872 (Menu action to export a watchonly wallet by achow101)
• #34681 (wallet: refactor ScanForWalletTransactions by Eunovo)
• #34400 (wallet: parallel fast rescan (approx 5x speed up with 8 threads) by Eunovo)
• #33034 (wallet: Store transactions in a separate sqlite table by achow101)
• #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)
• #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.

<!--5faf32d7da4f0f540f40219e4f7537a3-->

LLM Linter (✨ experimental)

Possible typos and grammar issues:

• furth -> further [misspelled in // - apply furth BIP388 restrictions; it should be further]
• swith -> switch [misspelled in // Replace keys in descriptor swith [@1](/bitcoin-bitcoin/contributor/1/), etc; it should be switch]
• manangers -> managers [misspelled in Derive a BIP388 policy from a pair of descriptor scriptpubkey manangers.; it should be managers]

Possible places where named args for integral literals may be used (e.g. func(x, /*named_arg=*/0) in C++, and func(x, named_arg=0) in Python):

• util::ReplaceAll(descriptor_template, key_info, strprintf("@%d", key_index), false) in src/wallet/wallet.cpp
• util::ReplaceAll(descriptor_template_check, key_info, strprintf("@%d", key_index), false) in src/wallet/wallet.cpp
• util::ReplaceAll(descriptor_template, "/0/*", "/**", false) in src/wallet/wallet.cpp
• util::ReplaceAll(descriptor_template_check, "/1/*", "/**", false) in src/wallet/wallet.cpp
• util::ReplaceAll(key, "h/", "'/", false) in src/wallet/wallet.cpp
• util::ReplaceAll(key, "h]", "']", false) in src/wallet/wallet.cpp

^{2026-04-28 14:36:23}

<!--85328a0da195eb286784d51f73fa0af9-->

🚧 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.}

<details><summary>Hints</summary>

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.

</details>

<!--85328a0da195eb286784d51f73fa0af9-->

🚧 At least one of the CI tasks failed. _{Task tidy: https://github.com/bitcoin/bitcoin/runs/47448999684} _{LLM reason (✨ experimental): The CI failure is due to an error flagged by clang-tidy in wallet.cpp at line 2621.}

<details><summary>Hints</summary>

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.

</details>

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.

In the range of devices supporting miniscript, only Ledger requires the software to store the Proof Of Registration, other devices stores it internally(SpecterDiy, BitBox, Coldcard, Jade) or not at all (Krux).

@pythcoiner thanks, updated the description.

<!--85328a0da195eb286784d51f73fa0af9-->

🚧 At least one of the CI tasks failed. _{Task tidy: https://github.com/bitcoin/bitcoin/actions/runs/21242962354/job/61125116517} _{LLM reason (✨ experimental): clang-tidy failure: parameter 'regex' is const-qualified in the ReplaceAll declaration, causing linting to fail.}

<details><summary>Hints</summary>

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.

</details>

I'm going to expand this to include address display (https://github.com/Sjors/bitcoin/pull/110), signing (https://github.com/Sjors/bitcoin/pull/111) and functional tests. That's a lot of fairly experimental code, so I'll open a PR on my own fork instead.