mirror of
https://github.com/dashpay/dash.git
synced 2024-12-26 12:32:48 +01:00
b8a87799f0
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
107 lines
5.4 KiB
Markdown
107 lines
5.4 KiB
Markdown
# 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.
|