script: render BIP-388 wallet policies in getdescriptorinfo #35287

Currently, Bitcoin Core has no support for generating BIP-388 wallet policies from descriptors. Hardware signing devices use these policies to display spending conditions before signing.

This PR adds wallet_policy_template and wallet_policy_keys to the getdescriptorinfo RPC response for BIP-388 policy-compatible multipath <M;N>/* descriptors. Per Sjors's comment on #32659, getdescriptorinfo is the recommended place to start.

The bulk of the work is in src/script/descriptor.cpp.

• Introduces three new virtual methods ToTemplateString, GetDerivationIndex, GetKeyOrigins in PubkeyProvider.
• Introduces two new virtual method BuildWalletPolicy and BuildWalletPolicyTemplate in DescriptorImpl.
• A new ParseDescriptorInfo() centralizes descriptor analysis and returns a structured DescriptorInfo, so the Bitcoin Core GUI and external signer tooling can reuse it.

Supported: pkh, wpkh, sh, wsh, tr, multi, sortedmulti, multi_a, sortedmulti_a. tr() may use musig() in the keypath or script leaves.

• Miniscript support for wsh and tr
• Key deduplication and disjointness checks for all keys, including MuSig participant and aggregate keys
• Test coverage for the BIP-388 spec vectors, including negative cases for repeated keys, non-disjoint multipath expressions, and derivation-before-aggregation in musig()

Examples:

./build/bin/bitcoin-cli -regtest getdescriptorinfo   "tr([6738736c/86h/0h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx/<0;1>/*,{sortedmulti_a(1,[6738736c/86h/0h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx/<2;3>/*,[a5fbe580/86h/1h/0h]tpubDCJjvYf4BeLDy1o2qEJ4cyuqSDvEr3PmygtzYgQRGA6KuV2djdXw2Sq8x9F34KYHM8V5eRdmhXuagaEzbsvroj2k1CKcjcFC3ouvRRkBgZA/<0;1>/*),pk([a5fbe580/86h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth/<0;1>/*)})"

{
  "descriptor": "tr([6738736c/86h/0h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx/0/*,{sortedmulti_a(1,[6738736c/86h/0h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx/2/*,[a5fbe580/86h/1h/0h]tpubDCJjvYf4BeLDy1o2qEJ4cyuqSDvEr3PmygtzYgQRGA6KuV2djdXw2Sq8x9F34KYHM8V5eRdmhXuagaEzbsvroj2k1CKcjcFC3ouvRRkBgZA/0/*),pk([a5fbe580/86h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth/0/*)})#e7m79gm2",
  "multipath_expansion": [
    "tr([6738736c/86h/0h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx/0/*,{sortedmulti_a(1,[6738736c/86h/0h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx/2/*,[a5fbe580/86h/1h/0h]tpubDCJjvYf4BeLDy1o2qEJ4cyuqSDvEr3PmygtzYgQRGA6KuV2djdXw2Sq8x9F34KYHM8V5eRdmhXuagaEzbsvroj2k1CKcjcFC3ouvRRkBgZA/0/*),pk([a5fbe580/86h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth/0/*)})#e7m79gm2",
    "tr([6738736c/86h/0h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx/1/*,{sortedmulti_a(1,[6738736c/86h/0h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx/3/*,[a5fbe580/86h/1h/0h]tpubDCJjvYf4BeLDy1o2qEJ4cyuqSDvEr3PmygtzYgQRGA6KuV2djdXw2Sq8x9F34KYHM8V5eRdmhXuagaEzbsvroj2k1CKcjcFC3ouvRRkBgZA/1/*),pk([a5fbe580/86h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth/1/*)})#x7w2qh8j"
  ],
  "checksum": "lu9vfk4s",
  "isrange": true,
  "issolvable": true,
  "hasprivatekeys": false,
  "wallet_policy_template": "tr(@0/**,{sortedmulti_a(1,@0/<2;3>/*,@1/**),pk(@2/**)})",
  "wallet_policy_keys": [
    "[6738736c/86h/0h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx",
    "[a5fbe580/86h/1h/0h]tpubDCJjvYf4BeLDy1o2qEJ4cyuqSDvEr3PmygtzYgQRGA6KuV2djdXw2Sq8x9F34KYHM8V5eRdmhXuagaEzbsvroj2k1CKcjcFC3ouvRRkBgZA",
    "[a5fbe580/86h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth"
  ]
}

./build/bin/bitcoin-cli -regtest getdescriptorinfo "tr(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/<0;1>/*,{and_v(v:pk(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth)/<0;1>/*),older(12960)),{and_v(v:pk(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/<0;1>/*),older(12960)),and_v(v:pk(musig([a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/<0;1>/*),older(12960))}})"

{
  "descriptor": "tr(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/0/*,{and_v(v:pk(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth)/0/*),older(12960)),{and_v(v:pk(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/0/*),older(12960)),and_v(v:pk(musig([a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/0/*),older(12960))}})#kh3lv33d",
  "multipath_expansion": [
    "tr(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/0/*,{and_v(v:pk(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth)/0/*),older(12960)),{and_v(v:pk(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/0/*),older(12960)),and_v(v:pk(musig([a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/0/*),older(12960))}})#kh3lv33d",
    "tr(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/1/*,{and_v(v:pk(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth)/1/*),older(12960)),{and_v(v:pk(musig([a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/1/*),older(12960)),and_v(v:pk(musig([a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth,[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys)/1/*),older(12960))}})#vuhahajv"
  ],
  "checksum": "se2qhdlw",
  "isrange": true,
  "issolvable": true,
  "hasprivatekeys": false,
  "wallet_policy_template": "tr(musig(@0,@1,@2)/**,{and_v(v:pk(musig(@0,@1)/**),older(12960)),{and_v(v:pk(musig(@0,@2)/**),older(12960)),and_v(v:pk(musig(@1,@2)/**),older(12960))}})",
  "wallet_policy_keys": [
    "[a5fbe580/84h/1h/0h]tpubDDCzbWt7MLgDapZVYVXfEXCT1GBLELmP7e9ax6t3qVeFP5CmFrJBxZty2F58CoVSsMozrR8dfyHWxSdQJKSno9d44dyKn2ajKbxkPCppYLx",
    "[a5fbe580/44h/1h/0h]tpubDDEhkX7QU6DQ6tYvYERTNxD7FuhfTj3rZqbu1eCxxTrgzRNefT4u3Z5om6WYu2aDudFbdE7GdoCEqLd63b8aVXSzEsh7Fj89Gv1LtkHAfth",
    "[a5fbe580/49h/1h/0h]tpubDCyCF2YKcTy76LBDXFZCM6Cfkmh81KJuFYRswyLFfumpdfH2nDnDsS4iJFUkZCVFYshGFCS9PVtqWZofnRohVnyvfa5qt8NiebkK8v13vys"
  ]
}

We fully support the BIP, and all test vectors pass.

TODO:

• Expose ParseDescriptorInfo through interfaces::Node

Refs #32659

<!--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/35287.

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

• #35011 (ci, iwyu: Fix warnings in src/script and treat them as errors by BrandonOdiwuor)
• #32489 (wallet: Add exportwatchonlywallet RPC to export a watchonly version of a wallet 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:

• endup -> end up [misspelled word in comment: “So we endup having...”]
• seme -> same [misspelled word in comment: “the seme key index”]

^{2026-05-15 22:41:20}

Force-pushed to add BIP-388 aggregate-level disjointness checks for repeated musig() placeholders, plus four tests covering disjoint and non-disjoint multipath, including cases where participants are reordered.

I think it's better to close this and open a PR on your own fork of the repo. Or on my fork, since I'm working on something similar and might be able to pull your changes in at some point: https://github.com/Sjors/bitcoin/pull/91

1. So far there's only light interest on #32659, and no concept ACKs
2. This is not a great choice for a first contribution, because our descriptor handling code is hard to understand even for experienced developers, and may need significant changes to accommodate BIP388. My own work in https://github.com/Sjors/bitcoin/pull/91 is a hack that I wouldn't upstream as-is.

Small meta nit: don't tag usernames in the PR description, because if it's ever merged, this will cause Github notifications each time a fork includes the change. @achow101 the Validation label is incorrect. It's technically also not Wallet, but that's probably the closest.

Force-pushed to add Miniscript rendering support.

Given your feedback, @Sjors, this may be the last push here. We now have full support for the BIP, including some more exotic Miniscript test cases, and all test vectors pass.

Looking at https://github.com/Sjors/bitcoin/pull/91, this could potentially slot in as a replacement for the current policy generation logic.

Happy to keep this PR open for visibility, close it, or move the rendering work over to https://github.com/Sjors/bitcoin/pull/91 in whatever form is most useful for your branch.