From 836ee95ac732357ee70c1de7f442331821573385 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Wed, 30 Aug 2023 11:34:34 +0930 Subject: [PATCH 1/3] BOLT 2: upgrade protocol on reestablish. This is the simplest upgrade mechanism I could come up with. It's ready for option_anchors_zero_fee_htlc_tx, too. Signed-off-by: Rusty Russell Header from folded patch 'spell-out-upgrades.patch': upgrade: spell out upgrade possibilities. This uses explicit "channel types", which are now merged into master. Also spell out the potential issues with back-to-back upgrades, and workarounds if you were to even have this issue. Signed-off-by: Rusty Russell Header from folded patch 'remove-channel-subtype.patch': BOLT 2: remove channel_type subtype, only allow one upgrade. We also define channel type elsewhere, so we can remove the now-outdated one. And clarify the example. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 92 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index b7ed62d40..5dc71a5a2 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -25,6 +25,7 @@ operation, and closing. * [Completing the Transition to the Updated State: `revoke_and_ack`](#completing-the-transition-to-the-updated-state-revoke_and_ack) * [Updating Fees: `update_fee`](#updating-fees-update_fee) * [Message Retransmission: `channel_reestablish` message](#message-retransmission) + * [Upgrading Channels](#upgrading-channels) * [Authors](#authors) # Channel @@ -1464,6 +1465,22 @@ messages are), they are independent of requirements here. * [`u64`:`next_revocation_number`] * [`32*byte`:`your_last_per_commitment_secret`] * [`point`:`my_current_per_commitment_point`] + * [`channel_reestablish_tlvs`:`tlvs`] + +1. `tlv_stream`: `channel_reestablish_tlvs` +2. types: + 1. type: 1 (`next_to_send`) + 2. data: + * [`tu64`:`commitment_number`] + 1. type: 3 (`desired_channel_type`) + 2. data: + * [`...*byte`:`type`] + 1. type: 5 (`current_channel_type`) + 2. data: + * [`...*byte`:`type`] + 1. type: 7 (`upgradable_channel_type`) + 2. data: + * [`...*byte`:`type`] `next_commitment_number`: A commitment number is a 48-bit incrementing counter for each commitment transaction; counters @@ -1471,6 +1488,9 @@ are independent for each peer in the channel and start at 0. They're only explicitly relayed to the other node in the case of re-establishment, otherwise they are implicit. +See [Upgrading Channels](#upgrading-channels) for the requirements +of some of the optional fields. + ### Requirements A funding node: @@ -1671,6 +1691,78 @@ fall-behind detection. An implementation can offer both, however, and fall back to the `option_data_loss_protect` behavior if `option_static_remotekey` is not negotiated. +### Upgrading Channels + +Upgrading channels (e.g. enabling `option_static_remotekey` for a +channel where it was not negotiated originally) is possible at +reconnection time if both implementations support it. + +For simplicity, upgrades are proposed by the original initiator of the +channel, and can only occur on channels with no pending updates and no +retransmissions on reconnection. This can be achieved explicitly +using the [quiescence protocol](#channel-quiescence). + +In case of disconnection where one peer doesn't receive +`channel_reestablish` it's possible that one peer will consider the +channel upgraded and the other not. But this will eventually be +resolved: the channel cannot progress until both sides have received +`channel_reestablish` anyway. + +#### Requirements + +A node sending `channel_reestablish`, if it supports upgrading channels: + - MUST set `next_to_send` the commitment number of the next `commitment_signed` it expects to send. + - if it initiated the channel: + - MUST set `desired_channel_type` to the defined channel type it wants for the channel. + - otherwise: + - MUST set `current_channel_type` to the current channel type of the channel. + - If it sets `upgradable_channel_type`: + - MUST set it to a defined channel type it could change to. + +A node receiving `channel_reestablish`: + - if it has to retransmit `commitment_signed` or `revoke_and_ack`: + - MUST consider the channel type change failed. + - if `next_to_send` is missing, or not equal to the `next_commitment_number` it sent: + - MUST consider the channel type change failed. + - if updates are pending on either sides' commitment transaction: + - MUST consider the channel type change failed. + - otherwise: + - if `desired_channel_type` matches `current_channel_type` or `upgradable_channel_type`: + - MUST consider the channel type to be `desired_channel_type`. + - otherwise: + - MUST consider the channel type change failed. + - if there is a `current_channel_type` field: + - MUST consider the channel type to be `current_channel_type`. + +#### Rationale + +The new `next_to_send` counter is needed to indicate that the peer +sent a new set of updates and `commitment_signed` which we didn't see +before disconnection (i.e. retransmissions are incoming). Existing logic +already tells us if we need to send retransmissions. + +If reconnection is aborted, there are four possibilities: both side +receive the `channel_reestablish` and are upgraded, neither side +receives the `channel_reestablish` and neither are upgraded, and the +two cases where one side is upgraded and the other is not. Note that +this is fine as long as it is resolved before any channel operations +are attempted (all of which require successful exchange of +`channel_reestablish` messages). + +On reconnect, if only the initiator is upgraded, it will reflect this +upgrade in the next `desired_channel_type`, causing the non-initiator to +upgrade. If only the non-initiator is upgraded, it will be reflected +in `current_channel_type` and the initiator will consider itself upgraded. + +There can be desynchronization across multiple upgrades. Both A and B nodes +start on channel_type T1, A sets `desired_channel_type` T2, receives +`channel_reestablish` from B which has `upgradable_channel_type` T2, but B +doesn't receive `channel_reestablish`. On reconnect, A tries +to upgrade again, setting `desired_channel_type` to T3, which is not equal +to B's `upgradable_channel_type` so fails. This is why, on such a failed upgrade, the +initiator considers the `current_channel_type` given by the non-initiator to +be canonical. + # Authors [ FIXME: Insert Author List ] From 900be99b9d1b2ab9e550d83e9d7fc498740b11f3 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Wed, 30 Aug 2023 11:45:12 +0930 Subject: [PATCH 2/3] features: add explicit option_upgradable. This makes it clear who supports it. Also point out that it can be used to enable anchors, and remove link to quiescence protocol, since this is no longer dependent. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 8 ++++---- 09-features.md | 2 ++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 5dc71a5a2..d7defb4f1 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1693,14 +1693,14 @@ fall back to the `option_data_loss_protect` behavior if ### Upgrading Channels -Upgrading channels (e.g. enabling `option_static_remotekey` for a +Upgrading channels (e.g. enabling `option_static_remotekey` or `option_anchors` for a channel where it was not negotiated originally) is possible at reconnection time if both implementations support it. For simplicity, upgrades are proposed by the original initiator of the channel, and can only occur on channels with no pending updates and no retransmissions on reconnection. This can be achieved explicitly -using the [quiescence protocol](#channel-quiescence). +using the quiescence protocol, when implemented. In case of disconnection where one peer doesn't receive `channel_reestablish` it's possible that one peer will consider the @@ -1710,7 +1710,7 @@ resolved: the channel cannot progress until both sides have received #### Requirements -A node sending `channel_reestablish`, if it supports upgrading channels: +A node sending `channel_reestablish`, if `option_upgradable` is negotiated: - MUST set `next_to_send` the commitment number of the next `commitment_signed` it expects to send. - if it initiated the channel: - MUST set `desired_channel_type` to the defined channel type it wants for the channel. @@ -1719,7 +1719,7 @@ A node sending `channel_reestablish`, if it supports upgrading channels: - If it sets `upgradable_channel_type`: - MUST set it to a defined channel type it could change to. -A node receiving `channel_reestablish`: +A node receiving `channel_reestablish`, if `option_upgradable` is negotiated: - if it has to retransmit `commitment_signed` or `revoke_and_ack`: - MUST consider the channel type change failed. - if `next_to_send` is missing, or not equal to the `next_commitment_number` it sent: diff --git a/09-features.md b/09-features.md index 730e6cd72..060002bf0 100644 --- a/09-features.md +++ b/09-features.md @@ -49,6 +49,7 @@ The Context column decodes as follows: | 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2][bolt02-channel-ready] | | 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields) | | 50/51 | `option_zeroconf` | Understands zeroconf channel types | IN | `option_scid_alias` | [BOLT #2][bolt02-channel-ready] | +| 58/59 | `option_upgradable` | Understands upgrade protocol on reconnect | IN | | [BOLT #2][bolt02-upgrading-channels] | ## Definitions @@ -101,6 +102,7 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li [bolt02-retransmit]: 02-peer-protocol.md#message-retransmission [bolt02-open]: 02-peer-protocol.md#the-open_channel-message +[bolt02-upgrading-channels]: 02-peer-protocol.md#upgrading-channels [bolt03-htlc-tx]: 03-transactions.md#htlc-timeout-and-htlc-success-transactions [bolt02-shutdown]: 02-peer-protocol.md#closing-initiation-shutdown [bolt02-channel-ready]: 02-peer-protocol.md#the-channel_ready-message From 084402f336cc9b200eb4c236a57f27e582f93d60 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Wed, 30 Aug 2023 11:45:27 +0930 Subject: [PATCH 3/3] BOLT 1: define what `offered` and `negotiated` mean. i.e. it was present in the init feature bits. We use this in several places, but assume everyone knows what it means. Signed-off-by: Rusty Russell --- 01-messaging.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/01-messaging.md b/01-messaging.md index bcd11d999..cfdfe4e58 100644 --- a/01-messaging.md +++ b/01-messaging.md @@ -255,6 +255,8 @@ Once authentication is complete, the first message reveals the features supporte [BOLT #9](09-features.md) specifies lists of features. Each feature is generally represented by 2 bits. The least-significant bit is numbered 0, which is _even_, and the next most significant bit is numbered 1, which is _odd_. For historical reasons, features are divided into global and local feature bitmasks. +We refer to a feature as *offered* if a peer set it in the `init` message for the current connection (as either even or odd), and *negotiated* if both peers offered it. + The `features` field MUST be padded to bytes with 0s. 1. type: 16 (`init`)