Add NegotiationFailureReason to SpliceFailed event

Each splice negotiation round can fail for different reasons, but
Event::SpliceFailed previously gave no indication of what went wrong.
Add a NegotiationFailureReason enum so users can distinguish failures
and take appropriate action (e.g., retry with a higher feerate vs.
wait for the channel to become usable).

The reason is determined at each channelmanager emission site based on
context rather than threaded through channel.rs internals, since the
channelmanager knows the triggering context (disconnect, tx_abort,
shutdown, etc.) while channel.rs functions like abandon_quiescent_action
handle both splice and non-splice quiescent actions.

The one exception is QuiescentError::FailSplice, which carries a reason
alongside the SpliceFundingFailed. This is appropriate because FailSplice
is already splice-specific, and the channel.rs code that constructs it
(e.g., contribution validation, feerate checks) knows the specific
failure cause. A with_negotiation_failure_reason method on QuiescentError
allows callers to override the default when needed.

Older serializations that lack the reason field default to Unknown via
default_value in deserialization. The persistence reload path uses
PeerDisconnected since a reload implies the peer connection was lost.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jkczyz

lightning/src/events/mod.rs

@@ -99,6 +99,67 @@ impl_writeable_tlv_based_enum!(FundingInfo,
 	}
 );
 
+/// The reason a funding negotiation round failed.
+///
+/// Each negotiation attempt (initial or RBF) resolves to either success or failure. This enum
+/// indicates what caused the failure.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum NegotiationFailureReason {
+	/// The reason was not available (e.g., from an older serialization).
+	Unknown,
+	/// The peer disconnected during negotiation. Retry by calling
+	/// [`ChannelManager::splice_channel`] after the peer reconnects.
+	///
+	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
+	PeerDisconnected,
+	/// The counterparty aborted the negotiation by sending `tx_abort`. Retry by calling
+	/// [`ChannelManager::splice_channel`], or wait for the counterparty to initiate.
+	///
+	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
+	CounterpartyAborted,
+	/// An error occurred while negotiating the interactive transaction (e.g., the counterparty
+	/// sent an invalid message). Retry by calling [`ChannelManager::splice_channel`].
+	///
+	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
+	NegotiationError,
+	/// The funding contribution was invalid (e.g., insufficient balance for the splice amount).
+	/// Adjust the contribution and retry via [`ChannelManager::splice_channel`].
+	///
+	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
+	ContributionInvalid,
+	/// The negotiation was locally abandoned via [`ChannelManager::abandon_splice`].
+	///
+	/// [`ChannelManager::abandon_splice`]: crate::ln::channelmanager::ChannelManager::abandon_splice
+	LocallyAbandoned,
+	/// The channel was not in a state to accept the funding contribution. Retry by calling
+	/// [`ChannelManager::splice_channel`] once [`ChannelDetails::is_usable`] returns `true`.
+	///
+	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
+	/// [`ChannelDetails::is_usable`]: crate::ln::channelmanager::ChannelDetails::is_usable
+	ChannelNotReady,
+	/// The channel is closing, so the negotiation cannot continue. See [`Event::ChannelClosed`]
+	/// for the closure reason.
+	ChannelClosing,
+	/// The contribution's feerate was too low. Retry with a higher feerate by calling
+	/// [`ChannelManager::splice_channel`] to obtain a new [`FundingTemplate`].
+	///
+	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
+	/// [`FundingTemplate`]: crate::ln::channelmanager::FundingTemplate
+	FeeRateTooLow,
+}
+
+impl_writeable_tlv_based_enum!(NegotiationFailureReason,
+	(0, Unknown) => {},
+	(2, PeerDisconnected) => {},
+	(4, CounterpartyAborted) => {},
+	(6, NegotiationError) => {},
+	(8, ContributionInvalid) => {},
+	(10, LocallyAbandoned) => {},
+	(12, ChannelNotReady) => {},
+	(14, ChannelClosing) => {},
+	(16, FeeRateTooLow) => {},
+);
+
 /// Some information provided on receipt of payment depends on whether the payment received is a
 /// spontaneous payment or a "conventional" lightning payment that's paying an invoice.
 #[derive(Clone, Debug, PartialEq, Eq)]
