From 12343441b9d4024c339836e6e9f8e3bc3ef69ca3 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Sun, 9 May 2021 14:47:21 +0930 Subject: [PATCH 01/32] BOLT 2: quiescence protocol. Signed-off-by: Rusty Russell --- .aspell.en.pws | 3 +++ 02-peer-protocol.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/.aspell.en.pws b/.aspell.en.pws index 6744cc297..7f1df78df 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -425,3 +425,6 @@ ints replaceability disincentivize UTXOs +quiesce +quiescing +SomeThing diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 38e2b72ac..168eeca50 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -32,6 +32,8 @@ 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) + * [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) @@ -1437,6 +1439,46 @@ 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`] + +### 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 b12653646c9de905a9d8c7df7f626de0020a44ac Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 24 May 2021 14:23:39 +0930 Subject: [PATCH 02/32] 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 168eeca50..2f10e31fb 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1451,6 +1451,7 @@ channel by indicating that "SomeThing Fundamental is Underway". 1. type: 2 (`stfu`) 2. data: * [`channel_id`:`channel_id`] + * [`u8`:`initiator`] ### Requirements @@ -1458,6 +1459,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`. @@ -1476,8 +1481,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 80083b1a2768ea491285b7a8f1725eaa05efecb7 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 24 May 2021 14:51:28 +0930 Subject: [PATCH 03/32] splicing: use the generic negotiation mechanism to splice in/out of a channel. The initiator (in the case of simultaneity, the higher feepayer) pays for the input and output, and sets the feerate. We freeze the channel while this construction is going on: it should be quick. Signed-off-by: Rusty Russell Header from folded patch 'fixup3.patch': fixup! splicing: use the generic negotiation mechanism to splice in/out of a channel. - Remove 1 per minute restriction: 25% growth limits us a lot (@niftynei) - Nomenclature: initiator, splice transaction, channel funding output. - Weaken reserve check to only cover iff they extract funds. --- 02-peer-protocol.md | 108 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 2f10e31fb..b934f78f3 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1490,6 +1490,114 @@ 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, no other changes can be made while the new +transaction is being negotiated, but operation returns to normal once +negotiation is done (while waiting for the splice transaction(s) to +confirm). + +### The `splice` Message + +1. type: 74 (`splice`) +2. data: + * [`chain_hash`:`chain_hash`] + * [`channel_id`:`channel_id`] + * [`u32`:`funding_feerate_perkw`] + * [`u64`:`generation`] + * [`point`:`payment_basepoint`] + * [`point`:`first_per_commitment_point`] + * [`point`:`next_per_commitment_point`] + +#### Requirements + +The sender: +- MUST NOT send `splice` before sending and receiving `funding_locked`. +- MUST NOT send another splice message while a splice is being negotiated. +- MUST NOT send a splice message after sending uncommitted changes. +- If a 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). +- MUST NOT send other channel updates until splice negotiation has completed. + +The receiver: +- SHOULD fail the splice 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 a `splice` message of its own if it has not already. +- MUST NOT reply with `splice` until all commitment updates are resolved by bother peers. +- MAY set `funding_feerate_perkw` below the received value. +- MUST use the higher of the two `funding_feerate_perkw` as the feerate for + the splice. +- MUST NOT send other channel updates until splice negotiation has completed. + + +#### Rationale + +Both sides agree to a splice: 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). + +Any pending updates are flushed before sending, but the reply must +wait until all changes are resolved.. So in the case where the A +sends `splice` while B has just added an HTLC, then B will have to +send `commitment_signed`, then A will have to reply with +`revoke_and_ack` then `commitment_signed`, the B will have to also +reply with `revoke_and_ack` before it can finally reply with `splice`. + +## 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 is defined as the side which offered the higher +`funding_feerate_perkw`, or if both sides are equal, the lower +SEC1-encoded node_id. + +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. + +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). + ## Channel Close Nodes can negotiate a mutual close of the connection, which unlike a From 4513becf5037fd6b0e9d167d27046b4a368dd442 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 24 May 2021 14:51:28 +0930 Subject: [PATCH 04/32] Splicing: rewrite it to work on top of quiescence. This is much simpler. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 62 ++++++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 35 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index b934f78f3..0dbaf7e2b 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1493,10 +1493,11 @@ other. ## Splicing Splicing is the term given for replacing the funding transaction with -a new one. For simplicity, no other changes can be made while the new -transaction is being negotiated, but operation returns to normal once -negotiation is done (while waiting for the splice transaction(s) to -confirm). +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` Message @@ -1505,43 +1506,37 @@ confirm). * [`chain_hash`:`chain_hash`] * [`channel_id`:`channel_id`] * [`u32`:`funding_feerate_perkw`] - * [`u64`:`generation`] - * [`point`:`payment_basepoint`] - * [`point`:`first_per_commitment_point`] - * [`point`:`next_per_commitment_point`] + * [`point`:`funding_pubkey`] + +1. type: 76 (`splice_ack`) +2. data: + * [`chain_hash`:`chain_hash`] + * [`channel_id`:`channel_id`] + * [`point`:`funding_pubkey`] #### Requirements -The sender: +The sender of `splice`: +- MUST have successfully initiated quiescence. - MUST NOT send `splice` before sending and receiving `funding_locked`. -- MUST NOT send another splice message while a splice is being negotiated. -- MUST NOT send a splice message after sending uncommitted changes. -- If a splice is in progress: +- 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). -- MUST NOT send other channel updates until splice negotiation has completed. -The receiver: -- SHOULD fail the splice 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 a `splice` message of its own if it has not already. -- MUST NOT reply with `splice` until all commitment updates are resolved by bother peers. -- MAY set `funding_feerate_perkw` below the received value. -- MUST use the higher of the two `funding_feerate_perkw` as the feerate for - the splice. -- MUST NOT send other channel updates until splice negotiation has completed. +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 -Both sides agree to a splice: 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). +#### Rationale -Any pending updates are flushed before sending, but the reply must -wait until all changes are resolved.. So in the case where the A -sends `splice` while B has just added an HTLC, then B will have to -send `commitment_signed`, then A will have to reply with -`revoke_and_ack` then `commitment_signed`, the B will have to also -reply with `revoke_and_ack` before it can finally reply with `splice`. +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 @@ -1554,10 +1549,6 @@ they both send consecutive `tx_complete`. (Note that many of these messages have their own, additional requirements detailed elsewhere). -The initiator is defined as the side which offered the higher -`funding_feerate_perkw`, or if both sides are equal, the lower -SEC1-encoded node_id. - 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. @@ -1584,6 +1575,7 @@ Upon receipt of consecutive `tx_complete`s, each node: - 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). From 552306f2264984526492c399b481b6d333b86836 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 24 May 2021 14:51:28 +0930 Subject: [PATCH 05/32] commitment_signed: add tlvs for splice sigs. Signed-off-by: Rusty Russell --- .aspell.en.pws | 1 + 02-peer-protocol.md | 26 +++++++++++++++++++++++++- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/.aspell.en.pws b/.aspell.en.pws index 7f1df78df..d2ea11f8e 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -428,3 +428,4 @@ UTXOs quiesce quiescing SomeThing +commitsigs diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 0dbaf7e2b..9a5ee98fc 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -2284,12 +2284,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 @@ -2300,6 +2314,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: @@ -2313,6 +2328,10 @@ A receiving node: - 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 send a `warning` and close the connection, or send an `error` and 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 @@ -2336,6 +2355,11 @@ stating time-locks on HTLC outputs. The `option_anchors` 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 From a798ca24ad3f5e93f35cb96eb691a5a92360e92e Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 24 May 2021 14:51:28 +0930 Subject: [PATCH 06/32] splice_locked: terminate this splice once one reaches agreed depths. Signed-off-by: Rusty Russell Header from folded patch 'fixup2.patch': fixup! splice_locked: terminate this splice once one reaches agreed depths. Use 6; we need to start announcing then anyway, so keep it simple. --- 02-peer-protocol.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 9a5ee98fc..42225b03b 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1499,6 +1499,10 @@ a new one. For simplicity, splicing takes place once a channel is 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`) @@ -1590,6 +1594,22 @@ 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 From 7bdf9f094d155cca45153944f71560743dabe7b6 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 24 May 2021 14:51:28 +0930 Subject: [PATCH 07/32] gossip: add a bit to indicate "splicing". This was Matt Corallo's idea; a simple flag means you should keep using the channel as it's being replaced. Signed-off-by: Rusty Russell --- 07-routing-gossip.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/07-routing-gossip.md b/07-routing-gossip.md index 4b67a381e..ab4e93f87 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -436,6 +436,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 provide additional details about the message: @@ -498,6 +499,7 @@ The origin node: - SHOULD NOT create redundant `channel_update`s - If it creates a new `channel_update` with updated channel parameters: - SHOULD keep accepting the previous channel parameters for 10 minutes + - 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`, @@ -574,6 +576,11 @@ The `must_be_one` field in `message_flags` was previously used to indicate the presence of the `htlc_maximum_msat` field. This field must now always be present, so `must_be_one` is a constant value, and ignored by receivers. +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 @@ -984,6 +991,8 @@ 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: + - if a `channel_update` had `splicing` in the `channel_flags`: + - SHOULD delay 10 blocks considering the output 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 From dcefef654f6a06af79c76e208efa29e63a6db9a6 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 24 May 2021 14:51:28 +0930 Subject: [PATCH 08/32] gossip: make sure to send new announcement_signatures post-splice. Signed-off-by: Rusty Russell Header from folded patch 'fixup.patch': fixup! gossip: make sure to send new announcement_signatures post-splice. It's called `splice_locked` and it's always sent 6 blocks. --- 07-routing-gossip.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/07-routing-gossip.md b/07-routing-gossip.md index ab4e93f87..44648c134 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 `channel_ready` 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): From 5b2da1df81c9ddf122aace3790ab4c7324d8c2dc Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Mon, 24 May 2021 15:08:11 +0930 Subject: [PATCH 09/32] BOLT 2: note splice requirements in the checks for adding HTLCs and setting fees. Any changes must be valid for all possible commitment transactions. A minor change, but for implementations which quote the spec and check those quotes this will highlight the changes needed. Signed-off-by: Rusty Russell --- 02-peer-protocol.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 42225b03b..32db5b75d 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -2112,7 +2112,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. @@ -2190,6 +2190,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. @@ -2449,6 +2452,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`. @@ -2471,7 +2476,7 @@ A receiving node: - MUST send a `warning` and close the connection, or send an `error` and fail the channel. - if the sender cannot afford the new fee rate on the receiving node's - current commitment transaction: + current commitment transactions: - SHOULD send a `warning` and close the connection, or send an `error` and fail the channel. - but MAY delay this check until the `update_fee` is committed. @@ -2509,6 +2514,9 @@ be trimmed at the updated feerate, this could overflow the configured `max_dust_htlc_exposure_msat`. Whether to close the channel preemptively or not is left as a matter of node policy. +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 From bb82cc10394e580d1926eb8462a64060796d58f8 Mon Sep 17 00:00:00 2001 From: Rusty Russell Date: Fri, 4 Jun 2021 15:06:22 +0930 Subject: [PATCH 10/32] BOLT 2: can't complete shutdown while splicing --- 02-peer-protocol.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 32db5b75d..061c814fa 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1654,11 +1654,14 @@ A sending node: - if there are updates pending on the receiving node's commitment transaction: - MUST NOT send a `shutdown`. - MUST NOT send multiple `shutdown` messages. + - 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 (including dust HTLCs) and neither side has a pending `revoke_and_ack` to send: - MUST NOT send any `update` message after that point. - 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: @@ -1676,8 +1679,9 @@ A receiving node: - SHOULD send a `warning`. - if it hasn't sent a `channel_ready` 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`: - MAY send a `warning`. - MUST fail the connection. @@ -1712,6 +1716,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, the channel is empty of HTLCs, there are no commitments From 787d789a97ba08bc84c68bf56ef2792e6e0659ad Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Fri, 21 Oct 2022 16:30:34 -0400 Subject: [PATCH 11/32] BOLT 2: Adjust commitment_signed req for splicing. `commitment_signed` is valid when a splice is candidate added. --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 061c814fa..4e09910ee 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -2336,7 +2336,7 @@ sign the resulting transaction (as defined in [BOLT #3](03-transactions.md)), an A sending node: - MUST NOT send a `commitment_signed` message that does not include any -updates, or add or remove splices. +updates or added splices. - MAY send a `commitment_signed` message that only alters the fee. - MAY send a `commitment_signed` message that doesn't From 1ea3aae0b1fcdb39ac2402fa9df5cc91987e37ba Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Fri, 21 Oct 2022 16:53:32 -0400 Subject: [PATCH 12/32] Bolt 2: Cleaning up splice related verbage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * the commitment tx includes the splice transaction commitment signatures (not the splice transaction’s own signatures). * “in progress” -> “awaiting confirmation” to add clarity. * No longer need a 10 block delay for splice closes since all close events are delayed 12 blocks. --- 02-peer-protocol.md | 4 ++-- 07-routing-gossip.md | 4 +--- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 4e09910ee..a684233f8 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1572,7 +1572,7 @@ Upon receipt of consecutive `tx_complete`s, each node: - 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. +- MUST increment the commitment number and send `commitment_signed`, including the commitment signatures for the splice transaction(s). - Upon receipt of `revoke_and_ack` for the previous commitment: - MUST send `tx_signatures` for the splice transaction. @@ -2347,7 +2347,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. + - MUST send a `commitsigs` for each splice awaiting confirmation, in increasing feerate order. A receiving node: - once all pending updates are applied: diff --git a/07-routing-gossip.md b/07-routing-gossip.md index 44648c134..e4cbee48a 100644 --- a/07-routing-gossip.md +++ b/07-routing-gossip.md @@ -992,9 +992,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: - - if a `channel_update` had `splicing` in the `channel_flags`: - - SHOULD delay 10 blocks considering the output spent. + - if the funding output of a channel is spent and received 12 block confirmations: - 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 From ea0beed1b8eac355021ec40665e4495d263fc411 Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Fri, 21 Oct 2022 17:06:32 -0400 Subject: [PATCH 13/32] Bolt 2: splicing and shutdown interactions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adding @niftynei’s shutdown updates. Her notes: `shutdown` MAY be sent while the splice is pending confirmation. New splice negotiations MAY BE initiated while the channel is in `shutdown`. The `shutdown` phase MUST NOT be considered concluded until all htlcs are resolved and the channel has exited the pending splice phase (`splice_locked` has been exchanged). --- 02-peer-protocol.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index a684233f8..7a6146d10 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1716,11 +1716,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. +`shutdown` MAY be sent while the splice is pending confirmation. New splice +negotiations MAY BE initiated while the channel is in `shutdown`. + +The `shutdown` phase MUST NOT be considered concluded until all htlcs are +resolved and the channel has exited the pending splice phase (`splice_locked` +has been exchanged). ### Closing Negotiation: `closing_signed` From f1df2ef3e5cacdf4d0742a3b35428f4bc7a814e8 Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Fri, 21 Oct 2022 17:12:35 -0400 Subject: [PATCH 14/32] Bolt 2: closing_signed must wait for splices The closing process, begining with `closing_signed` must not begin until one of the candidate splices is confirmed. --- 02-peer-protocol.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 7a6146d10..a7d118986 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1725,9 +1725,13 @@ has been exchanged). ### Closing Negotiation: `closing_signed` -Once shutdown is complete, the channel is empty of HTLCs, there are no commitments -for which a revocation is owed, and all updates are included on both commitments, -the final current commitment transactions will have no HTLCs, and closing fee +There may be multiple splice candidates (via RBF) however when one is confirmed +it invalidates the others awaiting confirmation. We refer to this state as all +splices being "cleared". + +Once shutdown is complete, all splices are cleared, the channel is empty +of HTLCs, there are no commitments for which a revocation is owed, the final +current commitment transactions will have no HTLCs, and closing fee negotiation begins. The funder chooses a fee it thinks is fair, and signs the closing transaction with the `scriptpubkey` fields from the `shutdown` messages (along with its chosen fee) and sends the signature; From 7615130a1663a6733a6f01a5f545d362e9245afd Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Thu, 10 Nov 2022 14:28:32 -0500 Subject: [PATCH 15/32] Bolt 2: Initial splice message must commit to new channel size --- 02-peer-protocol.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index a7d118986..4b4e0438d 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1509,6 +1509,7 @@ reached acceptable depth. 2. data: * [`chain_hash`:`chain_hash`] * [`channel_id`:`channel_id`] + * [`u64`:`funding_satoshis`] * [`u32`:`funding_feerate_perkw`] * [`point`:`funding_pubkey`] @@ -1516,8 +1517,14 @@ reached acceptable depth. 2. data: * [`chain_hash`:`chain_hash`] * [`channel_id`:`channel_id`] + * [`u64`:`funding_satoshis`] * [`point`:`funding_pubkey`] +`funding_satoshis` is the amount the sender is putting into the +post-splice channel. It includes their old funded channel amount +plus any satoshis they intend to add, or, less any satoshis they +intend to remove. + #### Requirements The sender of `splice`: From 396c63836fffb939d867caca0ccac066e82a0c4a Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Mon, 2 Jan 2023 14:41:18 -0500 Subject: [PATCH 16/32] Bolt 2: Add locktime to splice initiation --- 02-peer-protocol.md | 1 + 1 file changed, 1 insertion(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 4b4e0438d..52508b38b 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1511,6 +1511,7 @@ reached acceptable depth. * [`channel_id`:`channel_id`] * [`u64`:`funding_satoshis`] * [`u32`:`funding_feerate_perkw`] + * [`u32`:`locktime`] * [`point`:`funding_pubkey`] 1. type: 76 (`splice_ack`) From 298f605c74c65fb03eca542d57fb0731eccf352b Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Fri, 20 Jan 2023 11:15:55 -0500 Subject: [PATCH 17/32] Bolt 2: Add splicing feature flag --- 09-features.md | 1 + 1 file changed, 1 insertion(+) diff --git a/09-features.md b/09-features.md index 95c59e93a..ea052aa0f 100644 --- a/09-features.md +++ b/09-features.md @@ -50,6 +50,7 @@ The Context column decodes as follows: | 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2][bolt02-channel-ready] | | 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields) | | 50/51 | `option_zeroconf` | Understands zeroconf channel types | IN | `option_scid_alias` | [BOLT #2][bolt02-channel-ready] | +| 62/63 | `option_splice` | Allows replacing the funding transaction with a new one | IN | | [BOLT #2][bolt02-peer-protocol] ## Definitions From 28c27174ed38e7b334ce597c4eeaa72a59ad85d7 Mon Sep 17 00:00:00 2001 From: Dusty Daemon Date: Fri, 3 Feb 2023 13:14:03 -0500 Subject: [PATCH 18/32] splicing: Switch to multiple `commitment_signed` messages instead of a (potentially large) commitment_tlv --- 02-peer-protocol.md | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 52508b38b..2a693d528 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -2322,7 +2322,9 @@ leaking information to senders trying to probe the blinded route. When a node has changes for the remote commitment, it can apply them, sign the resulting transaction (as defined in [BOLT #3](03-transactions.md)), and send a -`commitment_signed` message. +`commitment_signed` message bundle. First it will send `commitment_signed` +for the active channel, then it will send another `commitment_signed` message +for each splice candidate awaiting confirmation. 1. type: 132 (`commitment_signed`) 2. data: @@ -2330,29 +2332,20 @@ 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`] + * [`splice_channel_id`:`channel_id`] #### Requirements A sending node: - - MUST NOT send a `commitment_signed` message that does not include any + - MUST send channel's original `channel_id` regardless of prior splice activity. + - MUST send `splice_channel_id` to specify which channel tx this commitment +is for. + - MUST NOT send a `commitment_signed` message bundle that does not include any updates or added splices. - - MAY send a `commitment_signed` message that only + - MAY send a `commitment_signed` message bundle that only alters the fee. - - MAY send a `commitment_signed` message that doesn't + - MAY send a `commitment_signed` message bundle that doesn't change the commitment transaction aside from the new revocation number (due to dust, identical HTLC replacement, or insignificant or multiple fee changes). @@ -2360,7 +2353,9 @@ 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 awaiting confirmation, in increasing feerate order. + - MUST first send a `commitment_signed` for the active channel then immediately +send a `commitment_signed` for each splice awaiting confirmation, in increasing +feerate order. A receiving node: - once all pending updates are applied: @@ -2378,6 +2373,9 @@ A receiving node: - 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. + - if the number of consecutive `commitment_signed` messages received is not the +number of splice candidates plus one: + - MUST fail the channel. - MUST respond with a `revoke_and_ack` message. #### Rationale From 817627a1803fc13a033e50759d0a351ada8fb0ee Mon Sep 17 00:00:00 2001 From: Dusty Daemon Date: Fri, 3 Feb 2023 13:50:02 -0500 Subject: [PATCH 19/32] splicing: Clarify only a single `revoke_and_ack` is sent for a bundle of `commitment_signed` messages. --- 02-peer-protocol.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 2a693d528..eae270e07 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -2332,7 +2332,13 @@ for each splice candidate awaiting confirmation. * [`signature`:`signature`] * [`u16`:`num_htlcs`] * [`num_htlcs*signature`:`htlc_signature`] - * [`splice_channel_id`:`channel_id`] + * [`commitment_signed_tlvs`:`tlvs`] + +1. `tlv_stream`: `commitment_signed_tlvs` +2. types: + 1. type: 0 (`splice_info`) + 2. data: + * [`channel_id`:`splice_channel_id`] #### Requirements @@ -2406,7 +2412,7 @@ 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 +Once the recipient of a `commitment_signed` bundle checks the signature and knows it has a valid new commitment transaction, it replies with the commitment preimage for the previous commitment transaction in a `revoke_and_ack` message. @@ -2445,6 +2451,8 @@ A node: - SHOULD NOT sign commitment transactions, unless it's about to broadcast them (due to a failed connection), - Note: this is to reduce the above risk. + - MUST send a single `revoke_and_ack` in response to a bundle of +`commitment_signed` messages. ### Updating Fees: `update_fee` From c8ebff231e0822c5ca56945286d2592b6a10c9d8 Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Fri, 7 Apr 2023 13:59:34 -0400 Subject: [PATCH 20/32] BOLT 2: splicing signing order & commitment_signed Splice now uses single `commitment_signed` message and `tx_signatures` order is enoucrage to be smaller added amount first but is not required. --- 02-peer-protocol.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index eae270e07..83d9b312b 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1577,13 +1577,18 @@ Upon receipt of consecutive `tx_complete`s, each node: - 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: +- 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 commitment signatures for the splice transaction(s). - -- Upon receipt of `revoke_and_ack` for the previous commitment: - - MUST send `tx_signatures` for the splice transaction. +- MUST send a single `commitment_signed` for the splice transaction. + - Peer MUST NOT reply with `revoke_and_ack` + +- If recipient's sum(tx_add_input.amount) < peer's sum(tx_add_input.amount); or +if recipient's sum(tx_add_input.amount) == peer's sum(tx_add_input.amount) and +recipient is the `initiator` of the splice: + - SHOULD send `tx_signatures` first for the splice transaction. +- else + - MAY send `tx_signatures` first. - Upon receipt of `tx_signatures` for the splice transaction: - MUST consider splice negotiation complete. From 787fdf22be30b5b4bfe3964ce2066adefbec6af7 Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Fri, 7 Apr 2023 17:14:10 -0400 Subject: [PATCH 21/32] Bolt 2: Splice commitment_signed & splice_locked * commitment_signed is now sent a single time while a splice is being negotiated * adding a spec for `splice_locked` * additional logic for avoding splice_locked race condition --- 02-peer-protocol.md | 39 ++++++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 83d9b312b..b8fae8a09 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1609,15 +1609,28 @@ through if this happens). ## Splice Completion +### The `splice_locked` Message + +1. type: 77 (`splice_locked`) +2. data: + * [`channel_id`:`channel_id`] + +`channel_id` is the pre-splice channel's `channel_id`. + Each node: - if any splice transaction reaches depth 6: - MUST send `splice_locked`. Once a node has received and sent `splice_locked`: + - Until sending OR receiving of `revoke_and_ack` + - MUST ignore `announcement_signatures` messages where `short_channel_id` + matches the pre-splice short channel id. + - MUST ignore `commitment_signed` messages where `splice_channel_id` + does not match the `channel_id` of the confirmed splice. - 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`). + - MUST send a new `commitment_signed` bundle (with no splice commitsigs bundle). On reconnection: - MUST retransmit the last `splice_locked` if the peer did not @@ -1859,20 +1872,20 @@ the closing transaction will likely never reach miners. Once both nodes have exchanged `channel_ready` (and optionally [`announcement_signatures`](07-routing-gossip.md#the-announcement_signatures-message)), the channel can be used to make payments via Hashed Time Locked Contracts. Changes are sent in batches: one or more `update_` messages are sent before a -`commitment_signed` message, as in the following diagram: +`commitment_signed` message bundle, as in the following diagram: +-------+ +-------+ | |--(1)---- update_add_htlc ---->| | | |--(2)---- update_add_htlc ---->| | | |<-(3)---- update_add_htlc -----| | | | | | - | |--(4)--- commitment_signed --->| | + | |--(4)- commitment_signed(s) -->| | | A |<-(5)---- revoke_and_ack ------| B | | | | | - | |<-(6)--- commitment_signed ----| | + | |<-(6)- commitment_signed(s) ---| | | |--(7)---- revoke_and_ack ----->| | | | | | - | |--(8)--- commitment_signed --->| | + | |--(8)- commitment_signed(s) -->| | | |<-(9)---- revoke_and_ack ------| | +-------+ +-------+ @@ -2353,7 +2366,7 @@ A sending node: - MUST send `splice_channel_id` to specify which channel tx this commitment is for. - MUST NOT send a `commitment_signed` message bundle that does not include any -updates or added splices. +updates. - MAY send a `commitment_signed` message bundle that only alters the fee. - MAY send a `commitment_signed` message bundle that doesn't @@ -2364,7 +2377,10 @@ 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 first send a `commitment_signed` for the active channel then immediately + - if during an active splice negotiation + - MUST send a single `commitment_signed` for the splice candidate. + - else + - MUST first send a `commitment_signed` for the active channel then immediately send a `commitment_signed` for each splice awaiting confirmation, in increasing feerate order. @@ -2384,10 +2400,11 @@ A receiving node: - 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. - - if the number of consecutive `commitment_signed` messages received is not the -number of splice candidates plus one: - - MUST fail the channel. - - MUST respond with a `revoke_and_ack` message. + - if not during an active splice negotiation + - if the number of consecutive `commitment_signed` messages received is not + the number of splice candidates plus one: + - MUST fail the channel. + - MUST respond with a `revoke_and_ack` message. #### Rationale From 03c47c11cfa89e5c03470758c50736898f72b3a0 Mon Sep 17 00:00:00 2001 From: Dusty Daemon Date: Thu, 6 Jul 2023 16:35:31 -0400 Subject: [PATCH 22/32] splicing: Clearly specify who is paying for what portions of the splice --- 02-peer-protocol.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index b8fae8a09..c3c7af342 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1566,6 +1566,9 @@ The initiator: - 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. +Each node: +- MUST pay for their own added inputs and outputs. + 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) From d2fc4e45cacffad557bba991441f81826ca49876 Mon Sep 17 00:00:00 2001 From: Dusty Daemon Date: Tue, 13 Feb 2024 15:18:20 -0500 Subject: [PATCH 23/32] fixup! splicing: use the generic negotiation mechanism to splice in/out of a channel. Co-authored-by: ProofOfKeags --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index c3c7af342..d19f0fd69 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1552,7 +1552,7 @@ consider to be overpaying). ## Splice Negotiation -The splice negotiation is very similar to the `init_rbf` negotiation: +The splice negotiation is very similar to the `tx_init_rbf` negotiation: both sides alternate sending `tx_add_input` and `tx_add_output` until they both send consecutive `tx_complete`. From 3c2ba1f7326faf962def0130b38c0f9526e6424a Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Tue, 13 Feb 2024 15:34:06 -0500 Subject: [PATCH 24/32] fixup! splice_locked: terminate this splice once one reaches agreed depths. --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index d19f0fd69..39a395307 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1500,7 +1500,7 @@ 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 +`splice_locked` to indicate that one of the splice transactions reached acceptable depth. ### The `splice` Message From 3e4cf2460a3e117bc98986641bd080d204565eba Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Tue, 13 Feb 2024 15:35:40 -0500 Subject: [PATCH 25/32] Bolt 2: Splice command uses signed relative sats Using relative sat amounts simplifies multiple aspects of the protocol. --- 02-peer-protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 39a395307..68ac8b551 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1509,7 +1509,7 @@ reached acceptable depth. 2. data: * [`chain_hash`:`chain_hash`] * [`channel_id`:`channel_id`] - * [`u64`:`funding_satoshis`] + * [`s64`:`relative_amount`] * [`u32`:`funding_feerate_perkw`] * [`u32`:`locktime`] * [`point`:`funding_pubkey`] @@ -1518,7 +1518,7 @@ reached acceptable depth. 2. data: * [`chain_hash`:`chain_hash`] * [`channel_id`:`channel_id`] - * [`u64`:`funding_satoshis`] + * [`s64`:`relative_amount`] * [`point`:`funding_pubkey`] `funding_satoshis` is the amount the sender is putting into the From fe8e682440ae5f80d89a9a18f3524952a1806480 Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Tue, 13 Feb 2024 15:37:21 -0500 Subject: [PATCH 26/32] Bolt 2: splice message must start with channel_id --- 02-peer-protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 68ac8b551..d80f6a1f6 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1507,8 +1507,8 @@ reached acceptable depth. 1. type: 74 (`splice`) 2. data: - * [`chain_hash`:`chain_hash`] * [`channel_id`:`channel_id`] + * [`chain_hash`:`chain_hash`] * [`s64`:`relative_amount`] * [`u32`:`funding_feerate_perkw`] * [`u32`:`locktime`] @@ -1516,8 +1516,8 @@ reached acceptable depth. 1. type: 76 (`splice_ack`) 2. data: - * [`chain_hash`:`chain_hash`] * [`channel_id`:`channel_id`] + * [`chain_hash`:`chain_hash`] * [`s64`:`relative_amount`] * [`point`:`funding_pubkey`] From 79bf5ae8d38a026370576abb9a518fd3ede2cde8 Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Tue, 13 Feb 2024 16:05:15 -0500 Subject: [PATCH 27/32] Bolt 2: Splice re-sending of `splice_locked` In cases where one side has sent `splice_locked` but the peer is attempting to resume splicing negotiation via reestablish we must re-send `splice_locked` This can occur if only one side has received splice signatures, and the peer goes offline. During this time the transaction may be published and confirmed. When the peer comes online it will be requesting splice signatures (via `next_funding_txid`) but since the transaction is already confirmed we must jump ahead to `splice_locked`. --- 02-peer-protocol.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index d80f6a1f6..853469b7f 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -2738,8 +2738,11 @@ A receiving node: - if it has already received `tx_signatures` for that funding transaction: - MUST send its `tx_signatures` for that funding transaction. - otherwise: - - MUST send `tx_abort` to let the sending node know that they can forget - this funding transaction. + - if `next_funding_txid` matches the latest confirmed function transaction: + - MUST re-send `splice_locked` + - otherwise: + - MUST send `tx_abort` to let the sending node know that they can forget + this funding transaction. A node: - MUST NOT assume that previously-transmitted messages were lost, From 678ae6116817a3b36864e8740ddaf22c33b62670 Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Tue, 13 Feb 2024 16:10:55 -0500 Subject: [PATCH 28/32] Bolt 2: Splice clarify pending splice A pending splice is one waiting for confirmation which is seperate from an ongoing splice negotation. Adjusting the language to remove ambiguity. --- 02-peer-protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 853469b7f..1026b2d78 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1536,7 +1536,7 @@ The sender of `splice`: - 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). +- SHOULD fail the connection if there is an pending 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. @@ -1683,7 +1683,7 @@ A sending node: - if there are updates pending on the receiving node's commitment transaction: - MUST NOT send a `shutdown`. - MUST NOT send multiple `shutdown` messages. - - if there is an ongoing splice: + - if there is an pending splice: - MUST NOT send a `shutdown`. - MUST NOT send an `update_add_htlc` after a `shutdown`. - if no HTLCs remain in either commitment transaction (including dust HTLCs) From e7f84dffb2c161d433f2613cdecbbd809940cdc2 Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Tue, 13 Feb 2024 16:12:58 -0500 Subject: [PATCH 29/32] Bolt 2: interactive-tx only confirmed inputs The interactive tx protocol must only use confirmed inputs. --- 02-peer-protocol.md | 1 + 1 file changed, 1 insertion(+) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 1026b2d78..4d95be2a5 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -205,6 +205,7 @@ This message contains a transaction input. The sending node: - MUST add all sent inputs to the transaction + - MUST only send confirmed inputs - MUST use a unique `serial_id` for each input currently added to the transaction - MUST set `sequence` to be less than or equal to 4294967293 (`0xFFFFFFFD`) From 10ee7dfe2333f64cdddc95e18a60f4222d95ac2c Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Tue, 13 Feb 2024 16:14:30 -0500 Subject: [PATCH 30/32] Bolt 02: Update splice to reference `channel_ready` Formally known as `funding_locked` --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 4d95be2a5..c59b328a4 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1531,7 +1531,7 @@ intend to remove. The sender of `splice`: - MUST have successfully initiated quiescence. -- MUST NOT send `splice` before sending and receiving `funding_locked`. +- MUST NOT send `splice` before sending and receiving `channel_ready`. - 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). From 76c46788f235dac3806cb2592faaa64791344eac Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Tue, 13 Feb 2024 16:20:53 -0500 Subject: [PATCH 31/32] Bolt 2: splice message numbers Jump to message numer 80 to avoid conflicts with `stfu` etc --- 02-peer-protocol.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index c59b328a4..2e8fdf289 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1506,7 +1506,7 @@ reached acceptable depth. ### The `splice` Message -1. type: 74 (`splice`) +1. type: 80 (`splice`) 2. data: * [`channel_id`:`channel_id`] * [`chain_hash`:`chain_hash`] @@ -1515,7 +1515,7 @@ reached acceptable depth. * [`u32`:`locktime`] * [`point`:`funding_pubkey`] -1. type: 76 (`splice_ack`) +1. type: 81 (`splice_ack`) 2. data: * [`channel_id`:`channel_id`] * [`chain_hash`:`chain_hash`] From c08f5b63bd7c9801f1b39eb872aaf0bab51cbd49 Mon Sep 17 00:00:00 2001 From: Dustin Dettmer Date: Tue, 13 Feb 2024 17:24:51 -0500 Subject: [PATCH 32/32] fixup! Bolt 2: Splice re-sending of `splice_locked` --- 02-peer-protocol.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 2e8fdf289..daa25a2ea 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -2739,7 +2739,7 @@ A receiving node: - if it has already received `tx_signatures` for that funding transaction: - MUST send its `tx_signatures` for that funding transaction. - otherwise: - - if `next_funding_txid` matches the latest confirmed function transaction: + - if `next_funding_txid` matches the latest confirmed funding transaction: - MUST re-send `splice_locked` - otherwise: - MUST send `tx_abort` to let the sending node know that they can forget