Document InvoiceRequestFailed in ChannelManager

diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
index 27e69131f073bce6e576ddb1ffaf706a1b649ac0..32192297432d1873c6898e79ccf41f8b66ada62a 100644 (file)
--- a/lightning/src/events/mod.rs
+++ b/lightning/src/events/mod.rs
@@ -514,9 +514,13 @@ pub enum Event {
                sender_intended_total_msat: Option<u64>,
        },
        /// Indicates a request for an invoice failed to yield a response in a reasonable amount of time
-       /// or was explicitly abandoned by [`ChannelManager::abandon_payment`].
+       /// 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.
        ///
        /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
+       /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+       /// [`Offer`]: crate::offers::offer::Offer
+       /// [`Refund`]: crate::offers::refund::Refund
        InvoiceRequestFailed {
                /// The `payment_id` to have been associated with payment for the requested invoice.
                payment_id: PaymentId,

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index ff961370d86c21d2e3f863efab67c1428b5c2541..aa187c93cdbae7deda268ef971551d0855b82e31 100644 (file)
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -3608,9 +3608,10 @@ where
        ///
        /// # Requested Invoices
        ///
-       /// In the case of paying a [`Bolt12Invoice`], abandoning the payment prior to receiving the
-       /// invoice will result in an [`Event::InvoiceRequestFailed`] and prevent any attempts at paying
-       /// it once received. The other events may only be generated once the invoice has been received.
+       /// In the case of paying a [`Bolt12Invoice`] via [`ChannelManager::pay_for_offer`], abandoning
+       /// the payment prior to receiving the invoice will result in an [`Event::InvoiceRequestFailed`]
+       /// and prevent any attempts at paying it once received. The other events may only be generated
+       /// once the invoice has been received.
        ///
        /// # Restart Behavior
        ///
@@ -7348,6 +7349,8 @@ where
        ///
        /// The provided `payment_id` is used to ensure that only one invoice is paid for the refund. To
        /// revoke the refund, use [`ChannelManager::abandon_payment`] prior to receiving the invoice.
+       /// If an invoice isn't received before expiration, the payment will fail with an
+       /// [`Event::InvoiceRequestFailed`].
        ///
        /// Uses a one-hop [`BlindedPath`] for the refund with [`ChannelManager::get_our_node_id`] as
        /// the introduction node and a derived payer id for sender privacy. As such, currently, the
@@ -7397,8 +7400,11 @@ where
        ///
        /// The provided `payment_id` is used to ensure that only one invoice is paid for the request
        /// when received. See [Avoiding Duplicate Payments] for other requirements once the payment has
-       /// been sent. To revoke the request, use [`ChannelManager::abandon_payment`] prior to receiving
-       /// the invoice.
+       /// been sent.
+       ///
+       /// To revoke the request, use [`ChannelManager::abandon_payment`] prior to receiving the
+       /// invoice. If abandoned, or an invoice isn't received in a reasonable amount of time, the
+       /// payment will fail with an [`Event::InvoiceRequestFailed`].
        ///
        /// Errors if a duplicate `payment_id` is provided given the caveats in the aforementioned link.
        ///