From: Jeffrey Czyz <jkczyz@gmail.com>
Date: Thu, 19 Oct 2023 14:16:08 +0000 (-0500)
Subject: Document InvoiceRequestFailed in ChannelManager
X-Git-Tag: v0.0.118~6^2~6
X-Git-Url: http://git.bitcoin.ninja/?a=commitdiff_plain;h=5a0b1116682bd530b0a51d5fc1050a76503986fb;p=rust-lightning

Document InvoiceRequestFailed in ChannelManager
---

diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
index 27e69131f..321922974 100644
--- 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 ff961370d..aa187c93c 100644
--- 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.
 	///