Include failure context in splice events#4514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TheBlueMatt merged 11 commits into from
May 7, 2026
Merged

Include failure context in splice events #4514

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
f0a8ceb
Add NegotiationFailureReason to SpliceFailed event
jkczyz Mar 25, 2026
450eb64
Add FundingContribution to SpliceFailed event
jkczyz Mar 25, 2026
14c6819
Emit DiscardFunding before SpliceFailed
jkczyz Mar 25, 2026
cc7fb0f
Rename SplicePending and SpliceFailed events
jkczyz Mar 25, 2026
2eb939b
Simplify contribution pop in reset_pending_splice_state
jkczyz Mar 27, 2026
9c6cca6
Fix output filtering in into_unique_contributions
jkczyz Mar 27, 2026
db45c83
Derive SpliceFundingFailed inputs from FundingContribution
jkczyz Mar 27, 2026
367ffaa
Remove unused NegotiationError and contributed_inputs_and_outputs met…
jkczyz Mar 27, 2026
b44076e
Add pending changelog for splice negotiation event changes
jkczyz Apr 3, 2026
ffbb8fe
Check can_initiate_rbf in stfu handler before sending tx_init_rbf
jkczyz Apr 13, 2026
51e6079
Derive DiscardFunding inputs and outputs from contributions on promotion
jkczyz Apr 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions fuzz/src/chanmon_consistency.rs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -930,6 +930,7 @@ fn assert_action_timeout_awaiting_response(action: &msgs::ErrorAction) {
action,
msgs::ErrorAction::DisconnectPeerWithWarning { msg }
if msg.data.contains("Disconnecting due to timeout awaiting response")
|| msg.data.contains("already sent splice_locked, cannot RBF")
),
"Expected timeout disconnect, got: {:?}",
action,
Expand DownExpand Up@@ -2091,7 +2092,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
)
.unwrap();
},
events::Event::SplicePending { new_funding_txo, .. } => {
events::Event::SpliceNegotiated { new_funding_txo, .. } => {
let broadcaster = match $node {
0 => &broadcast_a,
1 => &broadcast_b,
Expand All@@ -2103,7 +2104,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
assert_eq!(new_funding_txo.txid, splice_tx.compute_txid());
chain_state.add_pending_tx(splice_tx);
},
events::Event::SpliceFailed { .. } => {},
events::Event::SpliceNegotiationFailed { .. } => {},
events::Event::DiscardFunding {
funding_info:
events::FundingInfo::Contribution { .. }
Expand Down
4 changes: 2 additions & 2 deletions fuzz/src/full_stack.rs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -1137,10 +1137,10 @@ pub fn do_test(mut data: &[u8], logger: &Arc<dyn Logger + MaybeSend + MaybeSync>
signed_tx,
);
},
Event::SplicePending { .. } => {
Event::SpliceNegotiated { .. } => {
// Splice negotiation completed, waiting for confirmation
},
Event::SpliceFailed { .. } => {
Event::SpliceNegotiationFailed { .. } => {
// Splice failed, inputs can be re-spent
},
Event::OpenChannelRequest {
Expand Down
172 changes: 147 additions & 25 deletions lightning/src/events/mod.rs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ use crate::blinded_path::payment::{
use crate::chain::transaction;
use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
use crate::ln::channelmanager::{InterceptId, PaymentId};
use crate::ln::funding::FundingContribution;
use crate::ln::msgs;
use crate::ln::onion_utils::LocalHTLCFailureReason;
use crate::ln::outbound_payment::RecipientOnionFields;
Expand DownExpand Up@@ -99,6 +100,119 @@ 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. Use [`is_retriable`] to determine whether the splice can
/// be reattempted on this channel by calling [`ChannelManager::splice_channel`].
///
/// [`is_retriable`]: Self::is_retriable
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
#[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. Wait for the peer to reconnect, then retry.
PeerDisconnected,
/// The counterparty explicitly aborted the negotiation by sending `tx_abort`. Retrying with
/// the same parameters is unlikely to succeed — consider adjusting the contribution or
/// waiting for the counterparty to initiate.
CounterpartyAborted {
/// The counterparty's abort message.
///
/// This is counterparty-provided data. Use `Display` on [`UntrustedString`] for safe
/// logging.
msg: UntrustedString,
},
/// An error occurred during interactive transaction negotiation (e.g., the counterparty sent
/// an invalid message). The negotiation was aborted.
NegotiationError {
/// A developer-readable error message.
msg: String,
},
/// The funding contribution was invalid (e.g., insufficient balance for the splice amount).
/// Call [`ChannelManager::splice_channel`] for a fresh [`FundingTemplate`] and build a new
/// contribution with adjusted parameters.
///
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
ContributionInvalid,

@TheBlueMattTheBlueMattApr 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does seem like some of these could use more details (error message string?). As-is given the recommendation for ~all enum variants is "retry by calling splice_channel again" its not really clear to me why we should bother with an enum - an enum is useful if the downstream code has different handling for different cases, but here that doesn't really seem likely/possible. If we can't expose more details that are useful for automated action, we could probably do with an enum with three variants and a developer-readable string.

@jkczyzjkczyzApr 6, 2026

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the docs could be improved here. Maybe re-calling splice_channel isn't always necessary? In some cases, calling funding_contributed at a later time may be sufficient. We are providing the FundingContribution after all.

So it does seem like different actions are required depending on the variant.

  • PeerDisconnected: retry upon re-connection
  • ChannelNotReady: retry when channel is in a usable state (assuming it's not closing)
  • FeeRateTooLow: retry with a higher fee rate
  • ContributionInvalid: retry with a re-computed contribution
  • NegotiationError: probably not retryable as it indicates a counterparty error
  • CounterpartyAborted: might be able to retry but would need to examine the tx_abort message (e.g., counterparty doesn't like your fee rate).

We could have a top-level Retryable that holds one of these instead, if you prefer? We could go as far as only putting the FundingContribution in applicable sub-variants. Though a user may want to see it for other variants.

@TheBlueMattTheBlueMattApr 6, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume ChannelNotReady is really "you can't retry" (why were you splicing an unopened channel anyway? but probably its closing), FeeRateTooLow and ContributionInvalid are really "retry now with a fresh splice_channel call as that'll tell you what the new required feerate is to do a fresh rbf from scracth or will fix your contribution, hopefully". So it does seem like its basically "retry with a fresh splice_channel call, or not", with the one maybe-exception of PeerDisconnected? We could leave the enum and include a function that returns "retryable or not", but I'm not really sure why we shouldn't just return a string+bool pair (in a struct) - do we anticipate downstream code will have any different behavior based on anything beyond "should I retry this" or is it just gonna log/print an error?

@jkczyzjkczyzApr 6, 2026

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not other than when / how should you retry in case of the PeerDisconnected.

@jkczyzjkczyzApr 6, 2026

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose given we don't know when the peer will reconnect, we might as well just process it the same and call splice_channel again upon re-connection. Otherwise, we'd need to make sure not to process the associated DiscardFunding which would mean locking up the UTXOs indefinitely. Instead, the client can simply always queue up a "retry when connected".

@jkczyzjkczyzApr 7, 2026

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed offline. Updated to have an is_retryable method that the counterparty calls rather than examining the variant. Would prevent allocating strings in many cases.

/// The negotiation was locally abandoned via `ChannelManager::abandon_splice`.
LocallyAbandoned,
/// The channel is closing, so the negotiation cannot continue. See [`Event::ChannelClosed`]
/// for the closure reason.
ChannelClosing,
/// The contribution's feerate was too low for RBF. Call [`ChannelManager::splice_channel`]
/// for a fresh [`FundingTemplate`] (which includes the updated minimum feerate) and build a
/// new contribution with a higher feerate.
///
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
FeeRateTooLow,
/// An RBF attempt could not be initiated (e.g., a prior splice transaction already
/// confirmed). The channel remains operational — start a new splice with
/// [`ChannelManager::splice_channel`] if further changes are needed.
///
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
CannotInitiateRbf,
}

impl NegotiationFailureReason {
/// Whether the splice negotiation is likely to succeed if retried on this channel. When `true`,
/// call [`ChannelManager::splice_channel`] to obtain a fresh [`FundingTemplate`] and retry.
///
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
pub fn is_retriable(&self) -> bool {
match self {
Self::Unknown
| Self::PeerDisconnected
| Self::ContributionInvalid
| Self::FeeRateTooLow => true,
Self::CounterpartyAborted { .. }
| Self::NegotiationError { .. }
| Self::LocallyAbandoned
| Self::ChannelClosing
| Self::CannotInitiateRbf => false,
}
}
}

impl core::fmt::Display for NegotiationFailureReason {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
Self::Unknown => f.write_str("unknown reason"),
Self::PeerDisconnected => f.write_str("peer disconnected during negotiation"),
Self::CounterpartyAborted { msg } => {
write!(f, "counterparty aborted: {}", msg)
},
Self::NegotiationError { msg } => write!(f, "negotiation error: {}", msg),
Self::ContributionInvalid => f.write_str("funding contribution was invalid"),
Self::LocallyAbandoned => f.write_str("splice locally abandoned"),

Self::ChannelClosing => f.write_str("channel is closing"),
Self::FeeRateTooLow => f.write_str("feerate too low for RBF"),
Self::CannotInitiateRbf => f.write_str("cannot initiate RBF"),
}
}
}

impl_writeable_tlv_based_enum_upgradable!(NegotiationFailureReason,
(1, Unknown) => {},
(3, PeerDisconnected) => {},
(5, CounterpartyAborted) => {
(1, msg, required),
},
(7, NegotiationError) => {
(1, msg, required),
},
(9, ContributionInvalid) => {},
(11, LocallyAbandoned) => {},
(13, ChannelClosing) => {},
(15, FeeRateTooLow) => {},
(17, CannotInitiateRbf) => {},
);

/// 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)]
Expand DownExpand Up@@ -1541,8 +1655,8 @@ pub enum Event {
/// # Failure Behavior and Persistence
/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SplicePending {
/// The `channel_id` of the channel that has a pending splice funding transaction.
SpliceNegotiated {
/// The `channel_id` of the channel with the negotiated splice funding transaction.
channel_id: ChannelId,
/// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
/// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1560,19 +1674,20 @@ pub enum Event {
/// The witness script that is used to lock the channel's funding output to commitment transactions.
new_funding_redeem_script: ScriptBuf,
},
/// Used to indicate that a splice for the given `channel_id` has failed.
/// Used to indicate that a splice negotiation round for the given `channel_id` has failed.
///
/// This event may be emitted if a splice fails after it has been initiated but prior to signing
/// any negotiated funding transaction.
/// Each splice attempt (initial or RBF) resolves to either [`Event::SpliceNegotiated`] on
/// success or this event on failure. Prior successfully negotiated splice transactions are
/// unaffected.
///
/// Any UTXOs contributed to be spent by the funding transaction may be reused and will be
/// given in `contributed_inputs`.
/// Any UTXOs contributed to the failed round that are not committed to a prior negotiated
/// splice transaction will be returned via a preceding [`Event::DiscardFunding`].
///
/// # Failure Behavior and Persistence
/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SpliceFailed {
/// The `channel_id` of the channel for which the splice failed.
SpliceNegotiationFailed {
/// The `channel_id` of the channel for which the splice negotiation round failed.
channel_id: ChannelId,
/// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
/// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1582,10 +1697,17 @@ pub enum Event {
user_channel_id: u128,
/// The `node_id` of the channel counterparty.
counterparty_node_id: PublicKey,
/// The outpoint of the channel's splice funding transaction, if one was created.
abandoned_funding_txo: Option<OutPoint>,
/// The features that this channel will operate with, if available.
channel_type: Option<ChannelTypeFeatures>,
Comment on lines -1585 to -1588

@jkczyzjkczyzMar 26, 2026

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't feel like there was much value to these.

  • abandoned_funding_txo would be set only if there's a failure after the transaction was negotiated but before signed.
  • In the future, when channel_type can change, maybe it is just part of FundingContribution? Could also keep it if you prefer.

/// The reason the splice negotiation failed.
reason: NegotiationFailureReason,
/// The funding contribution from the failed negotiation round, if available. This can be
/// fed back to [`ChannelManager::funding_contributed`] to retry with the same parameters.
/// Alternatively, call [`ChannelManager::splice_channel`] to obtain a fresh
/// [`FundingTemplate`] and build a new contribution.
///
/// [`ChannelManager::funding_contributed`]: crate::ln::channelmanager::ChannelManager::funding_contributed
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
contribution: Option<FundingContribution>,
},
/// Used to indicate to the user that they can abandon the funding transaction and recycle the
/// inputs for another purpose.
Expand DownExpand Up@@ -2355,7 +2477,7 @@ impl Writeable for Event {
// We never write out FundingTransactionReadyForSigning events as they will be regenerated when
// necessary.
},
&Event::SplicePending {
&Event::SpliceNegotiated {
ref channel_id,
ref user_channel_id,
ref counterparty_node_id,
Expand All@@ -2373,20 +2495,20 @@ impl Writeable for Event {
(11, new_funding_redeem_script, required),
});
},
&Event::SpliceFailed {
&Event::SpliceNegotiationFailed {
ref channel_id,
ref user_channel_id,
ref counterparty_node_id,
ref abandoned_funding_txo,
ref channel_type,
ref reason,
ref contribution,
} => {
52u8.write(writer)?;
write_tlv_fields!(writer, {
(1, channel_id, required),
(3, channel_type, option),
(5, user_channel_id, required),
(7, counterparty_node_id, required),
(9, abandoned_funding_txo, option),
(11, reason, required),
(13, contribution, option),
});
},
// Note that, going forward, all new events must only write data inside of
Expand DownExpand Up@@ -3012,7 +3134,7 @@ impl MaybeReadable for Event {
(11, new_funding_redeem_script, required),
});

Ok(Some(Event::SplicePending {
Ok(Some(Event::SpliceNegotiated {
channel_id: channel_id.0.unwrap(),
user_channel_id: user_channel_id.0.unwrap(),
counterparty_node_id: counterparty_node_id.0.unwrap(),
Expand All@@ -3027,18 +3149,18 @@ impl MaybeReadable for Event {
let mut f = || {
_init_and_read_len_prefixed_tlv_fields!(reader, {
(1, channel_id, required),
(3, channel_type, option),
(5, user_channel_id, required),
(7, counterparty_node_id, required),
(9, abandoned_funding_txo, option),
(11, reason, upgradable_option),
(13, contribution, option),
});

Ok(Some(Event::SpliceFailed {
Ok(Some(Event::SpliceNegotiationFailed {
channel_id: channel_id.0.unwrap(),
user_channel_id: user_channel_id.0.unwrap(),
counterparty_node_id: counterparty_node_id.0.unwrap(),
abandoned_funding_txo,
channel_type,
reason: reason.unwrap_or(NegotiationFailureReason::Unknown),
contribution,
}))
};
f()
Expand Down
8 changes: 4 additions & 4 deletions lightning/src/ln/async_signer_tests.rs
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -1647,8 +1647,8 @@ fn test_async_splice_initial_commit_sig() {
get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

let _ = get_event!(initiator, Event::SplicePending);
let _ = get_event!(acceptor, Event::SplicePending);
let _ = get_event!(initiator, Event::SpliceNegotiated);
let _ = get_event!(acceptor, Event::SpliceNegotiated);
}

#[test]
Expand DownExpand Up@@ -1739,6 +1739,6 @@ fn test_async_splice_initial_commit_sig_waits_for_monitor_before_tx_signatures()
get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

let _ = get_event!(initiator, Event::SplicePending);
let _ = get_event!(acceptor, Event::SplicePending);
let _ = get_event!(initiator, Event::SpliceNegotiated);
let _ = get_event!(acceptor, Event::SpliceNegotiated);
}
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Include failure context in splice events#4514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

TheBlueMatt
merged 11 commits into

from

May 7, 2026
 Merged


Include failure context in splice events
#4514
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
f0a8ceb

Add NegotiationFailureReason to SpliceFailed event


jkczyz Mar 25, 2026
450eb64

Add FundingContribution to SpliceFailed event


jkczyz Mar 25, 2026
14c6819

Emit DiscardFunding before SpliceFailed


jkczyz Mar 25, 2026
cc7fb0f

Rename SplicePending and SpliceFailed events


jkczyz Mar 25, 2026
2eb939b

Simplify contribution pop in reset_pending_splice_state


jkczyz Mar 27, 2026
9c6cca6

Fix output filtering in into_unique_contributions


jkczyz Mar 27, 2026
db45c83

Derive SpliceFundingFailed inputs from FundingContribution


jkczyz Mar 27, 2026
367ffaa

Remove unused NegotiationError and contributed_inputs_and_outputs met…


jkczyz Mar 27, 2026
b44076e

Add pending changelog for splice negotiation event changes


jkczyz Apr 3, 2026
ffbb8fe

Check can_initiate_rbf in stfu handler before sending tx_init_rbf


jkczyz Apr 13, 2026
51e6079

Derive DiscardFunding inputs and outputs from contributions on promotion


jkczyz Apr 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 3 additions & 2 deletions
fuzz/src/chanmon_consistency.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -930,6 +930,7 @@ fn assert_action_timeout_awaiting_response(action: &msgs::ErrorAction) {
 action,
 msgs::ErrorAction::DisconnectPeerWithWarning { msg }
 if msg.data.contains("Disconnecting due to timeout awaiting response")
 || msg.data.contains("already sent splice_locked, cannot RBF")
 ),
 "Expected timeout disconnect, got: {:?}",
 action,
Expand DownExpand Up@@ -2091,7 +2092,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 )
 .unwrap();
 },
 events::Event::SplicePending { new_funding_txo, .. } => {
 events::Event::SpliceNegotiated { new_funding_txo, .. } => {
 let broadcaster = match $node {
 0 => &broadcast_a,
 1 => &broadcast_b,
Expand All@@ -2103,7 +2104,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 assert_eq!(new_funding_txo.txid, splice_tx.compute_txid());
 chain_state.add_pending_tx(splice_tx);
 },
 events::Event::SpliceFailed { .. } => {},
 events::Event::SpliceNegotiationFailed { .. } => {},
 events::Event::DiscardFunding {
 funding_info:
 events::FundingInfo::Contribution { .. }
Expand Down

4 changes: 2 additions & 2 deletions
fuzz/src/full_stack.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1137,10 +1137,10 @@ pub fn do_test(mut data: &[u8], logger: &Arc<dyn Logger + MaybeSend + MaybeSync>
 signed_tx,
 );
 },
 Event::SplicePending { .. } => {
 Event::SpliceNegotiated { .. } => {
 // Splice negotiation completed, waiting for confirmation
 },
 Event::SpliceFailed { .. } => {
 Event::SpliceNegotiationFailed { .. } => {
 // Splice failed, inputs can be re-spent
 },
 Event::OpenChannelRequest {
Expand Down

172 changes: 147 additions & 25 deletions
lightning/src/events/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ use crate::blinded_path::payment::{
use crate::chain::transaction;
use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
use crate::ln::channelmanager::{InterceptId, PaymentId};
use crate::ln::funding::FundingContribution;
use crate::ln::msgs;
use crate::ln::onion_utils::LocalHTLCFailureReason;
use crate::ln::outbound_payment::RecipientOnionFields;
Expand DownExpand Up@@ -99,6 +100,119 @@ 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. Use [`is_retriable`] to determine whether the splice can
/// be reattempted on this channel by calling [`ChannelManager::splice_channel`].
///
/// [`is_retriable`]: Self::is_retriable
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
#[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. Wait for the peer to reconnect, then retry.
	PeerDisconnected,
	/// The counterparty explicitly aborted the negotiation by sending `tx_abort`. Retrying with
	/// the same parameters is unlikely to succeed — consider adjusting the contribution or
	/// waiting for the counterparty to initiate.
	CounterpartyAborted {
 /// The counterparty's abort message.
 ///
 /// This is counterparty-provided data. Use `Display` on [`UntrustedString`] for safe
 /// logging.
 msg: UntrustedString,
	},
	/// An error occurred during interactive transaction negotiation (e.g., the counterparty sent
	/// an invalid message). The negotiation was aborted.
	NegotiationError {
 /// A developer-readable error message.
 msg: String,
	},
	/// The funding contribution was invalid (e.g., insufficient balance for the splice amount).
	/// Call [`ChannelManager::splice_channel`] for a fresh [`FundingTemplate`] and build a new
	/// contribution with adjusted parameters.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	ContributionInvalid,
@TheBlueMattTheBlueMattApr 3, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does seem like some of these could use more details (error message string?). As-is given the recommendation for ~all enum variants is "retry by calling splice_channel again" its not really clear to me why we should bother with an enum - an enum is useful if the downstream code has different handling for different cases, but here that doesn't really seem likely/possible. If we can't expose more details that are useful for automated action, we could probably do with an enum with three variants and a developer-readable string.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the docs could be improved here. Maybe re-calling splice_channel isn't always necessary? In some cases, calling funding_contributed at a later time may be sufficient. We are providing the FundingContribution after all.
So it does seem like different actions are required depending on the variant.
  • PeerDisconnected: retry upon re-connection
  • ChannelNotReady: retry when channel is in a usable state (assuming it's not closing)
  • FeeRateTooLow: retry with a higher fee rate
  • ContributionInvalid: retry with a re-computed contribution
  • NegotiationError: probably not retryable as it indicates a counterparty error
  • CounterpartyAborted: might be able to retry but would need to examine the tx_abort message (e.g., counterparty doesn't like your fee rate).
We could have a top-level Retryable that holds one of these instead, if you prefer? We could go as far as only putting the FundingContribution in applicable sub-variants. Though a user may want to see it for other variants.
@TheBlueMattTheBlueMattApr 6, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume ChannelNotReady is really "you can't retry" (why were you splicing an unopened channel anyway? but probably its closing), FeeRateTooLow and ContributionInvalid are really "retry now with a fresh splice_channel call as that'll tell you what the new required feerate is to do a fresh rbf from scracth or will fix your contribution, hopefully". So it does seem like its basically "retry with a fresh splice_channel call, or not", with the one maybe-exception of PeerDisconnected? We could leave the enum and include a function that returns "retryable or not", but I'm not really sure why we shouldn't just return a string+bool pair (in a struct) - do we anticipate downstream code will have any different behavior based on anything beyond "should I retry this" or is it just gonna log/print an error?
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not other than when / how should you retry in case of the PeerDisconnected.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose given we don't know when the peer will reconnect, we might as well just process it the same and call splice_channel again upon re-connection. Otherwise, we'd need to make sure not to process the associated DiscardFunding which would mean locking up the UTXOs indefinitely. Instead, the client can simply always queue up a "retry when connected".
@jkczyzjkczyzApr 7, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed offline. Updated to have an is_retryable method that the counterparty calls rather than examining the variant. Would prevent allocating strings in many cases.
	/// The negotiation was locally abandoned via `ChannelManager::abandon_splice`.
	LocallyAbandoned,
	/// The channel is closing, so the negotiation cannot continue. See [`Event::ChannelClosed`]
	/// for the closure reason.
	ChannelClosing,
	/// The contribution's feerate was too low for RBF. Call [`ChannelManager::splice_channel`]
	/// for a fresh [`FundingTemplate`] (which includes the updated minimum feerate) and build a
	/// new contribution with a higher feerate.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	FeeRateTooLow,
	/// An RBF attempt could not be initiated (e.g., a prior splice transaction already
	/// confirmed). The channel remains operational — start a new splice with
	/// [`ChannelManager::splice_channel`] if further changes are needed.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	CannotInitiateRbf,
}

impl NegotiationFailureReason {
	/// Whether the splice negotiation is likely to succeed if retried on this channel. When `true`,
	/// call [`ChannelManager::splice_channel`] to obtain a fresh [`FundingTemplate`] and retry.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	pub fn is_retriable(&self) -> bool {
 match self {
 Self::Unknown
 | Self::PeerDisconnected
 | Self::ContributionInvalid
 | Self::FeeRateTooLow => true,
 Self::CounterpartyAborted { .. }
 | Self::NegotiationError { .. }
 | Self::LocallyAbandoned
 | Self::ChannelClosing
 | Self::CannotInitiateRbf => false,
 }
	}
}

impl core::fmt::Display for NegotiationFailureReason {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
 match self {
 Self::Unknown => f.write_str("unknown reason"),
 Self::PeerDisconnected => f.write_str("peer disconnected during negotiation"),
 Self::CounterpartyAborted { msg } => {
 write!(f, "counterparty aborted: {}", msg)
 },
 Self::NegotiationError { msg } => write!(f, "negotiation error: {}", msg),
 Self::ContributionInvalid => f.write_str("funding contribution was invalid"),
 Self::LocallyAbandoned => f.write_str("splice locally abandoned"),

 Self::ChannelClosing => f.write_str("channel is closing"),
 Self::FeeRateTooLow => f.write_str("feerate too low for RBF"),
 Self::CannotInitiateRbf => f.write_str("cannot initiate RBF"),
 }
	}
}

impl_writeable_tlv_based_enum_upgradable!(NegotiationFailureReason,
	(1, Unknown) => {},
	(3, PeerDisconnected) => {},
	(5, CounterpartyAborted) => {
 (1, msg, required),
	},
	(7, NegotiationError) => {
 (1, msg, required),
	},
	(9, ContributionInvalid) => {},
	(11, LocallyAbandoned) => {},
	(13, ChannelClosing) => {},
	(15, FeeRateTooLow) => {},
	(17, CannotInitiateRbf) => {},
);

/// 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)]
Expand DownExpand Up@@ -1541,8 +1655,8 @@ pub enum Event {
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SplicePending {
 /// The `channel_id` of the channel that has a pending splice funding transaction.
SpliceNegotiated {
 /// The `channel_id` of the channel with the negotiated splice funding transaction.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1560,19 +1674,20 @@ pub enum Event {
 /// The witness script that is used to lock the channel's funding output to commitment transactions.
 new_funding_redeem_script: ScriptBuf,
	},
	/// Used to indicate that a splice for the given `channel_id` has failed.
	/// Used to indicate that a splice negotiation round for the given `channel_id` has failed.
	///
	/// This event may be emitted if a splice fails after it has been initiated but prior to signing
	/// any negotiated funding transaction.
	/// Each splice attempt (initial or RBF) resolves to either [`Event::SpliceNegotiated`] on
	/// success or this event on failure. Prior successfully negotiated splice transactions are
	/// unaffected.
	///
	/// Any UTXOs contributed to be spent by the funding transaction may be reused and will be
	/// given in `contributed_inputs`.
	/// Any UTXOs contributed to the failed round that are not committed to a prior negotiated
	/// splice transaction will be returned via a preceding [`Event::DiscardFunding`].
	///
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SpliceFailed {
 /// The `channel_id` of the channel for which the splice failed.
SpliceNegotiationFailed {
 /// The `channel_id` of the channel for which the splice negotiation round failed.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1582,10 +1697,17 @@ pub enum Event {
 user_channel_id: u128,
 /// The `node_id` of the channel counterparty.
 counterparty_node_id: PublicKey,
 /// The outpoint of the channel's splice funding transaction, if one was created.
 abandoned_funding_txo: Option<OutPoint>,
 /// The features that this channel will operate with, if available.
 channel_type: Option<ChannelTypeFeatures>,

Comment on lines

-1585
 to 
-1588

@jkczyzjkczyzMar 26, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't feel like there was much value to these.
  • abandoned_funding_txo would be set only if there's a failure after the transaction was negotiated but before signed.
  • In the future, when channel_type can change, maybe it is just part of FundingContribution? Could also keep it if you prefer.
 /// The reason the splice negotiation failed.
 reason: NegotiationFailureReason,
 /// The funding contribution from the failed negotiation round, if available. This can be
 /// fed back to [`ChannelManager::funding_contributed`] to retry with the same parameters.
 /// Alternatively, call [`ChannelManager::splice_channel`] to obtain a fresh
 /// [`FundingTemplate`] and build a new contribution.
 ///
 /// [`ChannelManager::funding_contributed`]: crate::ln::channelmanager::ChannelManager::funding_contributed
 /// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
 /// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
 contribution: Option<FundingContribution>,
	},
	/// Used to indicate to the user that they can abandon the funding transaction and recycle the
	/// inputs for another purpose.
Expand DownExpand Up@@ -2355,7 +2477,7 @@ impl Writeable for Event {
 // We never write out FundingTransactionReadyForSigning events as they will be regenerated when
 // necessary.
 },
 &Event::SplicePending {
 &Event::SpliceNegotiated {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
Expand All@@ -2373,20 +2495,20 @@ impl Writeable for Event {
 (11, new_funding_redeem_script, required),
 });
 },
 &Event::SpliceFailed {
 &Event::SpliceNegotiationFailed {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
 ref abandoned_funding_txo,
 ref channel_type,
 ref reason,
 ref contribution,
 } => {
 52u8.write(writer)?;
 write_tlv_fields!(writer, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, required),
 (13, contribution, option),
 });
 },
 // Note that, going forward, all new events must only write data inside of
Expand DownExpand Up@@ -3012,7 +3134,7 @@ impl MaybeReadable for Event {
 (11, new_funding_redeem_script, required),
 });

 Ok(Some(Event::SplicePending {
 Ok(Some(Event::SpliceNegotiated {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
Expand All@@ -3027,18 +3149,18 @@ impl MaybeReadable for Event {
 let mut f = || {
 _init_and_read_len_prefixed_tlv_fields!(reader, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, upgradable_option),
 (13, contribution, option),
 });

 Ok(Some(Event::SpliceFailed {
 Ok(Some(Event::SpliceNegotiationFailed {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
abandoned_funding_txo,
channel_type,
reason: reason.unwrap_or(NegotiationFailureReason::Unknown),
contribution,
 }))
 };
 f()
Expand Down

8 changes: 4 additions & 4 deletions
lightning/src/ln/async_signer_tests.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1647,8 +1647,8 @@ fn test_async_splice_initial_commit_sig() {
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}

#[test]
Expand DownExpand Up@@ -1739,6 +1739,6 @@ fn test_async_splice_initial_commit_sig_waits_for_monitor_before_tx_signatures()
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Include failure context in splice events#4514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

TheBlueMatt
merged 11 commits into

from

May 7, 2026
 Merged


Include failure context in splice events
#4514
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
f0a8ceb

Add NegotiationFailureReason to SpliceFailed event


jkczyz Mar 25, 2026
450eb64

Add FundingContribution to SpliceFailed event


jkczyz Mar 25, 2026
14c6819

Emit DiscardFunding before SpliceFailed


jkczyz Mar 25, 2026
cc7fb0f

Rename SplicePending and SpliceFailed events


jkczyz Mar 25, 2026
2eb939b

Simplify contribution pop in reset_pending_splice_state


jkczyz Mar 27, 2026
9c6cca6

Fix output filtering in into_unique_contributions


jkczyz Mar 27, 2026
db45c83

Derive SpliceFundingFailed inputs from FundingContribution


jkczyz Mar 27, 2026
367ffaa

Remove unused NegotiationError and contributed_inputs_and_outputs met…


jkczyz Mar 27, 2026
b44076e

Add pending changelog for splice negotiation event changes


jkczyz Apr 3, 2026
ffbb8fe

Check can_initiate_rbf in stfu handler before sending tx_init_rbf


jkczyz Apr 13, 2026
51e6079

Derive DiscardFunding inputs and outputs from contributions on promotion


jkczyz Apr 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 3 additions & 2 deletions
fuzz/src/chanmon_consistency.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -930,6 +930,7 @@ fn assert_action_timeout_awaiting_response(action: &msgs::ErrorAction) {
 action,
 msgs::ErrorAction::DisconnectPeerWithWarning { msg }
 if msg.data.contains("Disconnecting due to timeout awaiting response")
 || msg.data.contains("already sent splice_locked, cannot RBF")
 ),
 "Expected timeout disconnect, got: {:?}",
 action,
Expand DownExpand Up@@ -2091,7 +2092,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 )
 .unwrap();
 },
 events::Event::SplicePending { new_funding_txo, .. } => {
 events::Event::SpliceNegotiated { new_funding_txo, .. } => {
 let broadcaster = match $node {
 0 => &broadcast_a,
 1 => &broadcast_b,
Expand All@@ -2103,7 +2104,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 assert_eq!(new_funding_txo.txid, splice_tx.compute_txid());
 chain_state.add_pending_tx(splice_tx);
 },
 events::Event::SpliceFailed { .. } => {},
 events::Event::SpliceNegotiationFailed { .. } => {},
 events::Event::DiscardFunding {
 funding_info:
 events::FundingInfo::Contribution { .. }
Expand Down

4 changes: 2 additions & 2 deletions
fuzz/src/full_stack.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1137,10 +1137,10 @@ pub fn do_test(mut data: &[u8], logger: &Arc<dyn Logger + MaybeSend + MaybeSync>
 signed_tx,
 );
 },
 Event::SplicePending { .. } => {
 Event::SpliceNegotiated { .. } => {
 // Splice negotiation completed, waiting for confirmation
 },
 Event::SpliceFailed { .. } => {
 Event::SpliceNegotiationFailed { .. } => {
 // Splice failed, inputs can be re-spent
 },
 Event::OpenChannelRequest {
Expand Down

172 changes: 147 additions & 25 deletions
lightning/src/events/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ use crate::blinded_path::payment::{
use crate::chain::transaction;
use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
use crate::ln::channelmanager::{InterceptId, PaymentId};
use crate::ln::funding::FundingContribution;
use crate::ln::msgs;
use crate::ln::onion_utils::LocalHTLCFailureReason;
use crate::ln::outbound_payment::RecipientOnionFields;
Expand DownExpand Up@@ -99,6 +100,119 @@ 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. Use [`is_retriable`] to determine whether the splice can
/// be reattempted on this channel by calling [`ChannelManager::splice_channel`].
///
/// [`is_retriable`]: Self::is_retriable
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
#[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. Wait for the peer to reconnect, then retry.
	PeerDisconnected,
	/// The counterparty explicitly aborted the negotiation by sending `tx_abort`. Retrying with
	/// the same parameters is unlikely to succeed — consider adjusting the contribution or
	/// waiting for the counterparty to initiate.
	CounterpartyAborted {
 /// The counterparty's abort message.
 ///
 /// This is counterparty-provided data. Use `Display` on [`UntrustedString`] for safe
 /// logging.
 msg: UntrustedString,
	},
	/// An error occurred during interactive transaction negotiation (e.g., the counterparty sent
	/// an invalid message). The negotiation was aborted.
	NegotiationError {
 /// A developer-readable error message.
 msg: String,
	},
	/// The funding contribution was invalid (e.g., insufficient balance for the splice amount).
	/// Call [`ChannelManager::splice_channel`] for a fresh [`FundingTemplate`] and build a new
	/// contribution with adjusted parameters.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	ContributionInvalid,
@TheBlueMattTheBlueMattApr 3, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does seem like some of these could use more details (error message string?). As-is given the recommendation for ~all enum variants is "retry by calling splice_channel again" its not really clear to me why we should bother with an enum - an enum is useful if the downstream code has different handling for different cases, but here that doesn't really seem likely/possible. If we can't expose more details that are useful for automated action, we could probably do with an enum with three variants and a developer-readable string.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the docs could be improved here. Maybe re-calling splice_channel isn't always necessary? In some cases, calling funding_contributed at a later time may be sufficient. We are providing the FundingContribution after all.
So it does seem like different actions are required depending on the variant.
  • PeerDisconnected: retry upon re-connection
  • ChannelNotReady: retry when channel is in a usable state (assuming it's not closing)
  • FeeRateTooLow: retry with a higher fee rate
  • ContributionInvalid: retry with a re-computed contribution
  • NegotiationError: probably not retryable as it indicates a counterparty error
  • CounterpartyAborted: might be able to retry but would need to examine the tx_abort message (e.g., counterparty doesn't like your fee rate).
We could have a top-level Retryable that holds one of these instead, if you prefer? We could go as far as only putting the FundingContribution in applicable sub-variants. Though a user may want to see it for other variants.
@TheBlueMattTheBlueMattApr 6, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume ChannelNotReady is really "you can't retry" (why were you splicing an unopened channel anyway? but probably its closing), FeeRateTooLow and ContributionInvalid are really "retry now with a fresh splice_channel call as that'll tell you what the new required feerate is to do a fresh rbf from scracth or will fix your contribution, hopefully". So it does seem like its basically "retry with a fresh splice_channel call, or not", with the one maybe-exception of PeerDisconnected? We could leave the enum and include a function that returns "retryable or not", but I'm not really sure why we shouldn't just return a string+bool pair (in a struct) - do we anticipate downstream code will have any different behavior based on anything beyond "should I retry this" or is it just gonna log/print an error?
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not other than when / how should you retry in case of the PeerDisconnected.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose given we don't know when the peer will reconnect, we might as well just process it the same and call splice_channel again upon re-connection. Otherwise, we'd need to make sure not to process the associated DiscardFunding which would mean locking up the UTXOs indefinitely. Instead, the client can simply always queue up a "retry when connected".
@jkczyzjkczyzApr 7, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed offline. Updated to have an is_retryable method that the counterparty calls rather than examining the variant. Would prevent allocating strings in many cases.
	/// The negotiation was locally abandoned via `ChannelManager::abandon_splice`.
	LocallyAbandoned,
	/// The channel is closing, so the negotiation cannot continue. See [`Event::ChannelClosed`]
	/// for the closure reason.
	ChannelClosing,
	/// The contribution's feerate was too low for RBF. Call [`ChannelManager::splice_channel`]
	/// for a fresh [`FundingTemplate`] (which includes the updated minimum feerate) and build a
	/// new contribution with a higher feerate.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	FeeRateTooLow,
	/// An RBF attempt could not be initiated (e.g., a prior splice transaction already
	/// confirmed). The channel remains operational — start a new splice with
	/// [`ChannelManager::splice_channel`] if further changes are needed.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	CannotInitiateRbf,
}

impl NegotiationFailureReason {
	/// Whether the splice negotiation is likely to succeed if retried on this channel. When `true`,
	/// call [`ChannelManager::splice_channel`] to obtain a fresh [`FundingTemplate`] and retry.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	pub fn is_retriable(&self) -> bool {
 match self {
 Self::Unknown
 | Self::PeerDisconnected
 | Self::ContributionInvalid
 | Self::FeeRateTooLow => true,
 Self::CounterpartyAborted { .. }
 | Self::NegotiationError { .. }
 | Self::LocallyAbandoned
 | Self::ChannelClosing
 | Self::CannotInitiateRbf => false,
 }
	}
}

impl core::fmt::Display for NegotiationFailureReason {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
 match self {
 Self::Unknown => f.write_str("unknown reason"),
 Self::PeerDisconnected => f.write_str("peer disconnected during negotiation"),
 Self::CounterpartyAborted { msg } => {
 write!(f, "counterparty aborted: {}", msg)
 },
 Self::NegotiationError { msg } => write!(f, "negotiation error: {}", msg),
 Self::ContributionInvalid => f.write_str("funding contribution was invalid"),
 Self::LocallyAbandoned => f.write_str("splice locally abandoned"),

 Self::ChannelClosing => f.write_str("channel is closing"),
 Self::FeeRateTooLow => f.write_str("feerate too low for RBF"),
 Self::CannotInitiateRbf => f.write_str("cannot initiate RBF"),
 }
	}
}

impl_writeable_tlv_based_enum_upgradable!(NegotiationFailureReason,
	(1, Unknown) => {},
	(3, PeerDisconnected) => {},
	(5, CounterpartyAborted) => {
 (1, msg, required),
	},
	(7, NegotiationError) => {
 (1, msg, required),
	},
	(9, ContributionInvalid) => {},
	(11, LocallyAbandoned) => {},
	(13, ChannelClosing) => {},
	(15, FeeRateTooLow) => {},
	(17, CannotInitiateRbf) => {},
);

/// 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)]
Expand DownExpand Up@@ -1541,8 +1655,8 @@ pub enum Event {
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SplicePending {
 /// The `channel_id` of the channel that has a pending splice funding transaction.
SpliceNegotiated {
 /// The `channel_id` of the channel with the negotiated splice funding transaction.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1560,19 +1674,20 @@ pub enum Event {
 /// The witness script that is used to lock the channel's funding output to commitment transactions.
 new_funding_redeem_script: ScriptBuf,
	},
	/// Used to indicate that a splice for the given `channel_id` has failed.
	/// Used to indicate that a splice negotiation round for the given `channel_id` has failed.
	///
	/// This event may be emitted if a splice fails after it has been initiated but prior to signing
	/// any negotiated funding transaction.
	/// Each splice attempt (initial or RBF) resolves to either [`Event::SpliceNegotiated`] on
	/// success or this event on failure. Prior successfully negotiated splice transactions are
	/// unaffected.
	///
	/// Any UTXOs contributed to be spent by the funding transaction may be reused and will be
	/// given in `contributed_inputs`.
	/// Any UTXOs contributed to the failed round that are not committed to a prior negotiated
	/// splice transaction will be returned via a preceding [`Event::DiscardFunding`].
	///
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SpliceFailed {
 /// The `channel_id` of the channel for which the splice failed.
SpliceNegotiationFailed {
 /// The `channel_id` of the channel for which the splice negotiation round failed.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1582,10 +1697,17 @@ pub enum Event {
 user_channel_id: u128,
 /// The `node_id` of the channel counterparty.
 counterparty_node_id: PublicKey,
 /// The outpoint of the channel's splice funding transaction, if one was created.
 abandoned_funding_txo: Option<OutPoint>,
 /// The features that this channel will operate with, if available.
 channel_type: Option<ChannelTypeFeatures>,

Comment on lines

-1585
 to 
-1588

@jkczyzjkczyzMar 26, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't feel like there was much value to these.
  • abandoned_funding_txo would be set only if there's a failure after the transaction was negotiated but before signed.
  • In the future, when channel_type can change, maybe it is just part of FundingContribution? Could also keep it if you prefer.
 /// The reason the splice negotiation failed.
 reason: NegotiationFailureReason,
 /// The funding contribution from the failed negotiation round, if available. This can be
 /// fed back to [`ChannelManager::funding_contributed`] to retry with the same parameters.
 /// Alternatively, call [`ChannelManager::splice_channel`] to obtain a fresh
 /// [`FundingTemplate`] and build a new contribution.
 ///
 /// [`ChannelManager::funding_contributed`]: crate::ln::channelmanager::ChannelManager::funding_contributed
 /// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
 /// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
 contribution: Option<FundingContribution>,
	},
	/// Used to indicate to the user that they can abandon the funding transaction and recycle the
	/// inputs for another purpose.
Expand DownExpand Up@@ -2355,7 +2477,7 @@ impl Writeable for Event {
 // We never write out FundingTransactionReadyForSigning events as they will be regenerated when
 // necessary.
 },
 &Event::SplicePending {
 &Event::SpliceNegotiated {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
Expand All@@ -2373,20 +2495,20 @@ impl Writeable for Event {
 (11, new_funding_redeem_script, required),
 });
 },
 &Event::SpliceFailed {
 &Event::SpliceNegotiationFailed {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
 ref abandoned_funding_txo,
 ref channel_type,
 ref reason,
 ref contribution,
 } => {
 52u8.write(writer)?;
 write_tlv_fields!(writer, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, required),
 (13, contribution, option),
 });
 },
 // Note that, going forward, all new events must only write data inside of
Expand DownExpand Up@@ -3012,7 +3134,7 @@ impl MaybeReadable for Event {
 (11, new_funding_redeem_script, required),
 });

 Ok(Some(Event::SplicePending {
 Ok(Some(Event::SpliceNegotiated {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
Expand All@@ -3027,18 +3149,18 @@ impl MaybeReadable for Event {
 let mut f = || {
 _init_and_read_len_prefixed_tlv_fields!(reader, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, upgradable_option),
 (13, contribution, option),
 });

 Ok(Some(Event::SpliceFailed {
 Ok(Some(Event::SpliceNegotiationFailed {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
abandoned_funding_txo,
channel_type,
reason: reason.unwrap_or(NegotiationFailureReason::Unknown),
contribution,
 }))
 };
 f()
Expand Down

8 changes: 4 additions & 4 deletions
lightning/src/ln/async_signer_tests.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1647,8 +1647,8 @@ fn test_async_splice_initial_commit_sig() {
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}

#[test]
Expand DownExpand Up@@ -1739,6 +1739,6 @@ fn test_async_splice_initial_commit_sig_waits_for_monitor_before_tx_signatures()
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Include failure context in splice events#4514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

TheBlueMatt
merged 11 commits into

from

May 7, 2026
 Merged


Include failure context in splice events
#4514
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
f0a8ceb

Add NegotiationFailureReason to SpliceFailed event


jkczyz Mar 25, 2026
450eb64

Add FundingContribution to SpliceFailed event


jkczyz Mar 25, 2026
14c6819

Emit DiscardFunding before SpliceFailed


jkczyz Mar 25, 2026
cc7fb0f

Rename SplicePending and SpliceFailed events


jkczyz Mar 25, 2026
2eb939b

Simplify contribution pop in reset_pending_splice_state


jkczyz Mar 27, 2026
9c6cca6

Fix output filtering in into_unique_contributions


jkczyz Mar 27, 2026
db45c83

Derive SpliceFundingFailed inputs from FundingContribution


jkczyz Mar 27, 2026
367ffaa

Remove unused NegotiationError and contributed_inputs_and_outputs met…


jkczyz Mar 27, 2026
b44076e

Add pending changelog for splice negotiation event changes


jkczyz Apr 3, 2026
ffbb8fe

Check can_initiate_rbf in stfu handler before sending tx_init_rbf


jkczyz Apr 13, 2026
51e6079

Derive DiscardFunding inputs and outputs from contributions on promotion


jkczyz Apr 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 3 additions & 2 deletions
fuzz/src/chanmon_consistency.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -930,6 +930,7 @@ fn assert_action_timeout_awaiting_response(action: &msgs::ErrorAction) {
 action,
 msgs::ErrorAction::DisconnectPeerWithWarning { msg }
 if msg.data.contains("Disconnecting due to timeout awaiting response")
 || msg.data.contains("already sent splice_locked, cannot RBF")
 ),
 "Expected timeout disconnect, got: {:?}",
 action,
Expand DownExpand Up@@ -2091,7 +2092,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 )
 .unwrap();
 },
 events::Event::SplicePending { new_funding_txo, .. } => {
 events::Event::SpliceNegotiated { new_funding_txo, .. } => {
 let broadcaster = match $node {
 0 => &broadcast_a,
 1 => &broadcast_b,
Expand All@@ -2103,7 +2104,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 assert_eq!(new_funding_txo.txid, splice_tx.compute_txid());
 chain_state.add_pending_tx(splice_tx);
 },
 events::Event::SpliceFailed { .. } => {},
 events::Event::SpliceNegotiationFailed { .. } => {},
 events::Event::DiscardFunding {
 funding_info:
 events::FundingInfo::Contribution { .. }
Expand Down

4 changes: 2 additions & 2 deletions
fuzz/src/full_stack.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1137,10 +1137,10 @@ pub fn do_test(mut data: &[u8], logger: &Arc<dyn Logger + MaybeSend + MaybeSync>
 signed_tx,
 );
 },
 Event::SplicePending { .. } => {
 Event::SpliceNegotiated { .. } => {
 // Splice negotiation completed, waiting for confirmation
 },
 Event::SpliceFailed { .. } => {
 Event::SpliceNegotiationFailed { .. } => {
 // Splice failed, inputs can be re-spent
 },
 Event::OpenChannelRequest {
Expand Down

172 changes: 147 additions & 25 deletions
lightning/src/events/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ use crate::blinded_path::payment::{
use crate::chain::transaction;
use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
use crate::ln::channelmanager::{InterceptId, PaymentId};
use crate::ln::funding::FundingContribution;
use crate::ln::msgs;
use crate::ln::onion_utils::LocalHTLCFailureReason;
use crate::ln::outbound_payment::RecipientOnionFields;
Expand DownExpand Up@@ -99,6 +100,119 @@ 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. Use [`is_retriable`] to determine whether the splice can
/// be reattempted on this channel by calling [`ChannelManager::splice_channel`].
///
/// [`is_retriable`]: Self::is_retriable
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
#[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. Wait for the peer to reconnect, then retry.
	PeerDisconnected,
	/// The counterparty explicitly aborted the negotiation by sending `tx_abort`. Retrying with
	/// the same parameters is unlikely to succeed — consider adjusting the contribution or
	/// waiting for the counterparty to initiate.
	CounterpartyAborted {
 /// The counterparty's abort message.
 ///
 /// This is counterparty-provided data. Use `Display` on [`UntrustedString`] for safe
 /// logging.
 msg: UntrustedString,
	},
	/// An error occurred during interactive transaction negotiation (e.g., the counterparty sent
	/// an invalid message). The negotiation was aborted.
	NegotiationError {
 /// A developer-readable error message.
 msg: String,
	},
	/// The funding contribution was invalid (e.g., insufficient balance for the splice amount).
	/// Call [`ChannelManager::splice_channel`] for a fresh [`FundingTemplate`] and build a new
	/// contribution with adjusted parameters.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	ContributionInvalid,
@TheBlueMattTheBlueMattApr 3, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does seem like some of these could use more details (error message string?). As-is given the recommendation for ~all enum variants is "retry by calling splice_channel again" its not really clear to me why we should bother with an enum - an enum is useful if the downstream code has different handling for different cases, but here that doesn't really seem likely/possible. If we can't expose more details that are useful for automated action, we could probably do with an enum with three variants and a developer-readable string.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the docs could be improved here. Maybe re-calling splice_channel isn't always necessary? In some cases, calling funding_contributed at a later time may be sufficient. We are providing the FundingContribution after all.
So it does seem like different actions are required depending on the variant.
  • PeerDisconnected: retry upon re-connection
  • ChannelNotReady: retry when channel is in a usable state (assuming it's not closing)
  • FeeRateTooLow: retry with a higher fee rate
  • ContributionInvalid: retry with a re-computed contribution
  • NegotiationError: probably not retryable as it indicates a counterparty error
  • CounterpartyAborted: might be able to retry but would need to examine the tx_abort message (e.g., counterparty doesn't like your fee rate).
We could have a top-level Retryable that holds one of these instead, if you prefer? We could go as far as only putting the FundingContribution in applicable sub-variants. Though a user may want to see it for other variants.
@TheBlueMattTheBlueMattApr 6, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume ChannelNotReady is really "you can't retry" (why were you splicing an unopened channel anyway? but probably its closing), FeeRateTooLow and ContributionInvalid are really "retry now with a fresh splice_channel call as that'll tell you what the new required feerate is to do a fresh rbf from scracth or will fix your contribution, hopefully". So it does seem like its basically "retry with a fresh splice_channel call, or not", with the one maybe-exception of PeerDisconnected? We could leave the enum and include a function that returns "retryable or not", but I'm not really sure why we shouldn't just return a string+bool pair (in a struct) - do we anticipate downstream code will have any different behavior based on anything beyond "should I retry this" or is it just gonna log/print an error?
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not other than when / how should you retry in case of the PeerDisconnected.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose given we don't know when the peer will reconnect, we might as well just process it the same and call splice_channel again upon re-connection. Otherwise, we'd need to make sure not to process the associated DiscardFunding which would mean locking up the UTXOs indefinitely. Instead, the client can simply always queue up a "retry when connected".
@jkczyzjkczyzApr 7, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed offline. Updated to have an is_retryable method that the counterparty calls rather than examining the variant. Would prevent allocating strings in many cases.
	/// The negotiation was locally abandoned via `ChannelManager::abandon_splice`.
	LocallyAbandoned,
	/// The channel is closing, so the negotiation cannot continue. See [`Event::ChannelClosed`]
	/// for the closure reason.
	ChannelClosing,
	/// The contribution's feerate was too low for RBF. Call [`ChannelManager::splice_channel`]
	/// for a fresh [`FundingTemplate`] (which includes the updated minimum feerate) and build a
	/// new contribution with a higher feerate.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	FeeRateTooLow,
	/// An RBF attempt could not be initiated (e.g., a prior splice transaction already
	/// confirmed). The channel remains operational — start a new splice with
	/// [`ChannelManager::splice_channel`] if further changes are needed.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	CannotInitiateRbf,
}

impl NegotiationFailureReason {
	/// Whether the splice negotiation is likely to succeed if retried on this channel. When `true`,
	/// call [`ChannelManager::splice_channel`] to obtain a fresh [`FundingTemplate`] and retry.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	pub fn is_retriable(&self) -> bool {
 match self {
 Self::Unknown
 | Self::PeerDisconnected
 | Self::ContributionInvalid
 | Self::FeeRateTooLow => true,
 Self::CounterpartyAborted { .. }
 | Self::NegotiationError { .. }
 | Self::LocallyAbandoned
 | Self::ChannelClosing
 | Self::CannotInitiateRbf => false,
 }
	}
}

impl core::fmt::Display for NegotiationFailureReason {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
 match self {
 Self::Unknown => f.write_str("unknown reason"),
 Self::PeerDisconnected => f.write_str("peer disconnected during negotiation"),
 Self::CounterpartyAborted { msg } => {
 write!(f, "counterparty aborted: {}", msg)
 },
 Self::NegotiationError { msg } => write!(f, "negotiation error: {}", msg),
 Self::ContributionInvalid => f.write_str("funding contribution was invalid"),
 Self::LocallyAbandoned => f.write_str("splice locally abandoned"),

 Self::ChannelClosing => f.write_str("channel is closing"),
 Self::FeeRateTooLow => f.write_str("feerate too low for RBF"),
 Self::CannotInitiateRbf => f.write_str("cannot initiate RBF"),
 }
	}
}

impl_writeable_tlv_based_enum_upgradable!(NegotiationFailureReason,
	(1, Unknown) => {},
	(3, PeerDisconnected) => {},
	(5, CounterpartyAborted) => {
 (1, msg, required),
	},
	(7, NegotiationError) => {
 (1, msg, required),
	},
	(9, ContributionInvalid) => {},
	(11, LocallyAbandoned) => {},
	(13, ChannelClosing) => {},
	(15, FeeRateTooLow) => {},
	(17, CannotInitiateRbf) => {},
);

/// 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)]
Expand DownExpand Up@@ -1541,8 +1655,8 @@ pub enum Event {
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SplicePending {
 /// The `channel_id` of the channel that has a pending splice funding transaction.
SpliceNegotiated {
 /// The `channel_id` of the channel with the negotiated splice funding transaction.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1560,19 +1674,20 @@ pub enum Event {
 /// The witness script that is used to lock the channel's funding output to commitment transactions.
 new_funding_redeem_script: ScriptBuf,
	},
	/// Used to indicate that a splice for the given `channel_id` has failed.
	/// Used to indicate that a splice negotiation round for the given `channel_id` has failed.
	///
	/// This event may be emitted if a splice fails after it has been initiated but prior to signing
	/// any negotiated funding transaction.
	/// Each splice attempt (initial or RBF) resolves to either [`Event::SpliceNegotiated`] on
	/// success or this event on failure. Prior successfully negotiated splice transactions are
	/// unaffected.
	///
	/// Any UTXOs contributed to be spent by the funding transaction may be reused and will be
	/// given in `contributed_inputs`.
	/// Any UTXOs contributed to the failed round that are not committed to a prior negotiated
	/// splice transaction will be returned via a preceding [`Event::DiscardFunding`].
	///
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SpliceFailed {
 /// The `channel_id` of the channel for which the splice failed.
SpliceNegotiationFailed {
 /// The `channel_id` of the channel for which the splice negotiation round failed.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1582,10 +1697,17 @@ pub enum Event {
 user_channel_id: u128,
 /// The `node_id` of the channel counterparty.
 counterparty_node_id: PublicKey,
 /// The outpoint of the channel's splice funding transaction, if one was created.
 abandoned_funding_txo: Option<OutPoint>,
 /// The features that this channel will operate with, if available.
 channel_type: Option<ChannelTypeFeatures>,

Comment on lines

-1585
 to 
-1588

@jkczyzjkczyzMar 26, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't feel like there was much value to these.
  • abandoned_funding_txo would be set only if there's a failure after the transaction was negotiated but before signed.
  • In the future, when channel_type can change, maybe it is just part of FundingContribution? Could also keep it if you prefer.
 /// The reason the splice negotiation failed.
 reason: NegotiationFailureReason,
 /// The funding contribution from the failed negotiation round, if available. This can be
 /// fed back to [`ChannelManager::funding_contributed`] to retry with the same parameters.
 /// Alternatively, call [`ChannelManager::splice_channel`] to obtain a fresh
 /// [`FundingTemplate`] and build a new contribution.
 ///
 /// [`ChannelManager::funding_contributed`]: crate::ln::channelmanager::ChannelManager::funding_contributed
 /// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
 /// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
 contribution: Option<FundingContribution>,
	},
	/// Used to indicate to the user that they can abandon the funding transaction and recycle the
	/// inputs for another purpose.
Expand DownExpand Up@@ -2355,7 +2477,7 @@ impl Writeable for Event {
 // We never write out FundingTransactionReadyForSigning events as they will be regenerated when
 // necessary.
 },
 &Event::SplicePending {
 &Event::SpliceNegotiated {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
Expand All@@ -2373,20 +2495,20 @@ impl Writeable for Event {
 (11, new_funding_redeem_script, required),
 });
 },
 &Event::SpliceFailed {
 &Event::SpliceNegotiationFailed {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
 ref abandoned_funding_txo,
 ref channel_type,
 ref reason,
 ref contribution,
 } => {
 52u8.write(writer)?;
 write_tlv_fields!(writer, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, required),
 (13, contribution, option),
 });
 },
 // Note that, going forward, all new events must only write data inside of
Expand DownExpand Up@@ -3012,7 +3134,7 @@ impl MaybeReadable for Event {
 (11, new_funding_redeem_script, required),
 });

 Ok(Some(Event::SplicePending {
 Ok(Some(Event::SpliceNegotiated {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
Expand All@@ -3027,18 +3149,18 @@ impl MaybeReadable for Event {
 let mut f = || {
 _init_and_read_len_prefixed_tlv_fields!(reader, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, upgradable_option),
 (13, contribution, option),
 });

 Ok(Some(Event::SpliceFailed {
 Ok(Some(Event::SpliceNegotiationFailed {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
abandoned_funding_txo,
channel_type,
reason: reason.unwrap_or(NegotiationFailureReason::Unknown),
contribution,
 }))
 };
 f()
Expand Down

8 changes: 4 additions & 4 deletions
lightning/src/ln/async_signer_tests.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1647,8 +1647,8 @@ fn test_async_splice_initial_commit_sig() {
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}

#[test]
Expand DownExpand Up@@ -1739,6 +1739,6 @@ fn test_async_splice_initial_commit_sig_waits_for_monitor_before_tx_signatures()
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Include failure context in splice events#4514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

TheBlueMatt
merged 11 commits into

from

May 7, 2026
 Merged


Include failure context in splice events
#4514
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
f0a8ceb

Add NegotiationFailureReason to SpliceFailed event


jkczyz Mar 25, 2026
450eb64

Add FundingContribution to SpliceFailed event


jkczyz Mar 25, 2026
14c6819

Emit DiscardFunding before SpliceFailed


jkczyz Mar 25, 2026
cc7fb0f

Rename SplicePending and SpliceFailed events


jkczyz Mar 25, 2026
2eb939b

Simplify contribution pop in reset_pending_splice_state


jkczyz Mar 27, 2026
9c6cca6

Fix output filtering in into_unique_contributions


jkczyz Mar 27, 2026
db45c83

Derive SpliceFundingFailed inputs from FundingContribution


jkczyz Mar 27, 2026
367ffaa

Remove unused NegotiationError and contributed_inputs_and_outputs met…


jkczyz Mar 27, 2026
b44076e

Add pending changelog for splice negotiation event changes


jkczyz Apr 3, 2026
ffbb8fe

Check can_initiate_rbf in stfu handler before sending tx_init_rbf


jkczyz Apr 13, 2026
51e6079

Derive DiscardFunding inputs and outputs from contributions on promotion


jkczyz Apr 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 3 additions & 2 deletions
fuzz/src/chanmon_consistency.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -930,6 +930,7 @@ fn assert_action_timeout_awaiting_response(action: &msgs::ErrorAction) {
 action,
 msgs::ErrorAction::DisconnectPeerWithWarning { msg }
 if msg.data.contains("Disconnecting due to timeout awaiting response")
 || msg.data.contains("already sent splice_locked, cannot RBF")
 ),
 "Expected timeout disconnect, got: {:?}",
 action,
Expand DownExpand Up@@ -2091,7 +2092,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 )
 .unwrap();
 },
 events::Event::SplicePending { new_funding_txo, .. } => {
 events::Event::SpliceNegotiated { new_funding_txo, .. } => {
 let broadcaster = match $node {
 0 => &broadcast_a,
 1 => &broadcast_b,
Expand All@@ -2103,7 +2104,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 assert_eq!(new_funding_txo.txid, splice_tx.compute_txid());
 chain_state.add_pending_tx(splice_tx);
 },
 events::Event::SpliceFailed { .. } => {},
 events::Event::SpliceNegotiationFailed { .. } => {},
 events::Event::DiscardFunding {
 funding_info:
 events::FundingInfo::Contribution { .. }
Expand Down

4 changes: 2 additions & 2 deletions
fuzz/src/full_stack.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1137,10 +1137,10 @@ pub fn do_test(mut data: &[u8], logger: &Arc<dyn Logger + MaybeSend + MaybeSync>
 signed_tx,
 );
 },
 Event::SplicePending { .. } => {
 Event::SpliceNegotiated { .. } => {
 // Splice negotiation completed, waiting for confirmation
 },
 Event::SpliceFailed { .. } => {
 Event::SpliceNegotiationFailed { .. } => {
 // Splice failed, inputs can be re-spent
 },
 Event::OpenChannelRequest {
Expand Down

172 changes: 147 additions & 25 deletions
lightning/src/events/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ use crate::blinded_path::payment::{
use crate::chain::transaction;
use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
use crate::ln::channelmanager::{InterceptId, PaymentId};
use crate::ln::funding::FundingContribution;
use crate::ln::msgs;
use crate::ln::onion_utils::LocalHTLCFailureReason;
use crate::ln::outbound_payment::RecipientOnionFields;
Expand DownExpand Up@@ -99,6 +100,119 @@ 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. Use [`is_retriable`] to determine whether the splice can
/// be reattempted on this channel by calling [`ChannelManager::splice_channel`].
///
/// [`is_retriable`]: Self::is_retriable
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
#[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. Wait for the peer to reconnect, then retry.
	PeerDisconnected,
	/// The counterparty explicitly aborted the negotiation by sending `tx_abort`. Retrying with
	/// the same parameters is unlikely to succeed — consider adjusting the contribution or
	/// waiting for the counterparty to initiate.
	CounterpartyAborted {
 /// The counterparty's abort message.
 ///
 /// This is counterparty-provided data. Use `Display` on [`UntrustedString`] for safe
 /// logging.
 msg: UntrustedString,
	},
	/// An error occurred during interactive transaction negotiation (e.g., the counterparty sent
	/// an invalid message). The negotiation was aborted.
	NegotiationError {
 /// A developer-readable error message.
 msg: String,
	},
	/// The funding contribution was invalid (e.g., insufficient balance for the splice amount).
	/// Call [`ChannelManager::splice_channel`] for a fresh [`FundingTemplate`] and build a new
	/// contribution with adjusted parameters.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	ContributionInvalid,
@TheBlueMattTheBlueMattApr 3, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does seem like some of these could use more details (error message string?). As-is given the recommendation for ~all enum variants is "retry by calling splice_channel again" its not really clear to me why we should bother with an enum - an enum is useful if the downstream code has different handling for different cases, but here that doesn't really seem likely/possible. If we can't expose more details that are useful for automated action, we could probably do with an enum with three variants and a developer-readable string.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the docs could be improved here. Maybe re-calling splice_channel isn't always necessary? In some cases, calling funding_contributed at a later time may be sufficient. We are providing the FundingContribution after all.
So it does seem like different actions are required depending on the variant.
  • PeerDisconnected: retry upon re-connection
  • ChannelNotReady: retry when channel is in a usable state (assuming it's not closing)
  • FeeRateTooLow: retry with a higher fee rate
  • ContributionInvalid: retry with a re-computed contribution
  • NegotiationError: probably not retryable as it indicates a counterparty error
  • CounterpartyAborted: might be able to retry but would need to examine the tx_abort message (e.g., counterparty doesn't like your fee rate).
We could have a top-level Retryable that holds one of these instead, if you prefer? We could go as far as only putting the FundingContribution in applicable sub-variants. Though a user may want to see it for other variants.
@TheBlueMattTheBlueMattApr 6, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume ChannelNotReady is really "you can't retry" (why were you splicing an unopened channel anyway? but probably its closing), FeeRateTooLow and ContributionInvalid are really "retry now with a fresh splice_channel call as that'll tell you what the new required feerate is to do a fresh rbf from scracth or will fix your contribution, hopefully". So it does seem like its basically "retry with a fresh splice_channel call, or not", with the one maybe-exception of PeerDisconnected? We could leave the enum and include a function that returns "retryable or not", but I'm not really sure why we shouldn't just return a string+bool pair (in a struct) - do we anticipate downstream code will have any different behavior based on anything beyond "should I retry this" or is it just gonna log/print an error?
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not other than when / how should you retry in case of the PeerDisconnected.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose given we don't know when the peer will reconnect, we might as well just process it the same and call splice_channel again upon re-connection. Otherwise, we'd need to make sure not to process the associated DiscardFunding which would mean locking up the UTXOs indefinitely. Instead, the client can simply always queue up a "retry when connected".
@jkczyzjkczyzApr 7, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed offline. Updated to have an is_retryable method that the counterparty calls rather than examining the variant. Would prevent allocating strings in many cases.
	/// The negotiation was locally abandoned via `ChannelManager::abandon_splice`.
	LocallyAbandoned,
	/// The channel is closing, so the negotiation cannot continue. See [`Event::ChannelClosed`]
	/// for the closure reason.
	ChannelClosing,
	/// The contribution's feerate was too low for RBF. Call [`ChannelManager::splice_channel`]
	/// for a fresh [`FundingTemplate`] (which includes the updated minimum feerate) and build a
	/// new contribution with a higher feerate.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	FeeRateTooLow,
	/// An RBF attempt could not be initiated (e.g., a prior splice transaction already
	/// confirmed). The channel remains operational — start a new splice with
	/// [`ChannelManager::splice_channel`] if further changes are needed.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	CannotInitiateRbf,
}

impl NegotiationFailureReason {
	/// Whether the splice negotiation is likely to succeed if retried on this channel. When `true`,
	/// call [`ChannelManager::splice_channel`] to obtain a fresh [`FundingTemplate`] and retry.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	pub fn is_retriable(&self) -> bool {
 match self {
 Self::Unknown
 | Self::PeerDisconnected
 | Self::ContributionInvalid
 | Self::FeeRateTooLow => true,
 Self::CounterpartyAborted { .. }
 | Self::NegotiationError { .. }
 | Self::LocallyAbandoned
 | Self::ChannelClosing
 | Self::CannotInitiateRbf => false,
 }
	}
}

impl core::fmt::Display for NegotiationFailureReason {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
 match self {
 Self::Unknown => f.write_str("unknown reason"),
 Self::PeerDisconnected => f.write_str("peer disconnected during negotiation"),
 Self::CounterpartyAborted { msg } => {
 write!(f, "counterparty aborted: {}", msg)
 },
 Self::NegotiationError { msg } => write!(f, "negotiation error: {}", msg),
 Self::ContributionInvalid => f.write_str("funding contribution was invalid"),
 Self::LocallyAbandoned => f.write_str("splice locally abandoned"),

 Self::ChannelClosing => f.write_str("channel is closing"),
 Self::FeeRateTooLow => f.write_str("feerate too low for RBF"),
 Self::CannotInitiateRbf => f.write_str("cannot initiate RBF"),
 }
	}
}

impl_writeable_tlv_based_enum_upgradable!(NegotiationFailureReason,
	(1, Unknown) => {},
	(3, PeerDisconnected) => {},
	(5, CounterpartyAborted) => {
 (1, msg, required),
	},
	(7, NegotiationError) => {
 (1, msg, required),
	},
	(9, ContributionInvalid) => {},
	(11, LocallyAbandoned) => {},
	(13, ChannelClosing) => {},
	(15, FeeRateTooLow) => {},
	(17, CannotInitiateRbf) => {},
);

/// 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)]
Expand DownExpand Up@@ -1541,8 +1655,8 @@ pub enum Event {
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SplicePending {
 /// The `channel_id` of the channel that has a pending splice funding transaction.
SpliceNegotiated {
 /// The `channel_id` of the channel with the negotiated splice funding transaction.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1560,19 +1674,20 @@ pub enum Event {
 /// The witness script that is used to lock the channel's funding output to commitment transactions.
 new_funding_redeem_script: ScriptBuf,
	},
	/// Used to indicate that a splice for the given `channel_id` has failed.
	/// Used to indicate that a splice negotiation round for the given `channel_id` has failed.
	///
	/// This event may be emitted if a splice fails after it has been initiated but prior to signing
	/// any negotiated funding transaction.
	/// Each splice attempt (initial or RBF) resolves to either [`Event::SpliceNegotiated`] on
	/// success or this event on failure. Prior successfully negotiated splice transactions are
	/// unaffected.
	///
	/// Any UTXOs contributed to be spent by the funding transaction may be reused and will be
	/// given in `contributed_inputs`.
	/// Any UTXOs contributed to the failed round that are not committed to a prior negotiated
	/// splice transaction will be returned via a preceding [`Event::DiscardFunding`].
	///
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SpliceFailed {
 /// The `channel_id` of the channel for which the splice failed.
SpliceNegotiationFailed {
 /// The `channel_id` of the channel for which the splice negotiation round failed.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1582,10 +1697,17 @@ pub enum Event {
 user_channel_id: u128,
 /// The `node_id` of the channel counterparty.
 counterparty_node_id: PublicKey,
 /// The outpoint of the channel's splice funding transaction, if one was created.
 abandoned_funding_txo: Option<OutPoint>,
 /// The features that this channel will operate with, if available.
 channel_type: Option<ChannelTypeFeatures>,

Comment on lines

-1585
 to 
-1588

@jkczyzjkczyzMar 26, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't feel like there was much value to these.
  • abandoned_funding_txo would be set only if there's a failure after the transaction was negotiated but before signed.
  • In the future, when channel_type can change, maybe it is just part of FundingContribution? Could also keep it if you prefer.
 /// The reason the splice negotiation failed.
 reason: NegotiationFailureReason,
 /// The funding contribution from the failed negotiation round, if available. This can be
 /// fed back to [`ChannelManager::funding_contributed`] to retry with the same parameters.
 /// Alternatively, call [`ChannelManager::splice_channel`] to obtain a fresh
 /// [`FundingTemplate`] and build a new contribution.
 ///
 /// [`ChannelManager::funding_contributed`]: crate::ln::channelmanager::ChannelManager::funding_contributed
 /// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
 /// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
 contribution: Option<FundingContribution>,
	},
	/// Used to indicate to the user that they can abandon the funding transaction and recycle the
	/// inputs for another purpose.
Expand DownExpand Up@@ -2355,7 +2477,7 @@ impl Writeable for Event {
 // We never write out FundingTransactionReadyForSigning events as they will be regenerated when
 // necessary.
 },
 &Event::SplicePending {
 &Event::SpliceNegotiated {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
Expand All@@ -2373,20 +2495,20 @@ impl Writeable for Event {
 (11, new_funding_redeem_script, required),
 });
 },
 &Event::SpliceFailed {
 &Event::SpliceNegotiationFailed {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
 ref abandoned_funding_txo,
 ref channel_type,
 ref reason,
 ref contribution,
 } => {
 52u8.write(writer)?;
 write_tlv_fields!(writer, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, required),
 (13, contribution, option),
 });
 },
 // Note that, going forward, all new events must only write data inside of
Expand DownExpand Up@@ -3012,7 +3134,7 @@ impl MaybeReadable for Event {
 (11, new_funding_redeem_script, required),
 });

 Ok(Some(Event::SplicePending {
 Ok(Some(Event::SpliceNegotiated {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
Expand All@@ -3027,18 +3149,18 @@ impl MaybeReadable for Event {
 let mut f = || {
 _init_and_read_len_prefixed_tlv_fields!(reader, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, upgradable_option),
 (13, contribution, option),
 });

 Ok(Some(Event::SpliceFailed {
 Ok(Some(Event::SpliceNegotiationFailed {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
abandoned_funding_txo,
channel_type,
reason: reason.unwrap_or(NegotiationFailureReason::Unknown),
contribution,
 }))
 };
 f()
Expand Down

8 changes: 4 additions & 4 deletions
lightning/src/ln/async_signer_tests.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1647,8 +1647,8 @@ fn test_async_splice_initial_commit_sig() {
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}

#[test]
Expand DownExpand Up@@ -1739,6 +1739,6 @@ fn test_async_splice_initial_commit_sig_waits_for_monitor_before_tx_signatures()
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Include failure context in splice events#4514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

TheBlueMatt
merged 11 commits into

from

May 7, 2026
 Merged


Include failure context in splice events
#4514
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
f0a8ceb

Add NegotiationFailureReason to SpliceFailed event


jkczyz Mar 25, 2026
450eb64

Add FundingContribution to SpliceFailed event


jkczyz Mar 25, 2026
14c6819

Emit DiscardFunding before SpliceFailed


jkczyz Mar 25, 2026
cc7fb0f

Rename SplicePending and SpliceFailed events


jkczyz Mar 25, 2026
2eb939b

Simplify contribution pop in reset_pending_splice_state


jkczyz Mar 27, 2026
9c6cca6

Fix output filtering in into_unique_contributions


jkczyz Mar 27, 2026
db45c83

Derive SpliceFundingFailed inputs from FundingContribution


jkczyz Mar 27, 2026
367ffaa

Remove unused NegotiationError and contributed_inputs_and_outputs met…


jkczyz Mar 27, 2026
b44076e

Add pending changelog for splice negotiation event changes


jkczyz Apr 3, 2026
ffbb8fe

Check can_initiate_rbf in stfu handler before sending tx_init_rbf


jkczyz Apr 13, 2026
51e6079

Derive DiscardFunding inputs and outputs from contributions on promotion


jkczyz Apr 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 3 additions & 2 deletions
fuzz/src/chanmon_consistency.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -930,6 +930,7 @@ fn assert_action_timeout_awaiting_response(action: &msgs::ErrorAction) {
 action,
 msgs::ErrorAction::DisconnectPeerWithWarning { msg }
 if msg.data.contains("Disconnecting due to timeout awaiting response")
 || msg.data.contains("already sent splice_locked, cannot RBF")
 ),
 "Expected timeout disconnect, got: {:?}",
 action,
Expand DownExpand Up@@ -2091,7 +2092,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 )
 .unwrap();
 },
 events::Event::SplicePending { new_funding_txo, .. } => {
 events::Event::SpliceNegotiated { new_funding_txo, .. } => {
 let broadcaster = match $node {
 0 => &broadcast_a,
 1 => &broadcast_b,
Expand All@@ -2103,7 +2104,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 assert_eq!(new_funding_txo.txid, splice_tx.compute_txid());
 chain_state.add_pending_tx(splice_tx);
 },
 events::Event::SpliceFailed { .. } => {},
 events::Event::SpliceNegotiationFailed { .. } => {},
 events::Event::DiscardFunding {
 funding_info:
 events::FundingInfo::Contribution { .. }
Expand Down

4 changes: 2 additions & 2 deletions
fuzz/src/full_stack.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1137,10 +1137,10 @@ pub fn do_test(mut data: &[u8], logger: &Arc<dyn Logger + MaybeSend + MaybeSync>
 signed_tx,
 );
 },
 Event::SplicePending { .. } => {
 Event::SpliceNegotiated { .. } => {
 // Splice negotiation completed, waiting for confirmation
 },
 Event::SpliceFailed { .. } => {
 Event::SpliceNegotiationFailed { .. } => {
 // Splice failed, inputs can be re-spent
 },
 Event::OpenChannelRequest {
Expand Down

172 changes: 147 additions & 25 deletions
lightning/src/events/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ use crate::blinded_path::payment::{
use crate::chain::transaction;
use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
use crate::ln::channelmanager::{InterceptId, PaymentId};
use crate::ln::funding::FundingContribution;
use crate::ln::msgs;
use crate::ln::onion_utils::LocalHTLCFailureReason;
use crate::ln::outbound_payment::RecipientOnionFields;
Expand DownExpand Up@@ -99,6 +100,119 @@ 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. Use [`is_retriable`] to determine whether the splice can
/// be reattempted on this channel by calling [`ChannelManager::splice_channel`].
///
/// [`is_retriable`]: Self::is_retriable
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
#[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. Wait for the peer to reconnect, then retry.
	PeerDisconnected,
	/// The counterparty explicitly aborted the negotiation by sending `tx_abort`. Retrying with
	/// the same parameters is unlikely to succeed — consider adjusting the contribution or
	/// waiting for the counterparty to initiate.
	CounterpartyAborted {
 /// The counterparty's abort message.
 ///
 /// This is counterparty-provided data. Use `Display` on [`UntrustedString`] for safe
 /// logging.
 msg: UntrustedString,
	},
	/// An error occurred during interactive transaction negotiation (e.g., the counterparty sent
	/// an invalid message). The negotiation was aborted.
	NegotiationError {
 /// A developer-readable error message.
 msg: String,
	},
	/// The funding contribution was invalid (e.g., insufficient balance for the splice amount).
	/// Call [`ChannelManager::splice_channel`] for a fresh [`FundingTemplate`] and build a new
	/// contribution with adjusted parameters.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	ContributionInvalid,
@TheBlueMattTheBlueMattApr 3, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does seem like some of these could use more details (error message string?). As-is given the recommendation for ~all enum variants is "retry by calling splice_channel again" its not really clear to me why we should bother with an enum - an enum is useful if the downstream code has different handling for different cases, but here that doesn't really seem likely/possible. If we can't expose more details that are useful for automated action, we could probably do with an enum with three variants and a developer-readable string.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the docs could be improved here. Maybe re-calling splice_channel isn't always necessary? In some cases, calling funding_contributed at a later time may be sufficient. We are providing the FundingContribution after all.
So it does seem like different actions are required depending on the variant.
  • PeerDisconnected: retry upon re-connection
  • ChannelNotReady: retry when channel is in a usable state (assuming it's not closing)
  • FeeRateTooLow: retry with a higher fee rate
  • ContributionInvalid: retry with a re-computed contribution
  • NegotiationError: probably not retryable as it indicates a counterparty error
  • CounterpartyAborted: might be able to retry but would need to examine the tx_abort message (e.g., counterparty doesn't like your fee rate).
We could have a top-level Retryable that holds one of these instead, if you prefer? We could go as far as only putting the FundingContribution in applicable sub-variants. Though a user may want to see it for other variants.
@TheBlueMattTheBlueMattApr 6, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume ChannelNotReady is really "you can't retry" (why were you splicing an unopened channel anyway? but probably its closing), FeeRateTooLow and ContributionInvalid are really "retry now with a fresh splice_channel call as that'll tell you what the new required feerate is to do a fresh rbf from scracth or will fix your contribution, hopefully". So it does seem like its basically "retry with a fresh splice_channel call, or not", with the one maybe-exception of PeerDisconnected? We could leave the enum and include a function that returns "retryable or not", but I'm not really sure why we shouldn't just return a string+bool pair (in a struct) - do we anticipate downstream code will have any different behavior based on anything beyond "should I retry this" or is it just gonna log/print an error?
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not other than when / how should you retry in case of the PeerDisconnected.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose given we don't know when the peer will reconnect, we might as well just process it the same and call splice_channel again upon re-connection. Otherwise, we'd need to make sure not to process the associated DiscardFunding which would mean locking up the UTXOs indefinitely. Instead, the client can simply always queue up a "retry when connected".
@jkczyzjkczyzApr 7, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed offline. Updated to have an is_retryable method that the counterparty calls rather than examining the variant. Would prevent allocating strings in many cases.
	/// The negotiation was locally abandoned via `ChannelManager::abandon_splice`.
	LocallyAbandoned,
	/// The channel is closing, so the negotiation cannot continue. See [`Event::ChannelClosed`]
	/// for the closure reason.
	ChannelClosing,
	/// The contribution's feerate was too low for RBF. Call [`ChannelManager::splice_channel`]
	/// for a fresh [`FundingTemplate`] (which includes the updated minimum feerate) and build a
	/// new contribution with a higher feerate.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	FeeRateTooLow,
	/// An RBF attempt could not be initiated (e.g., a prior splice transaction already
	/// confirmed). The channel remains operational — start a new splice with
	/// [`ChannelManager::splice_channel`] if further changes are needed.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	CannotInitiateRbf,
}

impl NegotiationFailureReason {
	/// Whether the splice negotiation is likely to succeed if retried on this channel. When `true`,
	/// call [`ChannelManager::splice_channel`] to obtain a fresh [`FundingTemplate`] and retry.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	pub fn is_retriable(&self) -> bool {
 match self {
 Self::Unknown
 | Self::PeerDisconnected
 | Self::ContributionInvalid
 | Self::FeeRateTooLow => true,
 Self::CounterpartyAborted { .. }
 | Self::NegotiationError { .. }
 | Self::LocallyAbandoned
 | Self::ChannelClosing
 | Self::CannotInitiateRbf => false,
 }
	}
}

impl core::fmt::Display for NegotiationFailureReason {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
 match self {
 Self::Unknown => f.write_str("unknown reason"),
 Self::PeerDisconnected => f.write_str("peer disconnected during negotiation"),
 Self::CounterpartyAborted { msg } => {
 write!(f, "counterparty aborted: {}", msg)
 },
 Self::NegotiationError { msg } => write!(f, "negotiation error: {}", msg),
 Self::ContributionInvalid => f.write_str("funding contribution was invalid"),
 Self::LocallyAbandoned => f.write_str("splice locally abandoned"),

 Self::ChannelClosing => f.write_str("channel is closing"),
 Self::FeeRateTooLow => f.write_str("feerate too low for RBF"),
 Self::CannotInitiateRbf => f.write_str("cannot initiate RBF"),
 }
	}
}

impl_writeable_tlv_based_enum_upgradable!(NegotiationFailureReason,
	(1, Unknown) => {},
	(3, PeerDisconnected) => {},
	(5, CounterpartyAborted) => {
 (1, msg, required),
	},
	(7, NegotiationError) => {
 (1, msg, required),
	},
	(9, ContributionInvalid) => {},
	(11, LocallyAbandoned) => {},
	(13, ChannelClosing) => {},
	(15, FeeRateTooLow) => {},
	(17, CannotInitiateRbf) => {},
);

/// 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)]
Expand DownExpand Up@@ -1541,8 +1655,8 @@ pub enum Event {
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SplicePending {
 /// The `channel_id` of the channel that has a pending splice funding transaction.
SpliceNegotiated {
 /// The `channel_id` of the channel with the negotiated splice funding transaction.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1560,19 +1674,20 @@ pub enum Event {
 /// The witness script that is used to lock the channel's funding output to commitment transactions.
 new_funding_redeem_script: ScriptBuf,
	},
	/// Used to indicate that a splice for the given `channel_id` has failed.
	/// Used to indicate that a splice negotiation round for the given `channel_id` has failed.
	///
	/// This event may be emitted if a splice fails after it has been initiated but prior to signing
	/// any negotiated funding transaction.
	/// Each splice attempt (initial or RBF) resolves to either [`Event::SpliceNegotiated`] on
	/// success or this event on failure. Prior successfully negotiated splice transactions are
	/// unaffected.
	///
	/// Any UTXOs contributed to be spent by the funding transaction may be reused and will be
	/// given in `contributed_inputs`.
	/// Any UTXOs contributed to the failed round that are not committed to a prior negotiated
	/// splice transaction will be returned via a preceding [`Event::DiscardFunding`].
	///
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SpliceFailed {
 /// The `channel_id` of the channel for which the splice failed.
SpliceNegotiationFailed {
 /// The `channel_id` of the channel for which the splice negotiation round failed.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1582,10 +1697,17 @@ pub enum Event {
 user_channel_id: u128,
 /// The `node_id` of the channel counterparty.
 counterparty_node_id: PublicKey,
 /// The outpoint of the channel's splice funding transaction, if one was created.
 abandoned_funding_txo: Option<OutPoint>,
 /// The features that this channel will operate with, if available.
 channel_type: Option<ChannelTypeFeatures>,

Comment on lines

-1585
 to 
-1588

@jkczyzjkczyzMar 26, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't feel like there was much value to these.
  • abandoned_funding_txo would be set only if there's a failure after the transaction was negotiated but before signed.
  • In the future, when channel_type can change, maybe it is just part of FundingContribution? Could also keep it if you prefer.
 /// The reason the splice negotiation failed.
 reason: NegotiationFailureReason,
 /// The funding contribution from the failed negotiation round, if available. This can be
 /// fed back to [`ChannelManager::funding_contributed`] to retry with the same parameters.
 /// Alternatively, call [`ChannelManager::splice_channel`] to obtain a fresh
 /// [`FundingTemplate`] and build a new contribution.
 ///
 /// [`ChannelManager::funding_contributed`]: crate::ln::channelmanager::ChannelManager::funding_contributed
 /// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
 /// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
 contribution: Option<FundingContribution>,
	},
	/// Used to indicate to the user that they can abandon the funding transaction and recycle the
	/// inputs for another purpose.
Expand DownExpand Up@@ -2355,7 +2477,7 @@ impl Writeable for Event {
 // We never write out FundingTransactionReadyForSigning events as they will be regenerated when
 // necessary.
 },
 &Event::SplicePending {
 &Event::SpliceNegotiated {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
Expand All@@ -2373,20 +2495,20 @@ impl Writeable for Event {
 (11, new_funding_redeem_script, required),
 });
 },
 &Event::SpliceFailed {
 &Event::SpliceNegotiationFailed {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
 ref abandoned_funding_txo,
 ref channel_type,
 ref reason,
 ref contribution,
 } => {
 52u8.write(writer)?;
 write_tlv_fields!(writer, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, required),
 (13, contribution, option),
 });
 },
 // Note that, going forward, all new events must only write data inside of
Expand DownExpand Up@@ -3012,7 +3134,7 @@ impl MaybeReadable for Event {
 (11, new_funding_redeem_script, required),
 });

 Ok(Some(Event::SplicePending {
 Ok(Some(Event::SpliceNegotiated {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
Expand All@@ -3027,18 +3149,18 @@ impl MaybeReadable for Event {
 let mut f = || {
 _init_and_read_len_prefixed_tlv_fields!(reader, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, upgradable_option),
 (13, contribution, option),
 });

 Ok(Some(Event::SpliceFailed {
 Ok(Some(Event::SpliceNegotiationFailed {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
abandoned_funding_txo,
channel_type,
reason: reason.unwrap_or(NegotiationFailureReason::Unknown),
contribution,
 }))
 };
 f()
Expand Down

8 changes: 4 additions & 4 deletions
lightning/src/ln/async_signer_tests.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1647,8 +1647,8 @@ fn test_async_splice_initial_commit_sig() {
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}

#[test]
Expand DownExpand Up@@ -1739,6 +1739,6 @@ fn test_async_splice_initial_commit_sig_waits_for_monitor_before_tx_signatures()
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Include failure context in splice events#4514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

TheBlueMatt
merged 11 commits into

from

May 7, 2026
 Merged


Include failure context in splice events
#4514
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
f0a8ceb

Add NegotiationFailureReason to SpliceFailed event


jkczyz Mar 25, 2026
450eb64

Add FundingContribution to SpliceFailed event


jkczyz Mar 25, 2026
14c6819

Emit DiscardFunding before SpliceFailed


jkczyz Mar 25, 2026
cc7fb0f

Rename SplicePending and SpliceFailed events


jkczyz Mar 25, 2026
2eb939b

Simplify contribution pop in reset_pending_splice_state


jkczyz Mar 27, 2026
9c6cca6

Fix output filtering in into_unique_contributions


jkczyz Mar 27, 2026
db45c83

Derive SpliceFundingFailed inputs from FundingContribution


jkczyz Mar 27, 2026
367ffaa

Remove unused NegotiationError and contributed_inputs_and_outputs met…


jkczyz Mar 27, 2026
b44076e

Add pending changelog for splice negotiation event changes


jkczyz Apr 3, 2026
ffbb8fe

Check can_initiate_rbf in stfu handler before sending tx_init_rbf


jkczyz Apr 13, 2026
51e6079

Derive DiscardFunding inputs and outputs from contributions on promotion


jkczyz Apr 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 3 additions & 2 deletions
fuzz/src/chanmon_consistency.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -930,6 +930,7 @@ fn assert_action_timeout_awaiting_response(action: &msgs::ErrorAction) {
 action,
 msgs::ErrorAction::DisconnectPeerWithWarning { msg }
 if msg.data.contains("Disconnecting due to timeout awaiting response")
 || msg.data.contains("already sent splice_locked, cannot RBF")
 ),
 "Expected timeout disconnect, got: {:?}",
 action,
Expand DownExpand Up@@ -2091,7 +2092,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 )
 .unwrap();
 },
 events::Event::SplicePending { new_funding_txo, .. } => {
 events::Event::SpliceNegotiated { new_funding_txo, .. } => {
 let broadcaster = match $node {
 0 => &broadcast_a,
 1 => &broadcast_b,
Expand All@@ -2103,7 +2104,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 assert_eq!(new_funding_txo.txid, splice_tx.compute_txid());
 chain_state.add_pending_tx(splice_tx);
 },
 events::Event::SpliceFailed { .. } => {},
 events::Event::SpliceNegotiationFailed { .. } => {},
 events::Event::DiscardFunding {
 funding_info:
 events::FundingInfo::Contribution { .. }
Expand Down

4 changes: 2 additions & 2 deletions
fuzz/src/full_stack.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1137,10 +1137,10 @@ pub fn do_test(mut data: &[u8], logger: &Arc<dyn Logger + MaybeSend + MaybeSync>
 signed_tx,
 );
 },
 Event::SplicePending { .. } => {
 Event::SpliceNegotiated { .. } => {
 // Splice negotiation completed, waiting for confirmation
 },
 Event::SpliceFailed { .. } => {
 Event::SpliceNegotiationFailed { .. } => {
 // Splice failed, inputs can be re-spent
 },
 Event::OpenChannelRequest {
Expand Down

172 changes: 147 additions & 25 deletions
lightning/src/events/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ use crate::blinded_path::payment::{
use crate::chain::transaction;
use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
use crate::ln::channelmanager::{InterceptId, PaymentId};
use crate::ln::funding::FundingContribution;
use crate::ln::msgs;
use crate::ln::onion_utils::LocalHTLCFailureReason;
use crate::ln::outbound_payment::RecipientOnionFields;
Expand DownExpand Up@@ -99,6 +100,119 @@ 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. Use [`is_retriable`] to determine whether the splice can
/// be reattempted on this channel by calling [`ChannelManager::splice_channel`].
///
/// [`is_retriable`]: Self::is_retriable
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
#[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. Wait for the peer to reconnect, then retry.
	PeerDisconnected,
	/// The counterparty explicitly aborted the negotiation by sending `tx_abort`. Retrying with
	/// the same parameters is unlikely to succeed — consider adjusting the contribution or
	/// waiting for the counterparty to initiate.
	CounterpartyAborted {
 /// The counterparty's abort message.
 ///
 /// This is counterparty-provided data. Use `Display` on [`UntrustedString`] for safe
 /// logging.
 msg: UntrustedString,
	},
	/// An error occurred during interactive transaction negotiation (e.g., the counterparty sent
	/// an invalid message). The negotiation was aborted.
	NegotiationError {
 /// A developer-readable error message.
 msg: String,
	},
	/// The funding contribution was invalid (e.g., insufficient balance for the splice amount).
	/// Call [`ChannelManager::splice_channel`] for a fresh [`FundingTemplate`] and build a new
	/// contribution with adjusted parameters.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	ContributionInvalid,
@TheBlueMattTheBlueMattApr 3, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does seem like some of these could use more details (error message string?). As-is given the recommendation for ~all enum variants is "retry by calling splice_channel again" its not really clear to me why we should bother with an enum - an enum is useful if the downstream code has different handling for different cases, but here that doesn't really seem likely/possible. If we can't expose more details that are useful for automated action, we could probably do with an enum with three variants and a developer-readable string.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the docs could be improved here. Maybe re-calling splice_channel isn't always necessary? In some cases, calling funding_contributed at a later time may be sufficient. We are providing the FundingContribution after all.
So it does seem like different actions are required depending on the variant.
  • PeerDisconnected: retry upon re-connection
  • ChannelNotReady: retry when channel is in a usable state (assuming it's not closing)
  • FeeRateTooLow: retry with a higher fee rate
  • ContributionInvalid: retry with a re-computed contribution
  • NegotiationError: probably not retryable as it indicates a counterparty error
  • CounterpartyAborted: might be able to retry but would need to examine the tx_abort message (e.g., counterparty doesn't like your fee rate).
We could have a top-level Retryable that holds one of these instead, if you prefer? We could go as far as only putting the FundingContribution in applicable sub-variants. Though a user may want to see it for other variants.
@TheBlueMattTheBlueMattApr 6, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume ChannelNotReady is really "you can't retry" (why were you splicing an unopened channel anyway? but probably its closing), FeeRateTooLow and ContributionInvalid are really "retry now with a fresh splice_channel call as that'll tell you what the new required feerate is to do a fresh rbf from scracth or will fix your contribution, hopefully". So it does seem like its basically "retry with a fresh splice_channel call, or not", with the one maybe-exception of PeerDisconnected? We could leave the enum and include a function that returns "retryable or not", but I'm not really sure why we shouldn't just return a string+bool pair (in a struct) - do we anticipate downstream code will have any different behavior based on anything beyond "should I retry this" or is it just gonna log/print an error?
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not other than when / how should you retry in case of the PeerDisconnected.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose given we don't know when the peer will reconnect, we might as well just process it the same and call splice_channel again upon re-connection. Otherwise, we'd need to make sure not to process the associated DiscardFunding which would mean locking up the UTXOs indefinitely. Instead, the client can simply always queue up a "retry when connected".
@jkczyzjkczyzApr 7, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed offline. Updated to have an is_retryable method that the counterparty calls rather than examining the variant. Would prevent allocating strings in many cases.
	/// The negotiation was locally abandoned via `ChannelManager::abandon_splice`.
	LocallyAbandoned,
	/// The channel is closing, so the negotiation cannot continue. See [`Event::ChannelClosed`]
	/// for the closure reason.
	ChannelClosing,
	/// The contribution's feerate was too low for RBF. Call [`ChannelManager::splice_channel`]
	/// for a fresh [`FundingTemplate`] (which includes the updated minimum feerate) and build a
	/// new contribution with a higher feerate.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	FeeRateTooLow,
	/// An RBF attempt could not be initiated (e.g., a prior splice transaction already
	/// confirmed). The channel remains operational — start a new splice with
	/// [`ChannelManager::splice_channel`] if further changes are needed.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	CannotInitiateRbf,
}

impl NegotiationFailureReason {
	/// Whether the splice negotiation is likely to succeed if retried on this channel. When `true`,
	/// call [`ChannelManager::splice_channel`] to obtain a fresh [`FundingTemplate`] and retry.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	pub fn is_retriable(&self) -> bool {
 match self {
 Self::Unknown
 | Self::PeerDisconnected
 | Self::ContributionInvalid
 | Self::FeeRateTooLow => true,
 Self::CounterpartyAborted { .. }
 | Self::NegotiationError { .. }
 | Self::LocallyAbandoned
 | Self::ChannelClosing
 | Self::CannotInitiateRbf => false,
 }
	}
}

impl core::fmt::Display for NegotiationFailureReason {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
 match self {
 Self::Unknown => f.write_str("unknown reason"),
 Self::PeerDisconnected => f.write_str("peer disconnected during negotiation"),
 Self::CounterpartyAborted { msg } => {
 write!(f, "counterparty aborted: {}", msg)
 },
 Self::NegotiationError { msg } => write!(f, "negotiation error: {}", msg),
 Self::ContributionInvalid => f.write_str("funding contribution was invalid"),
 Self::LocallyAbandoned => f.write_str("splice locally abandoned"),

 Self::ChannelClosing => f.write_str("channel is closing"),
 Self::FeeRateTooLow => f.write_str("feerate too low for RBF"),
 Self::CannotInitiateRbf => f.write_str("cannot initiate RBF"),
 }
	}
}

impl_writeable_tlv_based_enum_upgradable!(NegotiationFailureReason,
	(1, Unknown) => {},
	(3, PeerDisconnected) => {},
	(5, CounterpartyAborted) => {
 (1, msg, required),
	},
	(7, NegotiationError) => {
 (1, msg, required),
	},
	(9, ContributionInvalid) => {},
	(11, LocallyAbandoned) => {},
	(13, ChannelClosing) => {},
	(15, FeeRateTooLow) => {},
	(17, CannotInitiateRbf) => {},
);

/// 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)]
Expand DownExpand Up@@ -1541,8 +1655,8 @@ pub enum Event {
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SplicePending {
 /// The `channel_id` of the channel that has a pending splice funding transaction.
SpliceNegotiated {
 /// The `channel_id` of the channel with the negotiated splice funding transaction.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1560,19 +1674,20 @@ pub enum Event {
 /// The witness script that is used to lock the channel's funding output to commitment transactions.
 new_funding_redeem_script: ScriptBuf,
	},
	/// Used to indicate that a splice for the given `channel_id` has failed.
	/// Used to indicate that a splice negotiation round for the given `channel_id` has failed.
	///
	/// This event may be emitted if a splice fails after it has been initiated but prior to signing
	/// any negotiated funding transaction.
	/// Each splice attempt (initial or RBF) resolves to either [`Event::SpliceNegotiated`] on
	/// success or this event on failure. Prior successfully negotiated splice transactions are
	/// unaffected.
	///
	/// Any UTXOs contributed to be spent by the funding transaction may be reused and will be
	/// given in `contributed_inputs`.
	/// Any UTXOs contributed to the failed round that are not committed to a prior negotiated
	/// splice transaction will be returned via a preceding [`Event::DiscardFunding`].
	///
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SpliceFailed {
 /// The `channel_id` of the channel for which the splice failed.
SpliceNegotiationFailed {
 /// The `channel_id` of the channel for which the splice negotiation round failed.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1582,10 +1697,17 @@ pub enum Event {
 user_channel_id: u128,
 /// The `node_id` of the channel counterparty.
 counterparty_node_id: PublicKey,
 /// The outpoint of the channel's splice funding transaction, if one was created.
 abandoned_funding_txo: Option<OutPoint>,
 /// The features that this channel will operate with, if available.
 channel_type: Option<ChannelTypeFeatures>,

Comment on lines

-1585
 to 
-1588

@jkczyzjkczyzMar 26, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't feel like there was much value to these.
  • abandoned_funding_txo would be set only if there's a failure after the transaction was negotiated but before signed.
  • In the future, when channel_type can change, maybe it is just part of FundingContribution? Could also keep it if you prefer.
 /// The reason the splice negotiation failed.
 reason: NegotiationFailureReason,
 /// The funding contribution from the failed negotiation round, if available. This can be
 /// fed back to [`ChannelManager::funding_contributed`] to retry with the same parameters.
 /// Alternatively, call [`ChannelManager::splice_channel`] to obtain a fresh
 /// [`FundingTemplate`] and build a new contribution.
 ///
 /// [`ChannelManager::funding_contributed`]: crate::ln::channelmanager::ChannelManager::funding_contributed
 /// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
 /// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
 contribution: Option<FundingContribution>,
	},
	/// Used to indicate to the user that they can abandon the funding transaction and recycle the
	/// inputs for another purpose.
Expand DownExpand Up@@ -2355,7 +2477,7 @@ impl Writeable for Event {
 // We never write out FundingTransactionReadyForSigning events as they will be regenerated when
 // necessary.
 },
 &Event::SplicePending {
 &Event::SpliceNegotiated {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
Expand All@@ -2373,20 +2495,20 @@ impl Writeable for Event {
 (11, new_funding_redeem_script, required),
 });
 },
 &Event::SpliceFailed {
 &Event::SpliceNegotiationFailed {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
 ref abandoned_funding_txo,
 ref channel_type,
 ref reason,
 ref contribution,
 } => {
 52u8.write(writer)?;
 write_tlv_fields!(writer, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, required),
 (13, contribution, option),
 });
 },
 // Note that, going forward, all new events must only write data inside of
Expand DownExpand Up@@ -3012,7 +3134,7 @@ impl MaybeReadable for Event {
 (11, new_funding_redeem_script, required),
 });

 Ok(Some(Event::SplicePending {
 Ok(Some(Event::SpliceNegotiated {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
Expand All@@ -3027,18 +3149,18 @@ impl MaybeReadable for Event {
 let mut f = || {
 _init_and_read_len_prefixed_tlv_fields!(reader, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, upgradable_option),
 (13, contribution, option),
 });

 Ok(Some(Event::SpliceFailed {
 Ok(Some(Event::SpliceNegotiationFailed {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
abandoned_funding_txo,
channel_type,
reason: reason.unwrap_or(NegotiationFailureReason::Unknown),
contribution,
 }))
 };
 f()
Expand Down

8 changes: 4 additions & 4 deletions
lightning/src/ln/async_signer_tests.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1647,8 +1647,8 @@ fn test_async_splice_initial_commit_sig() {
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}

#[test]
Expand DownExpand Up@@ -1739,6 +1739,6 @@ fn test_async_splice_initial_commit_sig_waits_for_monitor_before_tx_signatures()
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Include failure context in splice events#4514

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

TheBlueMatt
merged 11 commits into

from

May 7, 2026
 Merged


Include failure context in splice events
#4514
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


11 commits


Select commit
Hold shift + click to select a range
f0a8ceb

Add NegotiationFailureReason to SpliceFailed event


jkczyz Mar 25, 2026
450eb64

Add FundingContribution to SpliceFailed event


jkczyz Mar 25, 2026
14c6819

Emit DiscardFunding before SpliceFailed


jkczyz Mar 25, 2026
cc7fb0f

Rename SplicePending and SpliceFailed events


jkczyz Mar 25, 2026
2eb939b

Simplify contribution pop in reset_pending_splice_state


jkczyz Mar 27, 2026
9c6cca6

Fix output filtering in into_unique_contributions


jkczyz Mar 27, 2026
db45c83

Derive SpliceFundingFailed inputs from FundingContribution


jkczyz Mar 27, 2026
367ffaa

Remove unused NegotiationError and contributed_inputs_and_outputs met…


jkczyz Mar 27, 2026
b44076e

Add pending changelog for splice negotiation event changes


jkczyz Apr 3, 2026
ffbb8fe

Check can_initiate_rbf in stfu handler before sending tx_init_rbf


jkczyz Apr 13, 2026
51e6079

Derive DiscardFunding inputs and outputs from contributions on promotion


jkczyz Apr 16, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 3 additions & 2 deletions
fuzz/src/chanmon_consistency.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -930,6 +930,7 @@ fn assert_action_timeout_awaiting_response(action: &msgs::ErrorAction) {
 action,
 msgs::ErrorAction::DisconnectPeerWithWarning { msg }
 if msg.data.contains("Disconnecting due to timeout awaiting response")
 || msg.data.contains("already sent splice_locked, cannot RBF")
 ),
 "Expected timeout disconnect, got: {:?}",
 action,
Expand DownExpand Up@@ -2091,7 +2092,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 )
 .unwrap();
 },
 events::Event::SplicePending { new_funding_txo, .. } => {
 events::Event::SpliceNegotiated { new_funding_txo, .. } => {
 let broadcaster = match $node {
 0 => &broadcast_a,
 1 => &broadcast_b,
Expand All@@ -2103,7 +2104,7 @@ pub fn do_test<Out: Output + MaybeSend + MaybeSync>(data: &[u8], out: Out) {
 assert_eq!(new_funding_txo.txid, splice_tx.compute_txid());
 chain_state.add_pending_tx(splice_tx);
 },
 events::Event::SpliceFailed { .. } => {},
 events::Event::SpliceNegotiationFailed { .. } => {},
 events::Event::DiscardFunding {
 funding_info:
 events::FundingInfo::Contribution { .. }
Expand Down

4 changes: 2 additions & 2 deletions
fuzz/src/full_stack.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1137,10 +1137,10 @@ pub fn do_test(mut data: &[u8], logger: &Arc<dyn Logger + MaybeSend + MaybeSync>
 signed_tx,
 );
 },
 Event::SplicePending { .. } => {
 Event::SpliceNegotiated { .. } => {
 // Splice negotiation completed, waiting for confirmation
 },
 Event::SpliceFailed { .. } => {
 Event::SpliceNegotiationFailed { .. } => {
 // Splice failed, inputs can be re-spent
 },
 Event::OpenChannelRequest {
Expand Down

172 changes: 147 additions & 25 deletions
lightning/src/events/mod.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -25,6 +25,7 @@ use crate::blinded_path::payment::{
use crate::chain::transaction;
use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
use crate::ln::channelmanager::{InterceptId, PaymentId};
use crate::ln::funding::FundingContribution;
use crate::ln::msgs;
use crate::ln::onion_utils::LocalHTLCFailureReason;
use crate::ln::outbound_payment::RecipientOnionFields;
Expand DownExpand Up@@ -99,6 +100,119 @@ 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. Use [`is_retriable`] to determine whether the splice can
/// be reattempted on this channel by calling [`ChannelManager::splice_channel`].
///
/// [`is_retriable`]: Self::is_retriable
/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
#[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. Wait for the peer to reconnect, then retry.
	PeerDisconnected,
	/// The counterparty explicitly aborted the negotiation by sending `tx_abort`. Retrying with
	/// the same parameters is unlikely to succeed — consider adjusting the contribution or
	/// waiting for the counterparty to initiate.
	CounterpartyAborted {
 /// The counterparty's abort message.
 ///
 /// This is counterparty-provided data. Use `Display` on [`UntrustedString`] for safe
 /// logging.
 msg: UntrustedString,
	},
	/// An error occurred during interactive transaction negotiation (e.g., the counterparty sent
	/// an invalid message). The negotiation was aborted.
	NegotiationError {
 /// A developer-readable error message.
 msg: String,
	},
	/// The funding contribution was invalid (e.g., insufficient balance for the splice amount).
	/// Call [`ChannelManager::splice_channel`] for a fresh [`FundingTemplate`] and build a new
	/// contribution with adjusted parameters.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	ContributionInvalid,
@TheBlueMattTheBlueMattApr 3, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does seem like some of these could use more details (error message string?). As-is given the recommendation for ~all enum variants is "retry by calling splice_channel again" its not really clear to me why we should bother with an enum - an enum is useful if the downstream code has different handling for different cases, but here that doesn't really seem likely/possible. If we can't expose more details that are useful for automated action, we could probably do with an enum with three variants and a developer-readable string.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, the docs could be improved here. Maybe re-calling splice_channel isn't always necessary? In some cases, calling funding_contributed at a later time may be sufficient. We are providing the FundingContribution after all.
So it does seem like different actions are required depending on the variant.
  • PeerDisconnected: retry upon re-connection
  • ChannelNotReady: retry when channel is in a usable state (assuming it's not closing)
  • FeeRateTooLow: retry with a higher fee rate
  • ContributionInvalid: retry with a re-computed contribution
  • NegotiationError: probably not retryable as it indicates a counterparty error
  • CounterpartyAborted: might be able to retry but would need to examine the tx_abort message (e.g., counterparty doesn't like your fee rate).
We could have a top-level Retryable that holds one of these instead, if you prefer? We could go as far as only putting the FundingContribution in applicable sub-variants. Though a user may want to see it for other variants.
@TheBlueMattTheBlueMattApr 6, 2026

Copy link


Copy Markdown

Collaborator
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume ChannelNotReady is really "you can't retry" (why were you splicing an unopened channel anyway? but probably its closing), FeeRateTooLow and ContributionInvalid are really "retry now with a fresh splice_channel call as that'll tell you what the new required feerate is to do a fresh rbf from scracth or will fix your contribution, hopefully". So it does seem like its basically "retry with a fresh splice_channel call, or not", with the one maybe-exception of PeerDisconnected? We could leave the enum and include a function that returns "retryable or not", but I'm not really sure why we shouldn't just return a string+bool pair (in a struct) - do we anticipate downstream code will have any different behavior based on anything beyond "should I retry this" or is it just gonna log/print an error?
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably not other than when / how should you retry in case of the PeerDisconnected.
@jkczyzjkczyzApr 6, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose given we don't know when the peer will reconnect, we might as well just process it the same and call splice_channel again upon re-connection. Otherwise, we'd need to make sure not to process the associated DiscardFunding which would mean locking up the UTXOs indefinitely. Instead, the client can simply always queue up a "retry when connected".
@jkczyzjkczyzApr 7, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed offline. Updated to have an is_retryable method that the counterparty calls rather than examining the variant. Would prevent allocating strings in many cases.
	/// The negotiation was locally abandoned via `ChannelManager::abandon_splice`.
	LocallyAbandoned,
	/// The channel is closing, so the negotiation cannot continue. See [`Event::ChannelClosed`]
	/// for the closure reason.
	ChannelClosing,
	/// The contribution's feerate was too low for RBF. Call [`ChannelManager::splice_channel`]
	/// for a fresh [`FundingTemplate`] (which includes the updated minimum feerate) and build a
	/// new contribution with a higher feerate.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	FeeRateTooLow,
	/// An RBF attempt could not be initiated (e.g., a prior splice transaction already
	/// confirmed). The channel remains operational — start a new splice with
	/// [`ChannelManager::splice_channel`] if further changes are needed.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	CannotInitiateRbf,
}

impl NegotiationFailureReason {
	/// Whether the splice negotiation is likely to succeed if retried on this channel. When `true`,
	/// call [`ChannelManager::splice_channel`] to obtain a fresh [`FundingTemplate`] and retry.
	///
	/// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
	/// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
	pub fn is_retriable(&self) -> bool {
 match self {
 Self::Unknown
 | Self::PeerDisconnected
 | Self::ContributionInvalid
 | Self::FeeRateTooLow => true,
 Self::CounterpartyAborted { .. }
 | Self::NegotiationError { .. }
 | Self::LocallyAbandoned
 | Self::ChannelClosing
 | Self::CannotInitiateRbf => false,
 }
	}
}

impl core::fmt::Display for NegotiationFailureReason {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
 match self {
 Self::Unknown => f.write_str("unknown reason"),
 Self::PeerDisconnected => f.write_str("peer disconnected during negotiation"),
 Self::CounterpartyAborted { msg } => {
 write!(f, "counterparty aborted: {}", msg)
 },
 Self::NegotiationError { msg } => write!(f, "negotiation error: {}", msg),
 Self::ContributionInvalid => f.write_str("funding contribution was invalid"),
 Self::LocallyAbandoned => f.write_str("splice locally abandoned"),

 Self::ChannelClosing => f.write_str("channel is closing"),
 Self::FeeRateTooLow => f.write_str("feerate too low for RBF"),
 Self::CannotInitiateRbf => f.write_str("cannot initiate RBF"),
 }
	}
}

impl_writeable_tlv_based_enum_upgradable!(NegotiationFailureReason,
	(1, Unknown) => {},
	(3, PeerDisconnected) => {},
	(5, CounterpartyAborted) => {
 (1, msg, required),
	},
	(7, NegotiationError) => {
 (1, msg, required),
	},
	(9, ContributionInvalid) => {},
	(11, LocallyAbandoned) => {},
	(13, ChannelClosing) => {},
	(15, FeeRateTooLow) => {},
	(17, CannotInitiateRbf) => {},
);

/// 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)]
Expand DownExpand Up@@ -1541,8 +1655,8 @@ pub enum Event {
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SplicePending {
 /// The `channel_id` of the channel that has a pending splice funding transaction.
SpliceNegotiated {
 /// The `channel_id` of the channel with the negotiated splice funding transaction.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1560,19 +1674,20 @@ pub enum Event {
 /// The witness script that is used to lock the channel's funding output to commitment transactions.
 new_funding_redeem_script: ScriptBuf,
	},
	/// Used to indicate that a splice for the given `channel_id` has failed.
	/// Used to indicate that a splice negotiation round for the given `channel_id` has failed.
	///
	/// This event may be emitted if a splice fails after it has been initiated but prior to signing
	/// any negotiated funding transaction.
	/// Each splice attempt (initial or RBF) resolves to either [`Event::SpliceNegotiated`] on
	/// success or this event on failure. Prior successfully negotiated splice transactions are
	/// unaffected.
	///
	/// Any UTXOs contributed to be spent by the funding transaction may be reused and will be
	/// given in `contributed_inputs`.
	/// Any UTXOs contributed to the failed round that are not committed to a prior negotiated
	/// splice transaction will be returned via a preceding [`Event::DiscardFunding`].
	///
	/// # Failure Behavior and Persistence
	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
SpliceFailed {
 /// The `channel_id` of the channel for which the splice failed.
SpliceNegotiationFailed {
 /// The `channel_id` of the channel for which the splice negotiation round failed.
 channel_id: ChannelId,
 /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
 /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels.
Expand All@@ -1582,10 +1697,17 @@ pub enum Event {
 user_channel_id: u128,
 /// The `node_id` of the channel counterparty.
 counterparty_node_id: PublicKey,
 /// The outpoint of the channel's splice funding transaction, if one was created.
 abandoned_funding_txo: Option<OutPoint>,
 /// The features that this channel will operate with, if available.
 channel_type: Option<ChannelTypeFeatures>,

Comment on lines

-1585
 to 
-1588

@jkczyzjkczyzMar 26, 2026

Copy link


Copy Markdown

ContributorAuthor
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't feel like there was much value to these.
  • abandoned_funding_txo would be set only if there's a failure after the transaction was negotiated but before signed.
  • In the future, when channel_type can change, maybe it is just part of FundingContribution? Could also keep it if you prefer.
 /// The reason the splice negotiation failed.
 reason: NegotiationFailureReason,
 /// The funding contribution from the failed negotiation round, if available. This can be
 /// fed back to [`ChannelManager::funding_contributed`] to retry with the same parameters.
 /// Alternatively, call [`ChannelManager::splice_channel`] to obtain a fresh
 /// [`FundingTemplate`] and build a new contribution.
 ///
 /// [`ChannelManager::funding_contributed`]: crate::ln::channelmanager::ChannelManager::funding_contributed
 /// [`ChannelManager::splice_channel`]: crate::ln::channelmanager::ChannelManager::splice_channel
 /// [`FundingTemplate`]: crate::ln::funding::FundingTemplate
 contribution: Option<FundingContribution>,
	},
	/// Used to indicate to the user that they can abandon the funding transaction and recycle the
	/// inputs for another purpose.
Expand DownExpand Up@@ -2355,7 +2477,7 @@ impl Writeable for Event {
 // We never write out FundingTransactionReadyForSigning events as they will be regenerated when
 // necessary.
 },
 &Event::SplicePending {
 &Event::SpliceNegotiated {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
Expand All@@ -2373,20 +2495,20 @@ impl Writeable for Event {
 (11, new_funding_redeem_script, required),
 });
 },
 &Event::SpliceFailed {
 &Event::SpliceNegotiationFailed {
 ref channel_id,
 ref user_channel_id,
 ref counterparty_node_id,
 ref abandoned_funding_txo,
 ref channel_type,
 ref reason,
 ref contribution,
 } => {
 52u8.write(writer)?;
 write_tlv_fields!(writer, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, required),
 (13, contribution, option),
 });
 },
 // Note that, going forward, all new events must only write data inside of
Expand DownExpand Up@@ -3012,7 +3134,7 @@ impl MaybeReadable for Event {
 (11, new_funding_redeem_script, required),
 });

 Ok(Some(Event::SplicePending {
 Ok(Some(Event::SpliceNegotiated {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
Expand All@@ -3027,18 +3149,18 @@ impl MaybeReadable for Event {
 let mut f = || {
 _init_and_read_len_prefixed_tlv_fields!(reader, {
 (1, channel_id, required),
 (3, channel_type, option),
 (5, user_channel_id, required),
 (7, counterparty_node_id, required),
 (9, abandoned_funding_txo, option),
 (11, reason, upgradable_option),
 (13, contribution, option),
 });

 Ok(Some(Event::SpliceFailed {
 Ok(Some(Event::SpliceNegotiationFailed {
 channel_id: channel_id.0.unwrap(),
 user_channel_id: user_channel_id.0.unwrap(),
 counterparty_node_id: counterparty_node_id.0.unwrap(),
abandoned_funding_txo,
channel_type,
reason: reason.unwrap_or(NegotiationFailureReason::Unknown),
contribution,
 }))
 };
 f()
Expand Down

8 changes: 4 additions & 4 deletions
lightning/src/ln/async_signer_tests.rs

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -1647,8 +1647,8 @@ fn test_async_splice_initial_commit_sig() {
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}

#[test]
Expand DownExpand Up@@ -1739,6 +1739,6 @@ fn test_async_splice_initial_commit_sig_waits_for_monitor_before_tx_signatures()
 get_event_msg!(initiator, MessageSendEvent::SendTxSignatures, acceptor_node_id);
	acceptor.node.handle_tx_signatures(initiator_node_id, &tx_signatures);

	let _ = get_event!(initiator, Event::SplicePending);
	let _ = get_event!(acceptor, Event::SplicePending);
	let _ = get_event!(initiator, Event::SpliceNegotiated);
	let _ = get_event!(acceptor, Event::SpliceNegotiated);
}
Loading
Loading