@@ -1586,6 +1647,8 @@ pub enum Event {
 		abandoned_funding_txo: Option<OutPoint>,
 		/// The features that this channel will operate with, if available.
 		channel_type: Option<ChannelTypeFeatures>,
+		/// The reason the splice negotiation failed.
+		reason: NegotiationFailureReason,
 	},
 	/// Used to indicate to the user that they can abandon the funding transaction and recycle the
 	/// inputs for another purpose.
@@ -2379,6 +2442,7 @@ impl Writeable for Event {
 				ref counterparty_node_id,
 				ref abandoned_funding_txo,
 				ref channel_type,
+				ref reason,
 			} => {
 				52u8.write(writer)?;
 				write_tlv_fields!(writer, {
@@ -2387,6 +2451,7 @@ impl Writeable for Event {
 					(5, user_channel_id, required),
 					(7, counterparty_node_id, required),
 					(9, abandoned_funding_txo, option),
+					(11, reason, required),
 				});
 			},
 			// Note that, going forward, all new events must only write data inside of
@@ -3031,6 +3096,7 @@ impl MaybeReadable for Event {
 						(5, user_channel_id, required),
 						(7, counterparty_node_id, required),
 						(9, abandoned_funding_txo, option),
+						(11, reason, (default_value, NegotiationFailureReason::Unknown)),
 					});
 
 					Ok(Some(Event::SpliceFailed {
@@ -3039,6 +3105,7 @@ impl MaybeReadable for Event {
 						counterparty_node_id: counterparty_node_id.0.unwrap(),
 						abandoned_funding_txo,
 						channel_type,
+						reason: reason.0.unwrap(),
 					}))
 				};
 				f()

lightning/src/ln/channel.rs

@@ -36,7 +36,7 @@ use crate::chain::channelmonitor::{
 };
 use crate::chain::transaction::{OutPoint, TransactionData};
 use crate::chain::BestBlock;
-use crate::events::{ClosureReason, FundingInfo};
+use crate::events::{ClosureReason, FundingInfo, NegotiationFailureReason};
 use crate::ln::chan_utils;
 use crate::ln::chan_utils::{
 	get_commitment_transaction_number_obscure_factor, max_htlcs, second_stage_tx_fees_sat,
@@ -3174,7 +3174,17 @@ pub(crate) enum QuiescentAction {
 pub(super) enum QuiescentError {
 	DoNothing,
 	DiscardFunding { inputs: Vec<bitcoin::OutPoint>, outputs: Vec<bitcoin::TxOut> },
-	FailSplice(SpliceFundingFailed),
+	FailSplice(SpliceFundingFailed, NegotiationFailureReason),
+}
+
+impl QuiescentError {
+	fn with_negotiation_failure_reason(mut self, reason: NegotiationFailureReason) -> Self {
+		match self {
+			QuiescentError::FailSplice(_, ref mut r) => *r = reason,
+			_ => debug_assert!(false, "Expected FailSplice variant"),
+		}
+		self
+	}
 }
 
 pub(crate) enum StfuResponse {
@@ -7133,9 +7143,10 @@ where
 
 	fn quiescent_action_into_error(&self, action: QuiescentAction) -> QuiescentError {
 		match action {
-			QuiescentAction::Splice { contribution, .. } => {
-				QuiescentError::FailSplice(self.splice_funding_failed_for(contribution))
-			},
+			QuiescentAction::Splice { contribution, .. } => QuiescentError::FailSplice(
+				self.splice_funding_failed_for(contribution),
+				NegotiationFailureReason::Unknown,
+			),
 			#[cfg(any(test, fuzzing, feature = "_test_utils"))]
 			QuiescentAction::DoNothing => QuiescentError::DoNothing,
 		}
@@ -7144,7 +7155,7 @@ where
 	fn abandon_quiescent_action(&mut self) -> Option<SpliceFundingFailed> {
 		let action = self.quiescent_action.take()?;
 		match self.quiescent_action_into_error(action) {
-			QuiescentError::FailSplice(failed) => Some(failed),
+			QuiescentError::FailSplice(failed, _) => Some(failed),
 			#[cfg(any(test, fuzzing, feature = "_test_utils"))]
 			QuiescentError::DoNothing => None,
 			_ => {
@@ -12540,7 +12551,10 @@ where
 		}) {
 			log_error!(logger, "Channel {} cannot be funded: {}", self.context.channel_id(), e);
 
-			return Err(QuiescentError::FailSplice(self.splice_funding_failed_for(contribution)));
+			return Err(QuiescentError::FailSplice(
+				self.splice_funding_failed_for(contribution),
+				NegotiationFailureReason::ContributionInvalid,
+			));
 		}
 
 		if let Some(pending_splice) = self.pending_splice.as_ref() {
@@ -12556,6 +12570,7 @@ where
 				);
 				return Err(QuiescentError::FailSplice(
 					self.splice_funding_failed_for(contribution),
+					NegotiationFailureReason::FeeRateTooLow,
 				));
 			}
 		}
@@ -13998,7 +14013,8 @@ where
 
 		if !self.context.is_usable() {
 			log_debug!(logger, "Channel is not in a usable state to propose quiescence");
-			return Err(self.quiescent_action_into_error(action));
+			return Err(self.quiescent_action_into_error(action)
+				.with_negotiation_failure_reason(NegotiationFailureReason::ChannelNotReady));
 		}
 		if self.quiescent_action.is_some() {
 			log_debug!(
@@ -14115,7 +14131,10 @@ where
 								self.context.channel_id(),
 								e,
 							)),
-							QuiescentError::FailSplice(failed),
+							QuiescentError::FailSplice(
+								failed,
+								NegotiationFailureReason::ContributionInvalid,
+							),
 						));
 					}
 					let prior_contribution = contribution.clone();

