Changeset View
Changeset View
Standalone View
Standalone View
doc/descriptors.md
Show All 26 Lines | |||||
- Pay-to-script-hash scripts (P2SH), through the `sh` function. | - Pay-to-script-hash scripts (P2SH), through the `sh` function. | ||||
- Multisig scripts, through the `multi` function. | - Multisig scripts, through the `multi` function. | ||||
- Any type of supported address through the `addr` function. | - Any type of supported address through the `addr` function. | ||||
- Raw hex scripts through the `raw` function. | - Raw hex scripts through the `raw` function. | ||||
- Public keys (compressed and uncompressed) in hex notation, or BIP32 extended pubkeys with derivation paths. | - Public keys (compressed and uncompressed) in hex notation, or BIP32 extended pubkeys with derivation paths. | ||||
## Examples | ## Examples | ||||
- `pk(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` represents a P2PK output. | - `pk(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` describes a P2PK output with the specified public key. | ||||
- `pkh(02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5)` represents a P2PKH output. | - `pkh(02c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5)` describes a P2PKH output with the specified public key. | ||||
- `combo(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` represents a P2PK and P2PKH output. | - `combo(0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798)` describes any P2PK or P2PKH output with the specified public key. | ||||
- `multi(1,022f8bde4d1a07209355b4a7250a5c5128e88b84bddc619ab7cba8d569b240efe4,025cbdf0646e5db4eaa398f365f2ea7a0e3d419b7e0330e39ce92bddedcac4f9bc)` represents a bare *1-of-2* multisig. | - `multi(1,022f8bde4d1a07209355b4a7250a5c5128e88b84bddc619ab7cba8d569b240efe4,025cbdf0646e5db4eaa398f365f2ea7a0e3d419b7e0330e39ce92bddedcac4f9bc)` describes a bare *1-of-2* multisig output with keys in the specified order. | ||||
- `sh(multi(2,022f01e5e15cca351daff3843fb70f3c2f0a1bdd05e5af888a67784ef3e10a2a01,03acd484e2f0c7f65309ad178a9f559abde09796974c57e714c35f110dfc27ccbe))` represents a P2SH *2-of-2* multisig. | - `sh(multi(2,022f01e5e15cca351daff3843fb70f3c2f0a1bdd05e5af888a67784ef3e10a2a01,03acd484e2f0c7f65309ad178a9f559abde09796974c57e714c35f110dfc27ccbe))` describes a P2SH *2-of-2* multisig output with keys in the specified order. | ||||
- `pk(xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8)` refers to a single P2PK output, using the public key part from the specified xpub. | - `pk(xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8)` describes a P2PK output with the public key of the specified xpub. | ||||
- `pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1'/2)` refers to a single P2PKH output, using child key *1'/2* of the specified xpub. | - `pkh(xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw/1'/2)` describes a P2PKH output with 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'`. | - `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 | ## 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. | 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: | `SCRIPT` expressions: | ||||
- `sh(SCRIPT)` (top level only): P2SH embed the argument. | - `sh(SCRIPT)` (top level only): P2SH embed the argument. | ||||
▲ Show 20 Lines • Show All 41 Lines • ▼ Show 20 Lines | |||||
### Multisig | ### Multisig | ||||
Several pieces of software use multi-signature (multisig) scripts based | Several pieces of software use multi-signature (multisig) scripts based | ||||
on Bitcoin's OP_CHECKMULTISIG opcode. To support these, we introduce the | 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* | `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 | multisig policy, where any *k* out of the *n* provided public keys must | ||||
sign. | sign. | ||||
Key order is significant. A `multi()` expression describes a multisig script | |||||
with keys in the specified order, and in a search for TXOs, it will not match | |||||
outputs with multisig scriptPubKeys that have the same keys in a different | |||||
order. Also, to prevent a combinatorial explosion of the search space, if more | |||||
than one of the `multi()` key arguments is a BIP32 wildcard path ending in `/*` | |||||
or `*'`, the `multi()` expression only matches multisig scripts with the `i`th | |||||
child key from each wildcard path in lockstep, rather than scripts with any | |||||
combination of child keys from each wildcard path. | |||||
### BIP32 derived keys and chains | ### BIP32 derived keys and chains | ||||
Most modern wallet software and hardware uses keys that are derived using | Most modern wallet software and hardware uses keys that are derived using | ||||
BIP32 ("HD keys"). We support these directly by permitting strings | BIP32 ("HD keys"). We support these directly by permitting strings | ||||
consisting of an extended public key (commonly referred to as an *xpub*) | consisting of an extended public key (commonly referred to as an *xpub*) | ||||
plus derivation path anywhere a public key is expected. The derivation | plus derivation path anywhere a public key is expected. The derivation | ||||
path consists of a sequence of 0 or more integers (in the range | 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 | *0..2<sup>31</sup>-1*) each optionally followed by `'` or `h`, and | ||||
separated by `/` characters. The string may optionally end with the | separated by `/` characters. The string may optionally end with the | ||||
literal `/*` or `/*'` (or `/*h`) to refer to all unhardened or hardened | literal `/*` or `/*'` (or `/*h`) to refer to all unhardened or hardened | ||||
child keys instead. | child keys in a configurable range (by default `0-1000`, inclusive). | ||||
Whenever a public key is described using a hardened derivation step, the | Whenever a public key is described using a hardened derivation step, the | ||||
script cannot be computed without access to the corresponding private | script cannot be computed without access to the corresponding private | ||||
key. | key. | ||||
### Key origin identification | ### Key origin identification | ||||
In order to describe scripts whose signing keys reside on another device, | In order to describe scripts whose signing keys reside on another device, | ||||
Show All 28 Lines | |||||
supported, a private key in WIF format or xprv may be provided instead. | supported, a private key in WIF format or xprv may be provided instead. | ||||
This is useful when private keys are necessary for hardened derivation | This is useful when private keys are necessary for hardened derivation | ||||
steps, or for dumping wallet descriptors including private key material. | steps, or for dumping wallet descriptors including private key material. | ||||
### Compatibility with old wallets | ### Compatibility with old wallets | ||||
In order to easily represent the sets of scripts currently supported by | In order to easily represent the sets of scripts currently supported by | ||||
existing Bitcoin ABC wallets, a convenience function `combo` is provided, | existing Bitcoin ABC wallets, a convenience function `combo` is provided, | ||||
which takes as input a public key, and constructs the P2PK and P2PKH | which takes as input a public key, and describes a set of P2PK and P2PKH | ||||
scripts for that key. | scripts for that key. | ||||
### Checksums | ### Checksums | ||||
Descriptors can optionally be suffixed with a checksum to protect against | Descriptors can optionally be suffixed with a checksum to protect against | ||||
typos or copy-paste errors. | typos or copy-paste errors. | ||||
These checksums consist of 8 alphanumeric characters. As long as errors are | These checksums consist of 8 alphanumeric characters. As long as errors are | ||||
Show All 10 Lines |