diff --git a/05-onchain.md b/05-onchain.md index 6fe1fb4..936be0d 100644 --- 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