descriptors.md
1 # Support for Output Descriptors in Bitcoin Core 2 3 Many Bitcoin Core RPCs support Output Descriptors. This is a simple language 4 which can be used to describe collections of output scripts. The wallet code 5 internally stores and operates on these descriptors to reason about the sets 6 of outputs that belong to the wallet. 7 8 This document describes the language. For the specifics on usage, see the RPC 9 documentation. 10 11 ## Features 12 13 Output descriptors currently support: 14 - Pay-to-pubkey scripts (P2PK), through the `pk` function. 15 - Pay-to-pubkey-hash scripts (P2PKH), through the `pkh` function. 16 - Pay-to-witness-pubkey-hash scripts (P2WPKH, see [BIP 141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki)), through the `wpkh` function. 17 - Pay-to-script-hash scripts (P2SH, see [BIP 16](https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki)), through the `sh` function. 18 - Pay-to-witness-script-hash scripts (P2WSH, see [BIP 141](https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki)), through the `wsh` function. 19 - Pay-to-taproot outputs (P2TR, see [BIP 341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki)), through the `tr` function. 20 - Multisig scripts, through the `multi` function. 21 - Multisig scripts where the public keys are sorted lexicographically, through the `sortedmulti` function. 22 - Multisig scripts inside taproot script trees, through the `multi_a` (and `sortedmulti_a`) function. 23 - Any type of supported address through the `addr` function. 24 - Raw hex scripts through the `raw` function. 25 - Public keys (compressed and uncompressed) in hex notation, or [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) extended pubkeys with derivation paths. 26 - MuSig2 key aggregation, see [BIP 327](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki). 27 - Miniscript expressions in `wsh` (P2WSH) and `tr` (P2TR) functions, see [BIP 379](https://github.com/bitcoin/bips/blob/master/bip-0379.md). 28 29 ## Examples 30 31 - `pk(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` describes a P2PK output with the specified public key. 32 - `pkh(02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5)` describes a P2PKH output with the specified public key. 33 - `wpkh(02f9308a019258c31049344f85f89d5229b531c845836f99b08601f113bce036f9)` describes a P2WPKH output with the specified public key. 34 - `sh(wpkh(03fff97bd5755eeea420453a14355235d382f6472f8568a18b2f057a1460297556))` describes a P2SH-P2WPKH output with the specified public key. 35 - `combo(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` describes any P2PK, P2PKH, P2WPKH, or P2SH-P2WPKH output with the specified public key. 36 - `sh(wsh(pkh(02e493dbf1c10d80f3581e4904930b1404cc6c13900ee0758474fa94abe8c4cd13)))` describes an (overly complicated) P2SH-P2WSH-P2PKH output with the specified public key. 37 - `multi(1,022f8bde4d1a07209355b4a7250a5c5128e88b84bddc619ab7cba8d569b240efe4,025cbdf0646e5db4eaa398f365f2ea7a0e3d419b7e0330e39ce92bddedcac4f9bc)` describes a bare *1-of-2* multisig output with keys in the specified order. 38 - `sh(multi(2,022f01e5e15cca351daff3843fb70f3c2f0a1bdd05e5af888a67784ef3e10a2a01,03acd484e2f0c7f65309ad178a9f559abde09796974c57e714c35f110dfc27ccbe))` describes a P2SH *2-of-2* multisig output with keys in the specified order. 39 - `sh(sortedmulti(2,03acd484e2f0c7f65309ad178a9f559abde09796974c57e714c35f110dfc27ccbe,022f01e5e15cca351daff3843fb70f3c2f0a1bdd05e5af888a67784ef3e10a2a01))` describes a P2SH *2-of-2* multisig output with keys sorted lexicographically in the resulting redeemScript. 40 - `wsh(multi(2,03a0434d9e47f3c86235477c7b1ae6ae5d3442d49b1943c2b752a68e2a47e247c7,03774ae7f858a9411e5ef4246b70c65aac5649980be5c17891bbec17895da008cb,03d01115d548e7561b15c38f004d734633687cf4419620095bc5b0f47070afe85a))` describes a P2WSH *2-of-3* multisig output with keys in the specified order. 41 - `sh(wsh(multi(1,03f28773c2d975288bc7d1d205c3748651b075fbc6610e58cddeeddf8f19405aa8,03499fdf9e895e719cfd64e67f07d38e3226aa7b63678949e6e49b241a60e823e4,02d7924d4f7d43ea965a465ae3095ff41131e5946f3c85f79e44adbcf8e27e080e)))` describes a P2SH-P2WSH *1-of-3* multisig output with keys in the specified order. 42 - `pk(xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8)` describes a P2PK output with the public key of the specified xpub. 43 - `pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1/2)` describes a P2PKH output with child key *1/2* of the specified xpub. 44 - `pkh([d34db33f/44'/0'/0']xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/1/*)` describes a set of P2PKH outputs, but additionally specifies that the specified xpub is a child of a master with fingerprint `d34db33f`, and derived using path `44'/0'/0'`. 45 - `wsh(multi(1,xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB/1/0/*,xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/0/0/*))` describes a set of *1-of-2* P2WSH multisig outputs where the first multisig key is the *1/0/`i`* child of the first specified xpub and the second multisig key is the *0/0/`i`* child of the second specified xpub, and `i` is any number in a configurable range (`0-1000` by default). 46 - `wsh(sortedmulti(1,xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB/1/0/*,xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH/0/0/*))` describes a set of *1-of-2* P2WSH multisig outputs where one multisig key is the *1/0/`i`* child of the first specified xpub and the other multisig key is the *0/0/`i`* child of the second specified xpub, and `i` is any number in a configurable range (`0-1000` by default). The order of public keys in the resulting witnessScripts is determined by the lexicographic order of the public keys at that index. 47 - `tr(c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5,{pk(fff97bd5755eeea420453a14355235d382f6472f8568a18b2f057a1460297556),pk(e493dbf1c10d80f3581e4904930b1404cc6c13900ee0758474fa94abe8c4cd13)})` describes a P2TR output with the `c6...` x-only pubkey as internal key, and two script paths. 48 - `tr(c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5,sortedmulti_a(2,2f8bde4d1a07209355b4a7250a5c5128e88b84bddc619ab7cba8d569b240efe4,5cbdf0646e5db4eaa398f365f2ea7a0e3d419b7e0330e39ce92bddedcac4f9bc))` describes a P2TR output with the `c6...` x-only pubkey as internal key, and a single `multi_a` script that needs 2 signatures with 2 specified x-only keys, which will be sorted lexicographically. 49 - `wsh(sortedmulti(2,[6f53d49c/44h/1h/0h]tpubDDjsCRDQ9YzyaAq9rspCfq8RZFrWoBpYnLxK6sS2hS2yukqSczgcYiur8Scx4Hd5AZatxTuzMtJQJhchufv1FRFanLqUP7JHwusSSpfcEp2/<0;1>/*,[e6807791/44h/1h/0h]tpubDDAfvogaaAxaFJ6c15ht7Tq6ZmiqFYfrSmZsHu7tHXBgnjMZSHAeHSwhvjARNA6Qybon4ksPksjRbPDVp7yXA1KjTjSd5x18KHqbppnXP1s/<0;1>/*,[367c9cfa/44h/1h/0h]tpubDDtPnSgWYk8dDnaDwnof4ehcnjuL5VoUt1eW2MoAed1grPHuXPDnkX1fWMvXfcz3NqFxPbhqNZ3QBdYjLz2hABeM9Z2oqMR1Gt2HHYDoCgh/<0;1>/*))` describes a *2-of-3* multisig with a multipath descriptor specifying both receiving (/0) and change (/1) address derivation paths. 50 - `wsh(thresh(4,pk([7258e4f9/44h/1h/0h]tpubDCZrkQoEU3845aFKUu9VQBYWZtrTwxMzcxnBwKFCYXHD6gEXvtFcxddCCLFsEwmxQaG15izcHxj48SXg1QS5FQGMBx5Ak6deXKPAL7wauBU/<0;1>/*),s:pk([c80b1469/44h/1h/0h]tpubDD3UwwHoNUF4F3Vi5PiUVTc3ji1uThuRfFyBexTSHoAcHuWW2z8qEE2YujegcLtgthr3wMp3ZauvNG9eT9xfJyxXCfNty8h6rDBYU8UU1qq/<0;1>/*),s:pk([4e5024fe/44h/1h/0h]tpubDDLrpPymPLSCJyCMLQdmcWxrAWwsqqssm5NdxT2WSdEBPSXNXxwbeKtsHAyXPpLkhUyKovtZgCi47QxVpw9iVkg95UUgeevyAqtJ9dqBqa1/<0;1>/*),s:pk([3b1d1ee9/44h/1h/0h]tpubDCmDTANBWPzf6d8Ap1J5Ku7J1Ay92MpHMrEV7M5muWxCrTBN1g5f1NPcjMEL6dJHxbvEKNZtYCdowaSTN81DAyLsmv6w6xjJHCQNkxrsrfu/<0;1>/*),sln:after(840000),sln:after(1050000),sln:after(1260000)))` describes a Miniscript multisig with spending policy: `thresh(4,pk(key_1),pk(key_2),pk(key_3),pk(key_4),after(t1),after(t2),after(t3))` that starts as 4-of-4 and "decays" to 3-of-4, 2-of-4, and finally 1-of-4 at each future halvening block height. This uses a multipath descriptor specifying both receiving (/0) and change (/1) address derivation paths. 51 - `tr(musig(xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL,xpub68NZiKmJWnxxS6aaHmn81bvJeTESw724CRDs6HbuccFQN9Ku14VQrADWgqbhhTHBaohPX4CjNLf9fq9MYo6oDaPPLPxSb7gwQN3ih19Zm4Y)/0/*)` describes a MuSig2 multisig with key derivation. The internal keys are derived at `m/0/*` from the aggregate key computed from the 2 participants. 52 53 ## Reference 54 55 Descriptors consist of several types of expressions. The top level expression is either a `SCRIPT`, or `SCRIPT#CHECKSUM` where `CHECKSUM` is an 8-character alphanumeric descriptor checksum. 56 57 `SCRIPT` expressions, defined in [BIP 380](https://github.com/bitcoin/bips/blob/master/bip-0380.mediawiki): 58 - `sh(SCRIPT)` (top level only): P2SH-embed the argument, defined in [BIP 381](https://github.com/bitcoin/bips/blob/master/bip-0381.mediawiki). 59 - `wsh(SCRIPT)` (top level or inside `sh` only): P2WSH-embed the argument, defined in [BIP 382](https://github.com/bitcoin/bips/blob/master/bip-0382.mediawiki). 60 - `pk(KEY)` (anywhere): P2PK output for the given public key, defined in [BIP 381](https://github.com/bitcoin/bips/blob/master/bip-0381.mediawiki). 61 - `pkh(KEY)` (not inside `tr`): P2PKH output for the given public key (use `addr` if you only know the pubkey hash), defined in [BIP 381](https://github.com/bitcoin/bips/blob/master/bip-0381.mediawiki). 62 - `wpkh(KEY)` (top level or inside `sh` only): P2WPKH output for the given compressed pubkey, defined in [BIP 382](https://github.com/bitcoin/bips/blob/master/bip-0382.mediawiki). 63 - `combo(KEY)` (top level only): an alias for the collection of `pk(KEY)` and `pkh(KEY)`, defined in [BIP 384](https://github.com/bitcoin/bips/blob/master/bip-0384.mediawiki). If the key is compressed, it also includes `wpkh(KEY)` and `sh(wpkh(KEY))`. 64 - `multi(k,KEY_1,KEY_2,...,KEY_n)` (not inside `tr`): k-of-n multisig script using OP_CHECKMULTISIG, defined in [BIP 383](https://github.com/bitcoin/bips/blob/master/bip-0383.mediawiki). 65 - `sortedmulti(k,KEY_1,KEY_2,...,KEY_n)` (not inside `tr`): k-of-n multisig script with keys sorted lexicographically in the resulting script, defined in [BIP 383](https://github.com/bitcoin/bips/blob/master/bip-0383.mediawiki). 66 - `multi_a(k,KEY_1,KEY_2,...,KEY_N)` (only inside `tr`): k-of-n multisig script using OP_CHECKSIG, OP_CHECKSIGADD, and OP_NUMEQUAL, defined in [BIP 387](https://github.com/bitcoin/bips/blob/master/bip-0387.mediawiki). 67 - `sortedmulti_a(k,KEY_1,KEY_2,...,KEY_N)` (only inside `tr`): similar to `multi_a`, but the (x-only) public keys in it will be sorted lexicographically, defined in [BIP 387](https://github.com/bitcoin/bips/blob/master/bip-0387.mediawiki). 68 - `tr(KEY)` or `tr(KEY,TREE)` (top level only): P2TR output with the specified key as internal key, and optionally a tree of script paths, defined in [BIP 386](https://github.com/bitcoin/bips/blob/master/bip-0386.mediawiki). 69 - `addr(ADDR)` (top level only): the script which ADDR expands to, defined in [BIP 385](https://github.com/bitcoin/bips/blob/master/bip-0385.mediawiki). 70 - `raw(HEX)` (top level only): the script whose hex encoding is HEX, defined in [BIP 385](https://github.com/bitcoin/bips/blob/master/bip-0385.mediawiki). 71 - `rawtr(KEY)` (top level only): P2TR output with the specified key as output key. NOTE: while it's possible to use this to construct wallets, it has several downsides, like being unable to prove no hidden script path exists. Use at your own risk. 72 - The miniscript expressions `0`, `1`, `pk_k(KEY)`, `pk_h(KEY)`, `older(k)`, `after(k)`, `sha256(HEX)`, `hash256(HEX)`, `ripemd160(HEX)`, `hash160(HEX)`, `andor(SCRIPT,SCRIPT,SCRIPT)`, `and_v(SCRIPT,SCRIPT)`, `and_b(SCRIPT,SCRIPT)`, `and_n(SCRIPT,SCRIPT)`, `or_b(SCRIPT,SCRIPT)`, `or_c(SCRIPT,SCRIPT)`, `or_d(SCRIPT,SCRIPT)`, `or_i(SCRIPT,SCRIPT)`, `thresh(k,SCRIPT,SCRIPT,...)`, `a:SCRIPT`, `s:SCRIPT`, `c:SCRIPT`, `t:SCRIPT`, `d:SCRIPT`, `v:SCRIPT`, `j:SCRIPT`, `n:SCRIPT`, `l:SCRIPT`, and `u:SCRIPT`, all only inside `wsh()` and `tr()`. Various rules apply that control how these can be combined. For details, see [BIP 379](https://github.com/bitcoin/bips/blob/master/bip-0379.md). 73 74 `KEY` expressions, defined in [BIP 380](https://github.com/bitcoin/bips/blob/master/bip-0380.mediawiki): 75 - Optionally, key origin information, consisting of: 76 - An open bracket `[` 77 - Exactly 8 hex characters for the fingerprint of the key where the derivation starts (see [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)) 78 - Followed by zero or more `/NUM` or `/NUM'` path elements to indicate unhardened or hardened derivation steps between the fingerprint and the key or xpub/xprv root that follows 79 - A closing bracket `]` 80 - Followed by the actual key, which is either: 81 - Hex encoded public keys (either 66 characters starting with `02` or `03` for a compressed pubkey, or 130 characters starting with `04` for an uncompressed pubkey). 82 - Inside `wpkh` and `wsh`, only compressed public keys are permitted. 83 - Inside `tr` and `rawtr`, x-only pubkeys are also permitted (64 hex characters). 84 - [WIF](https://en.bitcoin.it/wiki/Wallet_import_format) encoded private keys may be specified instead of the corresponding public key, with the same meaning. 85 - `xpub` encoded extended public key or `xprv` encoded extended private key (as defined in [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)). 86 - Followed by zero or more `/NUM` unhardened and `/NUM'` hardened BIP32 derivation steps. 87 - No more than one of these derivation steps may be of the form `<NUM;NUM;...;NUM>` (including hardened indicators with either or both `NUM`). If such specifiers are included, the descriptor will be parsed as multiple descriptors where the first descriptor uses all of the first `NUM` in the pair, and the second descriptor uses the second `NUM` in the pair for all `KEY` expressions, and so on. Defined in [BIP 389](https://github.com/bitcoin/bips/blob/master/bip-0389.mediawiki). 88 - Optionally followed by a single `/*` or `/*'` final step to denote all (direct) unhardened or hardened children. 89 - The usage of hardened derivation steps requires providing the private key. 90 - `musig(KEY,KEY,...)` to represent the MuSig2 key aggregation of the relevant keys, only inside `tr()` expressions. It may be followed by unhardened `/NUM` derivation steps if all `KEY` subexpressions are xpubs or derived thereof, and none use `/*` or `/<NUM;NUM;...>`. Defined in [BIP 390](https://github.com/bitcoin/bips/blob/master/bip-0390.mediawiki). 91 92 (Anywhere a `'` suffix is permitted to denote hardened derivation, the suffix `h` can be used instead.) 93 94 `TREE` expressions, defined in [BIP 386](https://github.com/bitcoin/bips/blob/master/bip-0386.mediawiki): 95 - any `SCRIPT` expression 96 - An open brace `{`, a `TREE` expression, a comma `,`, a `TREE` expression, and a closing brace `}` 97 98 `ADDR` expressions are any type of supported address, defined in [BIP 385](https://github.com/bitcoin/bips/blob/master/bip-0385.mediawiki): 99 - P2PKH addresses (base58, of the form `1...` for mainnet or `[nm]...` for testnet). Note that P2PKH addresses in descriptors cannot be used for P2PK outputs (use the `pk` function instead). 100 - P2SH addresses (base58, of the form `3...` for mainnet or `2...` for testnet, defined in [BIP 13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki)). 101 - Segwit addresses (bech32 and bech32m, of the form `bc1...` for mainnet or `tb1...` for testnet, defined in [BIP 173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki) and [BIP 350](https://github.com/bitcoin/bips/blob/master/bip-0350.mediawiki)). 102 103 ## Explanation 104 105 ### Single-key scripts 106 107 Many single-key constructions are used in practice, generally including 108 P2PK, P2PKH, P2WPKH, and P2SH-P2WPKH. Many more combinations are 109 imaginable, though they may not be optimal: P2SH-P2PK, P2SH-P2PKH, 110 P2WSH-P2PK, P2WSH-P2PKH, P2SH-P2WSH-P2PK, P2SH-P2WSH-P2PKH. 111 112 To describe these, we model these as functions. The functions `pk` 113 (P2PK), `pkh` (P2PKH) and `wpkh` (P2WPKH) take as input a `KEY` expression, and return the 114 corresponding *scriptPubKey*. The functions `sh` (P2SH) and `wsh` (P2WSH) 115 take as input a `SCRIPT` expression, and return the script describing P2SH and P2WSH 116 outputs with the input as embedded script. The names of the functions do 117 not contain "p2" for brevity. 118 119 ### Multisig 120 121 Several pieces of software use multi-signature (multisig) scripts based 122 on Bitcoin's OP_CHECKMULTISIG opcode. To support these, we introduce the 123 `multi(k,key_1,key_2,...,key_n)` and `sortedmulti(k,key_1,key_2,...,key_n)` 124 functions. They represent a *k-of-n* 125 multisig policy, where any *k* out of the *n* provided `KEY` expressions must 126 sign. 127 128 Key order is significant for `multi()`. A `multi()` expression describes a multisig script 129 with keys in the specified order, and in a search for TXOs, it will not match 130 outputs with multisig scriptPubKeys that have the same keys in a different 131 order. Also, to prevent a combinatorial explosion of the search space, if more 132 than one of the `multi()` key arguments is a BIP32 wildcard path ending in `/*` 133 or `*'`, the `multi()` expression only matches multisig scripts with the `i`th 134 child key from each wildcard path in lockstep, rather than scripts with any 135 combination of child keys from each wildcard path. 136 137 Key order does not matter for `sortedmulti()`. `sortedmulti()` behaves in the same way 138 as `multi()` does but the keys are reordered in the resulting script such that they 139 are lexicographically ordered as described in BIP67. 140 141 #### Basic multisig example 142 143 For a good example of a basic M-of-N multisig between multiple participants using descriptor 144 wallets and PSBTs, as well as a signing flow, see [this functional test](/test/functional/wallet_multisig_descriptor_psbt.py). 145 146 Disclaimers: It is important to note that this example serves as a quick-start and is kept basic for readability. A downside of the approach 147 outlined here is that each participant must maintain (and backup) two separate wallets: a signer and the corresponding multisig. 148 It should also be noted that privacy best-practices are not "by default" here - participants should take care to only use the signer to sign 149 transactions related to the multisig. Lastly, it is not recommended to use anything other than a Bitcoin Core descriptor wallet to serve as your 150 signer(s). Other wallets, whether hardware or software, likely impose additional checks and safeguards to prevent users from signing transactions that 151 could lead to loss of funds, or are deemed security hazards. Conforming to various 3rd-party checks and verifications is not in the scope of this example. 152 153 The basic steps are: 154 155 1. Every participant generates an xpub. The most straightforward way is to create a new descriptor wallet which we will refer to as 156 the participant's signer wallet. Avoid reusing this wallet for any purpose other than signing transactions from the 157 corresponding multisig we are about to create. Hint: extract the wallet's xpubs using `listdescriptors` and pick the one from the 158 `pkh` descriptor since it's least likely to be accidentally reused (legacy addresses) 159 2. Create a watch-only descriptor wallet (blank, private keys disabled). Now the multisig is created by importing a single multipath descriptor: 160 `wsh(sortedmulti(<M>,XPUB1/<0;1>/*,XPUB2/<0;1>/*,…,XPUBN/<0;1>/*))` 161 This single descriptor specifies both receiving (`/0`) and change (`/1`) addresses. Every participant does this. All key origin information (master key fingerprint and all derivation steps) should be included with xpubs for proper support of hardware devices / external signers 162 3. A receiving address is generated for the multisig. As a check to ensure step 2 was done correctly, every participant 163 should verify they get the same addresses 164 4. Funds are sent to the resulting address 165 5. A sending transaction from the multisig is created using `walletcreatefundedpsbt` (anyone can initiate this). It is simple to do 166 this in the GUI by going to the `Send` tab in the multisig wallet and creating an unsigned transaction (PSBT) 167 6. At least `M` participants check the PSBT with their multisig using `decodepsbt` to verify the transaction is OK before signing it. 168 7. (If OK) the participant signs the PSBT with their signer wallet using `walletprocesspsbt`. It is simple to do this in the GUI by 169 loading the PSBT from file and signing it 170 8. The signed PSBTs are collected with `combinepsbt`, finalized w/ `finalizepsbt`, and then the resulting transaction is broadcasted 171 to the network. Note that any wallet (eg one of the signers or multisig) is capable of doing this. 172 9. Checks that balances are correct after the transaction has been included in a block 173 174 You may prefer a daisy chained signing flow where each participant signs the PSBT one after another until 175 the PSBT has been signed `M` times and is "complete." For the most part, the steps above remain the same, except (6, 7) 176 change slightly from signing the original PSBT in parallel to signing it in series. `combinepsbt` is not necessary with 177 this signing flow and the last (`m`th) signer can just broadcast the PSBT after signing. Note that a parallel signing flow may be 178 preferable in cases where there are more signers. This signing flow is also included in the test / Python example. 179 [The test](/test/functional/wallet_multisig_descriptor_psbt.py) is meant to be documentation as much as it is a functional test, so 180 it is kept as simple and readable as possible. 181 182 #### Basic Miniscript-enabled "decaying" multisig example 183 184 For an example of a multisig that starts as 4-of-4 and "decays" to 3-of-4, 2-of-4, and finally 1-of-4 at each future halvening block height, see [this functional test](/test/functional/wallet_miniscript_decaying_multisig_descriptor_psbt.py). 185 186 This has the same "architecture" and signing flow as the above [Basic multisig example](#basic-multisig-example). The basic steps are identical aside from the descriptor that defines this wallet, which is of the form: `wsh(thresh(4,pk(XPUB1),s:pk(XPUB2),s:pk(XPUB3),s:pk(XPUB4),sln:after(t1),sln:after(t2),sln:after(t3)))`. 187 188 [The test](/test/functional/wallet_miniscript_decaying_multisig_descriptor_psbt.py) is meant to be documentation as much as it is a functional test, so it is kept as simple and readable as possible. 189 190 ### BIP32 derived keys and chains 191 192 Most modern wallet software and hardware uses keys that are derived using 193 BIP32 ("HD keys"). We support these directly by permitting strings 194 consisting of an extended public key (commonly referred to as an *xpub*) 195 plus derivation path anywhere a public key is expected. The derivation 196 path consists of a sequence of 0 or more integers (in the range 197 *0..2<sup>31</sup>-1*) each optionally followed by `'` or `h`, and 198 separated by `/` characters. The string may optionally end with the 199 literal `/*` or `/*'` (or `/*h`) to refer to all unhardened or hardened 200 child keys in a configurable range (by default `0-1000`, inclusive). 201 202 Whenever a public key is described using a hardened derivation step, the 203 script cannot be computed without access to the corresponding private 204 key. 205 206 ### Key origin identification 207 208 In order to describe scripts whose signing keys reside on another device, 209 it may be necessary to identify the master key and derivation path an 210 xpub was derived with. 211 212 For example, when following BIP44, it would be useful to describe a 213 change chain directly as `xpub.../44'/0'/0'/1/*` where `xpub...` 214 corresponds with the master key `m`. Unfortunately, since there are 215 hardened derivation steps that follow the xpub, this descriptor does not 216 let you compute scripts without access to the corresponding private keys. 217 Instead, it should be written as `xpub.../1/*`, where xpub corresponds to 218 `m/44'/0'/0'`. 219 220 When interacting with a hardware device, it may be necessary to include 221 the entire path from the master down. [BIP 174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki) standardizes this by 222 providing the master key *fingerprint* (first 32 bits of the Hash160 of 223 the master pubkey), plus all derivation steps. To support constructing 224 these, we permit providing this key origin information inside the 225 descriptor language, even though it does not affect the actual 226 scriptPubKeys it refers to. 227 228 Every public key can be prefixed by an 8-character hexadecimal 229 fingerprint plus optional derivation steps (hardened and unhardened) 230 surrounded by brackets, identifying the master and derivation path the key or xpub 231 that follows was derived with. 232 233 Note that the fingerprint of the parent only serves as a fast way to detect 234 parent and child nodes in software, and software must be willing to deal with 235 collisions. 236 237 ### Including private keys 238 239 Often it is useful to communicate a description of scripts along with the 240 necessary private keys. For this reason, anywhere a public key or xpub is 241 supported, a private key in WIF format or xprv may be provided instead. 242 This is useful when private keys are necessary for hardened derivation 243 steps, for signing transactions, or for dumping wallet descriptors 244 including private key material. 245 246 For example, after importing the following 2-of-3 multisig descriptor 247 into a wallet, one could use `signrawtransactionwithwallet` 248 to sign a transaction with the first key: 249 ``` 250 sh(multi(2,xprv.../84'/0'/0'/0/0,xpub1...,xpub2...)) 251 ``` 252 Note how the first key is an xprv private key with a specific derivation path, 253 while the other two are public keys. 254 255 256 ### Specifying receiving and change descriptors in one descriptor 257 258 Since receiving and change addresses are frequently derived from the same 259 extended key(s) but with a single derivation index changed, it is convenient 260 to be able to specify a descriptor that can derive at the two different 261 indexes. Thus a single tuple of indexes is allowed in each derivation path 262 following the extended key. When this descriptor is parsed, multiple descriptors 263 will be produced, the first one will use the first index in the tuple for all 264 key expressions, the second will use the second index, the third will use the 265 third index, and so on.. 266 267 For example, a descriptor of the form: 268 269 multi(2,xpub.../<0;1;2>/0/*,xpub.../<2;3;4>/*) 270 271 will expand to the 3 descriptors 272 273 multi(2,xpub.../0/0/*,xpub.../2/*) 274 multi(2,xpub.../1/0/*,xpub.../3/*) 275 multi(2,xpub.../2/0/*,xpub.../4/*) 276 277 When this tuple contains only two elements, wallet implementations can use the 278 first descriptor for receiving addresses and the second descriptor for change addresses. 279 280 ### Compatibility with old wallets 281 282 In order to easily represent the sets of scripts currently supported by 283 existing Bitcoin Core wallets, a convenience function `combo` is 284 provided, which takes as input a public key, and describes a set of P2PK, 285 P2PKH, P2WPKH, and P2SH-P2WPKH scripts for that key. In case the key is 286 uncompressed, the set only includes P2PK and P2PKH scripts. 287 288 ### Checksums 289 290 Descriptors can optionally be suffixed with a checksum to protect against 291 typos or copy-paste errors. 292 293 These checksums consist of 8 alphanumeric characters. As long as errors are 294 restricted to substituting characters in `0123456789()[],'/*abcdefgh@:$%{}` 295 for others in that set and changes in letter case, up to 4 errors will always 296 be detected in descriptors up to 501 characters, and up to 3 errors in longer 297 ones. For larger numbers of errors, or other types of errors, there is a 298 roughly 1 in a trillion chance of not detecting the errors. 299 300 All RPCs in Bitcoin Core will include the checksum in their output. Only 301 certain RPCs require checksums on input, including `deriveaddresses` and 302 `importdescriptors`. The checksum for a descriptor without one can be computed 303 using the `getdescriptorinfo` RPC.