diff options
| -rw-r--r-- | doc/descriptors.md | 26 |
1 files changed, 15 insertions, 11 deletions
diff --git a/doc/descriptors.md b/doc/descriptors.md index b25678e06a..de4d4e574f 100644 --- a/doc/descriptors.md +++ b/doc/descriptors.md @@ -59,19 +59,20 @@ Descriptors consist of several types of expressions. The top level expression is - 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 `]` - 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). - Inside `wpkh` and `wsh`, only compressed public keys are permitted. - [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. - 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. -- 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: -- P2PKH addresses (base58, of the form `1...`). 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)). -- Segwit addresses (bech32, of the form `bc1...`, defined in [BIP 173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki)). +- 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...` for mainnet or `2...` for testnet, defined in [BIP 13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki)). +- Segwit addresses (bech32, of the form `bc1...` for mainnet or `tb1...` for testnet, defined in [BIP 173](https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki)). ## Explanation @@ -83,10 +84,9 @@ imaginable, though they may not be optimal: P2SH-P2PK, P2SH-P2PKH, P2WSH-P2PK, P2WSH-P2PKH, P2SH-P2WSH-P2PK, P2SH-P2WSH-P2PKH. To describe these, we model these as functions. The functions `pk` -(P2PK), `pkh` (P2PKH) and `wpkh` (P2WPKH) take as input a public key in -hexadecimal notation (which will be extended later), and return the +(P2PK), `pkh` (P2PKH) and `wpkh` (P2WPKH) take as input a `KEY` expression, and return the corresponding *scriptPubKey*. The functions `sh` (P2SH) and `wsh` (P2WSH) -take as input a script, and return the script describing P2SH and P2WSH +take as input a `SCRIPT` expression, and return the script describing P2SH and P2WSH outputs with the input as embedded script. The names of the functions do not contain "p2" for brevity. @@ -95,7 +95,7 @@ not contain "p2" for brevity. 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 +multisig policy, where any *k* out of the *n* provided `KEY` expressions must sign. Key order is significant. A `multi()` expression describes a multisig script @@ -138,7 +138,7 @@ 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 +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 the master pubkey), plus all derivation steps. To support constructing these, we permit providing this key origin information inside the @@ -150,6 +150,10 @@ 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. +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 Often it is useful to communicate a description of scripts along with the |