From 51dd344f26ca31d114fd06608eef4f8e6b6f8b57 Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Sat, 30 Oct 2021 01:52:43 +0000 Subject: [PATCH] Expand `InvoicePayer` documentation somewhat to clarify edge-cases --- lightning-invoice/src/payment.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/lightning-invoice/src/payment.rs b/lightning-invoice/src/payment.rs index eefae3fc..68b06faa 100644 --- a/lightning-invoice/src/payment.rs +++ b/lightning-invoice/src/payment.rs @@ -175,6 +175,10 @@ pub trait Router { } /// Number of attempts to retry payment path failures for an [`Invoice`]. +/// +/// Note that this is the number of *path* failures, not full payment retries. For multi-path +/// payments, if this is less than the total number of paths, we will never even retry all of the +/// payment's paths. #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)] pub struct RetryAttempts(pub usize); @@ -216,6 +220,10 @@ where } /// Pays the given [`Invoice`], caching it for later use in case a retry is needed. + /// + /// You should ensure that the `invoice.payment_hash()` is unique and the same payment_hash has + /// never been paid before. Because [`InvoicePayer`] is stateless no effort is made to do so + /// for you. pub fn pay_invoice(&self, invoice: &Invoice) -> Result { if invoice.amount_milli_satoshis().is_none() { Err(PaymentError::Invoice("amount missing")) @@ -226,6 +234,10 @@ where /// Pays the given zero-value [`Invoice`] using the given amount, caching it for later use in /// case a retry is needed. + /// + /// You should ensure that the `invoice.payment_hash()` is unique and the same payment_hash has + /// never been paid before. Because [`InvoicePayer`] is stateless no effort is made to do so + /// for you. pub fn pay_zero_value_invoice( &self, invoice: &Invoice, amount_msats: u64 ) -> Result { -- 2.30.2