X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fln%2Fchannelmanager.rs;h=d28270db5bb6b49542434064cdd8cbcc8dce6c83;hb=3fd9fc6fc04ed2ab4b471bbc95a271da4f060b8e;hp=064f6a3529af349481e5d139cc045b21202c5447;hpb=debc20cc3e1bb8ce8625e67294d0c3036314fdcb;p=rust-lightning

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index 064f6a35..d28270db 100644
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -3606,10 +3606,20 @@ where
 	/// wait until you receive either a [`Event::PaymentFailed`] or [`Event::PaymentSent`] event to
 	/// determine the ultimate status of a payment.
 	///
+	/// # Requested Invoices
+	///
+	/// 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
 	///
 	/// If an [`Event::PaymentFailed`] is generated and we restart without first persisting the
-	/// [`ChannelManager`], another [`Event::PaymentFailed`] may be generated.
+	/// [`ChannelManager`], another [`Event::PaymentFailed`] may be generated; likewise for
+	/// [`Event::InvoiceRequestFailed`].
+	///
+	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 	pub fn abandon_payment(&self, payment_id: PaymentId) {
 		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
 		self.pending_outbound_payments.abandon_payment(payment_id, PaymentFailureReason::UserAbandoned, &self.pending_events);
@@ -7308,6 +7318,8 @@ where
 	/// [`ChannelManager`] when handling [`InvoiceRequest`] messages for the offer. The offer will
 	/// not have an expiration unless otherwise set on the builder.
 	///
+	/// # Privacy
+	///
 	/// Uses a one-hop [`BlindedPath`] for the offer with [`ChannelManager::get_our_node_id`] as the
 	/// introduction node and a derived signing pubkey for recipient privacy. As such, currently,
 	/// the node must be announced. Otherwise, there is no way to find a path to the introduction
@@ -7332,19 +7344,32 @@ where
 	/// Creates a [`RefundBuilder`] such that the [`Refund`] it builds is recognized by the
 	/// [`ChannelManager`] when handling [`Bolt12Invoice`] messages for the refund.
 	///
+	/// # Payment
+	///
+	/// The provided `payment_id` is used to ensure that only one invoice is paid for the refund.
+	/// See [Avoiding Duplicate Payments] for other requirements once the payment has been sent.
+	///
 	/// The builder will have the provided expiration set. Any changes to the expiration on the
 	/// returned builder will not be honored by [`ChannelManager`]. For `no-std`, the highest seen
 	/// block time minus two hours is used for the current time when determining if the refund has
 	/// expired.
 	///
-	/// 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.
+	/// To revoke the refund, use [`ChannelManager::abandon_payment`] prior to receiving the
+	/// invoice. If abandoned, or an invoice isn't received before expiration, the payment will fail
+	/// with an [`Event::InvoiceRequestFailed`].
+	///
+	/// # Privacy
 	///
 	/// 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
 	/// node must be announced. Otherwise, there is no way to find a path to the introduction node
 	/// in order to send the [`Bolt12Invoice`].
 	///
+	/// # Errors
+	///
+	/// Errors if a duplicate `payment_id` is provided given the caveats in the aforementioned link
+	/// or if `amount_msats` is invalid.
+	///
 	/// [`Refund`]: crate::offers::refund::Refund
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 	pub fn create_refund_builder(
@@ -7386,12 +7411,20 @@ where
 	/// - `amount_msats` if overpaying what is required for the given `quantity` is desired, and
 	/// - `payer_note` for [`InvoiceRequest::payer_note`].
 	///
+	/// # Payment
+	///
 	/// 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
 	///
-	/// Errors if a duplicate `payment_id` is provided given the caveats in the aforementioned link.
+	/// Errors if a duplicate `payment_id` is provided given the caveats in the aforementioned link
+	/// or if the provided parameters are invalid for the offer.
 	///
 	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 	/// [`InvoiceRequest::quantity`]: crate::offers::invoice_request::InvoiceRequest::quantity