diff --git a/Makefile b/Makefile index 3f2ce068a..cac89c7ca 100644 --- a/Makefile +++ b/Makefile @@ -15,7 +15,7 @@ CCANDIR := ccan # Where we keep the BOLT RFCs BOLTDIR := ../lightning-rfc/ -BOLTVERSION := 914ebab9080ccccb0ff176cb16b7a6ba21e23bbe +BOLTVERSION := 3fef98d10695462edecc63cba05e4a96374f4664 -include config.vars diff --git a/closingd/closingd.c b/closingd/closingd.c index 041f4d8da..c4761821d 100644 --- a/closingd/closingd.c +++ b/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, diff --git a/common/bolt11.c b/common/bolt11.c index 5e6b40c71..553bd6412 100644 --- a/common/bolt11.c +++ b/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; @@ -211,10 +212,10 @@ 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; @@ -288,10 +289,10 @@ static char *decode_n(struct bolt11 *b11, data_length); /* 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,21 +491,18 @@ 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) - * 1. `amount`: optional number in that currency, followed by an optional - * `multiplier` letter - */ + * 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. 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, "Prefix '%s' does not start with ln", prefix); @@ -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,22 +553,22 @@ 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; } /* BOLT #11: * - * The data part of a Lightning invoice consists of multiple sections: - * - * 1. `timestamp`: seconds-since-1970 (35 bits, big-endian) - * 1. zero or more tagged parts - * 1. `signature`: bitcoin-style signature of above (520 bits) - */ + * The data part of a Lightning invoice consists of multiple sections: + * + * 1. `timestamp`: seconds-since-1970 (35 bits, big-endian) + * 1. zero or more tagged parts + * 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"); @@ -651,9 +651,10 @@ struct bolt11 *bolt11_decode(const tal_t *ctx, const char *str, struct sha256 sha; /* 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,13 +669,14 @@ 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"); @@ -688,13 +690,12 @@ struct bolt11 *bolt11_decode(const tal_t *ctx, const char *str, &b11->sig, &sig); /* 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, &b11->receiver_id.pubkey, @@ -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)); @@ -880,16 +880,13 @@ 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 - */ + * A writer: + * - 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; if (*b11->msatoshi % MSAT_PER_BTC == 0) { @@ -911,18 +908,18 @@ char *bolt11_encode_(const tal_t *ctx, /* BOLT #11: * - * 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. `timestamp`: seconds-since-1970 (35 bits, big-endian) + * 1. zero or more tagged parts + * 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); diff --git a/common/key_derive.c b/common/key_derive.c index df30ffa29..a1e3b6248 100644 --- a/common/key_derive.c +++ b/common/key_derive.c @@ -11,13 +11,14 @@ * * These pubkeys are simply generated by addition from their base points: * - * pubkey = basepoint + SHA256(per_commitment_point || basepoint) * G + * 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, diff --git a/common/keyset.c b/common/keyset.c index b84e24e59..f174b8770 100644 --- a/common/keyset.c +++ b/common/keyset.c @@ -7,22 +7,20 @@ bool derive_keyset(const struct pubkey *per_commitment_point, const struct basepoints *other, struct keyset *keyset) { - /* BOLT #3: + /* 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, diff --git a/common/test/run-bolt11.c b/common/test/run-bolt11.c index 302bc3a89..4c625fa27 100644 --- a/common/test/run-bolt11.c +++ b/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) @@ -191,7 +191,7 @@ int main(void) * * `xysxxatsyp3k7enxv4js`: '1 cup coffee' * * `x`: expiry time * * `qz`: `data_length` (`q` = 0, `z` = 2; 0 * 32 + 2 == 2) - * * `pu`: 60 seconds (`p` = 1, `u` = 28; 1 * 32 + 28 == 60) + * * `pu`: 60 seconds (`p` = 1, `u` = 28; 1 * 32 + 28 == 60) * * `aztrnwngzn3kdzw5hydlzf03qdgm2hdq27cqv3agm2awhz5se903vruatfhq77w3ls4evs3ch9zw97j25emudupq63nyw24cg27h2rsp`: signature * * `fj9srp`: Bech32 checksum */ @@ -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) diff --git a/connectd/handshake.c b/connectd/handshake.c index 49275093b..1040af9c2 100644 --- a/connectd/handshake.c +++ b/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); diff --git a/gossipd/routing.c b/gossipd/routing.c index 830c6c797..c92be999e 100644 --- a/gossipd/routing.c +++ b/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", diff --git a/hsmd/hsmd.c b/hsmd/hsmd.c index 65491d60e..b39f9de91 100644 --- a/hsmd/hsmd.c +++ b/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! */ diff --git a/onchaind/onchaind.c b/onchaind/onchaind.c index a21ceff41..813438018 100644 --- a/onchaind/onchaind.c +++ b/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); }