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
9.2 KiB
Support for Output Descriptors in Dash Core
Since Dash Core v0.17, 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.getaddressinfo
outputs a descriptor for solvable addresses (since v0.18).importmulti
takes as input descriptors to import into the wallet (since v0.18).generatetodescriptor
takes as input a descriptor and generates coins to it (regtest
only, since v0.19).utxoupdatepsbt
takes as input descriptors to add information to the psbt (since v0.19).
This document describes the language. For the specifics on usage, see the RPC documentation for the functions mentioned above.
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.combo(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)
represents a P2PK, P2PKHmulti(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.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 fingerprintd34db33f
, and derived using path44'/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:
pk(KEY)
(anywhere): P2PK output for the given public key.pkh(KEY)
(anywhere): P2PKH output for the given public key (useaddr
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 ofpk(KEY)
andpkh(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
]
- An open bracket
- Followed by the actual key, which is either:
- Hex encoded public keys (66 characters starting with
02
or03
, or 130 characters starting with04
). - WIF encoded private keys may be specified instead of the corresponding public key, with the same meaning.
-
xpub
encoded extended public key orxprv
encoded private key (as defined in BIP 32).- 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.
- Followed by zero or more
- Hex encoded public keys (66 characters starting with
- Anywhere a
'
suffix is permitted to denote hardened derivation, the suffixh
can be used instead.
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 thepk
function instead). - P2SH addresses (base58, of the form
7...
, defined in BIP 13).
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..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 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.
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 Dash Core 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.