lightning/src/ln/channelmanager.rs

@@ -4115,6 +4115,7 @@ impl<
 									user_channel_id: chan.context().get_user_id(),
 									abandoned_funding_txo: splice_funding_failed.funding_txo,
 									channel_type: splice_funding_failed.channel_type,
+									reason: events::NegotiationFailureReason::ChannelClosing,
 								},
 								None,
 							));
@@ -4421,6 +4422,7 @@ impl<
 						user_channel_id: shutdown_res.user_channel_id,
 						abandoned_funding_txo: splice_funding_failed.funding_txo,
 						channel_type: splice_funding_failed.channel_type,
+						reason: events::NegotiationFailureReason::ChannelClosing,
 					},
 					None,
 				));
@@ -4927,6 +4929,7 @@ impl<
 								user_channel_id: chan.context.get_user_id(),
 								abandoned_funding_txo: splice_funding_failed.funding_txo,
 								channel_type: splice_funding_failed.channel_type,
+								reason: events::NegotiationFailureReason::LocallyAbandoned,
 							},
 							None,
 						));
@@ -6609,12 +6612,15 @@ impl<
 					));
 				}
 			},
-			QuiescentError::FailSplice(SpliceFundingFailed {
-				funding_txo,
-				channel_type,
-				contributed_inputs,
-				contributed_outputs,
-			}) => {
+			QuiescentError::FailSplice(
+				SpliceFundingFailed {
+					funding_txo,
+					channel_type,
+					contributed_inputs,
+					contributed_outputs,
+				},
+				reason,
+			) => {
 				let pending_events = &mut self.pending_events.lock().unwrap();
 				pending_events.push_back((
 					events::Event::SpliceFailed {
@@ -6623,6 +6629,7 @@ impl<
 						user_channel_id,
 						abandoned_funding_txo: funding_txo,
 						channel_type,
+						reason,
 					},
 					None,
 				));
@@ -6764,7 +6771,7 @@ impl<
 											"Channel {} already has a pending funding contribution",
 											channel_id,
 										),
-										QuiescentError::FailSplice(_) => format!(
+										QuiescentError::FailSplice(..) => format!(
 											"Channel {} cannot accept funding contribution",
 											channel_id,
 										),
@@ -11858,6 +11865,7 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
 									user_channel_id: channel.context().get_user_id(),
 									abandoned_funding_txo: splice_funding_failed.funding_txo,
 									channel_type: splice_funding_failed.channel_type.clone(),
+									reason: events::NegotiationFailureReason::NegotiationError,
 								},
 								None,
 							));
