RBF splice funding transactions by jkczyz · Pull Request #4427 · lightningdevkit/rust-lightning

jkczyz · 2026-02-19T17:00:57Z

After a splice has been negotiated but hasn't been locked, its fee rate may be bumped using replace-by-fee (RBF). This requires the channel to re-enter quiescence upon which tx_init_rbf / tx_ack_rbf are exchanged and the interactive-tx constructor protocol commences as usual.

This PR adds support for initiating and accepting RBF attempts, as well as contributing to the attempt as an acceptor when losing the quiescence tie breaker, assuming the initiator's fee rate allows for it without needing to re-run coin selection. Instead, the difference in fee rate may be fine if not paying for common fields and shared input / outputs as the acceptor allows for it or if the change output (if any) can be adjusted accordingly.

TODO for follow-up PRs:

expose outstanding splicing / RBF attempts
refactor feerate in FundingTemplate to be min_feerate and have user supply it in FundingContribution builders
~~have RBF acceptor w/o QuiescentAction reuse any contributions from previous attempts~~
initiate RBF with splice_channel contribution if splice not yet locked
make sure DiscardFunding is generated in edge cases

Based on #4416

ldk-reviews-bot · 2026-02-19T17:01:01Z

👋 I see @TheBlueMatt was un-assigned.
If you'd like another reviewer assignment, please click here.

codecov · 2026-02-24T02:26:53Z

Codecov Report

❌ Patch coverage is 78.27427% with 141 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.07%. Comparing base (90b79e4) to head (eb2ab08).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/ln/channel.rs	81.58%	82 Missing and 13 partials ⚠️
lightning/src/ln/channelmanager.rs	64.51%	36 Missing and 8 partials ⚠️
lightning/src/ln/funding.rs	50.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4427      +/-   ##
==========================================
+ Coverage   85.97%   86.07%   +0.10%     
==========================================
  Files         159      159              
  Lines      104722   105727    +1005     
  Branches   104722   105727    +1005     
==========================================
+ Hits        90030    91009     +979     
+ Misses      12191    12185       -6     
- Partials     2501     2533      +32

