From 1d25dd1940d8f4d637536969d3eb90be9706a6b2 Mon Sep 17 00:00:00 2001 From: t-bast Date: Tue, 9 Sep 2025 13:59:39 +0200 Subject: [PATCH 1/3] Explicit `commit_sig` retransmission for `interactive-tx` When disconnecting in the middle of the signing steps of an `interactive-tx` transaction, we must retransmit signatures on reconnection to complete the `interactive-tx` protocol. Nodes first exchange `commitment_signed`, followed by `tx_signatures` once they have both sent and received `commitment_signed`. We previously always retransmitted `commitment_signed`, even when our peer had already received it. We now include an explicit bitfield that lets nodes request `commitment_signed` if they haven't received it. Note that this is a breaking change, and we are thus changing the TLV type to make it easier to detect. In practice it should be fine, since only `eclair` and `cln` have shipped support for dual funding, and those two implementations are already incompatible on reconnection because `eclair` implements #1214 but `cln` doesn't. This edge case only creates an issue when nodes disconnect after exchanging `tx_complete` but before receiving signatures, which should happen very infrequently. Replaces #1214. --- 02-peer-protocol.md | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 009555d0c..9571dda28 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -2653,9 +2653,10 @@ messages are), they are independent of requirements here. 1. `tlv_stream`: `channel_reestablish_tlvs` 2. types: - 1. type: 0 (`next_funding`) + 1. type: 1 (`next_funding`) 2. data: * [`sha256`:`next_funding_txid`] + * [`byte`:`retransmit_flags`] `next_commitment_number`: A commitment number is a 48-bit incrementing counter for each commitment transaction; counters @@ -2663,6 +2664,14 @@ are independent for each peer in the channel and start at 0. They're only explicitly relayed to the other node in the case of re-establishment, otherwise they are implicit. +The `next_funding.retransmit_flags` bitfield is used to let the +receiving peer know which messages they must retransmit for the +corresponding `next_funding_txid` after the reconnection: + +| Bit Position | Name | +| ------------- | --------------------| +| 0 | `commitment_signed` | + ### Requirements A funding node: @@ -2709,11 +2718,17 @@ The sending node: - MUST set `your_last_per_commitment_secret` to the last `per_commitment_secret` it received - if it has sent `commitment_signed` for an interactive transaction construction but it has not received `tx_signatures`: + - MUST include the `next_funding` TLV. - MUST set `next_funding_txid` to the txid of that interactive transaction. + - if it has not received `commitment_signed` for this `next_funding_txid`: + - MUST set the `commitment_signed` bit in `retransmit_flags`. - otherwise: - - MUST NOT set `next_funding_txid`. + - MUST NOT include the `next_funding` TLV. A node: + - if `next_commitment_number` is zero: + - MUST immediately fail the channel and broadcast any relevant latest commitment + transaction. - if `next_commitment_number` is 1 in both the `channel_reestablish` it sent and received: - MUST retransmit `channel_ready`. @@ -2726,12 +2741,8 @@ A node: the last `commitment_signed` message the receiving node has sent: - MUST reuse the same commitment number for its next `commitment_signed`. - otherwise: - - if `next_commitment_number` is not 1 greater than the - commitment number of the last `commitment_signed` message the receiving - node has sent: - - SHOULD send an `error` and fail the channel. - - if it has not sent `commitment_signed`, AND `next_commitment_number` - is not equal to 1: + - if `next_commitment_number` is not equal to the commitment number of the + next `commitment_signed` the receiving node will send: - SHOULD send an `error` and fail the channel. - if `next_revocation_number` is equal to the commitment number of the last `revoke_and_ack` the receiving node sent, AND the receiving node @@ -2761,10 +2772,11 @@ A node: - SHOULD send an `error` and fail the channel. A receiving node: - - if `next_funding_txid` is set: + - if the `next_funding` TLV is set: - if `next_funding_txid` matches the latest interactive funding transaction: - if it has not received `tx_signatures` for that funding transaction: - - MUST retransmit its `commitment_signed` for that funding transaction. + - if the `commitment_signed` bit is set in `retransmit_flags`: + - 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. @@ -2853,7 +2865,7 @@ transaction to the chain. The other node should wait for that `error` to give the fallen-behind node an opportunity to fix its state first (e.g by restarting with a different backup). -`next_funding_txid` allows peers to finalize the signing steps of an +The `next_funding` TLV allows peers to finalize the signing steps of an 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. From 314e79e3c8f97822985739525c94dcba738b504e Mon Sep 17 00:00:00 2001 From: t-bast Date: Tue, 16 Dec 2025 09:33:42 +0100 Subject: [PATCH 2/3] fixup! Explicit `commit_sig` retransmission for `interactive-tx` --- 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 9571dda28..5a307d0d3 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -2742,7 +2742,7 @@ A node: - MUST reuse the same commitment number for its next `commitment_signed`. - otherwise: - if `next_commitment_number` is not equal to the commitment number of the - next `commitment_signed` the receiving node will send: + next `commitment_signed` the receiving node would send: - SHOULD send an `error` and fail the channel. - if `next_revocation_number` is equal to the commitment number of the last `revoke_and_ack` the receiving node sent, AND the receiving node From 7646fc2ed2ada63cfc24eb1c772eccf2b9ada159 Mon Sep 17 00:00:00 2001 From: t-bast Date: Tue, 16 Dec 2025 16:16:59 +0100 Subject: [PATCH 3/3] fixup! Explicit `commit_sig` retransmission for `interactive-tx` --- 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 5a307d0d3..023bf0e88 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -2742,7 +2742,7 @@ A node: - MUST reuse the same commitment number for its next `commitment_signed`. - otherwise: - if `next_commitment_number` is not equal to the commitment number of the - next `commitment_signed` the receiving node would send: + next `commitment_signed` that the receiving node would send: - SHOULD send an `error` and fail the channel. - if `next_revocation_number` is equal to the commitment number of the last `revoke_and_ack` the receiving node sent, AND the receiving node