diff --git a/common/derive_basepoints.c b/common/derive_basepoints.c index 1c4404909..5c675bb5f 100644 --- a/common/derive_basepoints.c +++ b/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, - * and MUST NOT reveal the seed. + * A node: + * - 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 */ diff --git a/common/derive_basepoints.h b/common/derive_basepoints.h index 70c1e9863..2fd38e7f4 100644 --- a/common/derive_basepoints.h +++ b/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 - * decremented. + * The first secret used: + * - MUST be index 281474976710655, + * - and from there, the index is decremented. */ static inline u64 shachain_index(u64 per_commit_index) { diff --git a/common/htlc_tx.c b/common/htlc_tx.c index 93c03f84f..a6b5bd5bf 100644 --- a/common/htlc_tx.c +++ b/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 - * transaction which can be spent by a valid penalty transaction. + * HTLC-timeout transaction is timelocked. The HTLC-timeout + * 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)). - * * `txout[0]` script: version 0 P2WSH with witness script as shown - * below. + * (see [Fee Calculation](#fee-calculation)) + * * `txout[0]` script: version-0 P2WSH with witness script as shown + * 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, diff --git a/common/htlc_tx.h b/common/htlc_tx.h index 21774e6b5..76c1f642f 100644 --- a/common/htlc_tx.h +++ b/common/htlc_tx.h @@ -11,10 +11,10 @@ static inline u64 htlc_timeout_fee(u32 feerate_per_kw) { /* BOLT #3: * - * 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). + * 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). */ return feerate_per_kw * 663ULL / 1000; } @@ -23,10 +23,10 @@ static inline u64 htlc_success_fee(u32 feerate_per_kw) { /* BOLT #3: * - * 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). + * 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). */ return feerate_per_kw * 703ULL / 1000; } diff --git a/common/initial_commit_tx.c b/common/initial_commit_tx.c index 64e679f35..e30a2ef44 100644 --- a/common/initial_commit_tx.c +++ b/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 - * P2WPKH to `remotekey`. + * This output sends funds to the other peer and thus is a simple + * 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)); diff --git a/common/initial_commit_tx.h b/common/initial_commit_tx.h index 621ffc61b..6710b550c 100644 --- a/common/initial_commit_tx.h +++ b/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 - * calculated to match: - * - * 1. Start with `weight` = 724. + * The base fee for a commitment transaction: + * - 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 - * as specified in [Trimmed Outputs](#trimmed-outputs), add - * 172 to `weight`. + * 2. For each committed HTLC, if that output is not trimmed as + * specified in [Trimmed Outputs](#trimmed-outputs), add 172 + * to `weight`. */ weight += 172 * num_untrimmed_htlcs; /* BOLT #3: * - * 3. Multiply `feerate_per_kw` by `weight`, divide by 1000 - * (rounding down). + * 3. Multiply `feerate_per_kw` by `weight`, divide by 1000 (rounding + * down). */ return feerate_per_kw * weight / 1000; } diff --git a/common/key_derive.c b/common/key_derive.c index 052512a9b..614a22869 100644 --- a/common/key_derive.c +++ b/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` - * uses the remote node's `payment_basepoint`, the `local_delayedkey` - * uses the local node's `delayed_payment_basepoint`, the `local_htlckey` - * uses the local node's `htlc_basepoint` and the `remote_delayedkey` 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_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`. */ 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 - * secrets are known (i.e., `localkey`, `local_htlckey` and `local_delayedkey` - * only): + * The corresponding private keys can be similarly derived, if the basepoint + * secrets are known (i.e. the private keys corresponding to `localpubkey`, + * `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 - * commitment for a remote node, it uses its own `revocation_basepoint` and - * the remote node's `per_commitment_point` to derive a new `revocationkey` - * for the commitment. Once the remote node reveals (thereby revoking that - * commitment) the `per_commitment_secret` used, the node can now derive the - * `revocationsecretkey` as they now know the two secrets necessary to derive - * the key (`revocation_basepoint_secret` and `per_commitment_secret`). + * The `revocationpubkey` is a blinded key: when the local node wishes 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 `revocationpubkey` for the commitment. After the remote node + * reveals the `per_commitment_secret` used (thereby revoking that + * commitment), the local node can then derive the `revocationprivkey`, as it + * 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, diff --git a/common/keyset.c b/common/keyset.c index b20868575..d54b5600b 100644 --- a/common/keyset.c +++ b/common/keyset.c @@ -12,18 +12,19 @@ bool derive_keyset(const struct pubkey *per_commitment_point, { /* 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` uses the remote node's `payment_basepoint`, the - * `local_delayedkey` uses the local node's - * `delayed_payment_basepoint`, the `local_htlckey` uses the local - * node's `htlc_basepoint` and the `remote_delayedkey` uses the + * 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`. */ 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 - * a new commitment for a remote node, it uses its own + * The `revocationpubkey` is a blinded key: when the local node wishes + * 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,