wallet, rpc: Add analyzedescriptor for multisig setups #36885

pull pablomartin4btc wants to merge 13 commits into bitcoin:master from pablomartin4btc:analyze-descriptor changing 28 files +3848 −104
  1. pablomartin4btc commented at 5:48 AM on November 16, 2026: member

    Part of the multisig setup work tracked in #35645. Based on #35918 (the first 3 commits).

    Before importing a multisig descriptor received from a coordinator, each participant needs to check that it is the setup they agreed on: a k-of-n where any k cosigners can spend and nothing else can, that their own key is in it, and that they all derived the same first address. Today nothing in Core reports what a descriptor commits to, so tools had to parse the descriptor string by hand, as the multisig wizard in #36325 (now closed) did.

    This PR adds that check in three layers:

    1. Inspection (commits by w0xlt, with small changes listed below): GetKeyInfo(), GetKeyInventory() and GetPolicy() describe a parsed descriptor's key expressions, where each key is used, and how they combine. getdescriptorinfo gains a verbose option that returns them as keys and policy.
    2. Multisig analysis, no wallet: AnalyzeDescriptor() tells whether a descriptor is a recognized k-of-n setup, and if not, why. getdescriptorinfo verbose returns it as analysis, so it works even with -disablewallet.
    3. Wallet part: interfaces::Wallet::analyzeDescriptor (for the GUI) and the analyzedescriptor wallet RPC add which keys the wallet holds, whether it can sign, and the first receive address. They accept any descriptor, single-sig included; analysis.recognized tells whether it is a safe k-of-n.

    Recognized setups are wsh(multi)/wsh(sortedmulti), and tr(K,multi_a)/tr(K,sortedmulti_a) with a single leaf, where K is the BIP 341 NUMS point or a musig() of at least k distinct cosigners. Every cosigner must be an extended key with an unhardened ranged derivation, and no two cosigners may be the same key. Anything else is still analyzed and returned, with recognized: false and the list of issues: the analysis warns, it never refuses a descriptor.

    Example, run by one of the three cosigners:

    $ bitcoin-cli -rpcwallet=alice analyzedescriptor "wsh(sortedmulti(2,[a1b2c3d4/48h/1h/0h/2h]tpub.../<0;1>/*,...))"
    {
      "keys": [
        { "role": "ecdsa", "type": "bip32", "xpub": "tpub...", "derivation": "/0/*",
          "origin": { "master_fingerprint": "a1b2c3d4", "path": "m/48h/1h/0h/2h" }, "wallet": "mine" },
        { ..., "wallet": "not_mine" },
        { ..., "wallet": "not_mine" }
      ],
      "analysis": { "recognized": true, "shape": "wsh_multi", "sorted": true, "threshold": 2, "cosigners": [0, 1, 2], "issues": [] },
      "can_sign": true,
      "first_address": "bcrt1q..."
    }
    

    A locked wallet is not an error: a cosigner key with a hardened origin path can't be checked without the private key, so it is reported as "unknown", and can_sign is left out unless another key is already known to be the wallet's. Everything else (analysis, first_address) is still returned, and the caller can ask the user to unlock and retry. Only the candidate private key is decrypted.

    Commits

    Commit Author
    1‑3 #35918 pseudoramdom
    4‑7 key/policy inspection, getdescriptorinfo verbose w0xlt (see changes below)
    8 script: add AnalyzeDescriptor() for multisig setups co-authored with w0xlt
    9 rpc: add multisig analysis to getdescriptorinfo verbose
    10 wallet: add analyzeDescriptor to the wallet interface co-authored with w0xlt
    11 rpc: move descriptor key and analysis JSON helpers to a shared file move-only
    12 wallet, rpc: add analyzedescriptor co-authored with w0xlt

    Changes made to the inspection commits (4-7)

    The inspection commits come from w0xlt's descriptor inspection branch. These changes were made on top, for w0xlt to review and agree with or not (this section will be removed once agreed):

    • script: expose key expression structure (was "expose structured key program data")
      • Use m_root_extkey instead of *GetRootExtPubKey().
      • The derivation test also covers /0h/* and /1/*h, checking the last-hardened and derived caches.
      • wide += ')' instead of ")" in the participant test (clang-tidy performance-prefer-single-char-overloads).
    • script: identify descriptor key occurrences
      • KeyRole() is pure virtual; descriptors without key arguments (addr, raw, sh, wsh) say so explicitly with NONFATAL_UNREACHABLE().
      • Comment noting that frame is invalidated by the following push_back.
      • The walletload test mock is reduced to return {}.
    • script: expose descriptor policy nodes
      • The header documents the two forms of the same construct (descriptor function vs Miniscript fragment).
      • Assert → CHECK_NONFATAL; explicit static_cast<uint32_t> for the threshold.
      • The fuzz target checks where each child role may appear (tap leaves only under tr, script only under sh/wsh, the Taproot internal key only on tr, the output key only on rawtr).
    • rpc: add verbose option to getdescriptorinfo
      • The multipath note moved to the verbose argument help; the policy help explains both forms.
      • Tests for an origin without a path and for MuSig participant origins.

    Open question: script/descriptor_analysis.h describes and gives no verdict, while script/descriptor_analyzer.h gives the verdict; the names are easy to mix up. Rename the first to script/descriptor_inspection.h?

    Design choices

    • An unrecognized descriptor claims no setup: no threshold, cosigners, sorting or key path. For example wsh(sortedmulti(2,A,A,C)) is not a 2-of-3, since A alone can spend. Each issue lists the key IDs involved instead.
    • The same xpub with different paths in two cosigner slots is a repeated_key, as is an xpub and its own child xpub. BIP 388 allows the same key with disjoint paths in general policies, but in a k-of-n it lets one holder fill two slots.
    • A Taproot key path is either nums or musig. Any other internal key, a musig() of fewer than k cosigners, or one with an outsider or a repeated cosigner is key_path_spendable.
    • For a multipath descriptor every path is analyzed and must be the same setup (branches_differ otherwise). keys and policy describe the first path.
    • can_sign means the wallet holds the private key for at least one key of the descriptor, whatever its shape. Whether it is a safe k-of-n is a separate answer, analysis.recognized.

    The functional test scenarios of #36325 were adapted here. The analysis differs from that wizard in a few places:

    • wsh(multi(...)) is recognized, with sorted: false: it is a valid k-of-n, and requiring sortedmulti was the wizard's own policy.
    • A musig() key path of at least k distinct cosigners is recognized: those cosigners can already spend through the leaf.
    • A single-path descriptor (/0/*) is recognized; multipath_expansion already shows whether it is multipath.

    Known limits

    • A cosigner key is matched against the wallet's HD keys exactly, or by deriving its origin path from the HD key with that fingerprint (normally the master key). If the wallet only holds an imported account xprv, keys below it are matched only exactly.

    A release note will follow.

  2. DrahtBot commented at 5:48 AM on November 16, 2026: contributor

    <!--e57a25ab6845829454e8d69fc972939a-->

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

    <!--006a51241073e994b41acfe9ec718e94-->

    External sites

    <!--021abf342d371248e50ceaed478a90ca-->

    Reviews

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

    Type Reviewers
    Approach ACK w0xlt

    If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

    <!--174a7506f384e20aa4161008e828411d-->

    Conflicts

    Reviewers, this pull request conflicts with the following ones:

    • #36743 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36743.svg"></sub> ([RFC] build: build with -Wmissing-declarations/prototypes by fanquake)
    • #36710 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36710.svg"></sub> (test: Replace hardcoded extended keys with ExtendedKey helpers by nebula-21)
    • #36648 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36648.svg"></sub> (descriptor, rpc, wallet: do not echo key material in error messages by fametrano)
    • #36444 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36444.svg"></sub> (wallet: Store information about created and imported multipath descriptors by achow101)
    • #36443 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36443.svg"></sub> (descriptor: Reconstruct a multipath descriptor from its expansion by achow101)
    • #36442 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36442.svg"></sub> (descriptor: Represent multipath descriptors in a single Descriptor object by achow101)
    • #36167 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36167.svg"></sub> (build: Enable -Wunused by fanquake)
    • #36154 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36154.svg"></sub> (wallet: fill PSBT_GLOBAL_XPUB by jeanpablojp)
    • #36122 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36122.svg"></sub> (BIP460: CISA for Taproot key path spends by fjahr)
    • #36070 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36070.svg"></sub> (wallet: Add deriveHDKey interface by PraneethGunas)
    • #36005 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/36005.svg"></sub> (rpc, descriptor: warn when multipath expansion clones single-path key expressions by pythcoiner)
    • #35377 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35377.svg"></sub> (wallet: Allow importing of descriptors without private keys when the wallet has the private keys by achow101)
    • #35302 <sub><img src="https://drahtbot.space/ack_count/bitcoin/bitcoin/35302.svg"></sub> (Silent Payments: Sending (take 2) by Eunovo)

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

    • src/script/descriptor.cpp: builder.AddNode(DescriptorPolicy::Kind::ADDR, {}, 0, script)
    • src/script/descriptor.cpp: builder.AddNode(DescriptorPolicy::Kind::RAW, {}, 0, m_script)

    <sup>2026-11-19 03:42:20</sup>

  3. fanquake added the label Needs release note on Nov 16, 2026
  4. w0xlt commented at 7:15 PM on November 17, 2026: contributor

    Approach ACK

  5. pablomartin4btc referenced this in commit 4275cc25d2 on Nov 18, 2026
  6. pablomartin4btc force-pushed on Nov 18, 2026
  7. DrahtBot added the label CI failed on Nov 18, 2026
  8. DrahtBot commented at 3:50 PM on November 18, 2026: contributor

    <!--85328a0da195eb286784d51f73fa0af9-->

    🚧 At least one of the CI tasks failed. <sub>Task iwyu: https://github.com/bitcoin/bitcoin/actions/runs/44330374279/job/134892869102</sub> <sub>LLM reason (✨ experimental): CI failed because the IWYU lint check modified src/script/descriptor_analyzer.cpp, leaving a diff that caused git diff --exit-code to fail.</sub>

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

  9. pablomartin4btc referenced this in commit 2155dfd19f on Nov 18, 2026
  10. pablomartin4btc force-pushed on Nov 18, 2026
  11. descriptor: Reject trailing text after musig()
    The musig() parser split the input at the closing parenthesis without
    validating the remaining text. This allowed unexpected characters after
    the expression to be ignored.
    Add a requirement for nonempty char after musig() to begin with '/'.
    6be7221269
  12. descriptor: move PubkeyProvider to descriptor.h
    Expose the abstract interface by moving to descriptor.h to allow other
    modules to consume parsed key expressions.
    
    Mostly move-only. `HavePrivateKeys()` and `DetermineApostropheUse()`
    now have their impl in descriptor.cpp.
    a11c0f380c
  13. descriptor: Add public ParsePubkey overload
    Add an overload for parsing standalone key expressions using P2TR key
    rules.
    Also, expose explicitly provided origin information through GetOriginInfo(),
    allowing callers to inspect the fingerprint and derivation path without
    re-parsing the expression.
    a2065ade97
  14. script: expose key expression structure
    Inspect parsed key expressions through the PubkeyProvider interface
    without serialization, derivation, or key access.
    
    Return owned constant, BIP32, and MuSig records with numeric paths,
    wildcards, and explicit origins. Report x-only constant keys in their
    even form, as their serialization does, so a private key and its
    public form inspect the same. Preserve participant order and
    multiplicity using result-local links independent of cache indices.
    The result is linear in the size of the key expression.
    
    Test public/private inputs, hardened aliases, multipath branches,
    participant and aggregate derivation, ownership of results, deep paths
    and wide participant lists, and unchanged cached and uncached
    derivation.
    277c99450c
  15. script: identify descriptor key occurrences
    Expose an inventory of public key expressions on parsed and inferred
    descriptors. Give each occurrence a result-local ID so repeated keys
    and providers sharing cache indices remain distinct. Remap MuSig
    participant links into the complete inventory.
    
    Record signing roles from descriptor context, including compressed
    Taproot keys and full-key MuSig participants. Reuse provider inspection
    without expansion, private-key access, or subtree serialization. The
    traversal is iterative and the inventory is linear in the descriptor.
    
    Test parsed, inferred, and multipath-cloned descriptors, role
    boundaries, duplicates, participant links, owned public results, opaque
    forms, and large policies. Check inventory integrity throughout the
    existing descriptor fixtures, and check that each fixture's private
    form, public form, and re-parsed public serialization have equal
    inventories.
    820e99e458
  16. script: expose descriptor policy nodes
    Expose an owned policy tree with typed descriptor and Miniscript
    operators, local values and data, explicit child roles, and references
    to the public key occurrence inventory. Preserve Taproot leaf order and
    depths, and keep raw scripts and addresses explicitly opaque.
    
    Build key occurrences and policy nodes in one iterative traversal
    without serializing subtrees, so the result is linear in the
    descriptor and each key argument's occurrence ID is known when its
    policy node is created. The key inventory becomes the policy's key
    list. Map Miniscript operands through provider-local indices so
    inferred and cloned descriptors retain their correct key references.
    
    Cover structure, thresholds, hashes, opaque forms, reference integrity,
    and exact node counts. Check linear retained structure for 3,200 nested
    timelocks and 1,024 Taproot leaves, and exercise parsed and inferred
    policies, including MuSig participant links, in the descriptor fuzz
    targets.
    122794a90d
  17. rpc: add verbose option to getdescriptorinfo
    With verbose=true, getdescriptorinfo also returns the descriptor's key
    occurrences and policy structure, built from Descriptor::GetPolicy().
    
    Both are flat arrays whose indices are the IDs used within the result,
    so deep policies do not become deeply nested JSON. Keys report their
    role, public key material, derivation, and origin. Private keys in the
    input are reported by their public form. Policy nodes name their
    descriptor function or Miniscript fragment, and each child edge states
    its role in the parent, or its depth for a Taproot leaf.
    
    Mark the new fields as experimental, since their names form a new
    interface. Test the output for wsh, Taproot with MuSig, each child
    role, hashes, sorted multisig, opaque scripts, private keys, and
    multipath descriptors.
    e7211cf5a4
  18. script: add AnalyzeDescriptor() for multisig setups
    Tell whether a parsed descriptor is a recognized k-of-n multisig setup,
    using only its structure (no wallet). This is the check a participant
    needs before importing a descriptor received from a coordinator.
    
    Recognized shapes are wsh((sorted)multi) and tr(K,(sorted)multi_a) with
    a single leaf, where K is the BIP 341 NUMS point or a musig() of at least
    k distinct cosigners. Every cosigner must be an extended key with an
    unhardened ranged derivation, and every musig() participant must be
    derivable without private keys. Anything else is reported as unrecognized
    with the reasons, each listing the keys involved, and no setup is claimed
    for it: no threshold, cosigners, sorting or key path.
    
    Two cosigner slots are the same holder if they share a root key, derive
    the same key at the first address, or one is the other's unhardened child
    xpub (checked by deriving it). Slots linked through a chain of these are
    one group. Core accepts such descriptors, and fewer signers than the
    threshold can spend from them. A hardened child can't be derived from the
    xpub, so it is not linked to it.
    
    For multipath descriptors every branch is analyzed and must be the same
    setup. The descriptor_parse fuzz targets check the analysis invariants.
    
    Co-authored-by: w0xlt <w0xlt@users.noreply.github.com>
    bcb40c7444
  19. rpc: add multisig analysis to getdescriptorinfo verbose
    Return the result of AnalyzeDescriptor() as an "analysis" object next to
    "keys" and "policy", referring to the same key IDs. This gives users and
    tools such as a multisig setup wizard the setup check without parsing
    the descriptor string or loading a wallet.
    
    For a multipath descriptor, "keys" and "policy" still describe the first
    path, while the analysis checks every path. An unrecognized descriptor
    returns only its issues.
    5e11b6841a
  20. wallet: add analyzeDescriptor to the wallet interface
    Combine AnalyzeDescriptor() with what only the wallet knows: which of the
    descriptor's keys it holds, and so whether it can sign. Also return the
    first receive address, which participants compare to confirm they all
    built the same wallet. Any descriptor is accepted; the multisig analysis
    tells whether it is a recognized setup.
    
    An extended key is the wallet's if it is one of the wallet's HD keys, or
    if its origin fingerprint is one of theirs and deriving the origin path
    gives the same key. A cosigner key usually has a hardened origin path, so
    checking it needs the private key. A locked wallet is not an error: such
    keys are reported as unknown, and the caller can ask the user to unlock
    and retry. Only the one candidate key is decrypted.
    
    A constant key is the wallet's if the wallet stores its private key, or if
    it was derived from one of the wallet's HD keys, checked the same way from
    its origin: the one in the descriptor, or the one the wallet recorded when
    it derived the key, as for a public key from getaddressinfo. The new
    DescriptorScriptPubKeyMan::GetPubKeyOrigin() returns that recorded origin
    without any private key.
    
    Keys the wallet holds only as musig() participants are matched too, even
    though GetHDPubKeys() (and so gethdkeys) leaves them out.
    
    Co-authored-by: w0xlt <w0xlt@users.noreply.github.com>
    be46ca77a7
  21. rpc: move descriptor key and analysis JSON helpers to a shared file
    Move the code that turns a descriptor's key occurrences and multisig
    analysis into JSON, and the help for those fields, from
    rpc/output_script.cpp (node library) to rpc/descriptor_util.cpp (common
    library), so a wallet RPC can return the same fields.
    
    Move-only, apart from exposing the functions and the help text. Review
    with --color-moved=dimmed-zebra --color-moved-ws=allow-indentation-change.
    9e9c3bca94
  22. wallet, rpc: add analyzedescriptor
    Expose the wallet's descriptor analysis as an RPC: the same keys and
    multisig analysis as getdescriptorinfo verbose, plus which keys this
    wallet holds, whether it can sign, and the first receive address that
    participants compare. Any descriptor is accepted.
    
    It follows the usual wallet RPC rules (-rpcwallet when several wallets
    are loaded, unavailable with -disablewallet). A locked wallet is not an
    error: keys that need a private key to check are reported as "unknown"
    and can_sign is left out. Without a wallet, getdescriptorinfo verbose
    gives the rest.
    
    Co-authored-by: w0xlt <w0xlt@users.noreply.github.com>
    5effb67c82
  23. doc: add release note for #36885 c59b0a3eab
  24. pablomartin4btc force-pushed on Nov 19, 2026
  25. DrahtBot removed the label CI failed on Nov 19, 2026
  26. fanquake removed the label Needs release note on Nov 19, 2026

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2026-11-19 19:51 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me