bolt: Updated the BOLT specification to the latest version

This is mainly just copying over the copy-editing from the
lightning-rfc repository.

[ Split to just perform changes after the UNKNOWN_PAYMENT_HASH change --RR ]

Signed-off-by: Christian Decker <decker.christian@gmail.com>
Reported-by: Rusty Russell <@rustyrussell>

Makefile

@@ -15,7 +15,7 @@ CCANDIR := ccan
 
 # Where we keep the BOLT RFCs
 BOLTDIR := ../lightning-rfc/
-BOLTVERSION := 914ebab9080ccccb0ff176cb16b7a6ba21e23bbe
+BOLTVERSION := 3fef98d10695462edecc63cba05e4a96374f4664
 
 -include config.vars
 

closingd/closingd.c

@@ -287,8 +287,8 @@ static uint64_t receive_offer(struct crypto_state *cs,
 	/* BOLT #2:
 	 *
 	 * The receiving node:
-	 *   - if the `signature` is not valid for either variant of close
-	 *     transaction specified in [BOLT #3](03-transactions.md#closing-transaction):
+	 *   - if the `signature` is not valid for either variant of closing transaction
+	 *   specified in [BOLT #3](03-transactions.md#closing-transaction):
 	 *     - MUST fail the connection.
 	 */
 	tx = close_tx(tmpctx, cs, channel_id,

common/bolt11.c

@@ -150,8 +150,8 @@ static void decode_p(struct bolt11 *b11,
 {
         /* BOLT #11:
          *
-         * A payer SHOULD use the first `p` field that it did not skip as the
-         * payment hash.
+         * A payer... SHOULD use the first `p` field that it did NOT
+         * skip as the payment hash.
          */
         if (*have_p) {
                 unknown_field(b11, hu5, data, data_len, 'p', data_length);
@@ -160,9 +160,10 @@ static void decode_p(struct bolt11 *b11,
 
         /* BOLT #11:
          *
-         * A reader MUST skip over unknown fields, an `f` field with unknown
-         * `version`, or a `p`, `h`, or `n` field that does not have
-         * `data_length` 52, 52, or 53 respectively. */
+         * A reader... MUST skip over unknown fields, OR an `f` field
+	 * with unknown `version`, OR `p`, `h`, or `n` fields that do
+	 * NOT have `data_length`s of 52, 52, or 53, respectively.
+	*/
         if (data_length != 52) {
                 unknown_field(b11, hu5, data, data_len, 'p', data_length);
                 return;
@@ -212,9 +213,9 @@ static void decode_h(struct bolt11 *b11,
 
         /* BOLT #11:
 	 *
-         * A reader MUST skip over unknown fields, an `f` field with unknown
-         * `version`, or a `p`, `h`, or `n` field that does not have
-         * `data_length` 52, 52, or 53 respectively. */
+	 * A reader... MUST skip over unknown fields, OR an `f` field
+	 * with unknown `version`, OR `p`, `h`, or `n` fields that do
+	 * NOT have `data_length`s of 52, 52, or 53, respectively. */
         if (data_length != 52) {
                 unknown_field(b11, hu5, data, data_len, 'h', data_length);
                 return;
@@ -289,9 +290,9 @@ static char *decode_n(struct bolt11 *b11,
 
         /* BOLT #11:
 	 *
-         * A reader MUST skip over unknown fields, an `f` field with unknown
-         * `version`, or a `p`, `h`, or `n` field that does not have
-         * `data_length` 52, 52, or 53 respectively. */
+	 * A reader... MUST skip over unknown fields, OR an `f` field
+	 * with unknown `version`, OR `p`, `h`, or `n` fields that do
+	 * NOT have `data_length`s of 52, 52, or 53, respectively. */
         if (data_length != 53)
                 return unknown_field(b11, hu5, data, data_len, 'n',
                                      data_length);
@@ -307,9 +308,9 @@ static char *decode_n(struct bolt11 *b11,
 
 /* BOLT #11:
  *
- * `f` (9): `data_length` variable, depending on version. Fallback on-chain
- * address: for bitcoin, this starts with a 5-bit `version` and contains a
- * witness program or P2PKH or P2SH address.
+ * `f` (9): `data_length` variable, depending on version. Fallback
+ * on-chain address: for Bitcoin, this starts with a 5-bit `version`
+ * and contains a witness program or P2PKH or P2SH address.
  */
 static char *decode_f(struct bolt11 *b11,
                       struct hash_u5 *hu5,
@@ -325,9 +326,10 @@ static char *decode_f(struct bolt11 *b11,
 
         /* BOLT #11:
          *
-         * For bitcoin payments, a writer MUST set an `f` field to a
-         * valid witness version and program, or `17` followed by a
-         * public key hash, or `18` followed by a script hash. */
+	 * for Bitcoin payments... MUST set an `f` field to a valid
+	 * witness version and program, OR to `17` followed by a
+	 * public key hash, OR to `18` followed by a script hash.
+	*/
         if (version == 17) {
                 /* Pay to pubkey hash (P2PKH) */
                 struct bitcoin_address pkhash;
@@ -489,20 +491,17 @@ struct bolt11 *bolt11_decode(const tal_t *ctx, const char *str,
 
         /* BOLT #11:
          *
-         * The human-readable part of a Lightning invoice consists of two
-	 * sections:
-	 * 1. `prefix`: `ln` + BIP-0173 currency prefix (e.g. `lnbc` for bitcoin
-	 *     mainnet, `lntb` for bitcoin testnet and `lnbcrt` for bitcoin
-	 *     regtest)
+	 * The human-readable part of a Lightning invoice consists of two sections:
+	 * 1. `prefix`: `ln` + BIP-0173 currency prefix (e.g. `lnbc` for Bitcoin mainnet,
+	 *    `lntb` for Bitcoin testnet, and `lnbcrt` for Bitcoin regtest)
 	 * 1. `amount`: optional number in that currency, followed by an optional
-         *    `multiplier` letter
+	 *    `multiplier` letter. The unit encoded here is the 'social' convention of a payment unit -- in the case of Bitcoin the unit is 'bitcoin' NOT satoshis.
 	*/
         prefix = tal_strndup(tmpctx, hrp, strcspn(hrp, "0123456789"));
 
         /* BOLT #11:
          *
-         * A reader:
-         *   - MUST fail if it does not understand the `prefix`
+	 * A reader...if it does NOT understand the `prefix`... MUST fail the payment.
 	 */
         if (!strstarts(prefix, "ln"))
                 return decode_fail(b11, fail,
@@ -514,13 +513,13 @@ struct bolt11 *bolt11_decode(const tal_t *ctx, const char *str,
 
         /* BOLT #11:
          *
-         *   - If the `amount` is empty:
+         *   - if the `amount` is empty:
          * */
         amountstr = tal_strdup(tmpctx, hrp + strlen(prefix));
         if (streq(amountstr, "")) {
                 /* BOLT #11:
                  *
-	         * - SHOULD indicate if amount is unspecified
+	         * - SHOULD indicate to the payer that amount is unspecified.
                  */
                 b11->msatoshi = NULL;
         } else {
@@ -540,8 +539,9 @@ struct bolt11 *bolt11_decode(const tal_t *ctx, const char *str,
 
                 /* BOLT #11:
                  *
-                 * MUST fail if `amount` contains a non-digit or is followed by
-                 * anything except a `multiplier` in the table above
+                 * if `amount` contains a non-digit OR is followed by
+		 * anything except a `multiplier` (see table above)... MUST fail the
+		 * payment.
                  **/
                 amount = strtoull(amountstr, &end, 10);
                 if (amount == ULLONG_MAX && errno == ERANGE)
@@ -553,10 +553,10 @@ struct bolt11 *bolt11_decode(const tal_t *ctx, const char *str,
 
                 /* BOLT #11:
                  *
-                 * - If the `multiplier` is present:
-                 *   - MUST multiply `amount` by the `multiplier`
-                 *   value to derive the amount required for payment
-                 **/
+                 * if the `multiplier` is present...  MUST multiply
+		 * `amount` by the `multiplier` value to derive the
+		 * amount required for payment.
+		*/
                 b11->msatoshi = tal(b11, u64);
                 *b11->msatoshi = amount * m10 / 10;
         }
@@ -567,7 +567,7 @@ struct bolt11 *bolt11_decode(const tal_t *ctx, const char *str,
 	 *
 	 * 1. `timestamp`: seconds-since-1970 (35 bits, big-endian)
 	 * 1. zero or more tagged parts
-         * 1. `signature`: bitcoin-style signature of above (520 bits)
+	 * 1. `signature`: Bitcoin-style signature of above (520 bits)
 	 */
         if (!pull_uint(&hu5, &data, &data_len, &b11->timestamp, 35))
                 return decode_fail(b11, fail, "Can't get 35-bit timestamp");
@@ -652,8 +652,9 @@ struct bolt11 *bolt11_decode(const tal_t *ctx, const char *str,
 
                 /* BOLT #11:
 		 *
-                 * A reader MUST check that the SHA-2 256 in the `h` field
-                 * exactly matches the hashed description.
+                 * A reader... MUST check that the SHA2 256-bit hash
+		 * in the `h` field exactly matches the hashed
+		 * description.
                  */
                 if (!description)
                         return decode_fail(b11, fail,
@@ -668,12 +669,13 @@ struct bolt11 *bolt11_decode(const tal_t *ctx, const char *str,
 
         /* BOLT #11:
          *
-         * A writer MUST set `signature` to a valid 512-bit secp256k1
-         * signature of the SHA2 256-bit hash of the human-readable part,
-         * represented as UTF-8 bytes, concatenated with the data part
-         * (excluding the signature) with zero bits appended to pad the data
-         * to the next byte boundary, with a trailing byte containing the
-         * recovery ID (0, 1, 2 or 3).
+         * A writer...MUST set `signature` to a valid 512-bit
+	 * secp256k1 signature of the SHA2 256-bit hash of the
+	 * human-readable part, represented as UTF-8 bytes,
+	 * concatenated with the data part (excluding the signature)
+	 * with 0 bits appended to pad the data to the next byte
+	 * boundary, with a trailing byte containing the recovery ID
+	 * (0, 1, 2, or 3).
 	 */
         if (!pull_bits(NULL, &data, &data_len, sig_and_recid, 520, false))
                 return decode_fail(b11, fail, "signature truncated");
@@ -689,11 +691,10 @@ struct bolt11 *bolt11_decode(const tal_t *ctx, const char *str,
 
         /* BOLT #11:
 	 *
-         * A reader MUST check that the `signature` is valid (see the `n`
-         * tagged field specified below).
-         *...
-         * A reader MUST use the `n` field to validate the signature instead of
-         * performing signature recovery if a valid `n` field is provided.
+         * A reader...  MUST check that the `signature` is valid (see
+	 * the `n` tagged field specified below). ... A reader...
+	 * MUST use the `n` field to validate the signature instead of
+	 * performing signature recovery.
 	 */
         if (!have_n) {
                 if (!secp256k1_ecdsa_recover(secp256k1_ctx,
@@ -757,9 +758,8 @@ static void push_varlen_field(u5 **data, char type, u64 val)
 
 /* BOLT #11:
  *
- * `f` (9): `data_length` variable, depending on version.
- *
- * Fallback on-chain address: for bitcoin, this starts with a 5-bit `version`
+ * `f` (9): `data_length` variable, depending on version. Fallback
+ * on-chain address: for Bitcoin, this starts with a 5-bit `version`
  * and contains a witness program or P2PKH or P2SH address.
  */
 static void push_fallback_addr(u5 **data, u5 version, const void *addr, u16 addr_len)
@@ -811,9 +811,9 @@ static void encode_f(u5 **data, const u8 *fallback)
 
         /* BOLT #11:
          *
-         * For bitcoin payments, a writer MUST set an `f` field to a valid
-         * witness version and program, or `17` followed by a public key hash,
-         * or `18` followed by a script hash.
+	 * for Bitcoin payments... MUST set an `f` field to a valid
+	 * witness version and program, OR to `17` followed by a
+	 * public key hash, OR to `18` followed by a script hash.
          */
         if (is_p2pkh(fallback, &pkh)) {
                 push_fallback_addr(data, 17, &pkh, sizeof(pkh));
@@ -881,14 +881,11 @@ char *bolt11_encode_(const tal_t *ctx,
         /* BOLT #11:
          *
 	 * A writer:
-         *   - MUST encode `prefix` using the currency it requires
-         *   for successful payment
-         *   - If it requires a specific minimum amount for successful payment:
-	 *     - MUST include that `amount`
-	 *     - MUST encode `amount` as a positive decimal integer
-         *     with no leading zeroes
-	 *     - SHOULD use the shortest representation possible by
-         *     using the largest multiplier or omitting the multiplier
+	 * - MUST encode `prefix` using the currency required for successful payment.
+	 * - if a specific minimum `amount` is required for successful payment:
+	 *   - MUST include that `amount`.
+	 * - MUST encode `amount` as a positive decimal integer with no leading 0s.
+	 * - SHOULD use the shortest representation possible, by using the largest multiplier or omitting the multiplier.
 	 */
         if (b11->msatoshi) {
                 char postfix;
@@ -913,15 +910,15 @@ char *bolt11_encode_(const tal_t *ctx,
          *
 	 * 1. `timestamp`: seconds-since-1970 (35 bits, big-endian)
 	 * 1. zero or more tagged parts
-         * 1. `signature`: bitcoin-style signature of above (520 bits)
+	 * 1. `signature`: Bitcoin-style signature of above (520 bits)
          */
         push_varlen_uint(&data, b11->timestamp, 35);
 
         /* BOLT #11:
          *
-         * If a writer offers more than one of any field type, it MUST
-         * specify the most-preferred field first, followed by
-         * less-preferred fields in order.
+	 * if a writer offers more than one of any field type,
+	 * it... MUST specify the most-preferred field first, followed
+	 * by less-preferred fields, in order.
 	 */
         /* Thus we do built-in fields, then extras last. */
         encode_p(&data, &b11->payment_hash);

common/key_derive.c

@@ -13,11 +13,12 @@
  *
  *	pubkey = basepoint + SHA256(per_commitment_point || basepoint) * G
  *
- * The `localpubkey` uses the local node's `payment_basepoint`; the
- * `remotepubkey` uses the remote node's `payment_basepoint`; the
- * `local_delayedpubkey` uses the local node's `delayed_payment_basepoint`; the
- * `local_htlcpubkey` uses the local node's `htlc_basepoint`; and the
- * `remote_delayedpubkey` uses the remote node's `delayed_payment_basepoint`.
+ * The `localpubkey` uses the local node's `payment_basepoint`;
+ * the `remotepubkey` uses the remote node's `payment_basepoint`;
+ * the `local_htlcpubkey` uses the local node's `htlc_basepoint`;
+ * the `remote_htlcpubkey` uses the remote node's `htlc_basepoint`;
+ * the `local_delayedpubkey` uses the local node's `delayed_payment_basepoint`;
+ * and the `remote_delayedpubkey` uses the remote node's `delayed_payment_basepoint`.
  */
 bool derive_simple_key(const struct pubkey *basepoint,
 		    const struct pubkey *per_commitment_point,

common/keyset.c

@@ -9,20 +9,18 @@ bool derive_keyset(const struct pubkey *per_commitment_point,
 {
         /* BOLT #3:
 	 *
-	 * ### `localpubkey`, `remotepubkey`, `local_htlcpubkey`,
-	 *     `remote_htlcpubkey`, `local_delayedpubkey`, and
-	 *     `remote_delayedpubkey` Derivation
+	 * ### `localpubkey`, `remotepubkey`, `local_htlcpubkey`, `remote_htlcpubkey`, `local_delayedpubkey`, and `remote_delayedpubkey` Derivation
 	 *
 	 * These pubkeys are simply generated by addition from their base points:
 	 *
 	 *	pubkey = basepoint + SHA256(per_commitment_point || basepoint) * G
 	 *
-	 * The `localpubkey` uses the local node's `payment_basepoint`; the
-	 * `remotepubkey` uses the remote node's `payment_basepoint`; the
-	 * `local_delayedpubkey` uses the local node's
-	 * `delayed_payment_basepoint`; the `local_htlcpubkey` uses the local
-	 * node's `htlc_basepoint`; and the `remote_delayedpubkey` uses the
-	 * remote node's `delayed_payment_basepoint`.
+	 * The `localpubkey` uses the local node's `payment_basepoint`;
+	 * the `remotepubkey` uses the remote node's `payment_basepoint`;
+	 * the `local_htlcpubkey` uses the local node's `htlc_basepoint`;
+	 * the `remote_htlcpubkey` uses the remote node's `htlc_basepoint`;
+	 * the `local_delayedpubkey` uses the local node's `delayed_payment_basepoint`;
+	 * and the `remote_delayedpubkey` uses the remote node's `delayed_payment_basepoint`.
 	 */
 	if (!derive_simple_key(&self->payment,
 			       per_commitment_point,

common/test/run-bolt11.c

@@ -150,7 +150,7 @@ int main(void)
 	 *
 	 * Breakdown:
 	 *
-	 * * `lnbc`: prefix, lightning on bitcoin mainnet
+	 * * `lnbc`: prefix, Lightning on Bitcoin mainnet
 	 * * `1`: Bech32 separator
 	 * * `pvjluez`: timestamp (1496314658)
 	 * * `p`: payment hash
@@ -176,12 +176,12 @@ int main(void)
 
 	/* BOLT #11:
 	 *
-	 * > ### Please send $3 for a cup of coffee to the same peer, within 1 minute
+	 * > ### Please send $3 for a cup of coffee to the same peer, within one minute
 	 * > lnbc2500u1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdq5xysxxatsyp3k7enxv4jsxqzpuaztrnwngzn3kdzw5hydlzf03qdgm2hdq27cqv3agm2awhz5se903vruatfhq77w3ls4evs3ch9zw97j25emudupq63nyw24cg27h2rspfj9srp
 	 *
 	 * Breakdown:
 	 *
-	 * * `lnbc`: prefix, lightning on bitcoin mainnet
+	 * * `lnbc`: prefix, Lightning on Bitcoin mainnet
 	 * * `2500u`: amount (2500 micro-bitcoin)
 	 * * `1`: Bech32 separator
 	 * * `pvjluez`: timestamp (1496314658)
@@ -216,7 +216,7 @@ int main(void)
 	 *
 	 * Breakdown:
 	 *
-	 * * `lnbc`: prefix, lightning on bitcoin mainnet
+	 * * `lnbc`: prefix, Lightning on Bitcoin mainnet
 	 * * `20m`: amount (20 milli-bitcoin)
 	 * * `1`: Bech32 separator
 	 * * `pvjluez`: timestamp (1496314658)

connectd/handshake.c

@@ -109,10 +109,9 @@ static inline void check_act_three(const struct act_three *act3)
 {
 	/* BOLT #8:
 	 *
-	 * 1 byte for the handshake version, 33 bytes for the ephemeral
-	 * public key encrypted with the `ChaCha20` stream cipher, 16 bytes
-	 * for the encrypted public key's tag generated via the AEAD
-	 * construction, and 16 bytes for a final authenticating tag.
+	 * 1 byte for the handshake version, 33 bytes for the
+	 * compressed ephemeral public key of the initiator, and 16
+	 * bytes for the `poly1305` tag.
 	 */
 	BUILD_ASSERT(sizeof(act3->v) == 1);
 	BUILD_ASSERT(sizeof(act3->ciphertext) == 33 + 16);

gossipd/routing.c

@@ -1210,7 +1210,7 @@ u8 *handle_channel_update(struct routing_state *rstate, const u8 *update TAKES,
 	/* BOLT #7:
 	 *
 	 *  - if the `timestamp` is unreasonably far in the future:
-	 *    - MAY discard the `channel_announcement`.
+	 *    - MAY discard the `channel_update`.
 	 */
 	if (timestamp > time_now().ts.tv_sec + rstate->prune_timeout) {
 		status_debug("Received channel_update for %s with far time %u",

hsmd/hsmd.c

@@ -1459,12 +1459,13 @@ static struct io_plan *handle_sign_invoice(struct io_conn *conn,
 
 	/* BOLT #11:
 	 *
-	 * A writer MUST set `signature` to a valid 512-bit secp256k1
-	 * signature of the SHA2 256-bit hash of the human-readable part,
-	 * represented as UTF-8 bytes, concatenated with the data part
-	 * (excluding the signature) with zero bits appended to pad the data
-	 * to the next byte boundary, with a trailing byte containing the
-	 * recovery ID (0, 1, 2 or 3).
+	 * A writer... MUST set `signature` to a valid 512-bit
+	 * secp256k1 signature of the SHA2 256-bit hash of the
+	 * human-readable part, represented as UTF-8 bytes,
+	 * concatenated with the data part (excluding the signature)
+	 * with 0 bits appended to pad the data to the next byte
+	 * boundary, with a trailing byte containing the recovery ID
+	 * (0, 1, 2, or 3).
 	 */
 
 	/* FIXME: Check invoice! */

onchaind/onchaind.c

@@ -1297,11 +1297,10 @@ static void handle_mutual_close(const struct bitcoin_txid *txid,
 
 	/* BOLT #5:
 	 *
-	 * A mutual close transaction *resolves* the funding transaction output.
+	 * A closing transaction *resolves* the funding transaction output.
 	 *
-	 * In the case of a mutual close, a node need not do anything else, as
-	 * it has already agreed to the output, which is sent to its specified
-	 * `scriptpubkey`
+	 * In the case of a mutual close, a node need not do anything else, as it has
+	 * already agreed to the output, which is sent to its specified `scriptpubkey`
 	 */
 	resolved_by_other(outs[0], txid, MUTUAL_CLOSE);
 
@@ -2015,14 +2014,10 @@ static void handle_their_cheat(const struct bitcoin_tx *tx,
 		if (matches_direction(matches, htlcs) == LOCAL) {
 			/* BOLT #5:
 			 *
-			 *  - MUST *resolve* the _local node's offered HTLCs_
-			 *    in one of three ways:
-			 *    * spend the *commitment tx* using the payment
-			 *      revocation private key.
-			 *    * spend the *commitment tx* using the payment
-			 *      preimage (if known).
-			 *    * spend the *HTLC-timeout tx*, if the remote node
-			 *      has published it.
+			 *   - MUST *resolve* the _local node's offered HTLCs_ in one of three ways:
+			 *     * spend the *commitment tx* using the payment revocation private key.
+			 *     * spend the *commitment tx* once the HTLC timeout has passed.
+			 *     * spend the *HTLC-success tx*, if the remote node has published it.
 			 */
 			out = new_tracked_output(&outs, txid,
 						 tx_blockheight,
@@ -2044,12 +2039,10 @@ static void handle_their_cheat(const struct bitcoin_tx *tx,
 						 NULL);
 			/* BOLT #5:
 			 *
-			 *  - MUST *resolve* the _remote node's offered HTLCs_
-			 *    in one of two ways:
-			 *     * spend the *commitment tx* using the payment
-			 *       revocation key.
-			 *     * spend the *commitment tx* once the HTLC timeout
-			 *       has passed.
+			 *   - MUST *resolve* the _remote node's offered HTLCs_ in one of three ways:
+			 *     * spend the *commitment tx* using the payment revocation private key.
+			 *     * spend the *commitment tx* using the payment preimage (if known).
+			 *     * spend the *HTLC-timeout tx*, if the remote node has published it.
 			 */
 			steal_htlc(out);
 		}