A few minor formatting fixes and clarifications to descriptors.md

jnewbery · jnewbery · commit 8284756705dc · 2018-11-22T00:21:29.000-05:00
diff --git 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
