diff --git a/.aspell.en.pws b/.aspell.en.pws index 6744cc297..a63e1aeeb 100644 --- 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 index 5d02ec288..44ad37e51 100644 --- 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 index fa306270e..5ffb0a42a 100644 --- 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