Merge PR 'Document that funding signing events can go stale' (#4960)
What the developer wrote
Authored by Matt Corallo
Merge PR 'Document that funding signing events can go stale' (#4960)
from bot/4951-fundingtransactionreadyforsignin-fa0568 into main
Reviewed-on: https://git.rust-bitcoin.org/lightningdevkit/rust-lightning/pulls/4960
Reviewed-by: Matt Corallo <matt@noreply.git.rust-bitcoin.org>
What changed, and why it matters
This commit only adds documentation comments to two source files. It explains that certain funding-signing events can become stale if the underlying negotiation fails, and that callers may see specific harmless errors as a result. No code behavior was changed.
No action required; this is a documentation-only change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff adds rustdoc comments to Event::FundingTransactionReadyForSigning in lightning/src/events/mod.rs and to ChannelManager::funding_transaction_signed / ChannelManager::funding_transaction_signed (splice variant) in lightning/src/ln/channelmanager.rs. The comments clarify that APIError::APIMisuseError or APIError::ChannelUnavailable can be returned when the funding negotiation failed while the event was pending, and list the follow-up events (DiscardFunding, SpliceNegotiationFailed, ChannelClosed). There are no logic, API, or state-machine changes.
Changed components
lightning/src/events/mod.rslightning/src/ln/channelmanager.rsInspect captured patch +15 / −0
### lightning/src/events/mod.rs
@@ -2103,6 +2103,15 @@ pub enum Event {
/// signed funding transaction. For splices where you contributed inputs or outputs, call
/// [`ChannelManager::cancel_funding_contributed`] instead if you no longer wish to proceed.
///
+ /// The funding negotiation may fail while this event is pending, e.g. because the counterparty
+ /// aborted it or the channel was closed, in which case
+ /// [`ChannelManager::funding_transaction_signed`] returns an [`APIError::APIMisuseError`] or
+ /// [`APIError::ChannelUnavailable`] without you having done anything wrong. The negotiated
+ /// funding transaction will then never be used. For a splice, an [`Event::DiscardFunding`] (for
+ /// any contributions not also committed to another splice attempt) and an
+ /// [`Event::SpliceNegotiationFailed`] follow, whereas for a channel being opened an
+ /// [`Event::ChannelClosed`] is generated.
+ ///
/// Generated in [`ChannelManager`] message handling.
///
/// # Failure Behavior and Persistence
### lightning/src/ln/channelmanager.rs
@@ -5107,6 +5107,9 @@ impl<
///
/// Returns [`ChannelUnavailable`] when a channel is not found or an incorrect
/// `counterparty_node_id` is provided, or [`APIMisuseError`] otherwise with the error details.
+ /// As with [`ChannelManager::funding_transaction_signed`], either error may be returned simply
+ /// because the funding negotiation failed while its
+ /// [`Event::FundingTransactionReadyForSigning`] was being handled.
///
/// [`Event::FundingTransactionReadyForSigning`]: events::Event::FundingTransactionReadyForSigning
/// [`ChannelUnavailable`]: APIError::ChannelUnavailable
@@ -7181,6 +7184,9 @@ impl<
/// Returns [`APIMisuseError`] when a channel is not in a state where it is expecting funding
/// signatures or if any of the checks described above fail.
///
+ /// Note that either error may be returned simply because the funding negotiation failed while
+ /// its [`FundingTransactionReadyForSigning`] event was being handled.
+ ///
/// [`FundingTransactionReadyForSigning`]: events::Event::FundingTransactionReadyForSigning
/// [`ChannelUnavailable`]: APIError::ChannelUnavailable
/// [`APIMisuseError`]: APIError::APIMisuseErrorWhy this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.