Document `Failure Behavior and Persistence` for every event type

diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
index e51a0972cdcdfb67c7df06da7e99ebbeb9148590..0e24e8e82f715f3b92cd256f0b9bfaf19031f6b0 100644 (file)
--- 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<Vec<u8>>,
        },
        /// 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();