From: Elias Rohrer Date: Mon, 8 Jul 2024 13:43:18 +0000 (+0200) Subject: Document `Failure Behavior and Persistence` for every event type X-Git-Tag: v0.0.124-beta~41^2 X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=commitdiff_plain;h=e617a394e8c4a6339be48688c0a0a531f778fdbb;p=rust-lightning Document `Failure Behavior and Persistence` for every event type --- diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs index e51a0972c..0e24e8e82 100644 --- a/lightning/src/events/mod.rs +++ b/lightning/src/events/mod.rs @@ -551,6 +551,10 @@ pub enum Event { /// Note that *all inputs* in the funding transaction must spend SegWit outputs or your /// counterparty can steal your funds! /// + /// # Failure Behavior and Persistence + /// This event will eventually be replayed after failures-to-handle (i.e., the event handler + /// returning `Err(ReplayEvent ())`), but won't be persisted across restarts. + /// /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated FundingGenerationReady { @@ -608,6 +612,10 @@ pub enum Event { /// # Note /// This event used to be called `PaymentReceived` in LDK versions 0.0.112 and earlier. /// + /// # 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. + /// /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds /// [`ChannelManager::claim_funds_with_known_custom_tlvs`]: crate::ln::channelmanager::ChannelManager::claim_funds_with_known_custom_tlvs /// [`FailureCode::InvalidOnionPayload`]: crate::ln::channelmanager::FailureCode::InvalidOnionPayload @@ -677,6 +685,10 @@ pub enum Event { /// [`ChannelManager::claim_funds`] twice for the same [`Event::PaymentClaimable`] you may get /// multiple `PaymentClaimed` events. /// + /// # 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. + /// /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds PaymentClaimed { /// The node that received the payment. @@ -716,6 +728,10 @@ pub enum Event { /// This event will not be generated for onion message forwards; only for sends including /// replies. Handlers should connect to the node otherwise any buffered messages may be lost. /// + /// # Failure Behavior and Persistence + /// This event will eventually be replayed after failures-to-handle (i.e., the event handler + /// returning `Err(ReplayEvent ())`), but won't be persisted across restarts. + /// /// [`OnionMessage`]: msgs::OnionMessage /// [`MessageRouter`]: crate::onion_message::messenger::MessageRouter /// [`Destination`]: crate::onion_message::messenger::Destination @@ -730,6 +746,10 @@ pub enum Event { /// or was explicitly abandoned by [`ChannelManager::abandon_payment`]. This may be for an /// [`InvoiceRequest`] sent for an [`Offer`] or for a [`Refund`] that hasn't been redeemed. /// + /// # 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. + /// /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest /// [`Offer`]: crate::offers::offer::Offer @@ -746,6 +766,10 @@ pub enum Event { /// [`ChannelManager::abandon_payment`] to abandon the associated payment. See those docs for /// further details. /// + /// # 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. + /// /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest /// [`Refund`]: crate::offers::refund::Refund /// [`UserConfig::manually_handle_bolt12_invoices`]: crate::util::config::UserConfig::manually_handle_bolt12_invoices @@ -768,6 +792,10 @@ pub enum Event { /// /// Note for MPP payments: in rare cases, this event may be preceded by a `PaymentPathFailed` /// event. In this situation, you SHOULD treat this payment as having succeeded. + /// + /// # 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. PaymentSent { /// The `payment_id` passed to [`ChannelManager::send_payment`]. /// @@ -806,6 +834,10 @@ pub enum Event { /// received and processed. In this case, the [`Event::PaymentFailed`] event MUST be ignored, /// and the payment MUST be treated as having succeeded. /// + /// # 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. + /// /// [`Retry`]: crate::ln::channelmanager::Retry /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment PaymentFailed { @@ -825,6 +857,10 @@ pub enum Event { /// /// Always generated after [`Event::PaymentSent`] and thus useful for scoring channels. See /// [`Event::PaymentSent`] for obtaining the payment preimage. + /// + /// # 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. PaymentPathSuccessful { /// The `payment_id` passed to [`ChannelManager::send_payment`]. /// @@ -850,6 +886,10 @@ pub enum Event { /// See [`ChannelManager::abandon_payment`] for giving up on this payment before its retries have /// been exhausted. /// + /// # 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. + /// /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment PaymentPathFailed { /// The `payment_id` passed to [`ChannelManager::send_payment`]. @@ -889,6 +929,10 @@ pub enum Event { error_data: Option>, }, /// Indicates that a probe payment we sent returned successful, i.e., only failed at the destination. + /// + /// # 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. ProbeSuccessful { /// The id returned by [`ChannelManager::send_probe`]. /// @@ -902,6 +946,10 @@ pub enum Event { path: Path, }, /// Indicates that a probe payment we sent failed at an intermediary node on the path. + /// + /// # 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. ProbeFailed { /// The id returned by [`ChannelManager::send_probe`]. /// @@ -923,6 +971,10 @@ pub enum Event { /// Used to indicate that [`ChannelManager::process_pending_htlc_forwards`] should be called at /// a time in the future. /// + /// # 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 regenerated after restarts. + /// /// [`ChannelManager::process_pending_htlc_forwards`]: crate::ln::channelmanager::ChannelManager::process_pending_htlc_forwards PendingHTLCsForwardable { /// The minimum amount of time that should be waited prior to calling @@ -939,6 +991,10 @@ pub enum Event { /// [`ChannelManager::fail_intercepted_htlc`] MUST be called in response to this event. See /// their docs for more information. /// + /// # 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. + /// /// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid /// [`UserConfig::accept_intercept_htlcs`]: crate::util::config::UserConfig::accept_intercept_htlcs /// [`ChannelManager::forward_intercepted_htlc`]: crate::ln::channelmanager::ChannelManager::forward_intercepted_htlc @@ -974,6 +1030,10 @@ pub enum Event { /// You may hand them to the [`OutputSweeper`] utility which will store and (re-)generate spending /// transactions for you. /// + /// # 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. + /// /// [`OutputSweeper`]: crate::util::sweep::OutputSweeper SpendableOutputs { /// The outputs which you should store as spendable by you. @@ -985,6 +1045,10 @@ pub enum Event { }, /// This event is generated when a payment has been successfully forwarded through us and a /// forwarding fee earned. + /// + /// # 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. PaymentForwarded { /// The channel id of the incoming channel between the previous node and us. /// @@ -1046,6 +1110,10 @@ pub enum Event { /// This event is emitted when the funding transaction has been signed and is broadcast to the /// network. For 0conf channels it will be immediately followed by the corresponding /// [`Event::ChannelReady`] 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. ChannelPending { /// The `channel_id` of the channel that is pending confirmation. channel_id: ChannelId, @@ -1075,6 +1143,10 @@ pub enum Event { /// be used. This event is emitted either when the funding transaction has been confirmed /// on-chain, or, in case of a 0conf channel, when both parties have confirmed the channel /// establishment. + /// + /// # 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. ChannelReady { /// The `channel_id` of the channel that is ready. channel_id: ChannelId, @@ -1101,6 +1173,10 @@ pub enum Event { /// /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels + /// + /// # 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. ChannelClosed { /// The `channel_id` of the channel which has been closed. Note that on-chain transactions /// resolving the channel are likely still awaiting confirmation. @@ -1135,6 +1211,10 @@ pub enum Event { /// inputs for another purpose. /// /// This event is not guaranteed to be generated for channels that are closed due to a restart. + /// + /// # 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. DiscardFunding { /// The channel_id of the channel which has been closed. channel_id: ChannelId, @@ -1150,6 +1230,10 @@ pub enum Event { /// The event is only triggered when a new open channel request is received and the /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. /// + /// # 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. + /// /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel /// [`ChannelManager::force_close_without_broadcasting_txn`]: crate::ln::channelmanager::ChannelManager::force_close_without_broadcasting_txn /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels @@ -1206,6 +1290,10 @@ pub enum Event { /// /// This event, however, does not get generated if an HTLC fails to meet the forwarding /// requirements (i.e. insufficient fees paid, or a CLTV that is too soon). + /// + /// # 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. HTLCHandlingFailed { /// The channel over which the HTLC was received. prev_channel_id: ChannelId, @@ -1219,6 +1307,10 @@ pub enum Event { /// [`ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx`] config flag is set to true. /// It is limited to the scope of channels with anchor outputs. /// + /// # Failure Behavior and Persistence + /// This event will eventually be replayed after failures-to-handle (i.e., the event handler + /// returning `Err(ReplayEvent ())`), but will only be regenerated as needed after restarts. + /// /// [`ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx`]: crate::util::config::ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx BumpTransaction(BumpTransactionEvent), /// We received an onion message that is intended to be forwarded to a peer @@ -1226,6 +1318,10 @@ pub enum Event { /// `OnionMessenger` was initialized with /// [`OnionMessenger::new_with_offline_peer_interception`], see its docs. /// + /// # Failure Behavior and Persistence + /// This event will eventually be replayed after failures-to-handle (i.e., the event handler + /// returning `Err(ReplayEvent ())`), but won't be persisted across restarts. + /// /// [`OnionMessenger::new_with_offline_peer_interception`]: crate::onion_message::messenger::OnionMessenger::new_with_offline_peer_interception OnionMessageIntercepted { /// The node id of the offline peer. @@ -1239,6 +1335,10 @@ pub enum Event { /// initialized with /// [`OnionMessenger::new_with_offline_peer_interception`], see its docs. /// + /// # Failure Behavior and Persistence + /// This event will eventually be replayed after failures-to-handle (i.e., the event handler + /// returning `Err(ReplayEvent ())`), but won't be persisted across restarts. + /// /// [`OnionMessenger::new_with_offline_peer_interception`]: crate::onion_message::messenger::OnionMessenger::new_with_offline_peer_interception OnionMessagePeerConnected { /// The node id of the peer we just connected to, who advertises support for @@ -2335,7 +2435,8 @@ pub trait EventsProvider { /// An error type that may be returned to LDK in order to safely abort event handling if it can't /// currently succeed (e.g., due to a persistence failure). /// -/// LDK will ensure the event is persisted and will eventually be replayed. +/// Depending on the type, LDK may ensure the event is persisted and will eventually be replayed. +/// Please refer to the documentation of each [`Event`] variant for more details. #[derive(Clone, Copy, Debug)] pub struct ReplayEvent();