Clarify the sighash types for HTLC Success and Timeout transactions

01-messaging.md

@@ -265,8 +265,12 @@ The `features` field MUST be padded to bytes with 0s.
     2. data:
         * [`...*chain_hash`:`chains`]
 
+    1. type: 3 (`remote_addr`)
+    2. data:
+        * `address descriptor`  (1 byte type and data, see BOLT 7)
 
 The optional `networks` indicates the chains the node is interested in.
+The optional `remote_addr` can be used to circumvent NAT issues.
 
 #### Requirements
 
@@ -277,6 +281,10 @@ The sending node:
   - SHOULD NOT set features greater than 13 in `globalfeatures`.
   - SHOULD use the minimum length required to represent the `features` field.
   - SHOULD set `networks` to all chains it will gossip or open channels for.
+  - SHOULD set `remote_addr` to reflect the remote IP address (and port) of an
+    incoming connection, if the node is the receiver and the connection was done
+    via IP.
+  - SHOULD NOT set private addresses as `remote_addr`.
 
 The receiving node:
   - MUST wait to receive `init` before sending any other messages.
@@ -290,6 +298,7 @@ The receiving node:
     - MAY close the connection.
   - if the feature vector does not set all known, transitive dependencies:
     - MUST close the connection.
+  - MAY use the `remote_addr` to update its `node_annoucement`
 
 #### Rationale
 

02-peer-protocol.md

@@ -1405,7 +1405,7 @@ A node:
     `your_last_per_commitment_secret` is correct for that
     `next_revocation_number` minus 1:
       - MUST NOT broadcast its commitment transaction.
-      - SHOULD fail the channel.
+      - SHOULD send an `error` to request the peer to fail the channel.
     - otherwise:
       - if `your_last_per_commitment_secret` does not match the expected values:
         - SHOULD send an `error` and fail the channel.
@@ -1414,7 +1414,7 @@ A node:
     `your_last_per_commitment_secret` is correct for that
     `next_revocation_number` minus 1:
       - MUST NOT broadcast its commitment transaction.
