Add `FundingNeeded` event for splicing #4290

jkczyz · 2025-12-18T16:11:08Z

Rather than requiring the user to pass FundingTxInputs when initiating a splice, generate a FundingNeeded event once the channel has become quiescent. This simplifies error handling and UTXO / change address clean-up by consolidating it in SpliceFailed event handling.

Later, this event will be used for opportunistic contributions (i.e., when the counterparty wins quiescence or initiates), dual-funding, and RBF.

Based on #4261.

This is still fairly rough. It does not yet include any code for creating a FundingNegotiationContext from a FundingContribution. The former may need to a dedicated struct instead so that any data needed from ChannelManager or ChannelContext can be produced internally. Alternatively, that data could be included in FundingContribution, but it would need to be serializable.

ldk-reviews-bot · 2025-12-18T16:11:11Z

👋 Thanks for assigning @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

jkczyz · 2026-01-12T18:03:27Z

@TheBlueMatt @wpaulino Looking for some high-level feedback on the API introduced in the last commit. In summary:

User passes SpliceContribution -- which no longer contains any FundingTxInputs -- to ChannelManager::splice_channel
Upon quiescence LDK generates a FundingNeeded event which contains a FundingTemplate
User calls FundingTemplate::build or FundingTemplate::build_sync with a WalletSource or WalletSourceSync, respectively, to produce a FundingContribution
User passes FundingContribution -- which contains the FundingTxInputs -- to ChannelManager::funding_contributed
LDK validates that the FundingContribution can pay for inputs / outputs, causing LDK to either send splice_init or produce a SpliceFailed event.

The same mechanism can be used later for contributing inputs for counterparty-initiated splices or v2 channel opens since FundingTemplate and FundingContribution contains the context.

Test code still needs to be fixed up, and change_script generation will follow in another commit.

wpaulino

The API design LGTM, though there's one issue with WalletSource. One thing users need to keep in mind now is that from the moment they receive FundingNeeded, they need to act quickly to ensure the counterparty doesn't disconnect due to quiescence taking too long.

wpaulino · 2026-01-12T19:37:10Z

lightning/src/events/bump_transaction/sync.rs

 	fn list_confirmed_utxos(&self) -> Result<Vec<Utxo>, ()>;
