f Matt's feedback, mostly concerning the fact that we don't 'construct' per-commitment-points

Author: valentinewallace

lightning/src/ln/channel.rs

@@ -54,15 +54,20 @@ enum InboundHTLCRemovalReason {
 
 enum InboundHTLCState {
 	/// Offered by remote, to be included in next local commitment tx. I.e., the remote sent an
-	// update_add_htlc message for this HTLC.
+	/// update_add_htlc message for this HTLC.
 	RemoteAnnounced(PendingHTLCStatus),
-	/// Included in a received commitment_signed message (implying we've revoke_and_ack'd it), but
-	/// the remote hasn't yet revoked their previous state (see the example below). We have not yet
-	/// included this HTLC in a commitment_signed message because we are waiting on the remote's
-	/// aforementioned state revocation. The reason we need this remote RAA (revoke_and_ack) is
-	/// because every time we create a new "state", i.e. every time we create our next
-	/// per_commitment_point (see [BOLT #2]), we consume a prior revocation point (aka the
-	/// per_commitment_secret in the revoke_and_ack message (see BOLT #2)).
+	/// Included in a received commitment_signed message (implying we've
+	/// revoke_and_ack'd it), but the remote hasn't yet revoked their previous
+	/// state (see the example below). We have not yet included this HTLC in a
+	/// commitment_signed message because we are waiting on the remote's
+	/// aforementioned state revocation. One reason this missing remote RAA
+	/// (revoke_and_ack) blocks us from constructing a commitment_signed message
+	/// is because every time we create a new "state", i.e. every time we sign a
+	/// new commitment tx (see [BOLT #2]), we need a new per_commitment_point,
+	/// which are provided one-at-a-time in each RAA. E.g., the last RAA they
+	/// sent provided the per_commitment_point for our current commitment tx.
+	/// The other reason we should not send a commitment_signed without their RAA
+	/// is because their RAA serves to ACK our previous commitment_signed.
 	///
 	/// Here's an example of how an HTLC could come to be in this state:
 	/// remote --> update_add_htlc(prev_htlc)   --> local
@@ -72,10 +77,11 @@ enum InboundHTLCState {
 	/// [note that here, the remote does not respond with a RAA]
 	/// remote --> update_add_htlc(this_htlc)   --> local
 	/// remote --> commitment_signed(prev_htlc, this_htlc) --> local
-	/// Now `this_htlc` will be assigned this state. It's unable to be officially accepted, i.e.
-	/// included in a commitment_signed, because we're missing the RAA that would let us construct
-	/// our next per_commitment_point, which is used to derive commitment keys, which are used
-	/// to construct the signatures in a commitment_signed message.
+	/// Now `this_htlc` will be assigned this state. It's unable to be officially
+	/// accepted, i.e. included in a commitment_signed, because we're missing the
+	/// RAA that provides our next per_commitment_point. The per_commitment_point
+	/// is used to derive commitment keys, which are used to construct the
+	/// signatures in a commitment_signed message.
 	/// Implies AwaitingRemoteRevoke.
 	/// [BOLT #2]: https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md
 	AwaitingRemoteRevokeToAnnounce(PendingHTLCStatus),