From 9fabdce7ae3b769aac0f05f345c32ef354047f93 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Thu, 30 Sep 2021 14:37:49 +0930 Subject: [PATCH 1/4] BOLT 2: quiescence protocol. Signed-off-by: Rusty Russell --- .aspell.en.pws | 3 +++ 02-peer-protocol.md | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/.aspell.en.pws b/.aspell.en.pws index 2c0d09fdf..0e83fc885 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -387,3 +387,6 @@ CHECKSIGVERIFY IFDUP sats anysegwit +quiesce +quiescing +SomeThing diff --git a/02-peer-protocol.md b/02-peer-protocol.md index b869f02a4..ec1e1032b 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -13,6 +13,7 @@ operation, and closing. * [The `funding_created` Message](#the-funding_created-message) * [The `funding_signed` Message](#the-funding_signed-message) * [The `funding_locked` Message](#the-funding_locked-message) + * [Channel Quiescence](#channel-quiescence) * [Channel Close](#channel-close) * [Closing Initiation: `shutdown`](#closing-initiation-shutdown) * [Closing Negotiation: `closing_signed`](#closing-negotiation-closing_signed) @@ -492,6 +493,46 @@ to broadcast the commitment transaction to get his funds back and open a new channel. To avoid this, the funder should ensure the funding transaction confirms in the next 2016 blocks. +## Channel Quiescence + +Various fundamental changes, in particular protocol upgrades, are +easiest on channels where both commitment transactions match, and no +pending updates are in flight. We define a protocol to quiesce the +channel by indicating that "SomeThing Fundamental is Underway". + +### `stfu` + +1. type: 2 (`stfu`) +2. data: + * [`channel_id`:`channel_id`] + +### Requirements + +The sender of `stfu`: + - MUST NOT send `stfu` if any of the sender's htlc additions, htlc removals + or fee updates are pending for either peer. + - MUST NOT send `stfu` twice. + - MUST set `channel_id` to the id of the channel to quiesce. + - MUST now consider the channel to be quiescing. + - MUST NOT send an update message after `stfu`. + +The receiver of `stfu`: + - if it has sent `stfu` then: + - MUST now consider the channel to be quiescent + - otherwise: + - SHOULD NOT send any more update messages. + - MUST reply with `stfu` once it can do so. + +Upon disconnection: + - the channel is no longer considered quiescent. + +### Rationale + +The normal use would be to cease sending updates, then wait for all +the current updates to be acknowledged by both peers, then start +quiescence. If both sides send `stfu` simultaneously, the result is +exactly the same as if one had replied to the other. + ## Channel Close Nodes can negotiate a mutual close of the connection, which unlike a From 9832e176509b86c8e5a8a2c14167bdc6d752625a Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Thu, 30 Sep 2021 14:37:49 +0930 Subject: [PATCH 2/4] BOLT #2: Set an initiator in quiescence. This is especially useful for protocols such as splicing; for simplified commitment transactions, there is already an implied initiator at each point, so having the negotiation at splicing time would be redundant. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index ec1e1032b..57649d830 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -505,6 +505,7 @@ channel by indicating that "SomeThing Fundamental is Underway". 1. type: 2 (`stfu`) 2. data: * [`channel_id`:`channel_id`] + * [`u8`:`initiator`] ### Requirements @@ -512,6 +513,10 @@ The sender of `stfu`: - MUST NOT send `stfu` if any of the sender's htlc additions, htlc removals or fee updates are pending for either peer. - MUST NOT send `stfu` twice. + - if it is replying to an `stfu`: + - MUST set `initiator` to 0 + - otherwise: + - MUST set `initiator` to 1 - MUST set `channel_id` to the id of the channel to quiesce. - MUST now consider the channel to be quiescing. - MUST NOT send an update message after `stfu`. @@ -530,8 +535,14 @@ Upon disconnection: The normal use would be to cease sending updates, then wait for all the current updates to be acknowledged by both peers, then start -quiescence. If both sides send `stfu` simultaneously, the result is -exactly the same as if one had replied to the other. +quiescence. For some protocols, choosing the initiator matters, +so this flag is sent. + +If both sides send `stfu` simultaneously, they will both set +`initiator` to `1`, in which case the "initiator" is arbitrarily +considered to be the channel funder (the sender of `open_channel`). +The quiescence effect is exactly the same as if one had replied to the +other. ## Channel Close From a68d7b07cea0fb243f25e955cca6134cae5872cf Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Thu, 30 Sep 2021 14:46:19 +0930 Subject: [PATCH 3/4] option_quiesce: feature to support stfu method. In practice, sftu is useless unless you have something (e.g. channel_upgrade) which uses it, but adding a feature is best practice IMHO. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 1 + 09-features.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 57649d830..b1b33021a 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -510,6 +510,7 @@ channel by indicating that "SomeThing Fundamental is Underway". ### Requirements The sender of `stfu`: + - MUST NOT send `stfu` unless `option_quiesce` is negotiated. - MUST NOT send `stfu` if any of the sender's htlc additions, htlc removals or fee updates are pending for either peer. - MUST NOT send `stfu` twice. diff --git a/09-features.md b/09-features.md index 54cd2de6e..b205bea47 100644 --- a/09-features.md +++ b/09-features.md @@ -41,6 +41,7 @@ The Context column decodes as follows: | 20/21 | `option_anchor_outputs` | Anchor outputs | IN | `option_static_remotekey` | [BOLT #3](03-transactions.md) | | 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions | IN | | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]| | 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] | +| 34/35 | `option_quiesce` | Support for `stfu` message | IN | | [BOLT #2][bolt02-quiescence] | ## Definitions @@ -88,6 +89,7 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li [bolt02-open]: 02-peer-protocol.md#the-open_channel-message [bolt03-htlc-tx]: 03-transactions.md#htlc-timeout-and-htlc-success-transactions [bolt02-shutdown]: 02-peer-protocol.md#closing-initiation-shutdown +[bolt02-quiescence]: 02-peer-protocol.md#channel-quiescence [bolt04]: 04-onion-routing.md [bolt07-sync]: 07-routing-gossip.md#initial-sync [bolt07-query]: 07-routing-gossip.md#query-messages From 97cc9310050e6eb61a9c05e6d2919c999179a3cb Mon Sep 17 00:00:00 2001 From: Keagan McClelland Date: Mon, 20 May 2024 12:43:54 -0700 Subject: [PATCH 4/4] require quiescence sessions to be single-use --- 02-peer-protocol.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index b1b33021a..c4dbfa9fb 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -532,6 +532,11 @@ The receiver of `stfu`: Upon disconnection: - the channel is no longer considered quiescent. +Dependent Protocols: + - MUST specify all states that terminate quiescence. + - NOTE: this prevents batching executions of protocols that depend on + quiescence. + ### Rationale The normal use would be to cease sending updates, then wait for all @@ -545,6 +550,14 @@ considered to be the channel funder (the sender of `open_channel`). The quiescence effect is exactly the same as if one had replied to the other. +Dependent protocols have to specify termination conditions to prevent the need +for disconnection to resume channel traffic. An explicit resume message was +[considered but rejected](https://github.com/rustyrussell/lightning-rfc/pull/14) +since it introduces a number of edge cases that make bilateral consensus of +channel state significantly more complex to maintain. This introduces the +derivative property that it is impossible to batch multiple downstream protocols +in the same quiescence session. + ## Channel Close Nodes can negotiate a mutual close of the connection, which unlike a