+
+	///
+	fn select_confirmed_utxos(


Adding this here now requires implementers to satisfy this method when, in the context of anchor channels, WalletSource is only intended to be used such that we perform coin selection on behalf of the user. Ideally, we also give users the option between choosing WalletSource/CoinSelectionSource when funding channels.

Right, I guess I'm a bit confused why we can't use select_confirmed_utxos as-is? Indeed the claim_id is annoying, but we can make that either an enum across a ClaimId and some unit value describing a splice or just make it an Option. Aside from that it seems to be basically what we want.

Adding this here now requires implementers to satisfy this method when, in the context of anchor channels, WalletSource is only intended to be used such that we perform coin selection on behalf of the user. Ideally, we also give users the option between choosing WalletSource/CoinSelectionSource when funding channels.

Hmm... I see. Would a separate trait be desirable? Also, see my reply to @TheBlueMatt below.

Right, I guess I'm a bit confused why we can't use select_confirmed_utxos as-is? Indeed the claim_id is annoying, but we can make that either an enum across a ClaimId and some unit value describing a splice or just make it an Option. Aside from that it seems to be basically what we want.

The return value also isn't compatible. It contains Utxos but we also need the previous tx and sequence number as part of each FundingTxInput. Though its constructor will give a default sequence number.

We could change CoinSelection to use FundingTxInput instead of Utxo, but that would be odd for use with the anchor context.

Honestly that seems fine to me? We expect ~all of our users to want to use splicing, which implies they need to support the "return coin selection with full transactions" interface. So what if anchors throw away some of that data?

If we feel strongly about it we can add a new trait method that does return the full transactions and provide a default implementation for the current method so that those that really want to avoid always fetching the transaction data can.

Right, I don't have a strong opinion, but note that Wallet's implementation of CoinSelectionSource::select_confirmed_utxos delegates to WalletSource::list_confirmed_utxos. So it might be expensive to use that abstraction. @wpaulino WDYT?

I was thinking of keeping CoinSelectionSource the same (with the full transaction data in the response, or with the default-impl-method described above) but changing WalletSource so that we don't have to fetch all previous-transactions at the start.

Yeah, Wallet wraps a WalletSource and implements CoinSelectionSource by listing all the UTXOs and selecting from them. So WalletSource's interface would remain unchanged while CoinSelection would use FundingTxInput instead of Utxo. Which I guess means FundingTemplate::build should actually take a CoinSelectionSource.

Seems reasonable to require a sequence number in the response for that as well, even for anchors?

Hmm... in WalletSource::list_confirmed_utxos by adding a field to Utxto (and removing it from FundingTxInput)? Or by having the CoinSelectionSource implementation fill it in on FundingTxInput?

So WalletSource's interface would remain unchanged

Wouldn't we need a WalletSource::get_previous_transaction_for_utxo method to fetch the full tx data for the UTXOs we selected?

Hmm... in WalletSource::list_confirmed_utxos by adding a field to Utxto (and removing it from FundingTxInput)? Or by having the CoinSelectionSource implementation fill it in on FundingTxInput?

ISTM we should replace Utxo with FundingTxInput since FundingTxInput has strictly more fields (it contains a Utxo!) and we'd move to returning FundingTxInput from the trait.

Wouldn't we need a WalletSource::get_previous_transaction_for_utxo method to fetch the full tx data for the UTXOs we selected?

Right, we need another method for that.

ISTM we should replace Utxo with FundingTxInput since FundingTxInput has strictly more fields (it contains a Utxo!) and we'd move to returning FundingTxInput from the trait.

The question is more what should be setting Sequence? Either:

(1) Move it to Utxo and have WalletSource::list_confirmed_utxos set it since it returns Vec<Utxo>.
(2) Have CoinSelectionSource::select_confirmed_utxos set it since CoinSelection would now contain Vec<FundingTxInput>

We just can't replace Utxo with FundingTxInput in WalletSource::list_confirmed_utxos since we don't want to return the previous tx there.

(1) Move it to Utxo and have WalletSource::list_confirmed_utxos set it since it returns Vec.

Presumably this. No reason to want it to not be possible in WalletSource.

Done as discussed here and offline. I'm in the middle of updating the tests, but I've pushed an update for now.

TheBlueMatt

Aside from the above which-interface question I think the API is good.

ldk-reviews-bot · 2026-01-15T00:28:47Z

🔔 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-01-15T00:28: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-01-17T00:29:31Z

🔔 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-01-17T00:29:32Z

🔔 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-01-19T00:29:48Z

🔔 3rd 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-01-19T00:29:50Z

🔔 3rd 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.

A forthcoming commit will change CoinSelection to include FundingTxInput instead of Utxo, though the former will probably be renamed. This is so CoinSelectionSource can be used when funding a splice. Further updating WalletSource to use FundingTxInput is not desirable, however, as it would result in looking up each confirmed UTXOs previous transaction even if it is not selected. See Wallet's implementation of CoinSelectionSource, which delegates to WalletSource for listing all confirmed UTXOs. This commit moves FundingTxInput::sequence to Utxo, and thus the responsibility for setting it to WalletSource implementations. Doing so will allow Wallet's CoinSelectionSource implementation to delegate looking up previous transactions to WalletSource without having to explicitly set the sequence on any FundingTxInput.

In order to reuse CoinSelectionSource for splicing, the previous transaction of each UTXO is needed. Update CoinSelection to use FundingTxInput (renamed to ConfirmedUtxo) so that it is available. This requires adding a method to WalletSource to look up a previous transaction for a UTXO. Otherwise, Wallet's implementation of CoinSelectionSource would need WalletSource to include the previous transactions when listing confirmed UTXOs to select from. But this would be inefficient since only some UTXOs are selected.

jkczyz · 2026-01-20T19:20:35Z

lightning/src/ln/funding.rs

+			// FIXME: Should claim_id be an Option?
+			let claim_id = ClaimId([0; 32]);


Regarding the CoinSelectionSource API, do we want to make claim_id an Option?

jkczyz · 2026-01-20T19:24:28Z

lightning/src/ln/splicing_tests.rs

-		Amount::from_sat(383)
+		Amount::from_sat(385)
 	} else {
-		Amount::from_sat(384)
+		Amount::from_sat(386)


Seems select_confirmed_utxos_internal might be off on the change calculation because it's using the weight of the change output to compute additional fees instead of re-computing the total fees using the total weight when including a change output.

ldk-reviews-bot · 2026-01-21T00:30:25Z

🔔 4th 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-01-21T00:30:27Z

🔔 4th 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-01-24T00:00:25Z

🔔 5th 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-01-26T00:00:20Z

🔔 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-01-26T00:01:39Z

🔔 6th 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 · 2026-01-26T15:00:21Z

We discussed this a bunch offline on friday and I believe there are some further changes here. Let us know when you're ready for another look.

jkczyz · 2026-01-27T18:58:11Z

We discussed this a bunch offline on friday and I believe there are some further changes here. Let us know when you're ready for another look.

Pushed changes to move FundingNeeded prior to quiescence. This involved having QuiescentAction::AwaitingFunding contain a FundingContribution and LockTime. This is set but without set_awaiting_quiescence, which needs to be scrutinized. Is it possible to get stuck in this state?

Additionally, updated splice_channel to take a FeeRate instead of funding_contributed. This will help with RBF as the corresponding FundingNeeded event can be generated with an appropriate fee rate. Even if provided by user when initiating an RBF, it can at least be checked.

Working on separating contributed inputs and outputs from SpliceFailed into a separate DiscardFunding event since there are instances where we need this when splice_channel (and maybe funding_contributed?) fails.

wpaulino · 2026-01-27T19:14:54Z

lightning/src/ln/channel.rs

-			.map_err(|e| APIError::APIMisuseError { err: e.to_owned() })
+		// Don't use propose_quiescence as we don't want to initiate quiescence until FundingNeeded
+		// has been processed. This prevents initiating other quiescent actions in the meanwhile.
+		self.quiescent_action = Some(QuiescentAction::AwaitingFunding);


This changes the semantics of QuiescentAction from an action to take after becoming quiescent to also include actions before becoming quiescent. Can we instead rely on a FundingNeeded event still needing to be handled to fail early here?

Yeah, that was essentially what this was standing in for. Alternatively, IIUC, we'd need some other state to track that, right? Something like adding another flag to ChannelReadyFlags?

Discussed offline. We'll eventually want to queue up QuiescentActions, but it might be fine to let a second action jump ahead if the user hasn't processed FundingNeeded. The recent push checks if the FundingNeeded event is present to determine if a second splice attempt should be rejected. PTAL.

jkczyz · 2026-01-28T19:13:47Z

Squashed

CoinSelectionSource is used for anchor bumping where a ClaimId is passed in to avoid double spending other claims. To re-use this trait for funding a splice, the ClaimId must be optional. And, if None, then any locked UTXOs may be considered ineligible by an implementation.

Rather than requiring the user to pass FundingTxInputs when initiating a splice, generate a FundingNeeded event once the channel has become quiescent. This simplifies error handling and UTXO / change address clean-up by consolidating it in SpliceFailed event handling. Later, this event will be used for opportunistic contributions (i.e., when the counterparty wins quiescence or initiates), dual-funding, and RBF.

Now that CoinSelection is used to fund a splice funding transaction, use that for determining of a change output should be used. Previously, the initiator could either provide a change script upfront or let LDK generate one using SignerProvider::get_destination_script. Since older versions may have serialized a SpliceInstruction without a change script while waiting on quiescence, LDK must still generate a change output in this case.

Wallet-related types were tightly coupled to bump_transaction, making them less accessible for other use cases like channel funding and splicing. Extract these utilities to a dedicated module for improved code organization and reusability across the codebase. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Synchronous wallet utilities were coupled to bump_transaction::sync, limiting their reusability for other features like channel funding and splicing which need synchronous wallet operations. Consolidate all wallet utilities in a single module for consistency and improved code organization. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

FundingTxInput was originally designed for channel funding but is now used more broadly for coin selection and splicing. The name ConfirmedUtxo better reflects its general-purpose nature as a confirmed UTXO with previous transaction data. Make ConfirmedUtxo the real struct in wallet_utils and alias FundingTxInput to it for backward compatibility. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

jkczyz

I can split out the wallet_utils refactor into a separate PR, if preferred.

jkczyz · 2026-01-28T20:31:27Z

lightning/src/events/mod.rs

+	/// Indicates that funding is needed for a channel splice or a dual-funded channel open.
+	///
+	/// The client should build a [`FundingContribution`] from the provided [`FundingTemplate`] and
+	/// pass it to [`ChannelManager::funding_contributed`].


Now that the presence of this event in the pending events queue determines whether or not a splice can be initiated, no action is needed from the user if they no longer want to splice.

jkczyz · 2026-01-28T20:40:13Z

lightning/src/ln/channel.rs

+	) -> Result<msgs::SpliceInit, SpliceFundingFailed>
+	where
+		L::Target: Logger,
+	{


Based on offline discussion, we are no longer waiting to enter quiescence to generate FundingNeeded. It will instead be initiated when funding_contributed is called.

jkczyz · 2026-01-28T23:59:37Z

lightning/src/events/bump_transaction/mod.rs

 }

