From b5f1da60348028c60788f59e451737411e279206 Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Wed, 2 Nov 2022 01:06:39 +0000 Subject: [PATCH] Allow users to specify the `PaymentId` used in `InvoicePayer` In order to allow users to pass a custom idempotency key to the `send*` methods in `InvoicePayer`, we have to pipe the `PaymentId` through to the `Payer` methods, which we do here. By default, existing `InvoicePayer` methods use the `PaymentHash` as the `PaymentId`, however we also add duplicate `send*_with_id` methods which allow users to pass a custom `PaymentId`. Finally, appropriate documentation updates are made to clarify idempotency guarantees. --- lightning-invoice/src/payment.rs | 152 ++++++++++++++++++++++++------- lightning-invoice/src/utils.rs | 16 ++-- 2 files changed, 124 insertions(+), 44 deletions(-) diff --git a/lightning-invoice/src/payment.rs b/lightning-invoice/src/payment.rs index 4b2a682b3..7d5b87cf4 100644 --- a/lightning-invoice/src/payment.rs +++ b/lightning-invoice/src/payment.rs @@ -59,11 +59,12 @@ //! # fn node_id(&self) -> PublicKey { unimplemented!() } //! # fn first_hops(&self) -> Vec { unimplemented!() } //! # fn send_payment( -//! # &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option -//! # ) -> Result { unimplemented!() } +//! # &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option, +//! # payment_id: PaymentId +//! # ) -> Result<(), PaymentSendFailure> { unimplemented!() } //! # fn send_spontaneous_payment( -//! # &self, route: &Route, payment_preimage: PaymentPreimage -//! # ) -> Result { unimplemented!() } +//! # &self, route: &Route, payment_preimage: PaymentPreimage, payment_id: PaymentId, +//! # ) -> Result<(), PaymentSendFailure> { unimplemented!() } //! # fn retry_payment( //! # &self, route: &Route, payment_id: PaymentId //! # ) -> Result<(), PaymentSendFailure> { unimplemented!() } @@ -242,6 +243,18 @@ impl Display for PaymentAttempts { } /// A trait defining behavior of an [`Invoice`] payer. +/// +/// While the behavior of [`InvoicePayer`] provides idempotency of duplicate `send_*payment` calls +/// with the same [`PaymentHash`], it is up to the `Payer` to provide idempotency across restarts. +/// +/// [`ChannelManager`] provides idempotency for duplicate payments with the same [`PaymentId`]. +/// +/// In order to trivially ensure idempotency for payments, the default `Payer` implementation +/// reuses the [`PaymentHash`] bytes as the [`PaymentId`]. Custom implementations wishing to +/// provide payment idempotency with a different idempotency key (i.e. [`PaymentId`]) should map +/// the [`Invoice`] or spontaneous payment target pubkey to their own idempotency key. +/// +/// [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager pub trait Payer { /// Returns the payer's node id. fn node_id(&self) -> PublicKey; @@ -251,13 +264,14 @@ pub trait Payer { /// Sends a payment over the Lightning Network using the given [`Route`]. fn send_payment( - &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option - ) -> Result; + &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option, + payment_id: PaymentId + ) -> Result<(), PaymentSendFailure>; /// Sends a spontaneous payment over the Lightning Network using the given [`Route`]. fn send_spontaneous_payment( - &self, route: &Route, payment_preimage: PaymentPreimage - ) -> Result; + &self, route: &Route, payment_preimage: PaymentPreimage, payment_id: PaymentId + ) -> Result<(), PaymentSendFailure>; /// Retries a failed payment path for the [`PaymentId`] using the given [`Route`]. fn retry_payment(&self, route: &Route, payment_id: PaymentId) -> Result<(), PaymentSendFailure>; @@ -346,36 +360,76 @@ 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. + /// [`Invoice::payment_hash`] is used as the [`PaymentId`], which ensures idempotency as long + /// as the payment is still pending. Once the payment completes or fails, you must ensure that + /// a second payment with the same [`PaymentHash`] is never sent. + /// + /// If you wish to use a different payment idempotency token, see + /// [`Self::pay_invoice_with_id`]. pub fn pay_invoice(&self, invoice: &Invoice) -> Result { + let payment_id = PaymentId(invoice.payment_hash().into_inner()); + self.pay_invoice_with_id(invoice, payment_id).map(|()| payment_id) + } + + /// Pays the given [`Invoice`] with a custom idempotency key, caching the invoice for later use + /// in case a retry is needed. + /// + /// Note that idempotency is only guaranteed as long as the payment is still pending. Once the + /// payment completes or fails, no idempotency guarantees are made. + /// + /// You should ensure that the [`Invoice::payment_hash`] is unique and the same [`PaymentHash`] + /// has never been paid before. + /// + /// See [`Self::pay_invoice`] for a variant which uses the [`PaymentHash`] for the idempotency + /// token. + pub fn pay_invoice_with_id(&self, invoice: &Invoice, payment_id: PaymentId) -> Result<(), PaymentError> { if invoice.amount_milli_satoshis().is_none() { Err(PaymentError::Invoice("amount missing")) } else { - self.pay_invoice_using_amount(invoice, None) + self.pay_invoice_using_amount(invoice, None, payment_id) } } /// 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. + /// [`Invoice::payment_hash`] is used as the [`PaymentId`], which ensures idempotency as long + /// as the payment is still pending. Once the payment completes or fails, you must ensure that + /// a second payment with the same [`PaymentHash`] is never sent. + /// + /// If you wish to use a different payment idempotency token, see + /// [`Self::pay_zero_value_invoice_with_id`]. pub fn pay_zero_value_invoice( &self, invoice: &Invoice, amount_msats: u64 ) -> Result { + let payment_id = PaymentId(invoice.payment_hash().into_inner()); + self.pay_zero_value_invoice_with_id(invoice, amount_msats, payment_id).map(|()| payment_id) + } + + /// Pays the given zero-value [`Invoice`] using the given amount and custom idempotency key, + /// caching the invoice for later use in case a retry is needed. + /// + /// Note that idempotency is only guaranteed as long as the payment is still pending. Once the + /// payment completes or fails, no idempotency guarantees are made. + /// + /// You should ensure that the [`Invoice::payment_hash`] is unique and the same [`PaymentHash`] + /// has never been paid before. + /// + /// See [`Self::pay_zero_value_invoice`] for a variant which uses the [`PaymentHash`] for the + /// idempotency token. + pub fn pay_zero_value_invoice_with_id( + &self, invoice: &Invoice, amount_msats: u64, payment_id: PaymentId + ) -> Result<(), PaymentError> { if invoice.amount_milli_satoshis().is_some() { Err(PaymentError::Invoice("amount unexpected")) } else { - self.pay_invoice_using_amount(invoice, Some(amount_msats)) + self.pay_invoice_using_amount(invoice, Some(amount_msats), payment_id) } } fn pay_invoice_using_amount( - &self, invoice: &Invoice, amount_msats: Option - ) -> Result { + &self, invoice: &Invoice, amount_msats: Option, payment_id: PaymentId + ) -> Result<(), PaymentError> { debug_assert!(invoice.amount_milli_satoshis().is_some() ^ amount_msats.is_some()); let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner()); @@ -398,7 +452,7 @@ where }; let send_payment = |route: &Route| { - self.payer.send_payment(route, payment_hash, &payment_secret) + self.payer.send_payment(route, payment_hash, &payment_secret, payment_id) }; self.pay_internal(&route_params, payment_hash, send_payment) @@ -408,13 +462,41 @@ where /// Pays `pubkey` an amount using the hash of the given preimage, caching it for later use in /// case a retry is needed. /// - /// You should ensure that `payment_preimage` is unique and that its `payment_hash` has never - /// been paid before. Because [`InvoicePayer`] is stateless no effort is made to do so for you. + /// The hash of the [`PaymentPreimage`] is used as the [`PaymentId`], which ensures idempotency + /// as long as the payment is still pending. Once the payment completes or fails, you must + /// ensure that a second payment with the same [`PaymentPreimage`] is never sent. pub fn pay_pubkey( &self, pubkey: PublicKey, payment_preimage: PaymentPreimage, amount_msats: u64, final_cltv_expiry_delta: u32 ) -> Result { let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0).into_inner()); + let payment_id = PaymentId(payment_hash.0); + self.do_pay_pubkey(pubkey, payment_preimage, payment_hash, payment_id, amount_msats, + final_cltv_expiry_delta) + .map(|()| payment_id) + } + + /// Pays `pubkey` an amount using the hash of the given preimage and a custom idempotency key, + /// caching the invoice for later use in case a retry is needed. + /// + /// Note that idempotency is only guaranteed as long as the payment is still pending. Once the + /// payment completes or fails, no idempotency guarantees are made. + /// + /// You should ensure that the [`PaymentPreimage`] is unique and the corresponding + /// [`PaymentHash`] has never been paid before. + pub fn pay_pubkey_with_id( + &self, pubkey: PublicKey, payment_preimage: PaymentPreimage, payment_id: PaymentId, + amount_msats: u64, final_cltv_expiry_delta: u32 + ) -> Result<(), PaymentError> { + let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0).into_inner()); + self.do_pay_pubkey(pubkey, payment_preimage, payment_hash, payment_id, amount_msats, + final_cltv_expiry_delta) + } + + fn do_pay_pubkey( + &self, pubkey: PublicKey, payment_preimage: PaymentPreimage, payment_hash: PaymentHash, + payment_id: PaymentId, amount_msats: u64, final_cltv_expiry_delta: u32 + ) -> Result<(), PaymentError> { match self.payment_cache.lock().unwrap().entry(payment_hash) { hash_map::Entry::Occupied(_) => return Err(PaymentError::Invoice("payment pending")), hash_map::Entry::Vacant(entry) => entry.insert(PaymentInfo::new()), @@ -427,15 +509,15 @@ where }; let send_payment = |route: &Route| { - self.payer.send_spontaneous_payment(route, payment_preimage) + self.payer.send_spontaneous_payment(route, payment_preimage, payment_id) }; self.pay_internal(&route_params, payment_hash, send_payment) .map_err(|e| { self.payment_cache.lock().unwrap().remove(&payment_hash); e }) } - fn pay_internal Result + Copy>( + fn pay_internal Result<(), PaymentSendFailure> + Copy>( &self, params: &RouteParameters, payment_hash: PaymentHash, send_payment: F, - ) -> Result { + ) -> Result<(), PaymentError> { #[cfg(feature = "std")] { if has_expired(params) { log_trace!(self.logger, "Invoice expired prior to send for payment {}", log_bytes!(payment_hash.0)); @@ -452,11 +534,11 @@ where ).map_err(|e| PaymentError::Routing(e))?; match send_payment(&route) { - Ok(payment_id) => { + Ok(()) => { for path in route.paths { self.process_path_inflight_htlcs(payment_hash, path); } - Ok(payment_id) + Ok(()) }, Err(e) => match e { PaymentSendFailure::ParameterError(_) => Err(e), @@ -491,13 +573,13 @@ where // consider the payment sent, so return `Ok()` here, ignoring any retry // errors. let _ = self.retry_payment(payment_id, payment_hash, &retry_data); - Ok(payment_id) + Ok(()) } else { // This may happen if we send a payment and some paths fail, but // only due to a temporary monitor failure or the like, implying // they're really in-flight, but we haven't sent the initial // HTLC-Add messages yet. - Ok(payment_id) + Ok(()) } }, }, @@ -2056,13 +2138,13 @@ mod tests { self } - fn check_attempts(&self) -> Result { + fn check_attempts(&self) -> Result<(), PaymentSendFailure> { let mut attempts = self.attempts.borrow_mut(); *attempts += 1; match self.failing_on_attempt.borrow_mut().remove(&*attempts) { Some(failure) => Err(failure), - None => Ok(PaymentId([1; 32])), + None => Ok(()) } } @@ -2100,15 +2182,15 @@ mod tests { fn send_payment( &self, route: &Route, _payment_hash: PaymentHash, - _payment_secret: &Option - ) -> Result { + _payment_secret: &Option, _payment_id: PaymentId, + ) -> Result<(), PaymentSendFailure> { self.check_value_msats(Amount::ForInvoice(route.get_total_amount())); self.check_attempts() } fn send_spontaneous_payment( - &self, route: &Route, _payment_preimage: PaymentPreimage, - ) -> Result { + &self, route: &Route, _payment_preimage: PaymentPreimage, _payment_id: PaymentId, + ) -> Result<(), PaymentSendFailure> { self.check_value_msats(Amount::Spontaneous(route.get_total_amount())); self.check_attempts() } @@ -2117,7 +2199,7 @@ mod tests { &self, route: &Route, _payment_id: PaymentId ) -> Result<(), PaymentSendFailure> { self.check_value_msats(Amount::OnRetry(route.get_total_amount())); - self.check_attempts().map(|_| ()) + self.check_attempts() } fn abandon_payment(&self, _payment_id: PaymentId) { } diff --git a/lightning-invoice/src/utils.rs b/lightning-invoice/src/utils.rs index 1ef7cdee0..cf397ee5c 100644 --- a/lightning-invoice/src/utils.rs +++ b/lightning-invoice/src/utils.rs @@ -602,18 +602,16 @@ where } fn send_payment( - &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option - ) -> Result { - let payment_id = PaymentId(payment_hash.0); - self.send_payment(route, payment_hash, payment_secret, payment_id).map(|()| payment_id) + &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option, + payment_id: PaymentId + ) -> Result<(), PaymentSendFailure> { + self.send_payment(route, payment_hash, payment_secret, payment_id) } fn send_spontaneous_payment( - &self, route: &Route, payment_preimage: PaymentPreimage, - ) -> Result { - let payment_id = PaymentId(sha256::Hash::hash(&payment_preimage.0).into_inner()); - self.send_spontaneous_payment(route, Some(payment_preimage), payment_id) - .map(|_| payment_id) + &self, route: &Route, payment_preimage: PaymentPreimage, payment_id: PaymentId, + ) -> Result<(), PaymentSendFailure> { + self.send_spontaneous_payment(route, Some(payment_preimage), payment_id).map(|_| ()) } fn retry_payment( -- 2.39.5