BOLT 5: first pass copy edit to line 320, replace we/they terminology with local/remote;

05-onchain.md

@@ -3,8 +3,8 @@
 ## Abstract
 
 Lightning allows for two parties (nodes A and B) to conduct transactions
-off-chain by giving each of them a *cross-signed commitment transaction*, which
+off-chain by giving each of the parties a *cross-signed commitment transaction*,
-describes the current state of the channel (basically, the current balance).
+which describes the current state of the channel (basically, the current balance).
 This *commitment transaction* is updated every time a new payment is made and
 is spendable at all times.
 
@@ -256,65 +256,67 @@ In cases where both resolutions are possible (e.g. when a node receives payment
 success after timeout), either interpretation is acceptable; it is the
 responsibility of the recipient to spend it before this occurs.
 
-The local HTLC-timeout transaction needs to be used to time out the HTLC to
+The local HTLC-timeout transaction needs to be used to time out the HTLC (to
-prevent the remote node fulfilling it and claiming the funds, and before we can back-fail any
+prevent the remote node fulfilling it and claiming the funds) before the
-corresponding incoming HTLC, using `update_fail_htlc` (presumably with reason
+local node can back-fail any corresponding incoming HTLC, using
-`permanent_channel_failure`) as detailed in
+`update_fail_htlc` (presumably with reason `permanent_channel_failure`), as
+detailed in
 [BOLT 02](https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#forwarding-htlcs).
-If the incoming HTLC is on-chain too, we simply wait for it to timeout: there's
+If the incoming HTLC is also on-chain, a node must simply wait for it to
-no way to signal early failure.
+timeout: there is no way to signal early failure.
 
-If an HTLC is too small to appear in *any* commitment transaction, it
+If an HTLC is too small to appear in *any commitment transaction*, it can be
-can be safely failed immediately. Otherwise,
+safely failed immediately. Otherwise, if an HTLC isn't in the *local commitment
-if a HTLC isn't in *local* commitment transaction a node needs to make sure
+transaction*, a node needs to make sure that a blockchain reorganization, or
-that a blockchain reorganization or race does not switch to a
+race, does not switch to a commitment transaction that does contain the HTLC
-commitment transaction which does contain it before the node fails it, hence
+before the node fails it (hence the wait). The requirement that the incoming
-the wait. The requirement that the incoming HTLC be failed before its
+HTLC be failed before its own timeout still applies as an upper bound.
-own timeout still applies as an upper bound.
 
 ## HTLC Output Handling: Local Commitment, Remote Offers
 
-Each HTLC output can only be spent by us, the recipient, using the HTLC-success
+Each HTLC output can only be spent by the recipient, using the HTLC-success
-transaction, which we can only populate if we have the payment
+transaction, which it can only populate if it has the payment
-preimage. If we don't have the preimage (and don't discover it), it's
+preimage. If it doesn't have the preimage (and doesn't discover it), it's
 the offerer's responsibility to spend the HTLC output once it's timed out.
 
-There are actually several possible cases for an offered HTLC:
+There are several possible cases for an offered HTLC:
 
-1. The offerer is not irrevocably committed to it. The recipient won't
+1. The offerer is NOT irrevocably committed to it. The recipient will usually
-   normally know the preimage here, since it won't forward HTLCs until
+   not know the preimage, since it will not forward HTLCs until they're fully
-   they're fully committed. So using the preimage would reveal that
+   committed. So using the preimage would reveal that this recipient is the
-   this recipient is the final hop, so it's best to allow the HTLC to time out in
+   final hop; thus, in this case, it's best to allow the HTLC to time out.
-   this case.
+2. The offerer is irrevocably committed to the offered HTLC, but the recipient
-2. The offerer is irrevocably committed to the offered HTLC, but the recipient hasn't yet
+   has not yet committed to an outgoing HTLC. In this case, the recipient can
-   committed to an outgoing HTLC. In this case the recipient can either forward
+   either forward or timeout the offered HTLC.
-   or timeout.
+3. The recipient has committed to an outgoing HTLC, in exchange for the offered
-3. The recipient has committed to an outgoing HTLC for the offered one. In
+   HTLC. In this case, the recipient must use the preimage, once it receives it
-   this case the recipient has to use the preimage if it receives it from the
+   from the outgoing HTLC; otherwise, it will lose funds by sending an outgoing
-   outgoing HTLC, otherwise it will lose funds by making an outgoing
+   payment without redeeming the incoming payment.
-   payment without redeeming the incoming one.
 
 ### Requirements
 
-If the node receives (or already knows) a payment preimage for an
+A local node:
-unresolved HTLC output it was offered for which it has committed to an
+  - if it receives (or already possesses) a payment preimage for an unresolved
-outgoing HTLC, it MUST *resolve* the output by spending it using the
+  HTLC output that it has been offered AND for which it has committed to an
-HTLC-success transaction, and MUST resolve the output of that
+  outgoing HTLC:
-HTLC-success transaction. Otherwise, if the remote node is not
+    - MUST *resolve* the output by spending it, using the HTLC-success
-irrevocably committed to the HTLC, it MUST NOT *resolve* the output by
+    transaction.
-spending it.
+    - MUST resolve the output of that HTLC-success transaction.
+  - otherwise:
+    - if the *remote node* is NOT irrevocably committed to the HTLC:
+      - MUST NOT *resolve* the output by spending it.
+  - SHOULD resolve that HTLC-success transaction output by spending it to a
+  convenient address.
+  - MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified
+    by the *remote node's* `open_channel`'s `to_self_delay` field), before
+    spending that HTLC-success transaction output.
 
