From: Jeffrey Czyz Date: Thu, 19 Oct 2023 14:37:47 +0000 (-0500) Subject: Organize create_refund and pay_for_offer docs X-Git-Tag: v0.0.118~6^2~5 X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=commitdiff_plain;h=3fd9fc6fc04ed2ab4b471bbc95a271da4f060b8e;p=rust-lightning Organize create_refund and pay_for_offer docs --- diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs index aa187c93c..d28270db5 100644 --- a/lightning/src/ln/channelmanager.rs +++ b/lightning/src/ln/channelmanager.rs @@ -7318,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 @@ -7342,21 +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. - /// If an invoice isn't received before expiration, the payment will fail with an - /// [`Event::InvoiceRequestFailed`]. + /// 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( @@ -7398,6 +7411,8 @@ 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. @@ -7406,7 +7421,10 @@ where /// 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. + /// # Errors + /// + /// 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