From 17dab63e97dd92a7161e96d2c1d2009f16f23887 Mon Sep 17 00:00:00 2001 From: t-bast Date: Wed, 11 Jan 2023 09:51:39 +0100 Subject: [PATCH 1/3] Properly align statements This commit only contains cosmetic whitespace changes: statements weren't consistently aligned. I harmonized them as I find that it helps readability, especially with complex nested conditions. --- 02-peer-protocol.md | 52 ++++++++++++++++++++++----------------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 8a5751c01..18e2f0d33 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1398,15 +1398,15 @@ A node: - MUST handle continuation of a previous channel on a new encrypted transport. - upon disconnection: - MUST reverse any uncommitted updates sent by the other side (i.e. all - messages beginning with `update_` for which no `commitment_signed` has - been received). + messages beginning with `update_` for which no `commitment_signed` has + been received). - Note: a node MAY have already used the `payment_preimage` value from - the `update_fulfill_htlc`, so the effects of `update_fulfill_htlc` are not - completely reversed. + the `update_fulfill_htlc`, so the effects of `update_fulfill_htlc` are not + completely reversed. - upon reconnection: - if a channel is in an error state: - SHOULD retransmit the error packet and ignore any other packets for - that channel. + that channel. - otherwise: - MUST transmit `channel_reestablish` for each channel. - MUST wait to receive the other node's `channel_reestablish` @@ -1414,9 +1414,9 @@ A node: The sending node: - MUST set `next_commitment_number` to the commitment number of the - next `commitment_signed` it expects to receive. + next `commitment_signed` it expects to receive. - MUST set `next_revocation_number` to the commitment number of the - next `revoke_and_ack` message it expects to receive. + next `revoke_and_ack` message it expects to receive. - if `option_static_remotekey` applies to the commitment transaction: - MUST set `my_current_per_commitment_point` to a valid point. @@ -1431,7 +1431,7 @@ The sending node: A node: - if `next_commitment_number` is 1 in both the `channel_reestablish` it - sent and received: + sent and received: - MUST retransmit `channel_ready`. - otherwise: - MUST NOT retransmit `channel_ready`, but MAY send `channel_ready` with @@ -1439,37 +1439,37 @@ A node: - upon reconnection: - MUST ignore any redundant `channel_ready` it receives. - if `next_commitment_number` is equal to the commitment number of - the last `commitment_signed` message the receiving node has sent: + the last `commitment_signed` message the receiving node has sent: - MUST reuse the same commitment number for its next `commitment_signed`. - otherwise: - - if `next_commitment_number` is not 1 greater than the - commitment number of the last `commitment_signed` message the receiving - node has sent: + - if `next_commitment_number` is not 1 greater than the commitment number + of the last `commitment_signed` message the receiving + node has sent: - SHOULD send an `error` and fail the channel. - if it has not sent `commitment_signed`, AND `next_commitment_number` - is not equal to 1: + is not equal to 1: - SHOULD send an `error` and fail the channel. - if `next_revocation_number` is equal to the commitment number of - the last `revoke_and_ack` the receiving node sent, AND the receiving node - hasn't already received a `closing_signed`: + the last `revoke_and_ack` the receiving node sent, AND the receiving node + hasn't already received a `closing_signed`: - MUST re-send the `revoke_and_ack`. - if it has previously sent a `commitment_signed` that needs to be - retransmitted: + retransmitted: - MUST retransmit `revoke_and_ack` and `commitment_signed` in the same - relative order as initially transmitted. + relative order as initially transmitted. - otherwise: - if `next_revocation_number` is not equal to 1 greater than the - commitment number of the last `revoke_and_ack` the receiving node has sent: + commitment number of the last `revoke_and_ack` the receiving node has sent: - SHOULD send an `error` and fail the channel. - if it has not sent `revoke_and_ack`, AND `next_revocation_number` - is not equal to 0: + is not equal to 0: - SHOULD send an `error` and fail the channel. A receiving node: - if `option_static_remotekey` applies to the commitment transaction: - if `next_revocation_number` is greater than expected above, AND - `your_last_per_commitment_secret` is correct for that - `next_revocation_number` minus 1: + `your_last_per_commitment_secret` is correct for that + `next_revocation_number` minus 1: - MUST NOT broadcast its commitment transaction. - SHOULD send an `error` to request the peer to fail the channel. - otherwise: @@ -1477,23 +1477,23 @@ A node: - SHOULD send an `error` and fail the channel. - otherwise, if it supports `option_data_loss_protect`: - if `next_revocation_number` is greater than expected above, AND - `your_last_per_commitment_secret` is correct for that - `next_revocation_number` minus 1: + `your_last_per_commitment_secret` is correct for that + `next_revocation_number` minus 1: - MUST NOT broadcast its commitment transaction. - 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` - do not match the expected values): + do not match the expected values): - SHOULD send an `error` and fail the channel. A node: - MUST NOT assume that previously-transmitted messages were lost, - if it has sent a previous `commitment_signed` message: - MUST handle the case where the corresponding commitment transaction is - broadcast at any time by the other side, + broadcast at any time by the other side, - Note: this is particularly important if the node does not simply - retransmit the exact `update_` messages as previously sent. + retransmit the exact `update_` messages as previously sent. - upon reconnection: - if it has sent a previous `shutdown`: - MUST retransmit `shutdown`. From 1a0d59246e47ae9c08cbda40fe328c2421094629 Mon Sep 17 00:00:00 2001 From: t-bast Date: Wed, 11 Jan 2023 09:55:41 +0100 Subject: [PATCH 2/3] Merge last section in previous ones It's hard to follow when requirements are scattered in too many sections. --- 02-peer-protocol.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 18e2f0d33..27aeb10ac 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1403,6 +1403,12 @@ A node: - Note: a node MAY have already used the `payment_preimage` value from the `update_fulfill_htlc`, so the effects of `update_fulfill_htlc` are not completely reversed. + - MUST NOT assume that previously-transmitted messages were lost. + - if it has sent a previous `commitment_signed` message: + - MUST handle the case where the corresponding commitment transaction is + broadcast at any time by the other side. + - Note: this is particularly important if the node does not simply + retransmit the exact `update_` messages as previously sent. - upon reconnection: - if a channel is in an error state: - SHOULD retransmit the error packet and ignore any other packets for @@ -1438,6 +1444,8 @@ A node: a different `short_channel_id` `alias` field. - upon reconnection: - MUST ignore any redundant `channel_ready` it receives. + - if it has sent a previous `shutdown`: + - MUST retransmit `shutdown`. - if `next_commitment_number` is equal to the commitment number of the last `commitment_signed` message the receiving node has sent: - MUST reuse the same commitment number for its next `commitment_signed`. @@ -1487,17 +1495,6 @@ A node: do not match the expected values): - SHOULD send an `error` and fail the channel. -A node: - - MUST NOT assume that previously-transmitted messages were lost, - - if it has sent a previous `commitment_signed` message: - - MUST handle the case where the corresponding commitment transaction is - broadcast at any time by the other side, - - Note: this is particularly important if the node does not simply - retransmit the exact `update_` messages as previously sent. - - upon reconnection: - - if it has sent a previous `shutdown`: - - MUST retransmit `shutdown`. - ### Rationale The requirements above ensure that the opening phase is nearly From e46fd42f641ae19264785f0190590a2ef58d7a38 Mon Sep 17 00:00:00 2001 From: t-bast Date: Wed, 11 Jan 2023 11:31:53 +0100 Subject: [PATCH 3/3] Rework `channel_reestablish` error cases Rework the `channel_reestablish` receiver requirements: we first handle all error cases, then specify what should be retransmitted. --- 02-peer-protocol.md | 96 +++++++++++++++++++++------------------------ 1 file changed, 45 insertions(+), 51 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 27aeb10ac..5933c51d2 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1435,65 +1435,59 @@ The sending node: - otherwise: - MUST set `your_last_per_commitment_secret` to the last `per_commitment_secret` it received -A node: - - if `next_commitment_number` is 1 in both the `channel_reestablish` it - sent and received: - - MUST retransmit `channel_ready`. +The receiving node: + - if `next_revocation_number` is greater than the commitment number of the + last `commitment_signed` message the receiving node has sent: + - if `your_last_per_commitment_secret` is correct for that + `next_revocation_number` minus 1: + - MUST NOT broadcast its commitment transaction. + - 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. + - Note: the sending node proved that the receiving node has lost data. + - otherwise (`your_last_per_commitment_secret` is incorrect): + - 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. + - Note: the receiving node may or may not have lost data, but it + cannot be sure based on the data provided by the sending node. + - if the commitment number of the last `commitment_signed` message the + receiving node has sent is greater than `next_revocation_number` plus 1: + - MUST NOT broadcast its commitment transaction. + - SHOULD wait for the sending node to send an `error` or reconnect. + - Note: the sending node seems to have lost data. + - if `next_commitment_number` is greater than the commitment number of the + last `commitment_signed` message the receiving node has sent plus 1: + - 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. + - Note: the receiving node may or may not have lost data. + - if `next_commitment_number` is smaller than the commitment number of the + last `commitment_signed` message the receiving node has sent: + - MUST NOT broadcast its commitment transaction. + - SHOULD wait for the sending node to send an `error` or reconnect. + - Note: the sending node seems to have lost data. - otherwise: - - MUST NOT retransmit `channel_ready`, but MAY send `channel_ready` with - a different `short_channel_id` `alias` field. - - upon reconnection: + - if `next_commitment_number` is 1 in both the `channel_reestablish` it + sent and received: + - MUST retransmit `channel_ready`. + - otherwise: + - MUST NOT retransmit `channel_ready`, but MAY send `channel_ready` with + a different `short_channel_id` `alias` field. - MUST ignore any redundant `channel_ready` it receives. - if it has sent a previous `shutdown`: - MUST retransmit `shutdown`. - - if `next_commitment_number` is equal to the commitment number of - the last `commitment_signed` message the receiving node has sent: - - MUST reuse the same commitment number for its next `commitment_signed`. - - otherwise: - - if `next_commitment_number` is not 1 greater than the commitment number - of the last `commitment_signed` message the receiving - node has sent: - - SHOULD send an `error` and fail the channel. - - if it has not sent `commitment_signed`, AND `next_commitment_number` - is not equal to 1: - - SHOULD send an `error` and fail the channel. - - if `next_revocation_number` is equal to the commitment number of - the last `revoke_and_ack` the receiving node sent, AND the receiving node - hasn't already received a `closing_signed`: - - MUST re-send the `revoke_and_ack`. + - if `next_commitment_number` is equal to the commitment number of the + last `commitment_signed` message the receiving node has sent: + - MUST reuse the same commitment number for its next `commitment_signed`. + - if `next_revocation_number` is equal to the commitment number of the + last `revoke_and_ack` the receiving node sent, AND the receiving node + hasn't already received a `closing_signed`: + - MUST re-send the `revoke_and_ack`. - if it has previously sent a `commitment_signed` that needs to be retransmitted: - MUST retransmit `revoke_and_ack` and `commitment_signed` in the same relative order as initially transmitted. - - otherwise: - - if `next_revocation_number` is not equal to 1 greater than the - commitment number of the last `revoke_and_ack` the receiving node has sent: - - SHOULD send an `error` and fail the channel. - - if it has not sent `revoke_and_ack`, AND `next_revocation_number` - is not equal to 0: - - SHOULD send an `error` and fail the channel. - - A receiving node: - - if `option_static_remotekey` applies to the commitment transaction: - - if `next_revocation_number` is greater than expected above, AND - `your_last_per_commitment_secret` is correct for that - `next_revocation_number` minus 1: - - MUST NOT broadcast its commitment transaction. - - 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. - - otherwise, if it supports `option_data_loss_protect`: - - if `next_revocation_number` is greater than expected above, AND - `your_last_per_commitment_secret` is correct for that - `next_revocation_number` minus 1: - - MUST NOT broadcast its commitment transaction. - - 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` - do not match the expected values): - - SHOULD send an `error` and fail the channel. ### Rationale