-A node SHOULD resolve that HTLC-success transaction output by spending
+If the output is spent (as is recommended), the output is *resolved* by
-it to a convenient address. If the output is spent (as recommended),
+the spending transaction, otherwise it's considered *resolved* by the commitment
-the output is *resolved* by the spending transaction, otherwise it is
+transaction itself.
-considered *resolved* by the commitment transaction itself.
 
-A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed
+If it's NOT otherwise resolved, once the HTLC output has expired, it is
-(as specified by the remote node's `open_channel` `to_self_delay`
+considered *irrevocably resolved*.
-field) before spending that HTLC-success transaction output.
-
-If not otherwise resolved, once the HTLC output has expired, it is considered
-*irrevocably resolved*.
 
 # Unilateral Close Handling: Remote Commitment Transaction
 
@@ -358,8 +360,8 @@ HTLCs).
 
 ## HTLC Output Handling: Remote Commitment, Local Offers
 
-Each HTLC output can only be spent by us, the offerer, after it's timed out,
+Each HTLC output can only be spent by the *offerer* after it's timed out or by
-or by them, the recipient, if they have the payment preimage.
+the *recipient* if it has the payment preimage.
 
 The HTLC output has *timed out* once the depth of the latest block is equal
 or greater than the HTLC `cltv_expiry`.
@@ -387,8 +389,8 @@ contains an output corresponding to the HTLC.
 
 ### Rationale
 
-If the commitment transaction belongs to the *remote* node, the only way to
+If the commitment transaction belongs to the *remote* node, the only way for it
-spend the HTLC output using a payment preimage is for them to use the
+to spend the HTLC output (using a payment preimage) is for it to use the
 HTLC-success transaction.
 
 The payment preimage either serves to prove payment (when the offering node
@@ -397,16 +399,16 @@ another peer (when the offering node is forwarding the payment). Once a node has
 extracted the payment, it no longer cares about the fate of the HTLC-spending
 transaction itself.
 
-In cases where both resolutions are possible (e.g., when a node receives payment
+In cases where both resolutions are possible (e.g. when a node receives payment
 success after timeout), either interpretation is acceptable; it is the
 responsibility of the recipient to spend it before this occurs.
 
-We need to spend the HTLC output once it has timed out to prevent
+Once it has timed out, the HTLC output needs to be spent (to prevent
-them using the HTLC-success transaction, and before we can
+the remote node using the HTLC-success transaction) before the local node can
 back-fail any corresponding incoming HTLC, using `update_fail_htlc`
-(presumably with reason `permanent_channel_failure`) as detailed in
+(presumably with reason `permanent_channel_failure`), as detailed in
 [BOLT 02](https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md#forwarding-htlcs).
-If the incoming HTLC is on-chain too, we simply wait for it to
+If the incoming HTLC is also on-chain, a node simply waits for it to
 timeout: there's no way to signal early failure.
 
 If an HTLC is too small to appear in *any* commitment transaction, it
@@ -420,12 +422,14 @@ own timeout still applies as an upper bound.
 ## HTLC Output Handling: Remote Commitment, Remote Offers
 
 Each HTLC output can only be spent by us, the recipient, using the payment
-preimage. If we don't have the preimage (and don't discover it), it's
+preimage. If the local node does not possess the preimage (and doesn't discover
-the offerer's responsibility to spend the HTLC output once it's timed out.
+it), it's the offerer's responsibility to spend the HTLC output, once it's timed
+out.
 
-We can only spend remote HTLC outputs if we have the payment preimage.
+The remote HTLC outputs can only be spent by the local node if it has the
-If we don't have the preimage (and don't discover it), it's the remote's
+payment preimage. If the local node does not have the preimage (and doesn't
-responsibility to spend the HTLC output once it's timed out.
+discover it), it's the remote node's responsibility to spend the HTLC output,
+once it's timed out.
 
 There are actually several possible cases for an offered HTLC:
 
@@ -500,8 +504,8 @@ standard size limit thanks to the 483 HTLC-per-party limit (see
 Note that if a single transaction is used it may be invalidated as node B
 broadcasts HTLC-timeout and HTLC-success transactions, but the
 requirement of persistence, until all outputs are irrevocably resolved,
-should cover this. [FIXME: May have to divide and conquer here, since they may
+should cover this. [ FIXME: May have to divide and conquer here, since the remote
-be able to delay us long enough to avoid successful penalty spend? ]
+node may be able to delay the local node long enough to avoid successful penalty spend? ]
 
 ## Penalty Transactions Weight Calculation