diff --git a/01-messaging.md b/01-messaging.md index 84e402d70..935083b04 100644 --- a/01-messaging.md +++ b/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 diff --git a/02-peer-protocol.md b/02-peer-protocol.md index afc2919c4..445b1f54b 100644 --- a/02-peer-protocol.md +++ b/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 diff --git a/03-transactions.md b/03-transactions.md index 282533236..0ad86e211 100644 --- a/03-transactions.md +++ b/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: diff --git a/05-onchain.md b/05-onchain.md index 08cd27efa..934ab4f62 100644 --- a/05-onchain.md +++ b/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.