BOLT 5: first pass copy edit to line 248, further implement local/remote terminology;

05-onchain.md

@@ -31,7 +31,7 @@ encounters any of the above situations, on-chain.
   * [Commitment Transaction](#commitment-transaction)
   * [Failing a Channel](#failing-a-channel)
   * [Mutual Close Handling](#mutual-close-handling)
-  * [Unilateral Close Handling: Local Commitment Transaction](#unilateral-close-handling-local-own-commitment-transaction)
+  * [Unilateral Close Handling: Local Commitment Transaction](#unilateral-close-handling-local-commitment-transaction)
       * [HTLC Output Handling: Local Commitment, Local Offers](#htlc-output-handling-local-commitment-local-offers)
       * [HTLC Output Handling: Local Commitment, Remote Offers](#htlc-output-handling-local-commitment-remote-offers)
   * [Unilateral Close Handling: Remote Commitment Transaction](#unilateral-close-handling-remote-commitment-transaction)
@@ -80,7 +80,7 @@ A node:
 ## Rationale
 
 Once a local node has some funds at stake, monitoring the blockchain is required
-to ensure the remote party does not close unilaterally.
+to ensure the remote node does not close unilaterally.
 
 Invalid transactions (e.g. bad signatures) can be generated by anyone,
 (and will be ignored by the blockchain anyway), so they should not
@@ -101,8 +101,8 @@ return for a payment preimage.
 To incentivize nodes A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative
 timeout encumbers node *A's outputs* (in *A's commitment transaction*) and
 node *B's outputs* (in *B's commitment transaction*). So for example, if node A
-publishes its commitment transaction, it will have to wait to claim its funds,
+publishes its commitment transaction, it will have to wait to claim its own funds,
-whereas node B will have immediate access to its funds. As a consequence, the
+whereas node B will have immediate access to its own funds. As a consequence, the
 two commitment transactions are not identical, but they are (usually)
 symmetrical.
 
@@ -145,15 +145,15 @@ outputs (which would otherwise be left forever, unspent on the blockchain), it's
 insisted that all commitment transaction outputs be spent.
 
 In the early stages of a channel, it's common for one side to have
-little or no funds in the channel; in this case, it has nothing to lose, and
+little or no funds in the channel; in this case, having nothing at stake, a node
-thus it need not consume resources monitoring the channel state.
+need not consume resources monitoring the channel state.
 
 There exists a bias towards preferring mutual closes over unilateral closes,
 because outputs of the former are unencumbered by a delay and are directly
-spendable by wallets. In addition, fees tend to be less exaggerated than those
+spendable by wallets. In addition, mutual close fees tend to be less exaggerated
-of commitment transactions. So, the only reason not to use the signature from
+than those of commitment transactions. So, the only reason not to use the
-`closing_signed` would be if the fee offered was too small for it to be
+signature from `closing_signed` would be if the fee offered was too small for
-processed.
+it to be processed.
 
 # Mutual Close Handling
 
@@ -163,34 +163,40 @@ 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` (see
 [BOLT #2: Closing initiation: `shutdown`](02-peer-protocol.md#closing-initiation-shutdown)).
 
-# Unilateral Close Handling: Local Own Commitment Transaction
+# Unilateral Close Handling: Local Commitment Transaction
 
-This is the first of two cases involving unilateral closes: in this case, a
+This is the first of two cases involving unilateral closes. In this case, a
-node sees *its own commitment transaction*, which *resolves* the funding
+node discovers its *local commitment transaction*, which *resolves* the funding
 transaction output.
 
-However, a node cannot claim funds from the outputs of its own unilateral close
+However, a node cannot claim funds from the outputs of a unilateral close that
-until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by
+it initiated, until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified
-the other node's `to_self_delay` field). Where relevant, this is noted below.
+by the remote node's `to_self_delay` field). Where relevant, this situation is
+noted below.
 
 ## Requirements
 
-When a node sees *its own* commitment transaction:
+A node:
-
+  - upon discovering its *local commitment transaction*:
-1. `to_local` output: A node SHOULD spend this output to a convenient address.
+    - SHOULD spend the `to_local` output to a convenient address.
-   A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the remote
+    - MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as
-   node's `to_self_delay` field) before spending the output. If the
+    specified by the remote node's `to_self_delay` field) before spending the
-   output is spent (as recommended), the output is *resolved* by the spending
+    output.
-   transaction, otherwise it is considered *resolved* by the commitment transaction itself.
+      - Note: if the output is spent (as recommended), the output is *resolved*
-2. `to_remote` output: No action required, this output is considered *resolved*
+      by the spending transaction, otherwise it is considered *resolved* by the
-   by the commitment transaction itself.
+      commitment transaction itself.
-3. HTLCs offered by this node: See "HTLC Output Handling: Local Commitment, Local Offers" below.
+    - MAY ignore the `to_remote` output.
-4. HTLCs offered by the remote node: See "HTLC Output Handling: Local Commitment, Remote Offers" below.
+      - Note: No action is required by the local node, as `to_remote` is
+      considered *resolved* by the commitment transaction itself.
+    - [FIXME: SHOULD|MAY|MUST?] handle HTLCs offered by itself as specified in
+    "HTLC Output Handling: Local Commitment, Local Offers" below.
+    - [FIXME: SHOULD|MAY|MUST?] handle HTLCs offered by the remote node as
+    specified in "HTLC Output Handling: Local Commitment, Remote Offers" below.
 
 ## Rationale
 
 Spending the `to_local` output avoids having to remember the complicated
-witness script associated with that particular channel for later
+witness script, associated with that particular channel, for later
 spending.
 
 The `to_remote` output is entirely the business of the remote node, and
@@ -198,45 +204,45 @@ can be ignored.
 
 ## HTLC Output Handling: Local Commitment, Local Offers
 
-Each HTLC output can only be spent by us, the offerer, using the HTLC-timeout
+Each HTLC output can only be spent by either a local offerer, by using the HTLC-timeout
-transaction after it's timed out, or by them, the recipient, if they have the payment
+transaction after it's timed out, or a remote recipient, if it has the payment
 preimage.
 
 There can be HTLCs which are not represented by an output: either
-because they were trimmed as dust, or because it's only been partially
+because they were trimmed as dust, or because the transaction has only been
-committed.
+partially committed.
 
-The HTLC has *timed out* once the depth of the latest block is equal
+The HTLC has *timed out* once the depth of the latest block is equal to
 or greater than the HTLC `cltv_expiry`.
 
 ### Requirements
 
-If the commitment transaction HTLC output is spent using the payment
+A node:
-preimage, the output is considered *irrevocably resolved*, and the
+  - if the commitment transaction HTLC output is spent using the payment
-node MUST extract the payment preimage from the transaction input
+  preimage, the output is considered *irrevocably resolved*:
-witness.
+    - MUST extract the payment preimage from the transaction input witness.
-
+  - if the commitment transaction HTLC output has *timed out* and hasn't been
-If the commitment transaction HTLC output has *timed out* and not
+  *resolved*:
-been *resolved*, the node MUST *resolve* the output by spending it
+    - MUST *resolve* the output by spending it using the HTLC-timeout
-using the HTLC-timeout transaction, MUST fail the corresponding
+    transaction.
-incoming HTLC (if any) once the resolving transaction has reached
+    - once the resolving transaction has reached reasonable depth:
-reasonable depth, and MUST resolve the output of that HTLC-timeout
+      - MUST fail the corresponding incoming HTLC (if any).
-transaction.
+      - MUST resolve the output of that HTLC-timeout transaction.
-
+      - SHOULD resolve the HTLC-timeout transaction by spending it to a
-A node SHOULD resolve that HTLC-timeout transaction by spending it to
+      convenient address.
-a convenient address. If the output is spent (as recommended), the
+        - Note: if the output is spent (as recommended), the output is
-output is *resolved* by the spending transaction, otherwise it is
+        *resolved* by the spending transaction, otherwise it is considered
-considered *resolved* by the commitment transaction itself.
+        *resolved* by the commitment transaction itself.
-
+      - MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as
-A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed
+      specified by the remote node's `open_channel` `to_self_delay` field)
-(as specified by the remote node's `open_channel` `to_self_delay`
+      before spending that HTLC-timeout output.
-field) before spending that HTLC-timeout output.
+  - for any committed HTLC that does NOT have an output in this commitment
-
+  transaction:
-For any committed HTLC that does not have an output in this
+    - once the commitment transaction has reached reasonable depth:
-commitment transaction, the node MUST fail the corresponding incoming
+      - MUST fail the corresponding incoming HTLC (if any).
-HTLC (if any) once the commitment transaction has reached reasonable
+    - if no *valid* commitment transaction contains an output corresponding to
-depth, and MAY fail it sooner if no *valid* commitment transaction
+    the HTLC.
-contains an output corresponding to the HTLC.
+      - MAY fail the corresponding incoming HTLC sooner.
 
 ### Rationale
 
@@ -315,12 +321,13 @@ If not otherwise resolved, once the HTLC output has expired, it is considered
 The *remote node's* commitment transaction *resolves* the funding
 transaction output.
 
-There are no delays constraining behavior here, so it's simpler than
+There are no delays constraining node behavior in this case, so it's simpler for
-when dealing with one's own commitment transaction.
+a node to handle than the case in which it discovers its local commitment
+transaction.
 
 ## Requirements
 
-When a node sees a commitment transaction from the *remote node*:
+When a node discovers a commitment transaction from the *remote node*:
 
 1. `to_remote`: No action is required; this is a simple P2WPKH output to us.
    This output is considered *resolved* by the commitment transaction itself.
@@ -457,7 +464,7 @@ to claim all the funds.
 A node MUST NOT broadcast a commitment transaction for which *it* has
 exposed the revocation key.
 
-If a node sees a commitment transaction for which *it* has a
+If a node discovers a commitment transaction for which *it* has a
 revocation key, that *resolves* the funding transaction output.
 
 A node MUST resolve all unresolved outputs as follows:
@@ -538,7 +545,7 @@ Note that even if the `to_remote` output is not swept, the resulting
 
 # General Requirements
 
-A node SHOULD report an error to the operator if it sees a transaction
+A node SHOULD report an error to the operator if it discovers a transaction
 spend the funding transaction output which does not fall into one of
 these categories (mutual close, unilateral close, or revoked
 transaction close). Such a transaction implies its private key has