-      - SHOULD fail the channel.
+      - SHOULD send an `error` to request the peer to fail the channel.
       - SHOULD store `my_current_per_commitment_point` to retrieve funds
         should the sending node broadcast its commitment transaction on-chain.
     - otherwise (`your_last_per_commitment_secret` or `my_current_per_commitment_point`
@@ -1490,18 +1490,19 @@ Similarly, for the fundee's `funding_signed` message: it's better to
 remember a channel that never opens (and times out) than to let the
 funder open it while the fundee has forgotten it.
 
-`option_data_loss_protect` was added to allow a node, which has somehow fallen behind
-(e.g. has been restored from old backup), to detect that it's fallen-behind. A fallen-behind
-node must know it cannot broadcast its current commitment transaction — which would lead to
-total loss of funds — as the remote node can prove it knows the
-revocation preimage. The error returned by the fallen-behind node
-(or simply the invalid numbers in the `channel_reestablish` it has
-sent) should make the other node drop its current commitment
-transaction to the chain. This will, at least, allow the fallen-behind node to recover
-non-HTLC funds, if the `my_current_per_commitment_point`
-is valid. However, this also means the fallen-behind node has revealed this
-fact (though not provably: it could be lying), and the other node could use this to
-broadcast a previous state.
+`option_data_loss_protect` was added to allow a node, which has somehow fallen
+behind (e.g. has been restored from old backup), to detect that it has fallen
+behind. A fallen-behind node must know it cannot broadcast its current
+commitment transaction — which would lead to total loss of funds — as the
+remote node can prove it knows the revocation preimage. The `error` returned by
+the fallen-behind node should make the other node drop its current commitment
+transaction to the chain. The other node should wait for that `error` to give
+the fallen-behind node an opportunity to fix its state first (e.g by restarting
+with a different backup). If the fallen-behind node doesn't have the latest
+backup, this will, at least, allow it to recover non-HTLC funds, if the
+`my_current_per_commitment_point` is valid. However, this also means the
+fallen-behind node has revealed this fact (though not provably: it could be lying),
+and the other node could use this to broadcast a previous state.
 
 `option_static_remotekey` removes the changing `to_remote` key,
 so the `my_current_per_commitment_point` is unnecessary and thus

03-transactions.md

@@ -328,7 +328,7 @@ These HTLC transactions are almost identical, except the HTLC-timeout transactio
 * txout count: 1
    * `txout[0]` amount: the HTLC amount minus fees (see [Fee Calculation](#fee-calculation))
    * `txout[0]` script: version-0 P2WSH with witness script as shown below
-* if `option_anchors` applies to this commitment transaction, `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used.
+* if `option_anchors` applies to this commitment transaction, `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` is used as described in [BOLT #5](05-onchain.md#generation-of-htlc-transactions).
 
 The witness script for the output is:
 

05-onchain.md

@@ -143,12 +143,15 @@ A node:
       sufficient fee:
         - SHOULD use this fee to perform a *mutual close*.
       - otherwise:
-        - MUST use the *last commitment transaction*, for which it has a
-        signature, to perform a *unilateral close*.
-      - MUST spend any `to_local_anchor` output, providing sufficient fees as incentive to include the commitment transaction in a block
-        Special care must be taken when spending to a third-party, because this re-introduces the vulnerability that was
-        addressed by adding the CSV delay to the non-anchor outputs.
-	    - SHOULD use [replace-by-fee](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki) or other mechanism on the spending transaction if it proves insufficient for timely inclusion in a block.
+      	- if the node knows or assumes its channel state is outdated:
+      	  - MUST NOT broadcast its *last commitment transaction*.
+        - otherwise:
+          - MUST broadcast the *last commitment transaction*, for which it has a
+          signature, to perform a *unilateral close*.
+          - MUST spend any `to_local_anchor` output, providing sufficient fees as incentive to include the commitment transaction in a block.
+          Special care must be taken when spending to a third-party, because this re-introduces the vulnerability that was
+          addressed by adding the CSV delay to the non-anchor outputs.
+          - SHOULD use [replace-by-fee](https://github.com/bitcoin/bips/blob/master/bip-0125.mediawiki) or other mechanism on the spending transaction if it proves insufficient for timely inclusion in a block.
 
 ## Rationale
 
@@ -361,7 +364,7 @@ A local node:
       - MUST handle HTLCs offered by the remote node as specified in
       [HTLC Output Handling: Remote Commitment, Remote Offers](#htlc-output-handling-remote-commitment-remote-offers)
     - otherwise (it is NOT able to handle the broadcast for some reason):
-      - MUST send a warning regarding lost funds.
+      - MUST inform the user of potentially lost funds.
 
 ## Rationale
 
@@ -591,8 +594,8 @@ If `option_anchors` does not apply to the commitment transaction, then
 HTLC-timeout and HTLC-success transactions are complete transactions with
 (hopefully!) reasonable fees and must be used directly.
 
-Otherwise, the use of `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` on the HTLC
-signatures received from the peer allows HTLC transactions to be combined with
+Otherwise, `SIGHASH_SINGLE|SIGHASH_ANYONECANPAY` MUST be used on the
+HTLC signatures received from the peer, as this allows HTLC transactions to be combined with 
 other transactions.  The local signature MUST use `SIGHASH_ALL`, otherwise
 anyone can attach additional inputs and outputs to the tx.
 
@@ -625,7 +628,7 @@ A node:
   - upon discovering a transaction that spends a funding transaction output
   which does not fall into one of the above categories (mutual close, unilateral
   close, or revoked transaction close):
-    - MUST send a warning regarding lost funds.
+    - MUST warn the user of potentially lost funds.
       - Note: the existence of such a rogue transaction implies that its private
       key has leaked and that its funds may be lost as a result.
   - MAY simply monitor the contents of the most-work chain for transactions.