diff --git a/.aspell.en.pws b/.aspell.en.pws index c9e3a0206..99b58b6f8 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -386,3 +386,7 @@ csv CHECKSIGVERIFY IFDUP sats +quiesce +quiescing +SomeThing +commitsigs diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 974e51e9a..fff91b954 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) @@ -445,6 +446,177 @@ 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` 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. + +## Splicing + +Splicing is the term given for replacing the funding transaction with +a new one. For simplicity, splicing takes place once a channel is +[quiescent](#channel-quiescence). + +Operation returns to normal once negotiation is done (while waiting +for the splice transaction(s) to confirm). + +The splice is finally terminated when both sides send +`splice_complete` to indicate that one of the splice transactions +reached acceptable depth. + +### The `splice` Message + +1. type: 74 (`splice`) +2. data: + * [`chain_hash`:`chain_hash`] + * [`channel_id`:`channel_id`] + * [`u32`:`funding_feerate_perkw`] + * [`point`:`funding_pubkey`] + +1. type: 76 (`splice_ack`) +2. data: + * [`chain_hash`:`chain_hash`] + * [`channel_id`:`channel_id`] + * [`point`:`funding_pubkey`] + +#### Requirements + +The sender of `splice`: +- MUST have successfully initiated quiescence. +- MUST NOT send `splice` before sending and receiving `funding_locked`. +- MUST NOT send `splice` while a splice is being negotiated. +- If any splice is in progress: + - MUST NOT send a splice message with `funding_feerate_perkw` which is less than 1.25 the previous `funding_feerate_perkw` (rounded down). + +The receiver of `splice`: +- SHOULD fail the connection if there is an ongoing splice, and the `funding_feerate_perkw` is not at least 1.25 the previous `funding_feerate_perkw` (rounded down). +- MUST respond with `splice_ack` containing its own `funding_pubkey`. +- MUST begin splice negotiation. + +The receiver of `splice_ack`: +- MUST begin splice negotiation. + + +#### Rationale + +There is no harm in agreeing to a splice with a high feerate +(presumably the recipient will not contribute to the splice which they +consider to be overpaying). + +## Splice Negotiation + +The splice negotiation is very similar to the `init_rbf` negotiation: +both sides alternate sending `tx_add_input` and `tx_add_output` until +they both send consecutive `tx_complete`. + +### Requirements + +(Note that many of these messages have their own, additional +requirements detailed elsewhere). + +The initiator: +- MUST `tx_add_input` an input which spends the current funding transaction output. +- MUST `tx_add_output` a zero-value output which pays to the two funding keys using the higher of the two `generation` fields. +- MUST pay for the common fields. + +Upon receipt of consecutive `tx_complete`s, each node: +- MUST fail negotiation if there is not exactly one input spending the current funding transaction. +- MUST fail negotiation if there is not exactly one output with zero value paying to the two funding keys (a.k.a. the new channel funding output) +- MUST calculate the channel capacity for each side: + - Start with the previous balance + - Add that side's new inputs (excluding the one spending the current funding transaction) + - Subtracting each sides new outputs (except the zero-value one paying to the funding keys) + - Subtract the total fee that side is paying for the splice transaction. +- MUST replace the zero-value funding output amount with the total channel capacity. +- MUST calculate the channel balance for each side: + - Subtract any outstanding HTLCs offered by that side. +- if either side has added an output other than the new channel funding output: + - MUST fail the negotiation if the balance for that side is less than 1% of the total channel capacity. +- SHOULD NOT fail if the splice transaction is nonstandard. +- MUST increment the commitment number and send `commitment_signed`, including the signatures for the splice transaction. + +- Upon receipt of `revoke_and_ack` for the previous commitment: + - MUST send `tx_signatures` for the splice transaction. + +- Upon receipt of `tx_signatures` for the splice transaction: + - MUST consider splice negotiation complete. + - MUST consider the connection no longer quiescent. + +On reconnection: +- MUST retransmit the last splice `tx_signatures` (if any). +- MUST ignore any redundant `tx_signatures` it receives. + +### Rationale + +If a side does not meet the reserve requirements, that's OK: but if +they take funds out of the channel, they must ensure that they do meet +them. If your peer adds a massive amount to the channel, then you +only have to add more reserve if you want to contribute to the splice +(and you can use `tx_remove_output` and/or `tx_remove_input` part-way +through if this happens). + +## Splice Completion + +Each node: +- if any splice transaction reaches depth 6: + - MUST send `splice_locked`. + +Once a node has received and sent `splice_locked`: + - MUST consider the successful splice to be the new funding + transaction for all future `commitment_signed` and splice operations. + - MUST discard the previous funding transaction and other splice operations. + - MUST send a new `commitment_signed` (with no `splice_commitsigs`). + +On reconnection: + - MUST retransmit the last `splice_locked` if the peer did not + acknowledge the `commitment_signed`. + ## Channel Close Nodes can negotiate a mutual close of the connection, which unlike a @@ -488,10 +660,13 @@ A sending node: - MAY send a `shutdown` before a `funding_locked`, i.e. before the funding transaction has reached `minimum_depth`. - if there are updates pending on the receiving node's commitment transaction: - MUST NOT send a `shutdown`. + - if there is an ongoing splice: + - MUST NOT send a `shutdown`. - MUST NOT send an `update_add_htlc` after a `shutdown`. - if no HTLCs remain in either commitment transaction: - MUST NOT send any `update` message after a `shutdown`. - SHOULD fail to route any HTLC added after it has sent `shutdown`. + - MUST NOT initiate a new splice if none are already in progress after a `shutdown`. - if it sent a non-zero-length `shutdown_scriptpubkey` in `open_channel` or `accept_channel`: - MUST send the same value in `scriptpubkey`. - MUST set `scriptpubkey` in one of the following forms: @@ -509,8 +684,9 @@ A receiving node: - SHOULD fail the connection. - if it hasn't sent a `funding_locked` yet: - MAY reply to a `shutdown` message with a `shutdown` - - once there are no outstanding updates on the peer, UNLESS it has already sent a `shutdown`: + - once there are no outstanding updates on the peer and no ongoing splice, UNLESS it has already sent a `shutdown`: - MUST reply to a `shutdown` message with a `shutdown` + - MUST NOT initiate a new splice if none are already in progress. - if both nodes advertised the `option_upfront_shutdown_script` feature, and the receiving node received a non-zero-length `shutdown_scriptpubkey` in `open_channel` or `accept_channel`, and that `shutdown_scriptpubkey` is not equal to `scriptpubkey`: - MUST fail the connection. @@ -539,6 +715,12 @@ of the receiving node to change the `scriptpubkey`. The `shutdown` response requirement implies that the node sends `commitment_signed` to commit any outstanding changes before replying; however, it could theoretically reconnect instead, which would simply erase all outstanding uncommitted changes. +`shutdown` requires that there be no splice in progress, but if there +is already a splice in progress, it might require another splice to +"unstick" it (if the first splice was invalid, double-spent, or simply +had too low a fee), so in this case initiating another splice is legal +even after sending a shutdown. + ### Closing Negotiation: `closing_signed` Once shutdown is complete and the channel is empty of HTLCs, the final @@ -834,7 +1016,7 @@ A sending node: between implementations. - if it is _not responsible_ for paying the Bitcoin fee: - SHOULD NOT offer `amount_msat` if, once the remote node adds that HTLC to - its commitment transaction, it cannot pay the fee for the updated local or + any of its commitment transactions, it cannot pay the fee for the updated local or remote transaction at the current `feerate_per_kw` while maintaining its channel reserve. - MUST offer `amount_msat` greater than 0. @@ -911,6 +1093,9 @@ maintaining its channel reserve (because of the increased weight of the commitment transaction), resulting in a degraded channel. See [#728](https://github.com/lightningnetwork/lightning-rfc/issues/728) for more details. +If splicing is supported, there can be more than one commitment transaction +at a time: proposed changes must be valid for all of them. + ### Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc`, and `update_fail_malformed_htlc` For simplicity, a node can only remove HTLCs added by the other node. @@ -1006,12 +1191,26 @@ sign the resulting transaction (as defined in [BOLT #3](03-transactions.md)), an * [`signature`:`signature`] * [`u16`:`num_htlcs`] * [`num_htlcs*signature`:`htlc_signature`] + * [`commitment_signed_tlvs`:`tlvs`] + +1. `tlv_stream`: `commitment_signed_tlvs` +2. types: + 1. type: 0 (`splice_commitsigs`) + 2. data: + * [`...*commitsigs`:`sigs`] + +1. subtype: `commitsigs` +2. data: + * [`signature`:`commit_signature`] + * [`u16`:`num_htlcs`] + * [`num_htlcs*signature`:`htlc_signature`] + #### Requirements A sending node: - MUST NOT send a `commitment_signed` message that does not include any -updates. +updates, or add or remove splices. - MAY send a `commitment_signed` message that only alters the fee. - MAY send a `commitment_signed` message that doesn't @@ -1022,6 +1221,7 @@ fee changes). to the ordering of the commitment transaction (see [BOLT #3](03-transactions.md#transaction-input-and-output-ordering)). - if it has not recently received a message from the remote node: - SHOULD use `ping` and await the reply `pong` before sending `commitment_signed`. + - MUST send a `commitsigs` for each splice in progress, in increasing feerate order. A receiving node: - once all pending updates are applied: @@ -1032,6 +1232,10 @@ A receiving node: - MUST fail the channel. - if any `htlc_signature` is not valid for the corresponding HTLC transaction OR non-compliant with LOW-S-standard rule [LOWS](https://github.com/bitcoin/bitcoin/pull/6769): - MUST fail the channel. + - if there is not exactly one `commitsigs` for each splice in progress: + - MUST fail the channel. + - if `commit_signature`, `num_htlcs` or `htlc_signature` is not correct as specified above for each splice: + - MUST fail the channel. - MUST respond with a `revoke_and_ack` message. #### Rationale @@ -1051,6 +1255,11 @@ Note that the `htlc_signature` implicitly enforces the time-lock mechanism in th The `option_anchor_outputs` allows HTLC transactions to "bring their own fees" by attaching other inputs and outputs, hence the modified signature flags. +Splicing requires us to send and receive redundant signatures, as we +don't know which (if any) of the splice transactions will end up being +the new channel. Increasing feerate order is also the order in which +splices were negotiated (since each must increase the feerate). + ### Completing the Transition to the Updated State: `revoke_and_ack` Once the recipient of `commitment_signed` checks the signature and knows @@ -1119,6 +1328,8 @@ given in [BOLT #3](03-transactions.md#fee-calculation). The node _responsible_ for paying the Bitcoin fee: - SHOULD send `update_fee` to ensure the current fee rate is sufficient (by a significant margin) for timely processing of the commitment transaction. + - MUST NOT set `feerate_per_kw` in excess of what it can afford on any of the receiving node's + current commitment transactions. The node _not responsible_ for paying the Bitcoin fee: - MUST NOT send `update_fee`. @@ -1129,7 +1340,7 @@ A receiving node: - if the sender is not responsible for paying the Bitcoin fee: - MUST fail the channel. - if the sender cannot afford the new fee rate on the receiving node's - current commitment transaction: + current commitment transactions: - SHOULD fail the channel, - but MAY delay this check until the `update_fee` is committed. @@ -1155,6 +1366,9 @@ it's simplest to only allow it to set fee levels; however, as the same fee rate applies to HTLC transactions, the receiving node must also care about the reasonableness of the fee. +If splicing is supported, there can be more than one commitment transaction +at a time: proposed changes must be valid for all of them. + ## Message Retransmission Because communication transports are unreliable, and may need to be diff --git a/07-routing-gossip.md b/07-routing-gossip.md index b89c3d222..d54c38676 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -87,6 +87,8 @@ A node: - MUST send the `announcement_signatures` message. - MUST NOT send `announcement_signatures` messages until `funding_locked` has been sent and received AND the funding transaction has at least six confirmations. + - MUST send `announcement_signatures` message after `splice_locked` + has been sent and received. - otherwise: - MUST NOT send the `announcement_signatures` message. - upon reconnection (once the above timing requirements have been met): @@ -418,6 +420,7 @@ individual bits: | ------------- | ----------- | -------------------------------- | | 0 | `direction` | Direction this update refers to. | | 1 | `disable` | Disable the channel. | +| 2 | `splicing` | Temporarily ignore channel spend.| The `message_flags` bitfield is used to indicate the presence of optional fields in the `channel_update` message: @@ -485,6 +488,7 @@ The origin node: - MUST set `fee_proportional_millionths` to the amount (in millionths of a satoshi) it will charge per transferred satoshi. - SHOULD NOT create redundant `channel_update`s + - SHOULD set `splicing` in all `channel_update` once splicing has been negotiated for a channel. The receiving node: - if the `short_channel_id` does NOT match a previous `channel_announcement`, @@ -559,6 +563,11 @@ the channel when the peer reestablishes contact. Because gossip messages are batched and replace previous ones, the result may be a single seemingly-redundant update. +The simple `splicing` flag warns nodes that this channel will be +replaced; it tells them to give a grace period for the new channel to +appear (it can't be announced until it's 6 blocks deep) during which +it can use the old channel id. + ## Query Messages Negotiating the `gossip_queries` option via `init` enables a number @@ -966,7 +975,7 @@ The origin node: A node: - SHOULD monitor the funding transactions in the blockchain, to identify channels that are being closed. - - if the funding output of a channel is being spent: + - 12 blocks after the funding output of a channel being spent: - SHOULD be removed from the local network view AND be considered closed. - if the announced node no longer has any associated open channels: - MAY prune nodes added through `node_announcement` messages from their