Changeset View
Changeset View
Standalone View
Standalone View
doc/descriptors.md
Show First 20 Lines • Show All 59 Lines • ▼ Show 20 Lines | |||||
`KEY` expressions: | `KEY` expressions: | ||||
- Optionally, key origin information, consisting of: | - Optionally, key origin information, consisting of: | ||||
- An open bracket `[` | - An open bracket `[` | ||||
- Exactly 8 hex characters for the fingerprint of the key where the derivation starts (see BIP32 for details) | - 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 | - 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 `]` | - A closing bracket `]` | ||||
- Followed by the actual key, which is either: | - 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`). | - Hex encoded public keys (either 66 characters starting with `02` or `03` for a compressed pubkey, or 130 characters starting with `04` for an uncompressed pubkey). | ||||
- [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. | - [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)). | - `xpub` encoded extended public key or `xprv` encoded extended 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. | - 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. | - 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. | - 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. | |||||
(Anywhere a `'` suffix is permitted to denote hardened derivation, the suffix `h` can be used instead.) | |||||
`ADDR` expressions are any type of supported address: | `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). | - P2PKH addresses (base58, of the form `1...` for mainnet or `[nm]...` for testnet). 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)). | - P2SH addresses (base58, of the form `3...` for mainnet or `2...` for testnet, defined in [BIP 13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki)). | ||||
## Explanation | ## Explanation | ||||
### Single-key scripts | ### Single-key scripts | ||||
Many single-key constructions are used in practice, generally including | Many single-key constructions are used in practice, generally including | ||||
P2PK, and P2PKH. Many more combinations are imaginable, though they may | P2PK, and P2PKH. Many more combinations are imaginable, though they may | ||||
not be optimal: P2SH-P2PK, P2SH-P2PKH. | not be optimal: P2SH-P2PK, P2SH-P2PKH. | ||||
To describe these, we model these as functions. The functions `pk` (P2PK) and | 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 | `pkh` (P2PKH) take as input a `KEY` expression, and return the corresponding *scriptPubKey*. The function | ||||
be extended later), and return the corresponding *scriptPubKey*. The functions | `sh` (P2SH) takes as input a `SCRIPT` expression, and return the script describing P2SH | ||||
`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 | outputs with the input as embedded script. The names of the functions do | ||||
not contain "p2" for brevity. | not contain "p2" for brevity. | ||||
### 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)` and `sortedmulti(k,key_1,key_2,...,key_n)` | `multi(k,key_1,key_2,...,key_n)` and `sortedmulti(k,key_1,key_2,...,key_n)` | ||||
functions. They represent a *k-of-n* | functions. They represent 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 `KEY` expressions must | ||||
sign. | sign. | ||||
Key order is significant for `multi()`. A `multi()` expression describes a multisig script | Key order is significant for `multi()`. A `multi()` expression describes a multisig script | ||||
with keys in the specified order, and in a search for TXOs, it will not match | 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 | 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 | 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 `/*` | 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 | or `*'`, the `multi()` expression only matches multisig scripts with the `i`th | ||||
Show All 30 Lines | |||||
change chain directly as `xpub.../44'/0'/0'/1/*` where `xpub...` | change chain directly as `xpub.../44'/0'/0'/1/*` where `xpub...` | ||||
corresponds with the master key `m`. Unfortunately, since there are | corresponds with the master key `m`. Unfortunately, since there are | ||||
hardened derivation steps that follow the xpub, this descriptor does not | hardened derivation steps that follow the xpub, this descriptor does not | ||||
let you compute scripts without access to the corresponding private keys. | let you compute scripts without access to the corresponding private keys. | ||||
Instead, it should be written as `xpub.../1/*`, where xpub corresponds to | Instead, it should be written as `xpub.../1/*`, where xpub corresponds to | ||||
`m/44'/0'/0'`. | `m/44'/0'/0'`. | ||||
When interacting with a hardware device, it may be necessary to include | When interacting with a hardware device, it may be necessary to include | ||||
the entire path from the master down. BIP174 standardizes this by | the entire path from the master down. [BIP174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki) standardizes this by | ||||
providing the master key *fingerprint* (first 32 bit of the Hash160 of | providing the master key *fingerprint* (first 32 bit of the Hash160 of | ||||
the master pubkey), plus all derivation steps. To support constructing | the master pubkey), plus all derivation steps. To support constructing | ||||
these, we permit providing this key origin information inside the | these, we permit providing this key origin information inside the | ||||
descriptor language, even though it does not affect the actual | descriptor language, even though it does not affect the actual | ||||
scriptPubKeys it refers to. | scriptPubKeys it refers to. | ||||
Every public key can be prefixed by an 8-character hexadecimal | Every public key can be prefixed by an 8-character hexadecimal | ||||
fingerprint plus optional derivation steps (hardened and unhardened) | fingerprint plus optional derivation steps (hardened and unhardened) | ||||
surrounded by brackets, identifying the master and derivation path the key or xpub | surrounded by brackets, identifying the master and derivation path the key or xpub | ||||
that follows was derived with. | that follows was derived with. | ||||
Note that the fingerprint of the parent only serves as a fast way to detect | |||||
parent and child nodes in software, and software must be willing to deal with | |||||
collisions. | |||||
### Including private keys | ### Including private keys | ||||
Often it is useful to communicate a description of scripts along with the | 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 | 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. | 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. | ||||
Show All 23 Lines |