BOLT 2: quiescence protocol.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> Header from folded patch 'bolt_2__set_an_initiator_in_quiescence.patch': 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 <rusty@rustcorp.com.au> Header from folded patch 'option_quiesce__feature_to_support_stfu_method.patch': 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 <rusty@rustcorp.com.au>
lightning · Jun 17, 2024 · 5dd9d9c · 5dd9d9c
1 parent 57ce4b1
commit 5dd9d9c
Show file tree

Hide file tree

Showing 3 changed files with 58 additions and 0 deletions.
diff --git a/.aspell.en.pws b/.aspell.en.pws
@@ -406,6 +406,9 @@ CHECKSIGVERIFY
 IFDUP
 sats
 anysegwit
+quiesce
+quiescing
+SomeThing
 onionmsg
 griefing
 unspendable

diff --git a/02-peer-protocol.md b/02-peer-protocol.md
@@ -32,6 +32,7 @@ operation, and closing.
       * [The `commitment_signed` Message](#the-commitment_signed-message)
       * [Sharing funding signatures: `tx_signatures`](#sharing-funding-signatures-tx_signatures)
       * [Fee bumping: `tx_init_rbf` and `tx_ack_rbf`](#fee-bumping-tx_init_rbf-and-tx_ack_rbf)
+    * [Channel Quiescence](#channel-quiescence)
     * [Channel Close](#channel-close)
       * [Closing Initiation: `shutdown`](#closing-initiation-shutdown)
       * [Closing Negotiation: `closing_signed`](#closing-negotiation-closing_signed)
@@ -1428,6 +1429,58 @@ a large feerate change, instead sets their `sats` to zero, and decline to
 participate further in the channel funding: by not contributing, they
 may obtain incoming liquidity at no cost.
 
+## 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`]
+    * [`u8`:`initiator`]
+
+### 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.
+  - 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`.
+
+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.  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
 
 Nodes can negotiate a mutual close of the connection, which unlike a

diff --git a/09-features.md b/09-features.md
@@ -45,6 +45,7 @@ The Context column decodes as follows:
 | 24/25 | `option_route_blinding`           | Node supports blinded paths                               | IN9      |                           | [BOLT #4](bolt04-route-blinding)                                      |
 | 26/27 | `option_shutdown_anysegwit`       | Future segwit versions allowed in `shutdown`              | IN       |                           | [BOLT #2][bolt02-shutdown]                                            |
 | 28/29 | `option_dual_fund`                | Use v2 of channel open, enables dual funding              | IN       |                           | [BOLT #2](02-peer-protocol.md)                                        |
+| 34/35 | `option_quiesce`             | Support for `stfu` message                                     | IN       |                            | [BOLT #2][bolt02-quiescence]                                         |
 | 38/39 | `option_onion_messages`           | Can forward onion messages                                | IN       |                           | [BOLT #7](04-onion-routing.md#onion-messages)                         |
 | 44/45 | `option_channel_type`             | Node supports the `channel_type` field in open/accept     | IN       |                           | [BOLT #2](02-peer-protocol.md#the-open_channel-message)               |
 | 46/47 | `option_scid_alias`               | Supply channel aliases for routing                        | IN       |                           | [BOLT #2][bolt02-channel-ready]                                       |
@@ -97,6 +98,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
 [bolt02-channel-ready]: 02-peer-protocol.md#the-channel_ready-message
 [bolt04]: 04-onion-routing.md
 [bolt07-sync]: 07-routing-gossip.md#initial-sync