Merge #14096: Add reference documentation for descriptors language

2b5d6f8df24b381d35b75187c97ae0cc9f7c3ed0 Replace duplcate reference with reference to reference doc (Pieter Wuille)
89709db7a2710456011eac9dcd6a60d5e87b97ae Adjust TODO link (Pieter Wuille)
9254ffcf2d910ecb0f9ecbeef6d40a2008a44870 Add descriptor reference documentation (Pieter Wuille)

Pull request description:

Tree-SHA512: 1ca0d537f9bcbb23266e9a4a02a60013ef8309958fb701f638283887585b5ddea6bc9dab859454ec3a373b1a12a4fd69836e7030417bb2ca43fef26b104c0d65

doc/descriptors.md

@@ -0,0 +1,106 @@
+# Support for Output Descriptors in Dash Core
+
+Since Dash Core v0.17, there is support for Output Descriptors 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.
+- `multi(1,022f8bde4d1a07209355b4a7250a5c5128e88b84bddc619ab7cba8d569b240efe4,025cbdf0646e5db4eaa398f365f2ea7a0e3d419b7e0330e39ce92bddedcac4f9bc)` represents a bare *1-of-2* multisig.
+- `pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1'/2)` refers to a single P2PKH output, using child key *1'/2* of the specified xpub.
+
+## Reference
+
+Descriptors consist of several types of expressions. The top level expression is always a `SCRIPT`.
+
+`SCRIPT` expressions:
+- `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).
+- `sh(SCRIPT)` (top level only): P2SH embed the argument.
+- `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:
+- 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.
+  - Instead of a `'`, the suffix `h` can be used to denote hardened derivation.
+
+`ADDR` expressions are any type of supported address:
+- P2PKH addresses (base58, of the form `X...`). Note that P2PKH addresses in descriptors cannot be used for P2PK outputs (use the `pk` function instead).
+- P2SH addresses (base58, of the form `7...`, 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. More combinations are
+imaginable, though they may not be optimal: P2SH-P2PK and 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 `sh` (P2SH) function
+takes as input a script, and returns the script describing P2SH
+outputs with the input as embedded script. The name of the function does
+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..2<sup>31</sup>-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.
+
+### 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 Dash Core wallets, a convenience function `combo` is
+provided, which takes as input a public key, and constructs the P2PK and
+P2PKH scripts for that key.

src/rpc/blockchain.cpp

@@ -2362,7 +2362,7 @@ UniValue scantxoutset(const JSONRPCRequest& request)
             "or more path elements separated by \"/\", and optionally ending in \"/*\" (unhardened), or \"/*'\" or \"/*h\" (hardened) to specify all\n"
             "unhardened or hardened child keys.\n"
             "In the latter case, a range needs to be specified by below if different from 1000.\n"
-            "For more information on output descriptors, see the documentation at TODO\n"
+            "For more information on output descriptors, see the documentation in the doc/descriptors.md file.\n"
             "\nArguments:\n"
             "1. \"action\"                       (string, required) The action to execute\n"
             "                                      \"start\" for starting a scan\n"

src/script/descriptor.h

@@ -22,53 +22,8 @@
 // they can be included inside by changing public keys to private keys (WIF
 // format), and changing xpubs by xprvs.
 //
-// 1. Examples
+// Reference documentation about the descriptor language can be found in
-//
+// doc/descriptors.md.
-// A P2PK descriptor with a fixed public key:
-// - pk(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)
-//
-// A P2SH-P2WSH-P2PKH descriptor with a fixed public key:
-// - sh(wsh(pkh(02e493dbf1c10d80f3581e4904930b1404cc6c13900ee0758474fa94abe8c4cd13)))
-//
-// A bare 1-of-2 multisig descriptor:
-// - multi(1,022f8bde4d1a07209355b4a7250a5c5128e88b84bddc619ab7cba8d569b240efe4,025cbdf0646e5db4eaa398f365f2ea7a0e3d419b7e0330e39ce92bddedcac4f9bc)
-//
-// A chain of P2PKH outputs (this needs the corresponding private key to derive):
-// - pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1'/2/*)
-//
-// 2. Grammar description:
-//
-// X: xpub or xprv encoded extended key
-// I: decimal encoded integer
-// H: Hex encoded byte array
-// A: Address in P2PKH, P2SH, or Bech32 encoding
-//
-// S (Scripts):
-// * pk(P): Pay-to-pubkey (P2PK) output for public key P.
-// * pkh(P): Pay-to-pubkey-hash (P2PKH) output for public key P.
-// * sh(S): Pay-to-script-hash (P2SH) output for script S
-// * combo(P): combination of P2PK and P2PKH for public key P.
-// * multi(I,L): k-of-n multisig for given public keys
-// * addr(A): Output to address
-// * raw(H): scriptPubKey with raw bytes
-//
-// P (Public keys):
-// * H: fixed public key (or WIF-encoded private key)
-// * E: extended public key
-// * E/*: (ranged) all unhardened direct children of an extended public key
-// * E/*': (ranged) all hardened direct children of an extended public key
-//
-// L (Comma-separated lists of public keys):
-// * P
-// * L,P
-//
-// E (Extended public keys):
-// * X
-// * E/I: unhardened child
-// * E/I': hardened child
-// * E/Ih: hardened child (alternative notation)
-//
-// The top level is S.
 
 /** Interface for parsed descriptor objects. */
 struct Descriptor {