Organize create_refund and pay_for_offer docs

[rust-lightning] / lightning / src / ln / channelmanager.rs

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index 064f6a3529af349481e5d139cc045b21202c5447..d28270db5bb6b49542434064cdd8cbcc8dce6c83 100644 (file)
--- 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