+/// An unspent transaction output with at least one confirmation.
+pub type ConfirmedUtxo = FundingTxInput;


Moved to wallet_utils courtesy of claude. I reversed the type alias for now. I could drop it if you prefer. Just seems like FundingTxInput reads a little better in funding contexts.

jkczyz · 2026-01-29T01:44:05Z

lightning/src/ln/channel.rs

+		if self.context.channel_state.is_quiescent() {
+			return Err(APIError::APIMisuseError {
+				err: format!(
+					"Channel {} cannot be spliced as it is already quiescent",


I'll leave this for a follow-up PR.

ldk-reviews-bot · 2026-01-29T18:58:42Z

🔔 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.

TheBlueMatt · 2026-01-29T16:01:21Z

lightning/src/events/bump_transaction/mod.rs

-				}
-			}
-			Ok(tx)
+			// FIXME: Why does handle_channel_close override the witness?


Not sure i understand this comment

Ah, this is related to two commits later where test_op_return_under_funds is updated to not use a hardcoded value for the outpoint's txid. But then I realized the calling code handle_channel_close overrides the witness.

https://github.com/jkczyz/rust-lightning/blob/f3eb94ea54368a2cd1fa1eec5a0743451951dda1/lightning/src/events/bump_transaction/mod.rs#L921

So my question is why are we setting the witnesses in TestCoinSelectionSource::sign_pstb if not necessary for the test? Maybe that test should be checking its TestBroadcaster?

TheBlueMatt · 2026-01-29T16:14:22Z

lightning/src/util/wallet_utils.rs

+	// TODO: Do we care about cleaning this up once the UTXOs have a confirmed spend? We can do so
+	// by checking whether any UTXOs that exist in the map are no longer returned in
+	// `list_confirmed_utxos`.
+	locked_utxos: Mutex<HashMap<OutPoint, Option<ClaimId>>>,


Do we want to handle DiscardFunding now so that we can drop entries if a splice RBFs?

As in add a method on Wallet? Yeah, though I'll likely do that in a follow-up when refactoring DiscardFunding from SpliceFailed events.

For RBF, did we want to produce DiscardFunding before FundingNeeded so that the UTXOs can be reused in the RBF? Though an earlier splice / RBF attempt may still get confirmed...

IIUC, we already have DiscardFunding events generated by the ChannelMonitor once the splice is promoted. But ISTM that wouldn't let re-use the UTXOs in the RBF tx unless we generalize ClaimId to be used for splicing / dual-funding? Though, at least in the Wallet implementation`, we'll fall back to reusing UTXOs if we don't have any others to use.

ldk-reviews-bot · 2026-01-29T19:58:51Z

🔔 1st Reminder

Hey @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.

jkczyz added this to Weekly Goals Dec 18, 2025

jkczyz self-assigned this Dec 18, 2025

jkczyz force-pushed the 2025-12-new-splice-api branch from f5933e5 to 854e9ca Compare January 12, 2026 17:47

wpaulino reviewed Jan 12, 2026

View reviewed changes

TheBlueMatt reviewed Jan 12, 2026

View reviewed changes

jkczyz requested review from TheBlueMatt and wpaulino January 13, 2026 00:28

jkczyz force-pushed the 2025-12-new-splice-api branch from 854e9ca to 6d78c3f Compare January 14, 2026 17:03

jkczyz force-pushed the 2025-12-new-splice-api branch from 6d78c3f to 94b1aa9 Compare January 15, 2026 17:02

jkczyz mentioned this pull request Jan 16, 2026

Mixed mode splicing #4261

Merged

jkczyz added 3 commits January 20, 2026 13:16

FIXME: Why does handle_channel_close override the witness?

f3eb94e

jkczyz force-pushed the 2025-12-new-splice-api branch from 94b1aa9 to c3f3453 Compare January 20, 2026 19:16

jkczyz commented Jan 20, 2026

View reviewed changes

jkczyz marked this pull request as ready for review January 20, 2026 19:25

jkczyz force-pushed the 2025-12-new-splice-api branch from c3f3453 to 3253a99 Compare January 20, 2026 23:57

jkczyz force-pushed the 2025-12-new-splice-api branch 3 times, most recently from f2d9fa5 to fcccbac Compare January 21, 2026 18:22

jkczyz requested a review from TheBlueMatt January 22, 2026 22:28

TheBlueMatt removed request for TheBlueMatt and wpaulino January 26, 2026 14:59

jkczyz force-pushed the 2025-12-new-splice-api branch from fcccbac to 12eee3d Compare January 27, 2026 18:57

jkczyz requested review from TheBlueMatt and wpaulino January 27, 2026 18:58

wpaulino reviewed Jan 27, 2026

View reviewed changes

jkczyz requested a review from wpaulino January 27, 2026 19:58

jkczyz force-pushed the 2025-12-new-splice-api branch 2 times, most recently from 2e44da8 to 1c8e7e9 Compare January 28, 2026 19:13

jkczyz and others added 9 commits January 28, 2026 15:32

f - remove fuzz test case

484141c

f - update FundingNeeded docs

73bedd6

f - comment about LegacySplice deprecation

6a81b04

jkczyz force-pushed the 2025-12-new-splice-api branch from 1c8e7e9 to 78b4f3c Compare January 29, 2026 01:09

jkczyz commented Jan 29, 2026

View reviewed changes

TheBlueMatt reviewed Jan 29, 2026

View reviewed changes

		// FIXME: Should claim_id be an Option?
		let claim_id = ClaimId([0; 32]);

Add FundingNeeded event for splicing #4290

Are you sure you want to change the base?

Add FundingNeeded event for splicing #4290

Conversation

jkczyz commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ldk-reviews-bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

wpaulino 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!

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Jan 15, 2026

Uh oh!

ldk-reviews-bot commented Jan 15, 2026

Uh oh!

ldk-reviews-bot commented Jan 17, 2026

Uh oh!

ldk-reviews-bot commented Jan 17, 2026

Uh oh!

ldk-reviews-bot commented Jan 19, 2026

Uh oh!

ldk-reviews-bot commented Jan 19, 2026

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!

ldk-reviews-bot commented Jan 21, 2026

Uh oh!

ldk-reviews-bot commented Jan 21, 2026

Uh oh!

ldk-reviews-bot commented Jan 24, 2026

Uh oh!

ldk-reviews-bot commented Jan 26, 2026

Uh oh!

ldk-reviews-bot commented Jan 26, 2026

Uh oh!

TheBlueMatt commented Jan 26, 2026

Uh oh!

jkczyz commented Jan 27, 2026

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 Jan 28, 2026

Uh oh!

jkczyz left a comment

Add `FundingNeeded` event for splicing #4290

Add `FundingNeeded` event for splicing #4290

jkczyz commented Dec 18, 2025 •

edited

Loading

ldk-reviews-bot commented Dec 18, 2025 •

edited

Loading

jkczyz commented Jan 12, 2026 •

edited

Loading