diff --git a/doc/descriptors.md b/doc/descriptors.md index 5ad52d1e0..4dcbac364 100644 --- a/doc/descriptors.md +++ b/doc/descriptors.md @@ -1,160 +1,172 @@ # Support for Output Descriptors in Bitcoin ABC -Since Bitcoin ABC v0.20.7, there is support for Output Descriptors in the +Since Bitcoin ABC v0.20.7, there is support for Output Descriptors. This is a +simple language which can be used to describe collections of output scripts. +Supporting RPCs are: +- `scantxoutset` takes as input descriptors to scan for, and also reports + specialized descriptors for the matching UTXOs. +- `getdescriptorinfo` analyzes a descriptor, and reports a canonicalized version + with checksum added. +- `deriveaddresses` takes as input a descriptor and computes the corresponding + addresses. +- `listunspent` outputs a specialized descriptor for the reported unspent outputs. + +This document describes the language. For the specifics on usage, see the RPC +documentation for the functions mentioned above.in the `scantxoutset` RPC call. This is a simple language which can be used to describe collections of output scripts. This document describes the language. For the specifics on usage for scanning the UTXO set, see the `scantxoutset` RPC help. ## Features Output descriptors currently support: - Pay-to-pubkey scripts (P2PK), through the `pk` function. - Pay-to-pubkey-hash scripts (P2PKH), through the `pkh` function. - Pay-to-script-hash scripts (P2SH), through the `sh` function. - Multisig scripts, through the `multi` function. - Any type of supported address through the `addr` function. - Raw hex scripts through the `raw` function. - Public keys (compressed and uncompressed) in hex notation, or BIP32 extended pubkeys with derivation paths. ## Examples - `pk(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` represents a P2PK output. - `pkh(02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5)` represents a P2PKH output. - `combo(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` represents a P2PK and P2PKH output. - `multi(1,022f8bde4d1a07209355b4a7250a5c5128e88b84bddc619ab7cba8d569b240efe4,025cbdf0646e5db4eaa398f365f2ea7a0e3d419b7e0330e39ce92bddedcac4f9bc)` represents a bare *1-of-2* multisig. - `sh(multi(2,022f01e5e15cca351daff3843fb70f3c2f0a1bdd05e5af888a67784ef3e10a2a01,03acd484e2f0c7f65309ad178a9f559abde09796974c57e714c35f110dfc27ccbe))` represents a P2SH *2-of-2* multisig. - `pk(xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8)` refers to a single P2PK output, using the public key part from the specified xpub. - `pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1'/2)` refers to a single P2PKH output, using child key *1'/2* of the specified xpub. - `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'`. ## Reference 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. `SCRIPT` expressions: - `sh(SCRIPT)` (top level only): P2SH embed the argument. - `pk(KEY)` (anywhere): P2PK output for the given public key. - `pkh(KEY)` (anywhere): P2PKH output for the given public key (use `addr` if you only know the pubkey hash). - `combo(KEY)` (top level only): an alias for the collection of `pk(KEY)` and `pkh(KEY)`. - `multi(k,KEY_1,KEY_2,...,KEY_n)` (anywhere): k-of-n multisig script. - `addr(ADDR)` (top level only): the script which ADDR expands to. - `raw(HEX)` (top level only): the script whose hex encoding is HEX. `KEY` expressions: - Optionally, key origin information, consisting of: - An open bracket `[` - Exactly 8 hex characters for the fingerprint of the key where the derivation starts (see BIP32 for details) - 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 - A closing bracket `]` - Followed by the actual key, which is either: - Hex encoded public keys (66 characters starting with `02` or `03`, or 130 characters starting with `04`). - [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. -`xpub` encoded extended public key or `xprv` encoded private key (as defined in [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)). - Followed by zero or more `/NUM` unhardened and `/NUM'` hardened BIP32 derivation steps. - Optionally followed by a single `/*` or `/*'` final step to denote all (direct) unhardened or hardened children. - The usage of hardened derivation steps requires providing the private key. - Anywhere a `'` suffix is permitted to denote hardened derivation, the suffix `h` can be used instead. `ADDR` expressions are any type of supported address: - P2PKH addresses (base58, of the form `1...`). Note that P2PKH addresses in descriptors cannot be used for P2PK outputs (use the `pk` function instead). - P2SH addresses (base58, of the form `3...`, defined in [BIP 13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki)). ## Explanation ### Single-key scripts Many single-key constructions are used in practice, generally including P2PK, and P2PKH. Many more combinations are imaginable, though they may not be optimal: P2SH-P2PK, P2SH-P2PKH. To describe these, we model these as functions. The functions `pk` (P2PK) and `pkh` (P2PKH) take as input a public key in hexadecimal notation (which will be extended later), and return the corresponding *scriptPubKey*. The functions `sh` (P2SH) take as input a script, and return the script describing P2SH outputs with the input as embedded script. The names of the functions do not contain "p2" for brevity. ### Multisig Several pieces of software use multi-signature (multisig) scripts based on Bitcoin's OP_CHECKMULTISIG opcode. To support these, we introduce the `multi(k,key_1,key_2,...,key_n)` function. It represents a *k-of-n* multisig policy, where any *k* out of the *n* provided public keys must sign. ### BIP32 derived keys and chains Most modern wallet software and hardware uses keys that are derived using BIP32 ("HD keys"). We support these directly by permitting strings consisting of an extended public key (commonly referred to as an *xpub*) plus derivation path anywhere a public key is expected. The derivation path consists of a sequence of 0 or more integers (in the range *0..231-1*) each optionally followed by `'` or `h`, and separated by `/` characters. The string may optionally end with the literal `/*` or `/*'` (or `/*h`) to refer to all unhardened or hardened child keys instead. Whenever a public key is described using a hardened derivation step, the script cannot be computed without access to the corresponding private key. ### Key origin identification In order to describe scripts whose signing keys reside on another device, it may be necessary to identify the master key and derivation path an xpub was derived with. For example, when following BIP44, it would be useful to describe a change chain directly as `xpub.../44'/0'/0'/1/*` where `xpub...` corresponds with the master key `m`. Unfortunately, since there are hardened derivation steps that follow the xpub, this descriptor does not let you compute scripts without access to the corresponding private keys. Instead, it should be written as `xpub.../1/*`, where xpub corresponds to `m/44'/0'/0'`. When interacting with a hardware device, it may be necessary to include the entire path from the master down. BIP174 standardizes this by providing the master key *fingerprint* (first 32 bit of the Hash160 of the master pubkey), plus all derivation steps. To support constructing these, we permit providing this key origin information inside the descriptor language, even though it does not affect the actual scriptPubKeys it refers to. Every public key can be prefixed by an 8-character hexadecimal fingerprint plus optional derivation steps (hardened and unhardened) surrounded by brackets, identifying the master and derivation path the key or xpub that follows was derived with. ### Including private keys Often it is useful to communicate a description of scripts along with the necessary private keys. For this reason, anywhere a public key or xpub is supported, a private key in WIF format or xprv may be provided instead. This is useful when private keys are necessary for hardened derivation steps, or for dumping wallet descriptors including private key material. ### Compatibility with old wallets In order to easily represent the sets of scripts currently supported by existing Bitcoin ABC wallets, a convenience function `combo` is provided, which takes as input a public key, and constructs the P2PK and P2PKH scripts for that key. ### Checksums Descriptors can optionally be suffixed with a checksum to protect against typos or copy-paste errors. These checksums consist of 8 alphanumeric characters. As long as errors are restricted to substituting characters in `0123456789()[],'/*abcdefgh@:$%{}` for others in that set and changes in letter case, up to 4 errors will always be detected in descriptors up to 501 characters, and up to 3 errors in longer ones. For larger numbers of errors, or other types of errors, there is a roughly 1 in a trillion chance of not detecting the errors. All RPCs in Bitcoin ABC will include the checksum in their output. Only certain RPCs require checksums on input, including `deriveaddress` and `importmulti`. The checksum for a descriptor without one can be computed using the `getdescriptorinfo` RPC. diff --git a/doc/psbt.md b/doc/psbt.md index 5ddbfd82b..8b93a7e3d 100644 --- a/doc/psbt.md +++ b/doc/psbt.md @@ -1,132 +1,143 @@ # PSBT Howto for Bitcoin ABC Since Bitcoin ABC v0.20.7, an RPC interface exists for Partially Signed Bitcoin Transactions (PSBTs, as specified in [BIP 174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki)). This document describes the overall workflow for producing signed transactions through the use of PSBT, and the specific RPC commands used in typical scenarios. ## PSBT in general PSBT is an interchange format for Bitcoin transactions that are not fully signed yet, together with relevant metadata to help entities work towards signing it. It is intended to simplify workflows where multiple parties need to cooperate to produce a transaction. Examples include hardware wallets, multisig setups, and [CoinJoin](https://bitcointalk.org/?topic=279249) transactions. ### Overall workflow Overall, the construction of a fully signed Bitcoin transaction goes through the following steps: - A **Creator** proposes a particular transaction to be created. They construct a PSBT that contains certain inputs and outputs, but no additional metadata. - For each input, an **Updater** adds information about the UTXOs being spent by the transaction to the PSBT. They also add information about the scripts and public keys involved in each of the inputs (and possibly outputs) of the PSBT. - **Signers** inspect the transaction and its metadata to decide whether they agree with the transaction. They can use amount information from the UTXOs to assess the values and fees involved. If they agree, they produce a partial signature for the inputs for which they have relevant key(s). - A **Finalizer** is run for each input to convert the partial signatures and possibly script information into a final `scriptSig` and/or `scriptWitness`. - An **Extractor** produces a valid Bitcoin transaction (in network format) from a PSBT for which all inputs are finalized. Generally, each of the above (excluding Creator and Extractor) will simply add more and more data to a particular PSBT, until all inputs are fully signed. In a naive workflow, they all have to operate sequentially, passing the PSBT from one to the next, until the Extractor can convert it to a real transaction. In order to permit parallel operation, **Combiners** can be employed which merge metadata from different PSBTs for the same unsigned transaction. The names above in bold are the names of the roles defined in BIP174. They're useful in understanding the underlying steps, but in practice, software and hardware implementations will typically implement multiple roles simultaneously. ## PSBT in Bitcoin ABC ### RPCs - **`converttopsbt` (Creator)** is a utility RPC that converts an unsigned raw transaction to PSBT format. It ignores existing signatures. - **`createpsbt` (Creator)** is a utility RPC that takes a list of inputs and outputs and converts them to a PSBT with no additional information. It is equivalent to calling `createrawtransaction` followed by `converttopsbt`. - **`walletcreatefundedpsbt` (Creator, Updater)** is a wallet RPC that creates a PSBT with the specified inputs and outputs, adds additional inputs and change to it to balance it out, and adds relevant metadata. In particular, for inputs that the wallet knows about (counting towards its normal or watch-only balance), UTXO information will be added. For outputs and inputs with UTXO information present, key and script information will be added which the wallet knows about. It is equivalent to running `createrawtransaction`, followed by `fundrawtransaction`, and `converttopsbt`. - **`walletprocesspsbt` (Updater, Signer, Finalizer)** is a wallet RPC that takes as input a PSBT, adds UTXO, key, and script data to inputs and outputs that miss it, and optionally signs inputs. Where possible it also finalizes the partial signatures. +- **`utxoupdatepsbt` (Updater)** is a node RPC that takes a PSBT and updates it + to include information available from the UTXO set (works only for SegWit + inputs). - **`finalizepsbt` (Finalizer, Extractor)** is a utility RPC that finalizes any partial signatures, and if all inputs are finalized, converts the result to a fully signed transaction which can be broadcast with `sendrawtransaction`. - **`combinepsbt` (Combiner)** is a utility RPC that implements a Combiner. It can be used at any point in the workflow to merge information added to different versions of the same PSBT. In particular it is useful to combine the output of multiple Updaters or Signers. +- **`joinpsbts`** (Creator) is a utility RPC that joins multiple PSBTs together, + concatenating the inputs and outputs. This can be used to construct CoinJoin + transactions. - **`decodepsbt`** is a diagnostic utility RPC which will show all information in a PSBT in human-readable form, as well as compute its eventual fee if known. +- **`analyzepsbt`** is a utility RPC that examines a PSBT and reports the + current status of its inputs, the next step in the workflow if known, and if + possible, computes the fee of the resulting transaction and estimates the + final weight and feerate. + ### Workflows #### Multisig with multiple Bitcoin ABC instances Alice, Bob, and Carol want to create a 2-of-3 multisig address. They're all using Bitcoin ABC. We assume their wallets only contain the multisig funds. In case they also have a personal wallet, this can be accomplished through the multiwallet feature - possibly resulting in a need to add `-rpcwallet=name` to the command line in case `bitcoin-cli` is used. Setup: - All three call `getnewaddress` to create a new address; call these addresses *Aalice*, *Abob*, and *Acarol*. - All three call `getaddressinfo "X"`, with *X* their respective address, and remember the corresponding public keys. Call these public keys *Kalice*, *Kbob*, and *Kcarol*. - All three now run `addmultisigaddress 2 ["Kalice","Kbob","Kcarol"]` to teach their wallet about the multisig script. Call the address produced by this command *Amulti*. They may be required to explicitly specify the same addresstype option each, to avoid constructing different versions due to differences in configuration. - They also run `importaddress "Amulti" "" false` to make their wallets treat payments to *Amulti* as contributing to the watch-only balance. - Others can verify the produced address by running `createmultisig 2 ["Kalice","Kbob","Kcarol"]`, and expecting *Amulti* as output. Again, it may be necessary to explicitly specify the addresstype in order to get a result that matches. This command won't enable them to initiate transactions later, however. - They can now give out *Amulti* as address others can pay to. Later, when *V* BCH has been received on *Amulti*, and Bob and Carol want to move the coins in their entirety to address *Asend*, with no change. Alice does not need to be involved. - One of them - let's assume Carol here - initiates the creation. She runs `walletcreatefundedpsbt [] {"Asend":V} 0 {"subtractFeeFromOutputs":[0], "includeWatching":true}`. We call the resulting PSBT *P*. *P* does not contain any signatures. - Carol needs to sign the transaction herself. In order to do so, she runs `walletprocesspsbt "P"`, and gives the resulting PSBT *P2* to Bob. - Bob inspects the PSBT using `decodepsbt "P2"` to determine if the transaction has indeed just the expected input, and an output to *Asend*, and the fee is reasonable. If he agrees, he calls `walletprocesspsbt "P2"` to sign. The resulting PSBT *P3* contains both Carol's and Bob's signature. - Now anyone can call `finalizepsbt "P3"` to extract a fully signed transaction *T*. - Finally anyone can broadcast the transaction using `sendrawtransaction "T"`. In case there are more signers, it may be advantageous to let them all sign in parallel, rather than passing the PSBT from one signer to the next one. In the above example this would translate to Carol handing a copy of *P* to each signer separately. They can then all invoke `walletprocesspsbt "P"`, and end up with their individually-signed PSBT structures. They then all send those back to Carol (or anyone) who can combine them using `combinepsbt`. The last two steps (`finalizepsbt` and `sendrawtransaction`) remain unchanged.