Flag	Coverage Δ
tests	`86.07% <78.27%> (+0.10%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-reviews-bot · 2026-03-02T14:24:48Z

🔔 1st Reminder

Hey @TheBlueMatt @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-02T14:24:50Z

🔔 1st Reminder

Hey @TheBlueMatt @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

When a splice funding transaction has been negotiated but not yet confirmed, either party may initiate RBF to bump the feerate. This enables the acceptor to handle such requests, allowing continued progress toward on-chain confirmation of splices in rising fee environments. Only the acceptor side is implemented; the acceptor does not contribute funds beyond the shared funding input. The initiator side (sending tx_init_rbf and handling tx_ack_rbf) is left for a follow-up. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

ldk-reviews-bot · 2026-03-04T14:25:20Z

🔔 2nd Reminder

Hey @TheBlueMatt @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-03-04T14:25:22Z

🔔 2nd Reminder

Hey @TheBlueMatt @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

TheBlueMatt

Basically there.

TheBlueMatt · 2026-03-04T12:38:23Z

lightning/src/ln/channel.rs

+
+	/// Whether we (the holder) initiated the current quiescence session.
+	/// Set when quiescence is established, cleared when quiescence ends.
+	holder_is_quiescence_initiator: bool,


We avoided this for splicing (well, had it then removed it), and I think we can do the same here - in validate_splice_init we only check if there's a pending splice, as if we were the quiescence initiator we'd have set one immediately on entering quiescence. We can't just check for pending splice, ofc, but can we just check if there's a funding negotiation?

Yeah, @wpaulino mentioned this to me offline last week, but I haven't had a moment to update yet. And looks like we are already checking, too.

TheBlueMatt · 2026-03-04T12:39:29Z

lightning/src/ln/channel.rs

+			));
+		}
+
+		if self.context.minimum_depth(&self.funding) == Some(0) {


Is this mandated by the spec? I mean its probably right for now but long-term it would be nice to separate "chanel was opened 0conf" from "channel does 0conf splicing"

Yeah, it's in the spec, and IIRC we alway consider zero-conf channels to use zero-conf splices.

The receiving node: - If `option_zeroconf` has been negotiated: - MUST send a `warning` and close the connection or send an `error` and fail the channel.

Ugh, how annoying. Its something we should try to follow up on imo but certainly not in this PR.

TheBlueMatt · 2026-03-04T12:41:55Z

lightning/src/ln/channel.rs

+			)));
+		}
+
+		if pending_splice.received_funding_txid.is_some() {


Shouldn't we also check if we sent a splice_locked?

Hmm... not according to the spec. I suppose the we could have not seen a re-org yet?

Hmm, the inverse could be true too, though. They locked then saw a reorg and want to RBF but can't cause they locked. It seems like allowing this does more harm than good (implies we'll do a splice that will likely fail) and most likely its because of a bug not because of a weird reorg edge case?

Added the checks and reached out to tbast about this.

lightning/src/ln/channel.rs

TheBlueMatt · 2026-03-04T12:52:53Z

lightning/src/ln/channel.rs

+			));
+		}
+
+		if pending_splice.sent_funding_txid.is_some() {


Similarly here, shouldn't we fail if the counterparty sent a splice_locked?

Perhaps a similar argument regarding re-orgs?

lightning/src/ln/channelmanager.rs

TheBlueMatt · 2026-03-04T14:48:26Z

lightning/src/ln/channel.rs

+		})
+	}
+
+	fn validate_tx_ack_rbf(&self, msg: &msgs::TxAckRbf) -> Result<FundingScope, ChannelError> {


It does feel like there's some room to DRY up the RBF and splice logic somewhat. They're not 1-to-1 identical and generally not super long methods, but if you wouldn't mind doing (or asking claude to do) a pass to see what can be DRY'd I'd appreciate it. Definitely for the ack handling they're really close.

Done! tell me what you think.

Thanks, LGTM. Is there a similar step we could do for the init handling as well?

Done and worked the eariler refactor a little to match.

lightning/src/ln/channel.rs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fixup! Accept tx_init_rbf for pending splice transactions Remove redundant `holder_is_quiescence_initiator` field from `FundedChannel`. Checking `pending_splice.funding_negotiation.is_some()` already covers this case since `send_splice_init` is called in the same `stfu()` handler that establishes quiescence, immediately setting `funding_negotiation = Some(AwaitingAck)`. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fixup! Accept tx_init_rbf for pending splice transactions Remove unnecessary debug_assert!(false) in internal_tx_init_rbf; unreachable_no_such_peer already conveys the intent. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Extract resolve_queued_contribution and FundingNegotiation::for_acceptor helpers to deduplicate the shared head and tail of the splice_init and tx_init_rbf acceptor code paths. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The channel monitor previously rejected any new pending funding when one already existed. This prevented adding RBF candidates for a pending splice since each candidate needs its own pending funding entry. Relax the check to only reject new pending funding when its splice parent differs from existing entries, allowing multiple RBF candidates that compete to confirm the same splice. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Expose ChannelManager::rbf_channel as the entry point for bumping the feerate of a pending splice funding transaction. Like splice_channel, it returns a FundingTemplate to be completed and passed to funding_contributed. Validates that a pending splice exists with at least one negotiated candidate, no active funding negotiation, and that the new feerate satisfies the 25/24 increase rule required by the spec. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

When the quiescence initiator has a pending splice and enters the stfu handler with a QuiescentAction::Splice, send tx_init_rbf to bump the existing splice's feerate rather than starting a new splice_init. This reuses the same QuiescentAction::Splice variant for both initial splices and RBF attempts -- the stfu handler distinguishes them by checking whether pending_splice already exists. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

After sending tx_init_rbf, the initiator receives tx_ack_rbf from the acceptor. Implement the handler to validate the response and begin interactive transaction construction for the RBF funding transaction. Only clear the interactive signing session in `reset_pending_splice_state` when the current funding negotiation is in `AwaitingSignatures`. When an earlier round completed signing and a later RBF round is in `AwaitingAck` or `ConstructingTransaction`, the session belongs to the prior round and must be preserved. Otherwise, disconnecting mid-RBF would destroy the completed prior round's signing session and fire a false debug assertion. Update test_splice_rbf_acceptor_basic to exercise the full initiator flow: rbf_channel → funding_contributed → STFU exchange → tx_init_rbf → tx_ack_rbf → interactive TX → signing → mining → splice_locked. This replaces the previous test that manually constructed tx_init_rbf. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…itiator Add FundingNegotiation::for_initiator as a parallel to for_acceptor, and PendingFunding::take_awaiting_ack_context to extract the context from AwaitingAck at each call site. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove unnecessary debug_assert in internal_tx_ack_rbf since the unreachable_no_such_peer helper already handles the missing peer case consistently with other message handlers. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Previously, the tx_init_rbf acceptor always contributed zero to the RBF transaction. This is incorrect when both parties try to RBF simultaneously and one loses the quiescence tie-breaker — the loser becomes the acceptor but still has a pending QuiescentAction::Splice with inputs/outputs that should be included in the RBF transaction. Consume the acceptor's QuiescentAction in the tx_init_rbf handler, just as is already done in the splice_init handler, and report the contribution in the TxAckRbf response.

When the counterparty initiates an RBF and we have no new contribution queued via QuiescentAction, we must re-use our prior contribution so that our splice is not lost. Track contributions in a new field on PendingFunding so the last entry can be re-used in this scenario. Each entry stores the feerate-adjusted version because that reflects what was actually negotiated and allows correct feerate re-adjustment on subsequent RBFs. Only explicitly provided contributions (from a QuiescentAction) append to the vec. Re-used contributions are replaced in-place with the version adjusted for the new feerate so they remain accurate for further RBF rounds, without growing the vec. Add test_splice_rbf_acceptor_recontributes to verify that when the counterparty initiates an RBF and we have no new QuiescentAction queued, our prior contribution is automatically re-used so the splice is preserved. Add test_splice_rbf_recontributes_feerate_too_high to verify that when the counterparty RBFs at a feerate too high for our prior contribution to cover, the RBF is rejected rather than proceeding without our contribution. Add test for sequential RBF splice attempts Add test_splice_rbf_sequential that exercises three consecutive RBF rounds on the same splice (initial → RBF lightningdevkit#1 → RBF lightningdevkit#2) to verify: - Each round requires the 25/24 feerate increase (253 → 264 → 275) - DiscardFunding events reference the correct funding txid from each replaced candidate - The final RBF splice can be mined and splice_locked successfully Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

When funding_contributed is called while a splice negotiation is already in progress, unique contributions are computed to determine what to return via FailSplice or DiscardFunding. Without considering negotiated candidates stored in PendingFunding::contributions, UTXOs locked in earlier candidates could be incorrectly returned as reclaimable. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

SpliceFundingFailed events return contributed inputs and outputs to the user so they can unlock the associated UTXOs. When an RBF attempt is in progress, inputs/outputs already consumed by prior contributions must be excluded to avoid the user prematurely unlocking UTXOs that are still needed by the active funding negotiation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Replace the generic error handling in splice_init with explicit matching on FeeRateAdjustmentError variants: - FeeRateTooLow: initiator's feerate is below our minimum. Proceed without contribution and preserve QuiescentAction for an RBF retry at our preferred feerate. - FeeRateTooHigh: initiator's feerate exceeds our maximum and would consume too much of our change output. Reject the splice with WarnAndDisconnect. - BudgetInsufficient: our fee budget can't cover the acceptor's fair fee at this feerate. Proceed without contribution. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…play Move behavioral suffixes ("proceeding without contribution") into the Display impl for non-fatal FeeRateAdjustmentError variants, allowing the match in splice_init to collapse from 3 Err arms to 2 with a common log prefix. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Apply the same explicit FeeRateAdjustmentError handling to the tx_init_rbf acceptor path as was done for splice_init: - TooLow: proceed without queued contribution, preserve QuiescentAction for an RBF retry at our preferred feerate. - TooHigh: reject with WarnAndDisconnect. - BudgetInsufficient: proceed without queued contribution. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

TheBlueMatt · 2026-03-05T21:04:21Z

lightning/src/ln/channel.rs

+				match c.net_value_for_acceptor_at_feerate(feerate, holder_balance.unwrap()) {
+					Ok(net_value) => Some(net_value),
+					Err(e @ FeeRateAdjustmentError::FeeRateTooHigh { .. }) => {
+						return Err(ChannelError::WarnAndDisconnect(format!(


Oh I missed this. Why are we rejecting the entire splice if the feerate is too high? I guess it implies we won't be able to RBF to add our additions immediately (because the feerate will be too high for us) but it seems kinda antisocial to reject the splice entirely.

Our contributions may have been from the last round (initial splice or RBF attempt) not because of a lost tie-breaker. So if our counterparty initiates RBF here with a fee rate we aren't comfortable with, we'd effectively drop our contribution if we didn't reject. So we'd either need to go back to the user and have them approve the higher fee rate / select new coins (not possible currently) or wait for the splice to lock before starting a new splice.

Oh, duh, I think I had seen that and concluded the same. I'm tired today 🤦

wpaulino · 2026-03-05T22:38:34Z

lightning/src/ln/channel.rs

+
+	/// The feerate used in the last successfully negotiated funding transaction.
+	/// Used for validating the 25/24 feerate increase rule on RBF attempts.
+	last_funding_feerate_sat_per_1000_weight: Option<u32>,


Can't we just use the last one in candidates?

wpaulino · 2026-03-05T22:43:17Z

lightning/src/ln/channel.rs

+			)));
+		}
+
+		let first_candidate = match pending_splice.negotiated_candidates.first() {


Shouldn't this be the last candidate?

wpaulino · 2026-03-05T22:44:26Z

lightning/src/ln/channel.rs

+		// Check the 25/24 feerate increase rule
+		let prev_feerate =
+			pending_splice.last_funding_feerate_sat_per_1000_weight.unwrap_or_else(|| {
+				fee_estimator.bounded_sat_per_1000_weight(ConfirmationTarget::UrgentOnChainSweep)


This should be unreachable, right?

wpaulino · 2026-03-05T22:49:48Z

lightning/src/chain/channelmonitor.rs

 		if let Some(parent_funding_txid) = channel_parameters.splice_parent_funding_txid.as_ref() {
-			// Only one splice can be negotiated at a time after we've exchanged `channel_ready`
-			// (implying our funding is confirmed) that spends our currently locked funding.
-			if !self.pending_funding.is_empty() {


This made sure a dual-funded channel became locked prior to allowing a splice to happen.

wpaulino · 2026-03-05T23:04:55Z

lightning/src/ln/splicing_tests.rs

+		let discard_txids: Vec<_> = events[1..]
+			.iter()
+			.map(|e| match e {
+				Event::DiscardFunding { funding_info: FundingInfo::Tx { transaction }, .. } => {


Shouldn't we be getting the contribution variant?

wpaulino · 2026-03-05T23:12:44Z

lightning/src/ln/splicing_tests.rs

+		&[first_splice_tx.compute_txid()],
+	);
+
+	// Clean up old watched outpoints.


Do this in lock_rbf_splice_after_blocks like we do with lock_splice_after_blocks?

wpaulino · 2026-03-05T23:13:33Z

lightning/src/ln/splicing_tests.rs

+	expect_splice_pending_event(&nodes[1], &node_id_0);
+
+	// Step 12: Mine, lock, and verify DiscardFunding for the replaced splice candidate.
+	lock_rbf_splice_after_blocks(


Would be nice to not have a separate version to lock_splice_after_blocks and instead add an argument is_rbf

wpaulino · 2026-03-05T23:14:44Z

lightning/src/ln/channel.rs

+		self.contributions.iter().flat_map(|c| c.contributed_inputs())
+	}
+
+	fn contributed_outputs(&self) -> impl Iterator<Item = &TxOut> + '_ {


Reminder to filter by script_pubkey instead. IIRC you also mentioned that the change output may not be included here?

wpaulino · 2026-03-05T23:19:46Z

lightning/src/ln/channel.rs

 	MAX_LOCAL_BREAKDOWN_TIMEOUT, MIN_CLTV_EXPIRY_DELTA,
 };
-use crate::ln::funding::{FundingContribution, FundingTemplate, FundingTxInput};
+use crate::ln::funding::{


Commit 759da6a still refers to "fee budget"

wpaulino · 2026-03-05T23:21:25Z

lightning/src/ln/funding.rs

 pub(super) enum FeeRateAdjustmentError {
 	/// The counterparty's proposed feerate is below `min_feerate`, which was used as the feerate
-	/// during coin selection.
+	/// during coin selection. We'll retry via RBF at our preferred feerate.


Commit 9c91289 only has test code but the message makes it seem like we're changing actual code behavior

jkczyz self-assigned this Feb 19, 2026

jkczyz added this to Weekly Goals Feb 19, 2026

jkczyz requested review from TheBlueMatt and wpaulino February 19, 2026 17:04

jkczyz force-pushed the 2026-02-splicing-rbf branch from 1552b89 to 08c05f6 Compare February 23, 2026 22:54

jkczyz force-pushed the 2026-02-splicing-rbf branch from 08c05f6 to 97858df Compare February 25, 2026 18:18

jkczyz force-pushed the 2026-02-splicing-rbf branch 3 times, most recently from 4aaa312 to d40306c Compare March 4, 2026 04:35

jkczyz force-pushed the 2026-02-splicing-rbf branch from d40306c to f76abb6 Compare March 4, 2026 05:44

TheBlueMatt reviewed Mar 4, 2026

View reviewed changes

jkczyz force-pushed the 2026-02-splicing-rbf branch from f76abb6 to eb2ab08 Compare March 5, 2026 07:10

jkczyz marked this pull request as ready for review March 5, 2026 07:10

jkczyz requested a review from TheBlueMatt March 5, 2026 07:11

TheBlueMatt removed their request for review March 5, 2026 14:52

jkczyz and others added 8 commits March 5, 2026 11:21

f - Also check sent_funding_txid in validate_tx_init_rbf

7384231

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

f - DRY up splice_init and tx_init_rbf acceptor paths

77071bb

Extract resolve_queued_contribution and FundingNegotiation::for_acceptor helpers to deduplicate the shared head and tail of the splice_init and tx_init_rbf acceptor code paths. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

f - Also check received_funding_txid in can_initiate_rbf

0133f7d

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jkczyz and others added 13 commits March 5, 2026 11:21

f - Extract awaiting_ack_context and begin_funding_negotiation helpers

99b2c19

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

f - Use specific expect messages in tx_ack_rbf and splice_ack

c97e2e0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

f - Add test_splice_rbf_not_quiescence_initiator test

d7a7d51

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

jkczyz force-pushed the 2026-02-splicing-rbf branch from eb2ab08 to 9c91289 Compare March 5, 2026 17:24

TheBlueMatt reviewed Mar 5, 2026

View reviewed changes

wpaulino reviewed Mar 5, 2026

View reviewed changes

Conversation

jkczyz commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ldk-reviews-bot commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ldk-reviews-bot commented Mar 2, 2026

Uh oh!

ldk-reviews-bot commented Mar 2, 2026

Uh oh!

ldk-reviews-bot commented Mar 4, 2026

Uh oh!

ldk-reviews-bot commented Mar 4, 2026

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkczyz commented Feb 19, 2026 •

edited

Loading

ldk-reviews-bot commented Feb 19, 2026 •

edited

Loading

codecov bot commented Feb 24, 2026 •

edited

Loading

TheBlueMatt Mar 5, 2026 •

edited

Loading