mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2025-03-13 11:35:41 +01:00
Code Issues Projects Releases Wiki Activity

Merge 8c907f6b8d into 216914d492

Browse source
This commit is contained in:
Bastien Teinturier 2025-03-11 09:52:43 +01:00 • committed by GitHub
commit 94b1d3feac
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 1322 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

594
02-peer-protocol.md
View file

@ -33,6 +33,11 @@ operation, and closing.
* [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 Splicing](#channel-splicing)
* [The `splice_init` Message](#the-splice_init-message)
* [The `splice_ack` Message](#the-splice_ack-message)
* [Splice Transaction Construction](#splice-transaction-construction)
* [Splice Completion](#splice-completion)
* [Channel Close](#channel-close)
* [Closing Initiation: `shutdown`](#closing-initiation-shutdown)
* [Closing Negotiation: `closing_signed`](#closing-negotiation-closing_signed)
@ -200,6 +205,13 @@ This message contains a transaction input.
* [`prevtx_len*byte`:`prevtx`]
* [`u32`:`prevtx_vout`]
* [`u32`:`sequence`]
* [`tx_add_input_tlvs`:`tlvs`]
1. `tlv_stream`: `tx_add_input_tlvs`
2. types:
1. type: 0 (`shared_input_txid`)
2. data:
* [`sha256`:`funding_txid`]
#### Requirements
@ -393,12 +405,19 @@ the byte size of the input and output counts on the transaction to one (1).
* [`sha256`:`txid`]
* [`u16`:`num_witnesses`]
* [`num_witnesses*witness`:`witnesses`]
* [`tx_signatures_tlvs`:`tlvs`]
1. subtype: `witness`
2. data:
* [`u16`:`len`]
* [`len*byte`:`witness_data`]
1. `tlv_stream`: `tx_signatures_tlvs`
2. types:
1. type: 0 (`shared_input_signature`)
2. data:
* [`signature`:`signature`]
#### Requirements
The sending node:
@ -1498,6 +1517,444 @@ 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 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 the splice transaction has been signed
(while waiting for one of the splice transactions to confirm), at which
point the channel isn't quiescent anymore.
The splice is finally terminated when both sides send `splice_locked`
to indicate that one of the splice transactions reached acceptable depth.
+-------+ +-------+
| |--- splice_init -------------->| |
| A |<--------------- splice_ack ---| B |
| | | |
| |--- tx_add_input ------------->| |
| |<------------- tx_add_input ---| |
| |--- tx_add_input ------------->| |
| |<------------ tx_add_output ---| |
| |--- tx_add_output ------------>| |
| |<-------------- tx_complete ---| |
| |--- tx_add_output ------------>| |
| |<-------------- tx_complete ---| |
| |--- tx_complete -------------->| |
| | | |
| |--- commit_sig --------------->| |
| |<--------------- commit_sig ---| |
| |--- tx_signatures ------------>| |
| |<------------ tx_signatures ---| |
| | | |
| | <RESUME CHANNEL> | |
| | | |
| |--- update_add_htlc ---------->| |
| |--- commit_sig --------------->| |
| |--- commit_sig --------------->| |
| |<----------- revoke_and_ack ---| |
| |<--------------- commit_sig ---| |
| |<--------------- commit_sig ---| |
| |--- revoke_and_ack ----------->| |
| | | |
| | <RBF> | |
| | | |
| |<-------------- tx_init_rbf ---| |
| |--- tx_ack_rbf --------------->| |
| |<------------- tx_add_input ---| |
| |--- tx_add_input ------------->| |
| |<------------- tx_add_input ---| |
| |--- tx_add_output ------------>| |
| |<------------ tx_add_output ---| |
| |--- tx_complete -------------->| |
| |<------------ tx_add_output ---| |
| |--- tx_complete -------------->| |
| |<-------------- tx_complete ---| |
| | | |
| |<--------------- commit_sig ---| |
| |--- commit_sig --------------->| |
| |--- tx_signatures ------------>| |
| |<------------ tx_signatures ---| |
| | | |
| | <RESUME CHANNEL> | |
| | | |
| |--- update_add_htlc ---------->| |
| |--- commit_sig --------------->| |
| |--- commit_sig --------------->| |
| |--- commit_sig --------------->| |
| |<----------- revoke_and_ack ---| |
| |<--------------- commit_sig ---| |
| |<--------------- commit_sig ---| |
| |<--------------- commit_sig ---| |
| |--- revoke_and_ack ----------->| |
| | | |
| | <SPLICE COMPLETION> | |
| | | |
| |--- splice_locked ------------>| |
| |<------------ splice_locked ---| |
| | | |
| | <RESUME CHANNEL> | |
| | | |
| |--- update_add_htlc ---------->| |
| |--- commit_sig --------------->| |
| |<----------- revoke_and_ack ---| |
| |<--------------- commit_sig ---| |
| |--- revoke_and_ack ----------->| |
| | | |
+-------+ +-------+
### The `splice_init` Message
1. type: 80 (`splice_init`)
2. data:
* [`channel_id`:`channel_id`]
* [`s64`:`funding_contribution_satoshis`]
* [`u32`:`funding_feerate_perkw`]
* [`u32`:`locktime`]
* [`point`:`funding_pubkey`]
* [`splice_init_tlvs`:`tlvs`]
1. `tlv_stream`: `splice_init_tlvs`
2. types:
1. type: 2 (`require_confirmed_inputs`)
`funding_contribution_satoshis` is the amount the sender is adding to their
channel balance (splice-in) or removing from their channel balance (splice-out).
#### Requirements
The sending node:
- MUST NOT send `splice_init` if the channel is not quiescent.
- MUST NOT send `splice_init` if it is not the quiescence initiator.
- MUST NOT send `splice_init` before sending and receiving `channel_ready`.
- MUST NOT send `splice_init` while another splice is being negotiated.
- MUST NOT send `splice_init` if another splice has been negotiated but
`splice_locked` has not been sent and received.
- MUST NOT send `splice_init` if it has previously sent `shutdown`.
- If it is splicing funds out of the channel:
- MUST set `funding_contribution_satoshis` to a negative value matching
the amount that will be subtracted from its current channel balance.
- If it is splicing funds into the channel:
- MUST set `funding_contribution_satoshis` to a positive value matching
the amount that will be added to its current channel balance.
- If it requires the receiving node to only use confirmed inputs:
- MUST set `require_confirmed_inputs`.
- SHOULD use a different `funding_pubkey` than the one used for the
previous funding transaction.
The receiving node:
- If the channel is not quiescent:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
- If the sending node is not the quiescence initiator:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
- If another splice is already being negotiated:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
- If another splice has been negotiated but isn't locked yet:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
- If it has received `shutdown`:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
- If `funding_contribution_satoshis` is negative and its absolute value is
greater than the sending node's current channel balance:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
- If it accepts the splice attempt:
- MUST respond with `splice_ack`.
- Otherwise (it rejects the splice):
- MUST respond with `tx_abort`.
### The `splice_ack` Message
1. type: 81 (`splice_ack`)
2. data:
* [`channel_id`:`channel_id`]
* [`s64`:`funding_contribution_satoshis`]
* [`point`:`funding_pubkey`]
* [`splice_ack_tlvs`:`tlvs`]
1. `tlv_stream`: `splice_ack_tlvs`
2. types:
1. type: 2 (`require_confirmed_inputs`)
#### Requirements
The sending node:
- SHOULD use a different `funding_pubkey` than the one used for the
previous funding transaction.
- MAY set `funding_contribution_satoshis` to `0` if they don't want
to contribute to the splice.
- If it requires the receiving node to only use confirmed inputs:
- MUST set `require_confirmed_inputs`.
The receiving node:
- If it has sent `splice_init`:
- If `funding_contribution_satoshis` is negative and its absolute value is
greater than the sending node's current channel balance:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
- If it accepts the splice attempt:
- MUST start an `interactive-tx` session to create the splice transaction.
- Otherwise:
- MUST reject the splice attempt by sending `tx_abort`.
- Otherwise (it has not sent `splice_init`):
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
### Splice Transaction Construction
The splice transaction is created using the
[Interactive Transaction Construction](#interactive-transaction-construction)
protocol, with the following additional requirements.
#### The `tx_add_input` Message
##### Requirements
The sending node:
- If it is the splice initiator:
- MUST add the current channel input to the splice transaction by
sending `tx_add_input` with `shared_input_txid` containing the
`txid` of the latest funding transaction.
- MUST NOT include `prevtx` for that shared input.
- If the receiver set `require_confirmed_inputs` in `splice_init`,
`splice_ack`, `tx_init_rbf` or `tx_ack_rbf`:
- MUST NOT send a `tx_add_input` that contains an unconfirmed input.
The receiving node:
- If `shared_input_txid` is set:
- If it doesn't match the `txid` of the latest funding transaction:
- MUST fail the negotiation by sending `tx_abort`.
##### Rationale
The splice transaction must spend the current channel funding output. The
splice initiator is responsible for adding that input to the transaction,
and pay the fees for its weight. Since both peers already have access to
the funding transaction, it is wasteful to transmit it in the `prevtx`
field. It may also exceed 65kB, which makes it impossible to include it
in `tx_add_input` anyway, so we only transmit its `txid`.
#### The `tx_add_output` Message
##### Requirements
The sending node:
- If it is the splice initiator:
- MUST send at least one `tx_add_output`, which contains the new
channel's funding output based on the `funding_pubkey`s from
`splice_init` and `splice_ack`.
- MUST set the amount of that `tx_add_output` to the previous
channel capacity with the `funding_contribution_satoshis`s from
`splice_init` and `splice_ack` applied.
##### Rationale
The splice initiator is responsible for adding the new channel funding
output to the transaction and paying the fees for its weight.
#### The `tx_complete` Message
##### Requirements
The receiving node:
- MUST compute the channel balance for each side by adding their respective
`funding_contribution_satoshis` to their previous channel balance.
- MUST fail the negotiation by sending `tx_abort` if:
- There is not exactly one input spending the current funding transaction.
- There is not exactly one channel funding output using the funding public
keys and funding contributions from `splice_init` and `splice_ack`.
- This is an RBF attempt and the transaction's total fees is less than
the last successfully negotiated splice transaction's fees.
- Either side has added an output other than the channel funding output
and the balance for that side is less than the channel reserve that
matches the new channel capacity.
##### 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).
### The `commitment_signed` Message
After exchanging `tx_complete`, both peers send `commitment_signed` to commit
to the splice transaction by creating a commitment transaction spending the
new channel funding output.
The usual [`commitment_signed`](#committing-updates-so-far-commitment_signed)
requirements apply with the following additions.
#### Requirements
The sending node:
- MUST create a commitment transaction that spends the splice funding output and:
- Adds `funding_contribution_satoshis` from `splice_init` and `splice_ack`
to the main balance of their respective sender.
- Uses the same feerate as the existing commitment transaction.
- Uses the same `commitment_number` as the existing commitment transaction.
- Does not set the `batch` field.
- MUST send signatures for pending HTLCs.
- MUST remember the details of this splice transaction.
The receiving node:
- MUST NOT respond with `revoke_and_ack`.
- If it has not already transmitted its `commitment_signed`:
- MUST send `commitment_signed`.
- If it should sign first, as specified in the [`tx_signatures` requirements](#the-tx_signatures-message):
- MUST send `tx_signatures`.
On reconnection:
- If `next_funding_txid` matches the splice transaction:
- MUST retransmit `commitment_signed`.
#### Rationale
Once peers are ready to exchange commitment signatures, they must remember
the details of the splice transaction to allow resuming the signatures
exchange if a disconnection happens.
#### The `tx_signatures` Message
##### Requirements
The sending node:
- MUST set `shared_input_signature` to a valid ECDSA signature for the
`tx_add_input` spending the previous channel funding output using the
`funding_pubkey` that matches this input.
The receiving node:
- If `shared_input_signature` is not set:
- MUST send an `error` and fail the channel.
- If `shared_input_signature` is not valid or non-compliant with the
LOW-S-standard rule<sup>[LOWS](https://github.com/bitcoin/bitcoin/pull/6769)</sup>:
- MUST send an `error` and fail the channel.
- MUST consider the channel no longer quiescent.
On reconnection:
- If `next_funding_txid` matches the splice transaction:
- MUST retransmit `tx_signatures`.
##### Rationale
Spending the channel funding output requires a signature from both peers.
Each peer transmits its own signature, which allows creating a valid
witness for the shared input without adding an additional message.
Once `tx_signatures` have been exchanged, the splice transaction can be
broadcast. The channel is no longer quiescent: normal operation can resume
while waiting for the transaction to confirm and `splice_locked` messages
to be exchanged.
#### The `tx_init_rbf` Message
##### Requirements
The sending node:
- MUST NOT send `tx_init_rbf` if the channel is not quiescent.
- MUST NOT send `tx_init_rbf` if it is not the quiescence initiator.
- MAY send `tx_init_rbf` even if it is not the splice initiator.
- MUST NOT send `tx_init_rbf` if it has previously sent `splice_locked`.
- MAY set `funding_output_contribution` to a different value than the
`funding_contribution_satoshis` used in `splice_init` or `splice_ack`,
or in previous RBF attempts.
The receiving node:
- If the channel is not quiescent:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
- If the sending node is not the quiescence initiator:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
- If the sender previously sent `splice_locked`:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
- If `funding_output_contribution` is negative and its absolute value is
greater than the sending node's current channel balance:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
##### Rationale
Splice transactions can be RBF-ed to react to changes in the mempool feerate.
We allow both nodes to initiate RBF, because any one of them may want to take
this opportunity to splice additional funds into or out of the channel without
waiting for the initial splice transaction to confirm.
Since splice transactions always spend the current channel funding output, the
RBF attempts automatically double-spend each other.
#### The `tx_ack_rbf` Message
##### Requirements
The sending node:
- MAY set `funding_output_contribution` to a different value than the
`funding_contribution_satoshis` used in `splice_init` or `splice_ack`,
or in previous RBF attempts.
The receiving node:
- If `funding_output_contribution` is negative and its absolute value is
greater than the sending node's current channel balance:
- MUST send a `warning` and close the connection or send an `error`
and fail the channel.
### Splice Completion
Once splice transactions have been signed but haven't reached acceptable
depth, channel operations go back to normal and HTLCs can be exchanged,
with the caveat that payments must be valid for all splice transactions.
Nodes keep track of multiple commitment transactions (one for the current
funding transaction and one for each splice transaction) and exchange
signatures for each of these commitment transactions.
```
+------------+ +-----------+
| Funding Tx |---+--->| Commit Tx |
+------------+ | +-----------+
| +-----------+ +-----------+
+--->| Splice Tx |----------->| Commit Tx |
| +-----------+ +-----------+
| +---------------+ +-----------+
+--->| Splice RBF #1 |------->| Commit Tx |
| +---------------+ +-----------+
| +---------------+ +-----------+
+--->| Splice RBF #2 |------->| Commit Tx |
+---------------+ +-----------+
```
The splice completes by exchanging `splice_locked` messages, at which point
the locked transaction replaces the previous funding transaction.
#### The `splice_locked` Message
1. type: 77 (`splice_locked`)
2. data:
* [`channel_id`:`channel_id`]
* [`sha256`:`splice_txid`]
##### Requirements
Each node:
- If any splice transaction reaches acceptable depth:
- MUST send `splice_locked` with the `txid` of that transaction.
Once a node has sent and received `splice_locked`:
- MUST consider the locked splice transaction to be the new funding
transaction for all future `commitment_signed` messages and splice
negotiations.
- SHOULD discard the previous funding transaction and RBF attempts.
- MUST send `announcement_signatures` with `short_channel_id` matching
the locked splice transaction.
## Channel Close
Nodes can negotiate a mutual close of the connection, which unlike a
@ -1608,6 +2065,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.
- MUST NOT send `shutdown` if there is a splice transaction that isn't locked yet.
- 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:
@ -2271,6 +2729,8 @@ A sending node:
- MUST increase the value of `id` by 1 for each successive offer.
- if it is relaying a payment inside a blinded route:
- MUST set `path_key` (see [Route Blinding](04-onion-routing.md#route-blinding))
- if a splice is pending:
- MUST ensure that requirements are met for all commmitment transactions.
`id` MUST NOT be reset to 0 after the update is complete (i.e. after `revoke_and_ack` has
been received). It MUST continue incrementing instead.
@ -2302,6 +2762,8 @@ A receiving node:
- MUST respond with an error as detailed in [Failure Messages](04-onion-routing.md#failure-messages)
- Otherwise:
- MUST follow the requirements for the reader of `payload` in [Payload Format](04-onion-routing.md#payload-format)
- If a splice is pending:
- MUST ensure that requirements are met for all commmitment transactions.
The `onion_routing_packet` contains an obfuscated list of hops and instructions for each hop along the path.
It commits to the HTLC by setting the `payment_hash` as associated data, i.e. includes the `payment_hash` in the computation of HMACs.
@ -2337,6 +2799,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.
@ -2451,6 +2916,14 @@ 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 (`batch`)
2. data:
* [`u16`:`batch_size`]
* [`sha256`:`funding_txid`]
#### Requirements
@ -2467,6 +2940,13 @@ 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`.
- If there are `N` pending splice transactions:
- MUST send `commitment_signed` for the current channel funding output.
- MUST send `commitment_signed` for each of the splice transactions.
- MUST set `batch_size` to `N + 1` in every `commitment_signed` message.
- MUST set `funding_txid` to the funding transaction spent by that commitment.
- Otherwise:
- MUST NOT include the `batch` field.
A receiving node:
- once all pending updates are applied:
@ -2480,7 +2960,25 @@ A receiving node:
- if any `htlc_signature` is not valid for the corresponding HTLC transaction OR non-compliant with LOW-S-standard rule <sup>[LOWS](https://github.com/bitcoin/bitcoin/pull/6769)</sup>:
- MUST send a `warning` and close the connection, or send an
`error` and fail the channel.
- MUST respond with a `revoke_and_ack` message.
- If there are pending splice transactions and `batch` is not set:
- MUST send an `error` and fail the channel.
- If `batch` is set:
- MUST wait until it has received `batch_size` messages.
- If there are pending splice transactions:
- MUST validate each `commitment_signed` based on `funding_txid`.
- If `commitment_signed` is missing for a funding transaction:
- MUST send an `error` and fail the channel.
- Otherwise:
- MUST respond with a `revoke_and_ack` message.
- Otherwise (no pending splice transactions):
- MUST ignore `commitment_signed` where `funding_txid` does not match
the current funding transaction.
- If `commitment_signed` is missing for the current funding transaction:
- MUST send an `error` and fail the channel.
- Otherwise:
- MUST respond with a `revoke_and_ack` message.
- Otherwise:
- MUST respond with a `revoke_and_ack` message.
#### Rationale
@ -2503,6 +3001,13 @@ 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 additional signatures, as we don't
know which (if any) of the splice transactions will end up being the new
channel funding transaction. We send `commitment_signed` for each of the
pending splice transactions and for the current funding transaction. When
sending `splice_locked`, we may receive obsolete `commitment_signed` from
our peer: we can safely ignore them by filtering on `funding_txid`.
### Completing the Transition to the Updated State: `revoke_and_ack`
Once the recipient of `commitment_signed` checks the signature and knows
@ -2530,6 +3035,8 @@ A sending node:
the previous commitment transaction.
- MUST set `next_per_commitment_point` to the values for its next commitment
transaction.
- MUST send a single `revoke_and_ack` message, even if it is responding to
a `batch` of `commitment_signed` messages.
A receiving node:
- if `per_commitment_secret` is not a valid secret key or does not generate the previous `per_commitment_point`:
@ -2585,6 +3092,8 @@ A sending node:
- if the dust balance of the local transaction at the updated `feerate_per_kw` is greater than `max_dust_htlc_exposure_msat`:
- MAY NOT send `update_fee`
- MAY fail the channel
- if a splice is pending:
- MUST ensure that requirements are met for all commmitment transactions.
A receiving node:
- if the `update_fee` is too low for timely processing, OR is unreasonably large:
@ -2604,6 +3113,8 @@ A receiving node:
- MAY fail the channel
- if the dust balance of the local transaction at the updated `feerate_per_kw` is greater than `max_dust_htlc_exposure_msat`:
- MAY fail the channel
- if a splice is pending:
- MUST ensure that requirements are met for all commmitment transactions.
#### Rationale
@ -2632,6 +3143,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
@ -2667,6 +3181,11 @@ messages are), they are independent of requirements here.
1. type: 0 (`next_funding`)
2. data:
* [`sha256`:`next_funding_txid`]
1. type: 1 (`your_last_funding_locked`)
2. data:
* [`sha256`:`your_last_funding_locked_txid`]
1. type: 3 (`my_current_funding_locked`)
* [`sha256`:`my_current_funding_locked_txid`]
`next_commitment_number`: A commitment number is a 48-bit
incrementing counter for each commitment transaction; counters
@ -2721,12 +3240,39 @@ The sending node:
- if it has sent `commitment_signed` for an interactive transaction construction but
it has not received `tx_signatures`:
- MUST set `next_funding_txid` to the txid of that interactive transaction.
- if it has not received `commitment_signed` for that interactive transaction:
- MUST set `next_commitment_number` to the commitment number of the `commitment_signed` it sent.
- otherwise:
- MUST NOT set `next_funding_txid`.
- if `option_splice` was negotiated:
- MUST set `your_last_funding_locked` to the txid of the last `splice_locked` it received.
- if it never received `splice_locked` for any transaction, but it received `channel_ready`:
- MUST set `your_last_funding_locked` to the txid of the channel funding transaction.
- otherwise (it has never received `channel_ready` or `splice_locked`):
- MUST NOT set `your_last_funding_locked`.
- if a splice transaction reached acceptable depth while disconnected:
- MUST set `my_current_funding_locked` to the txid of the latest such transaction.
- MUST send `splice_locked` for that transaction after `channel_reestablish`.
- otherwise:
- MUST set `my_current_funding_locked` to the txid of the last `splice_locked` it sent.
- if it never sent `splice_locked` for any transaction, but it sent `channel_ready`:
- MUST set `my_current_funding_locked` to the txid of the channel funding transaction.
- otherwise (it has never sent `channel_ready` or `splice_locked`):
- MUST NOT set `my_current_funding_locked`.
- if `my_current_funding_locked` is included and `announce_channel` is set for this channel:
- if it has not received `announcement_signatures` for that transaction:
- MUST retransmit `channel_ready` or `splice_locked` after `channel_reestablish`.
- if it receives `channel_ready` for that transaction after `channel_reestablish`:
- MUST retransmit `channel_ready` in response, if not already sent.
- if it receives `splice_locked` for that transaction after `channel_reestablish`:
- MUST retransmit `splice_locked` in response, if not already sent.
A node:
- if `next_commitment_number` is 1 in both the `channel_reestablish` it
sent and received:
sent and received and `option_splice` was NOT negotiated:
- MUST retransmit `channel_ready`.
- if `option_splice` was negotiated and `your_last_funding_locked` is not
set in the `channel_reestablish` it received:
- MUST retransmit `channel_ready`.
- otherwise:
- MUST NOT retransmit `channel_ready`, but MAY send `channel_ready` with
@ -2773,18 +3319,33 @@ A node:
A receiving node:
- if `next_funding_txid` is set:
- if `next_funding_txid` matches the latest interactive funding transaction:
- if it has not received `tx_signatures` for that funding transaction:
- if `next_funding_txid` matches the latest interactive funding transaction
or the current channel funding transaction:
- if `next_commitment_number` is equal to the commitment number of the
`commitment_signed` message it sent for this funding transaction:
- MUST retransmit its `commitment_signed` for that funding transaction.
- if it has already received `commitment_signed` and it should sign first,
as specified in the [`tx_signatures` requirements](#the-tx_signatures-message):
- MUST send its `tx_signatures` for that funding transaction.
- if it has already received `commitment_signed` and it should sign first,
as specified in the [`tx_signatures` requirements](#the-tx_signatures-message):
- MUST send its `tx_signatures` for that funding transaction.
- if it has already received `tx_signatures` for that funding transaction:
- MUST send its `tx_signatures` for that funding transaction.
- if it also sets `next_funding_txid` in its own `channel_reestablish`, but the
values don't match:
- MUST send an `error` and fail the channel.
- otherwise:
- MUST send `tx_abort` to let the sending node know that they can forget
this funding transaction.
A receiving node:
- if `my_current_funding_locked` does not match the most recent `splice_locked`
it has received:
- MUST process `my_current_funding_locked` as if it was receiving `splice_locked`
for this `txid`, and thus discard the previous funding transaction and RBF
attempts if it has previously sent its own `splice_locked` for that `txid`.
- if `your_last_funding_locked` is not set, or if it does not match the most recent
`splice_locked` it has sent:
- MUST retransmit `splice_locked`.
A node:
- MUST NOT assume that previously-transmitted messages were lost,
- if it has sent a previous `commitment_signed` message:
@ -2844,16 +3405,6 @@ operation, which is known to have begun after a `commitment_signed` has been
received — hence, the test for a `next_commitment_number` greater
than 1.
A previous draft insisted that the funder "MUST remember ...if it has
broadcast the funding transaction, otherwise it MUST NOT": this was in
fact an impossible requirement. A node must either firstly commit to
disk and secondly broadcast the transaction or vice versa. The new
language reflects this reality: it's surely better to remember a
channel which hasn't been broadcast than to forget one which has!
Similarly, for the fundee's `funding_signed` message: it's better to
remember a channel that never opens (and times out) than to let the
funder open it while the fundee has forgotten it.
A node, which has somehow fallen
behind (e.g. has been restored from old backup), can detect that it has fallen
behind. A fallen-behind node must know it cannot broadcast its current
@ -2869,6 +3420,15 @@ interactive transaction construction, or safely abort that transaction
if it was not signed by one of the peers, who has thus already removed
it from its state.
`your_last_funding_locked` allows peers to detect that their `splice_locked`
was lost during the disconnection and must be retransmitted. When a splice
transaction reaches acceptable depth while peers are disconnected, it also
allows locking that splice transaction immediately after `channel_reestablish`
instead of waiting for the `splice_locked` message, which could otherwise
create a race condition with channel updates. For more details about this
race condition, see [this example](./bolt02/splicing-test.md#disconnection-with-concurrent-splice_locked).
Redundant `splice_locked` messages are harmless and can be safely ignored.
# Authors
[ FIXME: Insert Author List ]

45
07-routing-gossip.md
View file

@ -86,6 +86,8 @@ A node:
- If the `open_channel` message has the `announce_channel` bit set AND a `shutdown` message has not been sent:
- After `channel_ready` has been sent and received AND the funding transaction has enough confirmations to ensure that it won't be reorganized:
- MUST send `announcement_signatures` for the funding transaction.
- After `splice_locked` has been sent and received AND the splice transaction has enough confirmations to ensure that it won't be reorganized:
- MUST send `announcement_signatures` for the matching splice transaction.
- Otherwise:
- MUST NOT send the `announcement_signatures` message.
- Upon reconnection (once the above timing requirements have been met):
@ -93,19 +95,23 @@ A node:
- MUST send its own `announcement_signatures` message.
- If it receives `announcement_signatures` for the funding transaction:
- MUST respond with its own `announcement_signatures` message.
- If it has NOT previously received `announcement_signatures` for a splice transaction:
- MUST retransmit `splice_locked` for that splice transaction.
- After receiving the remote `splice_locked`:
- MUST send its `announcement_signatures` message.
A recipient node:
- If the `short_channel_id` is NOT correct:
- SHOULD send a `warning` and close the connection, or send an
`error` and fail the channel.
- If the `short_channel_id` doesn't match one of its funding transactions:
- SHOULD send a `warning`.
- If the `node_signature` OR the `bitcoin_signature` is NOT correct:
- MAY send a `warning` and close the connection, or send an
`error` and fail the channel.
- MAY send a `warning` and close the connection, or send an `error` and fail the channel.
- If it has sent AND received a valid `announcement_signatures` message:
- If the funding transaction has at least 6 confirmations:
- SHOULD queue the `channel_announcement` message for its peers.
- If it has not sent `channel_ready`:
- SHOULD defer handling the `announcement_signatures` until after it has sent `channel_ready`.
- If it has not sent `splice_locked` for the transaction matching this `short_channel_id`:
- SHOULD defer handling the `announcement_signatures` until after it has sent `splice_locked`.
### Rationale
@ -113,6 +119,12 @@ Channels must not be announced before the funding transaction has enough
confirmations, because a blockchain reorganization would otherwise invalidate
the `short_channel_id`.
When splicing is used, a `channel_announcement` is generated for every splice
transaction once both sides have sent `splice_locked`. This lets the network
know that the transaction spending a currently active channel is a splice and
not a closing transaction, and this channel can still be used with its updated
`short_channel_id`.
## The `channel_announcement` Message
This gossip message contains ownership information regarding a channel. It ties
@ -162,9 +174,18 @@ The origin node:
that the channel was opened within:
- for the _Bitcoin blockchain_:
- MUST set `chain_hash` value (encoded in hex) equal to `6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000`.
- MUST set `short_channel_id` to refer to the confirmed funding transaction,
as specified in [BOLT #2](02-peer-protocol.md#the-channel_ready-message).
- Note: the corresponding output MUST be a P2WSH, as described in [BOLT #3](03-transactions.md#funding-transaction-output).
- When announcing a channel creation:
- MUST set `short_channel_id` to refer to the confirmed funding transaction,
as specified in [BOLT #2](02-peer-protocol.md#the-channel_ready-message).
- When announcing a splice transaction:
- MUST set `short_channel_id` to refer to the confirmed splice transaction
for which `splice_locked` has been sent and received, as specified in
[BOLT #2](02-peer-protocol.md#the-splice_locked-message).
- SHOULD keep relaying payments that use the `short_channel_id`s of its
previous `channel_announcement`s.
- SHOULD send a new `channel_update` using the `short_channel_id` that
matches the latest `channel_announcement`.
- Note: the corresponding output MUST be a P2WSH, as described in [BOLT #3](03-transactions.md#funding-transaction-output).
- MUST set `node_id_1` and `node_id_2` to the public keys of the two nodes
operating the channel, such that `node_id_1` is the lexicographically-lesser of the
two compressed keys sorted in ascending lexicographic order.
@ -252,9 +273,11 @@ optional) features will have _odd_ feature bits, while incompatible features
will have _even_ feature bits
(["It's OK to be odd!"](00-introduction.md#glossary-and-terminology-guide)).
A delay of 12 blocks is used when forgetting a channel on funding output spend
as to permit a new `channel_announcement` to propagate which indicates this
channel was spliced.
A delay of 12 blocks is used when forgetting a channel after detecting that it
has been spent: this can allow a new `channel_announcement` to propagate to
indicate that this channel was spliced and not closed. Thanks to this delay,
payments can still be relayed on the channel while the splice transaction is
waiting for enough confirmations.
## The `node_announcement` Message

1
09-features.md
View file

@ -53,6 +53,7 @@ The Context column decodes as follows:
| 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] |
| 60/61 | `option_simple_close` | Simplified closing negotiation | IN | `option_shutdown_anysegwit` | [BOLT #2][bolt02-simple-close] |
| 62/63 | `option_splice` | Allows replacing the funding transaction with a new one | IN | | [BOLT #2](02-peer-protocol.md#channel-splicing) |
## Requirements

710
bolt02/splicing-test.md Normal file
View file

@ -0,0 +1,710 @@
# Splicing Tests
This file details various [splicing](../02-peer-protocol.md#channel-splicing) protocol flows.
We detail the exact flow of messages for each scenario, and highlight several edge cases that must be correctly handled by implementations.
## Table of Contents
* [Terminology](#terminology)
* [Test Vectors](#test-vectors)
* [Successful single splice](#successful-single-splice)
* [Multiple splices with concurrent `splice_locked`](#multiple-splices-with-concurrent-splice_locked)
* [Disconnection with one side sending `commit_sig`](#disconnection-with-one-side-sending-commit_sig)
* [Disconnection with both sides sending `commit_sig`](#disconnection-with-both-sides-sending-commit_sig)
* [Disconnection with one side sending `tx_signatures`](#disconnection-with-one-side-sending-tx_signatures)
* [Disconnection with both sides sending `tx_signatures`](#disconnection-with-both-sides-sending-tx_signatures)
* [Disconnection with both sides sending `tx_signatures` and channel updates](#disconnection-with-both-sides-sending-tx_signatures-and-channel-updates)
* [Disconnection with concurrent `splice_locked`](#disconnection-with-concurrent-splice_locked)
## Terminology
We call "active commitments" the set of valid commitment transactions to which updates (`update_add_htlc`, `update_fulfill_htlc`, `update_fail_htlc`, `update_fail_malformed_htlc`, `update_fee`) must be applied.
While a funding transaction is not locked (ie `splice_locked` hasn't been exchanged), updates must be valid for all active commitments.
When representing active commitments, we will only draw the corresponding funding transactions for simplicity.
The related commitment transaction simply spends that funding transaction.
For example, the following diagram displays the active commitments when we have an unconfirmed splice (`FundingTx2a`) and 2 RBF attempts for that splice (`FundingTx2b` and `FundingTx2c`).
We thus have 4 active commitments:
* the commitment spending `FundingTx1`
* the commitments spending each splice transaction (`FundingTx2a`, `FundingTx2b` and `FundingTx2c`)
```text
+------------+ +-------------+
| FundingTx1 |--------+------>| FundingTx2a |
+------------+ | +-------------+
|
| +-------------+
+------>| FundingTx2b |
| +-------------+
|
| +-------------+
+------>| FundingTx2c |
+-------------+
```
**Peers must always agree on the set of active commitments**, otherwise one side will expect signatures that the other side will not send, which will lead to force-closing the channel.
## Test Vectors
In the protocol flows below, we omit the `interactive-tx` messages that build the transaction.
The only `interactive-tx` messages we explicitly list are the consecutive `tx_complete` that mark the end of the `interactive-tx` construction.
We also assume that both peers use the same `commitment_number` for simplicity.
### Successful single splice
Let's warm up with the simplest possible flow: a splice transaction that confirms without any disconnection.
```text
Initial active commitments:
commitment_number = 10
+------------+
| FundingTx1 |
+------------+
Alice initiates a splice:
Alice Bob
| stfu |
|----------------------------->|
| stfu |
|<-----------------------------|
| splice_init |
|----------------------------->|
| splice_ack |
|<-----------------------------|
| |
| <interactive-tx> |
|<---------------------------->|
| |
| tx_complete |
|----------------------------->|
| tx_complete |
|<-----------------------------|
| commit_sig |
|----------------------------->|
| commit_sig |
|<-----------------------------|
| tx_signatures |
|----------------------------->|
| tx_signatures |
|<-----------------------------|
| | The channel is no longer quiescent at that point.
| | Active commitments:
| |
| | commitment_number = 10
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
| |
| update_add_htlc | Alice and Bob use the channel while the splice transaction is unconfirmed.
|----------------------------->|
| update_add_htlc |
|----------------------------->|
| commit_sig | batch_size = 2, funding_txid = FundingTx1, commitment_number = 11
|----------------------------->|
| commit_sig | batch_size = 2, funding_txid = FundingTx2, commitment_number = 11
|----------------------------->|
| revoke_and_ack |
|<-----------------------------|
| commit_sig | batch_size = 2, funding_txid = FundingTx1, commitment_number = 11
|<-----------------------------|
| commit_sig | batch_size = 2, funding_txid = FundingTx2, commitment_number = 11
|<-----------------------------|
| revoke_and_ack |
|----------------------------->|
| | Active commitments:
| |
| | commitment_number = 11
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
| |
| splice_locked | The splice transaction confirms.
|----------------------------->|
| splice_locked |
|<-----------------------------|
| | Active commitments:
| |
| | commitment_number = 11
| | +------------+
| | | FundingTx2 |
| | +------------+
| |
| update_add_htlc | Alice and Bob can use the channel and forget the previous FundingTx1.
|----------------------------->|
| commit_sig |
|----------------------------->|
| revoke_and_ack |
|<-----------------------------|
| commit_sig |
|<-----------------------------|
| revoke_and_ack |
|----------------------------->|
| | Active commitments:
| |
| | commitment_number = 12
| | +------------+
| | | FundingTx2 |
| | +------------+
```
### Multiple splices with concurrent `splice_locked`
Since nodes have different views of the blockchain, they may send `splice_locked` at slightly different times.
Moreover, nodes may send `splice_locked` concurrently with other channel updates, in which case they will receive some `commit_sig` messages for obsolete commitments.
This is fine: nodes know how many `commit_sig` messages to expect thanks to the `batch_size` field, and they can simply ignore `commit_sig` messages for which the `funding_txid` cannot be found in the active commitments.
```text
Initial active commitments:
commitment_number = 10
+------------+
| FundingTx1 |
+------------+
Alice initiates a splice:
Alice Bob
| stfu |
|----------------------------->|
| stfu |
|<-----------------------------|
| splice_init |
|----------------------------->|
| splice_ack |
|<-----------------------------|
| |
| <interactive-tx> |
|<---------------------------->|
| |
| tx_complete |
|----------------------------->|
| tx_complete |
|<-----------------------------|
| commit_sig |
|----------------------------->|
| commit_sig |
|<-----------------------------|
| tx_signatures |
|----------------------------->|
| tx_signatures |
|<-----------------------------|
| | Active commitments:
| |
| | commitment_number = 10
| | +------------+ +-------------+
| | | FundingTx1 |------->| FundingTx2a |
| | +------------+ +-------------+
| |
| stfu |
|----------------------------->|
| stfu |
|<-----------------------------|
| tx_init_rbf | Alice RBFs the splice attempt.
|----------------------------->|
| tx_ack_rbf |
|<-----------------------------|
| |
| <interactive-tx> |
|<---------------------------->|
| |
| tx_complete |
|----------------------------->|
| tx_complete |
|<-----------------------------|
| commit_sig |
|----------------------------->|
| commit_sig |
|<-----------------------------|
| tx_signatures |
|----------------------------->|
| tx_signatures |
|<-----------------------------|
| | Active commitments:
| |
| | commitment_number = 10
| | +------------+ +-------------+
| | | FundingTx1 |---+--->| FundingTx2a |
| | +------------+ | +-------------+
| | |
| | | +-------------+
| | +--->| FundingTx2b |
| | +-------------+
| |
| update_add_htlc | Alice and Bob use the channel while the splice transactions are unconfirmed.
|----------------------------->|
| update_add_htlc |
|----------------------------->|
| commit_sig | batch_size = 3, funding_txid = FundingTx1, commitment_number = 11
|----------------------------->|
| commit_sig | batch_size = 3, funding_txid = FundingTx2a, commitment_number = 11
|----------------------------->|
| commit_sig | batch_size = 3, funding_txid = FundingTx2b, commitment_number = 11
|----------------------------->|
| revoke_and_ack |
|<-----------------------------|
| commit_sig | batch_size = 3, funding_txid = FundingTx1, commitment_number = 11
|<-----------------------------|
| commit_sig | batch_size = 3, funding_txid = FundingTx2a, commitment_number = 11
|<-----------------------------|
| commit_sig | batch_size = 3, funding_txid = FundingTx2b, commitment_number = 11
|<-----------------------------|
| revoke_and_ack |
|----------------------------->|
| | Active commitments:
| |
| | commitment_number = 11
| | +------------+ +-------------+
| | | FundingTx1 |---+--->| FundingTx2a |
| | +------------+ | +-------------+
| | |
| | | +-------------+
| | +--->| FundingTx2b |
| | +-------------+
| |
| splice_locked | splice_txid = FundingTx2a
|----------------------------->|
| update_add_htlc |
|----------------------------->|
| commit_sig | batch_size = 3, funding_txid = FundingTx1, commitment_number = 12 -> this message will be ignored by Bob since FundingTx2a will be locked before the end of the batch
|----------------------------->|
| splice_locked | splice_txid = FundingTx2a
|<-----------------------------|
| commit_sig | batch_size = 3, funding_txid = FundingTx2a, commitment_number = 12
|----------------------------->|
| commit_sig | batch_size = 3, funding_txid = FundingTx2b, commitment_number = 12 -> this message can be ignored by Bob since FundingTx2a has been locked
|----------------------------->|
| revoke_and_ack |
|<-----------------------------|
| commit_sig |
|<-----------------------------|
| revoke_and_ack |
|----------------------------->|
| | Active commitments:
| |
| | commitment_number = 12
| | +-------------+
| | | FundingTx2b |
| | +-------------+
```
### Disconnection with one side sending `commit_sig`
In this scenario, a disconnection happens when one side has sent `commit_sig` but not the other.
```text
Initial active commitments:
commitment_number = 10
+------------+
| FundingTx1 |
+------------+
Alice initiates a splice, but disconnects before receiving Bob's tx_complete:
Alice Bob
| stfu |
|----------------------------->|
| stfu |
|<-----------------------------|
| splice_init |
|----------------------------->|
| splice_ack |
|<-----------------------------|
| |
| <interactive-tx> |
|<---------------------------->|
| |
| tx_complete |
|----------------------------->|
| tx_complete |
| X----------------------|
| commit_sig |
| X----------------------|
| | Active commitments for Alice:
| |
| | commitment_number = 10
| | +------------+
| | | FundingTx1 |
| | +------------+
| |
| | Active commitments for Bob:
| |
| | commitment_number = 10
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
| |
| channel_reestablish | next_funding_txid = null, next_commitment_number = 11, next_revocation_number = 10
|----------------------------->|
| channel_reestablish | next_funding_txid = FundingTx2, next_commitment_number = 10, next_revocation_number = 10
|<-----------------------------|
| tx_abort |
|----------------------------->|
| tx_abort |
|<-----------------------------|
| | Bob can safely forget the splice attempt because he hasn't sent tx_signatures.
| | Active commitments for Alice and Bob:
| |
| | commitment_number = 10
| | +------------+
| | | FundingTx1 |
| | +------------+
```
### Disconnection with both sides sending `commit_sig`
In this scenario, a disconnection happens when both sides have sent `commit_sig`.
They are able to resume the signatures exchange on reconnection.
In this example, Bob is supposed to send `tx_signatures` first.
```text
Initial active commitments:
commitment_number = 10
+------------+
| FundingTx1 |
+------------+
Alice initiates a splice, but disconnects before receiving Bob's commit_sig:
Alice Bob
| stfu |
|----------------------------->|
| stfu |
|<-----------------------------|
| splice_init |
|----------------------------->|
| splice_ack |
|<-----------------------------|
| |
| <interactive-tx> |
|<---------------------------->|
| |
| tx_complete |
|----------------------------->|
| tx_complete |
|<-----------------------------|
| commit_sig |
|--------------------X |
| commit_sig |
| X----------------------|
| | Active commitments:
| |
| | commitment_number = 10
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
| |
| channel_reestablish | next_funding_txid = FundingTx2, next_commitment_number = 10, next_revocation_number = 10
|----------------------------->|
| channel_reestablish | next_funding_txid = FundingTx2, next_commitment_number = 10, next_revocation_number = 10
|<-----------------------------|
| commit_sig |
|----------------------------->|
| commit_sig |
|<-----------------------------|
| tx_signatures |
|<-----------------------------|
| tx_signatures |
|----------------------------->|
| | Active commitments:
| |
| | commitment_number = 10
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
```
### Disconnection with one side sending `tx_signatures`
In this scenario, a disconnection happens when one side has sent `tx_signatures` but not the other.
They are able to resume the signatures exchange on reconnection.
```text
Initial active commitments:
commitment_number = 10
+------------+
| FundingTx1 |
+------------+
Alice initiates a splice, but disconnects before receiving Bob's tx_signatures:
Alice Bob
| stfu |
|----------------------------->|
| stfu |
|<-----------------------------|
| splice_init |
|----------------------------->|
| splice_ack |
|<-----------------------------|
| |
| <interactive-tx> |
|<---------------------------->|
| |
| tx_complete |
|----------------------------->|
| tx_complete |
|<-----------------------------|
| commit_sig |
|----------------------------->|
| commit_sig |
|<-----------------------------|
| tx_signatures |
| X----------------------|
| | Active commitments:
| |
| | commitment_number = 10
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
| |
| channel_reestablish | next_funding_txid = FundingTx2, next_commitment_number = 11, next_revocation_number = 10
|----------------------------->|
| channel_reestablish | next_funding_txid = FundingTx2, next_commitment_number = 11, next_revocation_number = 10
|<-----------------------------|
| tx_signatures |
|<-----------------------------|
| tx_signatures |
|----------------------------->|
| | Active commitments:
| |
| | commitment_number = 10
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
```
### Disconnection with both sides sending `tx_signatures`
In this scenario, a disconnection happens when both sides have sent `tx_signatures`, but one side has not received it.
They are able to resume the signatures exchange on reconnection.
```text
Initial active commitments:
commitment_number = 10
+------------+
| FundingTx1 |
+------------+
Alice initiates a splice, but disconnects before Bob receives her tx_signatures:
Alice Bob
| stfu |
|----------------------------->|
| stfu |
|<-----------------------------|
| splice_init |
|----------------------------->|
| splice_ack |
|<-----------------------------|
| |
| <interactive-tx> |
|<---------------------------->|
| |
| tx_complete |
|----------------------------->|
| tx_complete |
|<-----------------------------|
| commit_sig |
|----------------------------->|
| commit_sig |
|<-----------------------------|
| tx_signatures |
|<-----------------------------|
| tx_signatures |
|----------------------X |
| | Active commitments:
| |
| | commitment_number = 10
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
| |
| channel_reestablish | next_funding_txid = null, next_commitment_number = 11, next_revocation_number = 10
|----------------------------->|
| channel_reestablish | next_funding_txid = FundingTx2, next_commitment_number = 11, next_revocation_number = 10
|<-----------------------------|
| tx_signatures |
|----------------------------->|
| | Active commitments:
| |
| | commitment_number = 10
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
```
### Disconnection with both sides sending `tx_signatures` and channel updates
In this scenario, a disconnection happens when both sides have sent `tx_signatures`, but one side has not received it.
The second signer also sent a new signature for additional changes to apply after their `tx_signatures`.
They are able to resume the signatures exchange on reconnection and retransmit new updates.
```text
Initial active commitments:
commitment_number = 10
+------------+
| FundingTx1 |
+------------+
Alice initiates a splice, but disconnects before Bob receives her tx_signatures and new updates:
Alice Bob
| stfu |
|----------------------------->|
| stfu |
|<-----------------------------|
| splice_init |
|----------------------------->|
| splice_ack |
|<-----------------------------|
| |
| <interactive-tx> |
|<---------------------------->|
| |
| tx_complete |
|----------------------------->|
| tx_complete |
|<-----------------------------|
| commit_sig |
|----------------------------->|
| commit_sig |
|<-----------------------------|
| tx_signatures |
|<-----------------------------|
| tx_signatures |
|----------------------X |
| update_add_htlc |
|----------------------X |
| commit_sig | batch_size = 2, funding_txid = FundingTx1, commitment_number = 11
|----------------------X |
| commit_sig | batch_size = 2, funding_txid = FundingTx2, commitment_number = 11
|----------------------X |
| | Active commitments:
| |
| | commitment_number = 10
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
| |
| channel_reestablish | next_funding_txid = null, next_commitment_number = 11, next_revocation_number = 10
|----------------------------->|
| channel_reestablish | next_funding_txid = FundingTx2, next_commitment_number = 11, next_revocation_number = 10
|<-----------------------------|
| tx_signatures |
|----------------------------->|
| update_add_htlc |
|----------------------------->|
| commit_sig | batch_size = 2, funding_txid = FundingTx1, commitment_number = 11
|----------------------------->|
| commit_sig | batch_size = 2, funding_txid = FundingTx2, commitment_number = 11
|----------------------------->|
| revoke_and_ack |
|<-----------------------------|
| commit_sig | batch_size = 2, funding_txid = FundingTx1, commitment_number = 11
|<-----------------------------|
| commit_sig | batch_size = 2, funding_txid = FundingTx2, commitment_number = 11
|<-----------------------------|
| revoke_and_ack |
|----------------------------->|
| | Active commitments:
| |
| | commitment_number = 11
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
```
### Disconnection with concurrent `splice_locked`
In this scenario, disconnections happen while nodes are exchanging `splice_locked`.
The `splice_locked` message must be retransmitted on reconnection if it wasn't previously received.
When `last_funding_locked` is set, this lets nodes immediately lock the latest splice transaction.
```text
Initial active commitments:
+------------+
| FundingTx1 |
+------------+
Alice initiates a splice, but disconnections happen when exchanging splice_locked:
Alice Bob
| stfu |
|----------------------------->|
| stfu |
|<-----------------------------|
| splice_init |
|----------------------------->|
| splice_ack |
|<-----------------------------|
| |
| <interactive-tx> |
|<---------------------------->|
| |
| tx_complete |
|----------------------------->|
| tx_complete |
|<-----------------------------|
| commit_sig |
|----------------------------->|
| commit_sig |
|<-----------------------------|
| tx_signatures |
|<-----------------------------|
| tx_signatures |
|----------------------------->|
| splice_locked |
|---------------------X |
| | Active commitments:
| |
| | +------------+ +------------+
| | | FundingTx1 |------->| FundingTx2 |
| | +------------+ +------------+
| |
| channel_reestablish | next_funding_txid = null, your_last_funding_locked = funding_tx1, my_current_funding_locked = funding_tx2
|----------------------------->|
| channel_reestablish | next_funding_txid = null, your_last_funding_locked = funding_tx1, my_current_funding_locked = funding_tx1
|<-----------------------------|
| splice_locked |
|----------------------------->|
| splice_locked | At that point, Bob has locked funding_tx2, but Alice doesn't know it because she hasn't received splice_locked yet.
| X----------------------|
| |
| channel_reestablish | next_funding_txid = null, your_last_funding_locked = funding_tx1, my_current_funding_locked = funding_tx2
|----------------------------->|
| channel_reestablish | next_funding_txid = null, your_last_funding_locked = funding_tx2, my_current_funding_locked = funding_tx2
|<-----------------------------|
| | Alice doesn't need to retransmit splice_locked, since Bob's your_last_funding_locked indicates that he received it.
| | Bob's my_current_funding_locked lets Alice know that Bob has locked funding_tx2 while they were disconnected and will send his splice_locked.
| | She can thus immediately lock it as well even though she hasn't received yet Bob's splice_locked.
| |
| | Active commitments:
| |
| | +------------+
| | | FundingTx2 |
| | +------------+
| |
| update_add_htlc |
|----------------------------->|
| commit_sig | Alice doesn't need to sent commit_sig for funding_tx1 since funding_tx2 was locked.
|----------------------------->|
| splice_locked | Bob's splice_locked is sent concurrently with Alice's update_add_htlc and commit_sig: this is fine.
|<-----------------------------|
| revoke_and_ack |
|<-----------------------------|
| commit_sig |
|<-----------------------------|
| revoke_and_ack |
|----------------------------->|
```