@@ -12017,6 +12025,7 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
 									user_channel_id: chan.context().get_user_id(),
 									abandoned_funding_txo: splice_funding_failed.funding_txo,
 									channel_type: splice_funding_failed.channel_type.clone(),
+									reason: events::NegotiationFailureReason::NegotiationError,
 								},
 								None,
 							));
@@ -12187,6 +12196,7 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
 								user_channel_id: chan_entry.get().context().get_user_id(),
 								abandoned_funding_txo: splice_funding_failed.funding_txo,
 								channel_type: splice_funding_failed.channel_type,
+								reason: events::NegotiationFailureReason::CounterpartyAborted,
 							},
 							None,
 						));
@@ -12335,6 +12345,7 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
 									user_channel_id: chan.context().get_user_id(),
 									abandoned_funding_txo: splice_funding_failed.funding_txo,
 									channel_type: splice_funding_failed.channel_type,
+									reason: events::NegotiationFailureReason::ChannelClosing,
 								},
 								None,
 							));
@@ -15451,6 +15462,7 @@ impl<
 								user_channel_id: chan.context().get_user_id(),
 								abandoned_funding_txo: splice_funding_failed.funding_txo,
 								channel_type: splice_funding_failed.channel_type,
+								reason: events::NegotiationFailureReason::PeerDisconnected,
 							});
 							splice_failed_events.push(events::Event::DiscardFunding {
 								channel_id: chan.context().channel_id(),
@@ -18123,6 +18135,7 @@ impl<
 							user_channel_id: chan.context.get_user_id(),
 							abandoned_funding_txo: splice_funding_failed.funding_txo,
 							channel_type: splice_funding_failed.channel_type,
+							reason: events::NegotiationFailureReason::PeerDisconnected,
 						},
 						None,
 					));

lightning/src/ln/functional_test_utils.rs

@@ -17,8 +17,8 @@ use crate::chain::{BestBlock, ChannelMonitorUpdateStatus, Confirm, Listen, Watch
 use crate::events::bump_transaction::sync::BumpTransactionEventHandlerSync;
 use crate::events::bump_transaction::BumpTransactionEvent;
 use crate::events::{
-	ClaimedHTLC, ClosureReason, Event, FundingInfo, HTLCHandlingFailureType, PaidBolt12Invoice,
-	PathFailure, PaymentFailureReason, PaymentPurpose,
+	ClaimedHTLC, ClosureReason, Event, FundingInfo, HTLCHandlingFailureType,
+	NegotiationFailureReason, PaidBolt12Invoice, PathFailure, PaymentFailureReason, PaymentPurpose,
 };
 use crate::ln::chan_utils::{
 	commitment_tx_base_weight, COMMITMENT_TX_WEIGHT_PER_HTLC, TRUC_MAX_WEIGHT,
@@ -3243,13 +3243,14 @@ pub fn expect_splice_pending_event<'a, 'b, 'c, 'd>(
 #[cfg(any(test, ldk_bench, feature = "_test_utils"))]
 pub fn expect_splice_failed_events<'a, 'b, 'c, 'd>(
 	node: &'a Node<'b, 'c, 'd>, expected_channel_id: &ChannelId,
-	funding_contribution: FundingContribution,
+	funding_contribution: FundingContribution, expected_reason: NegotiationFailureReason,
 ) {
 	let events = node.node.get_and_clear_pending_events();
 	assert_eq!(events.len(), 2);
 	match &events[0] {
-		Event::SpliceFailed { channel_id, .. } => {
+		Event::SpliceFailed { channel_id, reason, .. } => {
 			assert_eq!(*expected_channel_id, *channel_id);
+			assert_eq!(*reason, expected_reason);
 		},
 		_ => panic!("Unexpected event"),
 	}