Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

require quiescence sessions to be single-use #15

Closed
wants to merge 4 commits into from
Closed

require quiescence sessions to be single-use #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9fabdce
BOLT 2: quiescence protocol.
rustyrussell Sep 30, 2021
9832e17
BOLT #2: Set an initiator in quiescence.
rustyrussell Sep 30, 2021
a68d7b0
option_quiesce: feature to support stfu method.
rustyrussell Sep 30, 2021
97cc931
require quiescence sessions to be single-use
ProofOfKeags May 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .aspell.en.pws
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -387,3 +387,6 @@ CHECKSIGVERIFY
IFDUP
sats
anysegwit
quiesce
quiescing
SomeThing
66 changes: 66 additions & 0 deletions 02-peer-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -492,6 +493,71 @@ 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`]
* [`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.

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
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.

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
Expand Down
2 changes: 2 additions & 0 deletions 09-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down