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:
- Inspection (commits by w0xlt, with small changes listed below):
GetKeyInfo(),GetKeyInventory()andGetPolicy()describe a parsed descriptor's key expressions, where each key is used, and how they combine.getdescriptorinfogains averboseoption that returns them askeysandpolicy. - Multisig analysis, no wallet:
AnalyzeDescriptor()tells whether a descriptor is a recognized k-of-n setup, and if not, why.getdescriptorinfo verbosereturns it asanalysis, so it works even with-disablewallet. - Wallet part:
interfaces::Wallet::analyzeDescriptor(for the GUI) and theanalyzedescriptorwallet RPC add which keys the wallet holds, whether it can sign, and the first receive address. They accept any descriptor, single-sig included;analysis.recognizedtells 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_extkeyinstead 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-tidyperformance-prefer-single-char-overloads).
- Use
- script: identify descriptor key occurrences
KeyRole()is pure virtual; descriptors without key arguments (addr,raw,sh,wsh) say so explicitly withNONFATAL_UNREACHABLE().- Comment noting that
frameis invalidated by the followingpush_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; explicitstatic_cast<uint32_t>for the threshold.- The fuzz target checks where each child role may appear (tap leaves only under
tr,scriptonly undersh/wsh, the Taproot internal key only ontr, the output key only onrawtr).
- rpc: add verbose option to getdescriptorinfo
- The multipath note moved to the
verboseargument help; thepolicyhelp explains both forms. - Tests for an origin without a path and for MuSig participant origins.
- The multipath note moved to the
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
numsormusig. Any other internal key, amusig()of fewer than k cosigners, or one with an outsider or a repeated cosigner iskey_path_spendable. - For a multipath descriptor every path is analyzed and must be the same setup (
branches_differotherwise).keysandpolicydescribe the first path. can_signmeans 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, withsorted: false: it is a valid k-of-n, and requiringsortedmultiwas 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_expansionalready 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.