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

2024-11-19 01:50:03 +01:00 · 2017-12-11 06:47:46 -08:00 · 2017-12-11 06:47:46 -08:00 · 1a2021ea91
commit 1a2021ea91
parent 6a2b1dd841
1 changed files with 71 additions and 64 deletions
--- a/05-onchain.md
+++ b/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,
-whereas node B will have immediate access to its funds. As a consequence, the
+publishes its commitment transaction, it will have to wait to claim its own funds,
+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
-thus it need not consume resources monitoring the channel state.
+little or no funds in the channel; in this case, having nothing at stake, a node
+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
-of commitment transactions. So, the only reason not to use the signature from
-`closing_signed` would be if the fee offered was too small for it to be
-processed.
+spendable by wallets. In addition, mutual close fees tend to be less exaggerated
+than those of commitment transactions. So, the only reason not to use the
+signature from `closing_signed` would be if the fee offered was too small for
+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
-node sees *its own commitment transaction*, which *resolves* the funding
+This is the first of two cases involving unilateral closes. In this case, a
+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
-until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by
-the other node's `to_self_delay` field). Where relevant, this is noted below.
+However, a node cannot claim funds from the outputs of a unilateral close that
+it initiated, until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified
+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:
-
-1. `to_local` output: A node SHOULD spend this output to a convenient address.
-   A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the remote
-   node's `to_self_delay` field) before spending the output. If the
-   output is spent (as recommended), the output is *resolved* by the spending
-   transaction, otherwise it is considered *resolved* by the commitment transaction itself.
-2. `to_remote` output: No action required, this output is considered *resolved*
-   by the commitment transaction itself.
-3. HTLCs offered by this node: See "HTLC Output Handling: Local Commitment, Local Offers" below.
-4. HTLCs offered by the remote node: See "HTLC Output Handling: Local Commitment, Remote Offers" below.
+A node:
+  - upon discovering its *local commitment transaction*:
+    - SHOULD spend the `to_local` output to a convenient address.
+    - MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as
+    specified by the remote node's `to_self_delay` field) before spending the
+    output.
+      - Note: if the output is spent (as recommended), the output is *resolved*
+      by the spending transaction, otherwise it is considered *resolved* by the
+      commitment transaction itself.
+    - MAY ignore the `to_remote` output.
+      - 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
-transaction after it's timed out, or by them, the recipient, if they have the payment
+Each HTLC output can only be spent by either a local offerer, by using the HTLC-timeout
+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
-committed.
+because they were trimmed as dust, or because the transaction has only been
+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
-preimage, the output is considered *irrevocably resolved*, and the
-node MUST extract the payment preimage from the transaction input
-witness.
-
-If the commitment transaction HTLC output has *timed out* and not
-been *resolved*, the node MUST *resolve* the output by spending it
-using the HTLC-timeout transaction, MUST fail the corresponding
-incoming HTLC (if any) once the resolving transaction has reached
-reasonable depth, and MUST resolve the output of that HTLC-timeout
-transaction.
-
-A node SHOULD resolve that HTLC-timeout transaction by spending it to
-a convenient address. If the output is spent (as recommended), the
-output is *resolved* by the spending transaction, otherwise it is
-considered *resolved* by the commitment transaction itself.
-
-A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed
-(as specified by the remote node's `open_channel` `to_self_delay`
-field) before spending that HTLC-timeout output.
-
-For any committed HTLC that does not have an output in this
-commitment transaction, the node MUST fail the corresponding incoming
-HTLC (if any) once the commitment transaction has reached reasonable
-depth, and MAY fail it sooner if no *valid* commitment transaction
-contains an output corresponding to the HTLC.
+A node:
+  - if the commitment transaction HTLC output is spent using the payment
+  preimage, the output is considered *irrevocably resolved*:
+    - MUST extract the payment preimage from the transaction input witness.
+  - if the commitment transaction HTLC output has *timed out* and hasn't been
+  *resolved*:
+    - MUST *resolve* the output by spending it using the HTLC-timeout
+    transaction.
+    - once the resolving transaction has reached reasonable depth:
+      - MUST fail the corresponding incoming HTLC (if any).
+      - MUST resolve the output of that HTLC-timeout transaction.
+      - SHOULD resolve the HTLC-timeout transaction by spending it to a
+      convenient address.
+        - Note: if the output is spent (as recommended), the output is
+        *resolved* by the spending transaction, otherwise it is considered
+        *resolved* by the commitment transaction itself.
+      - MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as
+      specified by the remote node's `open_channel` `to_self_delay` field)
+      before spending that HTLC-timeout output.
+  - for any committed HTLC that does NOT have an output in this commitment
+  transaction:
+    - once the commitment transaction has reached reasonable depth:
+      - MUST fail the corresponding incoming HTLC (if any).
+    - if no *valid* commitment transaction 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
-when dealing with one's own commitment transaction.
+There are no delays constraining node behavior in this case, so it's simpler for
+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