common: fix up BOLT 3 references.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

common/derive_basepoints.c

@@ -40,8 +40,9 @@ bool derive_basepoints(const struct privkey *seed,
 
 	/* BOLT #3:
 	 *
-	 * A node MUST select an unguessable 256-bit seed for each connection,
+	 * A node:
-	 * and MUST NOT reveal the seed.
+	 *  - MUST select an unguessable 256-bit seed for each connection,
+	 *  - MUST NOT reveal the seed.
 	 */
 	if (shaseed)
 		*shaseed = keys.shaseed;
@@ -69,7 +70,8 @@ bool per_commit_point(const struct sha256 *shaseed,
 
 	/* BOLT #3:
 	 *
-	 * The `per_commitment_point` is generated using EC multiplication:
+	 * The `per_commitment_point` is generated using elliptic-curve
+	 * multiplication:
 	 *
 	 * 	per_commitment_point = per_commitment_secret * G
 	 */

common/derive_basepoints.h

@@ -60,8 +60,9 @@ bool per_commit_point(const struct sha256 *shaseed,
 
 /* BOLT #3:
  *
- * the first secret used MUST be index 281474976710655, and then the index
+ * The first secret used:
- * decremented.
+ *   - MUST be index 281474976710655,
+ *     - and from there, the index is decremented.
  */
 static inline u64 shachain_index(u64 per_commit_index)
 {

common/htlc_tx.c

@@ -23,8 +23,9 @@ static struct bitcoin_tx *htlc_tx(const tal_t *ctx,
 	 * ## HTLC-Timeout and HTLC-Success Transactions
 	 *
 	 * These HTLC transactions are almost identical, except the
-	 * HTLC-Timeout transaction is timelocked.  This is also the
+	 * HTLC-timeout transaction is timelocked.  The HTLC-timeout
-	 * transaction which can be spent by a valid penalty transaction.
+	 * transaction is also the transaction that can be spent by a valid
+	 * penalty transaction.
 	 */
 
 	/* BOLT #3:
@@ -33,7 +34,7 @@ static struct bitcoin_tx *htlc_tx(const tal_t *ctx,
 	assert(tx->version == 2);
 
 	/* BOLT #3:
-	 * * locktime: `0` for HTLC-Success, `cltv_expiry` for HTLC-Timeout.
+	 * * locktime: `0` for HTLC-success, `cltv_expiry` for HTLC-timeout
 	 */
 	tx->lock_time = locktime;
 
@@ -41,7 +42,7 @@ static struct bitcoin_tx *htlc_tx(const tal_t *ctx,
 	 * * txin count: 1
 	 *    * `txin[0]` outpoint: `txid` of the commitment transaction and
 	 *      `output_index` of the matching HTLC output for the HTLC
-	 *      transaction.
+	 *      transaction
 	 */
 	tx->input[0].txid = *commit_txid;
 	tx->input[0].index = commit_output_number;
@@ -58,9 +59,9 @@ static struct bitcoin_tx *htlc_tx(const tal_t *ctx,
 	/* BOLT #3:
 	 * * txout count: 1
 	 *    * `txout[0]` amount: the HTLC amount minus fees
-	 *       (see [Fee Calculation](#fee-calculation)).
+	 *       (see [Fee Calculation](#fee-calculation))
-	 *    * `txout[0]` script: version 0 P2WSH with witness script as shown
+	 *    * `txout[0]` script: version-0 P2WSH with witness script as shown
-	 *       below.
+	 *       below
 	 */
 	tx->output[0].amount = amount - htlc_fee_satoshi;
 	wscript = bitcoin_wscript_htlc_tx(tx, to_self_delay,
@@ -80,7 +81,7 @@ struct bitcoin_tx *htlc_success_tx(const tal_t *ctx,
 				   const struct keyset *keyset)
 {
 	/* BOLT #3:
-	 * * locktime: `0` for HTLC-Success, `cltv_expiry` for HTLC-Timeout.
+	 * * locktime: `0` for HTLC-success, `cltv_expiry` for HTLC-timeout
 	 */
 	return htlc_tx(ctx, commit_txid, commit_output_number, htlc_msatoshi,
 		       to_self_delay,
@@ -126,7 +127,7 @@ struct bitcoin_tx *htlc_timeout_tx(const tal_t *ctx,
 				   const struct keyset *keyset)
 {
 	/* BOLT #3:
-	 * * locktime: `0` for HTLC-Success, `cltv_expiry` for HTLC-Timeout.
+	 * * locktime: `0` for HTLC-success, `cltv_expiry` for HTLC-timeout
 	 */
 	return htlc_tx(ctx, commit_txid, commit_output_number, htlc_msatoshi,
 		       to_self_delay,

common/htlc_tx.h

@@ -11,8 +11,8 @@ static inline u64 htlc_timeout_fee(u32 feerate_per_kw)
 {
 	/* BOLT #3:
 	 *
-	 * The fee for an HTLC-timeout transaction MUST BE calculated to match:
+	 * The fee for an HTLC-timeout transaction:
-	 *
+	 *  - MUST BE calculated to match:
 	 *    1. Multiply `feerate_per_kw` by 663 and divide by 1000 (rounding
 	 *       down).
 	 */
@@ -23,8 +23,8 @@ static inline u64 htlc_success_fee(u32 feerate_per_kw)
 {
 	/* BOLT #3:
 	 *
-	 * The fee for an HTLC-success transaction MUST BE calculated to match:
+	 * The fee for an HTLC-success transaction:
-	 *
+	 *   - MUST BE calculated to match:
 	 *     1. Multiply `feerate_per_kw` by 703 and divide by 1000 (rounding
 	 *     down).
 	 */

common/initial_commit_tx.c

@@ -97,7 +97,7 @@ struct bitcoin_tx *initial_commit_tx(const tal_t *ctx,
 	/* BOLT #3:
 	 *
 	 * 3. Subtract this base fee from the funder (either `to_local` or
-	 * `to_remote`), with a floor of zero (see [Fee Payment](#fee-payment)).
+	 * `to_remote`), with a floor of 0 (see [Fee Payment](#fee-payment)).
 	 */
 	if (!try_subtract_fee(funder, side, base_fee_msat,
 			      &self_pay_msat, &other_pay_msat)) {
@@ -158,7 +158,7 @@ struct bitcoin_tx *initial_commit_tx(const tal_t *ctx,
 	 *
 	 * 5. If the `to_local` amount is greater or equal to
 	 *    `dust_limit_satoshis`, add a [`to_local`
-	 *    Output](#to-local-output).
+	 *    output](#to-local-output).
 	 */
 	if (self_pay_msat / 1000 >= dust_limit_satoshis) {
 		u8 *wscript = to_self_wscript(tmpctx, to_self_delay,keyset);
@@ -171,15 +171,15 @@ struct bitcoin_tx *initial_commit_tx(const tal_t *ctx,
 	 *
 	 * 6. If the `to_remote` amount is greater or equal to
 	 *    `dust_limit_satoshis`, add a [`to_remote`
-	 *    Output](#to-remote-output).
+	 *    output](#to-remote-output).
 	 */
 	if (other_pay_msat / 1000 >= dust_limit_satoshis) {
 		/* BOLT #3:
 		 *
 		 * #### `to_remote` Output
 		 *
-		 * This output sends funds to the other peer, thus is a simple
+		 * This output sends funds to the other peer and thus is a simple
-		 * P2WPKH to `remotekey`.
+		 * P2WPKH to `remotepubkey`.
 		 */
 		tx->output[n].amount = other_pay_msat / 1000;
 		tx->output[n].script = scriptpubkey_p2wpkh(tx,
@@ -208,7 +208,7 @@ struct bitcoin_tx *initial_commit_tx(const tal_t *ctx,
 	/* BOLT #3:
 	 *
 	 * * locktime: upper 8 bits are 0x20, lower 24 bits are the lower
-	 *   24 bits of the obscured commitment transaction number.
+	 *   24 bits of the obscured commitment transaction number
 	 */
 	tx->lock_time
 		= (0x20000000 | (obscured_commitment_number & 0xFFFFFF));
@@ -225,7 +225,7 @@ struct bitcoin_tx *initial_commit_tx(const tal_t *ctx,
 	/* BOLT #3:
 	 *
 	 *    * `txin[0]` sequence: upper 8 bits are 0x80, lower 24 bits are
-	 *       upper 24 bits of the obscured commitment transaction number.
+	 *       upper 24 bits of the obscured commitment transaction number
 	 */
 	tx->input[0].sequence_number
 		= (0x80000000 | ((obscured_commitment_number>>24) & 0xFFFFFF));

common/initial_commit_tx.h

@@ -25,25 +25,24 @@ static inline u64 commit_tx_base_fee(u32 feerate_per_kw,
 
 	/* BOLT #3:
 	 *
-	 * The base fee for a commitment transaction MUST BE
+	 * The base fee for a commitment transaction:
-	 * calculated to match:
+	 *  - MUST be calculated to match:
-	 *
 	 *    1. Start with `weight` = 724.
 	 */
 	weight = 724;
 
 	/* BOLT #3:
 	 *
-	 * 2. For each committed HTLC, if that output is not trimmed
+	 *    2. For each committed HTLC, if that output is not trimmed as
-	 *    as specified in [Trimmed Outputs](#trimmed-outputs), add
+	 *       specified in [Trimmed Outputs](#trimmed-outputs), add 172
-	 *    172 to `weight`.
+	 *       to `weight`.
 	 */
 	weight += 172 * num_untrimmed_htlcs;
 
 	/* BOLT #3:
 	 *
-	 * 3. Multiply `feerate_per_kw` by `weight`, divide by 1000
+	 *    3. Multiply `feerate_per_kw` by `weight`, divide by 1000 (rounding
-	 *    (rounding down).
+	 *    down).
 	 */
 	return feerate_per_kw * weight / 1000;
 }

common/key_derive.c

@@ -7,17 +7,17 @@
 
 /* BOLT #3:
  *
- * ### `localkey`, `remotekey`, `local_htlckey`, `remote_htlckey`, `local_delayedkey` and `remote_delayedkey` Derivation
+ * ### `localpubkey`, `remotepubkey`, `local_htlcpubkey`, `remote_htlcpubkey`, `local_delayedpubkey`, and `remote_delayedpubkey` Derivation
  *
- * These keys are simply generated by addition from their base points:
+ * 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 `localkey` uses the local node's `payment_basepoint`, `remotekey`
+ * The `localpubkey` uses the local node's `payment_basepoint`; the
- * uses the remote node's `payment_basepoint`, the `local_delayedkey`
+ * `remotepubkey` uses the remote node's `payment_basepoint`; the
- * uses the local node's `delayed_payment_basepoint`, the `local_htlckey`
+ * `local_delayedpubkey` uses the local node's `delayed_payment_basepoint`; the
- * uses the local node's `htlc_basepoint` and the `remote_delayedkey` uses
+ * `local_htlcpubkey` uses the local node's `htlc_basepoint`; and the
- * the remote node's `delayed_payment_basepoint`.
+ * `remote_delayedpubkey` uses the remote node's `delayed_payment_basepoint`.
  */
 bool derive_simple_key(const struct pubkey *basepoint,
 		    const struct pubkey *per_commitment_point,
@@ -53,11 +53,11 @@ bool derive_simple_key(const struct pubkey *basepoint,
 
 /* BOLT #3:
  *
- * The corresponding private keys can be derived similarly if the basepoint
+ * The corresponding private keys can be similarly derived, if the basepoint
- * secrets are known (i.e., `localkey`, `local_htlckey` and `local_delayedkey`
+ * secrets are known (i.e. the private keys corresponding to `localpubkey`,
- * only):
+ * `local_htlcpubkey`, and `local_delayedpubkey` only):
  *
- *     secretkey = basepoint_secret + SHA256(per_commitment_point || basepoint)
+ *     privkey = basepoint_secret + SHA256(per_commitment_point || basepoint)
  */
 bool derive_simple_privkey(const struct secret *base_secret,
 			const struct pubkey *basepoint,
@@ -93,22 +93,23 @@ bool derive_simple_privkey(const struct secret *base_secret,
 
 /* BOLT #3:
  *
- * The `revocationkey` is a blinded key: when a node wishes to create a new
+ * The `revocationpubkey` is a blinded key: when the local node wishes to
- * commitment for a remote node, it uses its own `revocation_basepoint` and
+ * create a new commitment for the remote node, it uses its own
- * the remote node's `per_commitment_point` to derive a new `revocationkey`
+ * `revocation_basepoint` and the remote node's `per_commitment_point` to
- * for the commitment. Once the remote node reveals (thereby revoking that
+ * derive a new `revocationpubkey` for the commitment. After the remote node
- * commitment) the `per_commitment_secret` used, the node can now derive the
+ * reveals the `per_commitment_secret` used (thereby revoking that
- * `revocationsecretkey` as they now know the two secrets necessary to derive
+ * commitment), the local node can then derive the `revocationprivkey`, as it
- * the key (`revocation_basepoint_secret` and `per_commitment_secret`).
+ * now knows the two secrets necessary to derive the key
+ * (`revocation_basepoint_secret` and `per_commitment_secret`).
  *
- * The `per_commitment_point` is generated using EC multiplication:
+ * The `per_commitment_point` is generated using elliptic-curve multiplication:
  *
  * 	per_commitment_point = per_commitment_secret * G
  *
- * And this is used to derive the revocation key from the remote node's
+ * And this is used to derive the revocation pubkey from the remote node's
  * `revocation_basepoint`:
  *
- * 	revocationkey = revocation_basepoint * SHA256(revocation_basepoint || per_commitment_point) + per_commitment_point*SHA256(per_commitment_point || revocation_basepoint)
+ * 	revocationpubkey = revocation_basepoint * SHA256(revocation_basepoint || per_commitment_point) + per_commitment_point * SHA256(per_commitment_point || revocation_basepoint)
  */
 bool derive_revocation_key(const struct pubkey *basepoint,
 			const struct pubkey *per_commitment_point,
@@ -177,7 +178,7 @@ bool derive_revocation_key(const struct pubkey *basepoint,
  * The corresponding private key can be derived once the `per_commitment_secret`
  * is known:
  *
- *     revocationsecretkey = revocation_basepoint_secret * SHA256(revocation_basepoint || per_commitment_point) + per_commitment_secret*SHA256(per_commitment_point || revocation_basepoint)
+ *     revocationprivkey = revocation_basepoint_secret * SHA256(revocation_basepoint || per_commitment_point) + per_commitment_secret * SHA256(per_commitment_point || revocation_basepoint)
  */
 bool derive_revocation_privkey(const struct secret *base_secret,
 			       const struct secret *per_commitment_secret,

common/keyset.c

@@ -12,18 +12,19 @@ bool derive_keyset(const struct pubkey *per_commitment_point,
 {
 	/* BOLT #3:
 	 *
-	 * ### `localkey`, `remotekey`, `local_htlckey`, `remote_htlckey`,
+	 * ### `localpubkey`, `remotepubkey`, `local_htlcpubkey`,
-	 *     `local_delayedkey` and `remote_delayedkey` Derivation
+	 *     `remote_htlcpubkey`, `local_delayedpubkey`, and
+	 *     `remote_delayedpubkey` Derivation
 	 *
-	 * These keys are simply generated by addition from their base points:
+	 * 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 `localkey` uses the local node's `payment_basepoint`,
+	 * The `localpubkey` uses the local node's `payment_basepoint`; the
-	 * `remotekey` uses the remote node's `payment_basepoint`, the
+	 * `remotepubkey` uses the remote node's `payment_basepoint`; the
-	 * `local_delayedkey` uses the local node's
+	 * `local_delayedpubkey` uses the local node's
-	 * `delayed_payment_basepoint`, the `local_htlckey` uses the local
+	 * `delayed_payment_basepoint`; the `local_htlcpubkey` uses the local
-	 * node's `htlc_basepoint` and the `remote_delayedkey` uses the
+	 * node's `htlc_basepoint`; and the `remote_delayedpubkey` uses the
 	 * remote node's `delayed_payment_basepoint`.
 	 */
 	if (!derive_simple_key(self_payment_basepoint,
@@ -53,12 +54,12 @@ bool derive_keyset(const struct pubkey *per_commitment_point,
 
 	/* BOLT #3:
 	 *
-	 * ### `revocationkey` Derivation
+	 * ### `revocationpubkey` Derivation
 	 *
-	 * The `revocationkey` is a blinded key: when a node wishes to create
+	 * The `revocationpubkey` is a blinded key: when the local node wishes
-	 * a new commitment for a remote node, it uses its own
+	 * to create a new commitment for the remote node, it uses its own
 	 * `revocation_basepoint` and the remote node's `per_commitment_point`
-	 * to derive a new `revocationkey` for the commitment.
+	 * to derive a new `revocationpubkey` for the commitment.
 	 */
 	if (!derive_revocation_key(other_revocation_basepoint,
 				   per_commitment_point,