Closing tx detailed specification

02-peer-protocol.md

@@ -414,38 +414,35 @@ The sender SHOULD set the initial `fee_satoshis` according to its
 estimate of cost of inclusion in a block.
 
 The sender MUST set `signature` to the Bitcoin signature of the close
-transaction with the node responsible for paying the bitcoin fee
-paying `fee_satoshis`, then removing any output which is below
-its own `dust_limit_satoshis`. The sender MAY then also eliminate its own
-output from the mutual close transaction.
+transaction as specified in [BOLT #3](03-transactions.md#closing-transaction).
 
-The receiver MUST check `signature` is valid for either the close
-transaction with the given `fee_satoshis` as detailed above and its
-own `dust_limit_satoshis` OR that same transaction with the sender's
-output eliminated, and MUST fail the connection if it is not.
+The receiver MUST check `signature` is valid for either variant of close
+transaction specified in [BOLT #3](03-transactions.md#closing-transaction),
+and MUST fail the connection if it is not.
+
+If `fee_satoshis` is equal to its previously sent `fee_satoshis`, the receiver
+SHOULD close the connection and SHOULD sign and broadcast the final closing
+transaction.
+
+Otherwise, the
+recipient MUST fail the connection if `fee_satoshis` is greater than
+the base fee of the final commitment transaction as calculated in
+[BOLT #3](03-transactions.md#fee-calculation), and the
+recipient SHOULD fail the connection if `fee_satoshis` is not strictly
+between its last-sent `fee_satoshis` and its previously-received
+`fee_satoshis`, unless it has reconnected since then.
 
 If the receiver agrees with the fee, it SHOULD reply with a
 `closing_signed` with the same `fee_satoshis` value, otherwise it
-SHOULD propose a value strictly between the received `fee_satoshis`
+MUST propose a value strictly between the received `fee_satoshis`
 and its previously-sent `fee_satoshis`.
 
-Once a node has sent or received a `closing_signed` with matching
-`fee_satoshis` it SHOULD close the connection and SHOULD sign and
-broadcast the final closing transaction.
-
 #### Rationale
 
-There is a possibility of irreparable differences on closing if one
-node considers the other's output too small to allow propagation on
-the bitcoin network (aka "dust"), and that other node instead
-considers that output to be too valuable to discard.  This is why each
-side uses its own `dust_limit_satoshis`, and the result can be a
-signature validation failure, if they disagree on what the closing
-transaction should look like.
-
-However, if one side chooses to eliminate its own output, there's no
-reason for the other side to fail the closing protocol, so this is
-explicitly allowed.
+The "strictly between" requirements ensure that we make forward
+progress, even if only by a single satoshi at a time.  To avoid
+keeping state and handle the corner case where fees have shifted
+between reconnections, negotiation restarts on reconnection.
 
 Note that there is limited risk if the closing transaction is
 delayed, and it will be broadcast very soon, so there is usually no
@@ -994,7 +991,7 @@ same `update_` messages as previously sent.
 
 On reconnection if the node has sent a previous `shutdown` it MUST
 retransmit it, and if the node has sent a previous `closing_signed` it
-MUST then retransmit the last `closing_signed`.
+MUST send another `closing_signed`.
 
 ### Rationale
 
@@ -1012,7 +1009,9 @@ because there are also occasions where a node can simply forget the
 channel altogether.
 
 There is similarly no acknowledgment for `closing_signed`, or
-`shutdown`, so they are also retransmitted on reconnection.
+`shutdown`, so they are also retransmitted on reconnection.  In the
+case of `closing_signed`, negotation restarts on reconnection, so it
+need not be an exact retransmission.
 
 The handling of updates is similarly atomic: if the commit is not
 acknowledged (or wasn't sent) the updates are re-sent.  However, we

03-transactions.md

@@ -15,6 +15,7 @@ This details the exact format of on-chain transactions, which both sides need to
         * [Received HTLC Outputs](#received-htlc-outputs)
         * [Trimmed Outputs](#trimmed-outputs)
     * [HTLC-Timeout and HTLC-Success Transactions](#htlc-timeout-and-htlc-success-transactions)
+	* [Closing Transaction](#closing-transaction)
     * [Fees](#fees)
         * [Fee Calculation](#fee-calculation)   
         * [Fee Payment](#fee-payment)
@@ -234,6 +235,44 @@ The witness script for the output is:
 
 To spend this via penalty, the remote node uses a witness stack `<revocationsig> 1` and to collect the output the local node uses an input with nSequence `to_self_delay` and a witness stack `<local_delayedsig> 0`
 
+## Closing Transaction
+
+Note that there are two possible variants for each node.
+
+* version: 1
+* locktime: 0
+* txin count: 1
+   * `txin[0]` outpoint: `txid` and `output_index` from `funding_created` message
+   * `txin[0]` sequence: 0xFFFFFFFF
+   * `txin[0]` script bytes: 0
+   * `txin[0]` witness: `0 <signature_for_key1> <signature_for_key2>`
+* txout count: 0, 1 or 2
+   * `txout` amount: final balance to be paid to one node (minus `fee_satoshis` from `closing_signed` if this peer funded the channel)
+   * `txout` script: as specified in that node's `scriptpubkey` in its `shutdown` message.
+
+### Requirements
+
+Each node offering a signature MUST subtract the fee given by `fee_satoshis` from
+the output to the funder; it MUST then remove any output below its own `dust_limit_satoshis`, and MAY also eliminate its own output.
+
+### Rationale
+
+There is a possibility of irreparable differences on closing if one
+node considers the other's output too small to allow propagation on
+the bitcoin network (aka "dust"), and that other node instead
+considers that output to be too valuable to discard.  This is why each
+side uses its own `dust_limit_satoshis`, and the result can be a
+signature validation failure, if they disagree on what the closing
+transaction should look like.
+
+However, if one side chooses to eliminate its own output, there's no
+reason for the other side to fail the closing protocol, so this is
+explicitly allowed.  The signature will indicate which variant
+has been used.
+
+There will be at least one output if `dust_limit_satoshis` is greater
+than twice the funding amount.
+
 ## Fees
 
 ### Fee Calculation