1 // This file is Copyright its original authors, visible in version control
4 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
5 // or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
7 // You may not use this file except in accordance with one or both of these
10 //! A module for paying Lightning invoices.
12 //! Defines an [`InvoicePayer`] utility for paying invoices, parameterized by [`Payer`] and
13 //! [`Router`] traits. Implementations of [`Payer`] provide the payer's node id, channels, and means
14 //! to send a payment over a [`Route`]. Implementations of [`Router`] find a [`Route`] between payer
15 //! and payee using information provided by the payer and from the payee's [`Invoice`].
17 //! [`InvoicePayer`] is capable of retrying failed payments. It accomplishes this by implementing
18 //! [`EventHandler`] which decorates a user-provided handler. It will intercept any
19 //! [`Event::PaymentPathFailed`] events and retry the failed paths for a fixed number of total
20 //! attempts or until retry is no longer possible. In such a situation, [`InvoicePayer`] will pass
21 //! along the events to the user-provided handler.
26 //! # extern crate lightning;
27 //! # extern crate lightning_invoice;
28 //! # extern crate secp256k1;
30 //! # use lightning::ln::{PaymentHash, PaymentSecret};
31 //! # use lightning::ln::channelmanager::{ChannelDetails, PaymentId, PaymentSendFailure};
32 //! # use lightning::ln::msgs::LightningError;
33 //! # use lightning::routing::router::{Route, RouteParameters};
34 //! # use lightning::util::events::{Event, EventHandler, EventsProvider};
35 //! # use lightning::util::logger::{Logger, Record};
36 //! # use lightning_invoice::Invoice;
37 //! # use lightning_invoice::payment::{InvoicePayer, Payer, RetryAttempts, Router};
38 //! # use secp256k1::key::PublicKey;
39 //! # use std::ops::Deref;
41 //! # struct FakeEventProvider {}
42 //! # impl EventsProvider for FakeEventProvider {
43 //! # fn process_pending_events<H: Deref>(&self, handler: H) where H::Target: EventHandler {}
46 //! # struct FakePayer {}
47 //! # impl Payer for FakePayer {
48 //! # fn node_id(&self) -> PublicKey { unimplemented!() }
49 //! # fn first_hops(&self) -> Vec<ChannelDetails> { unimplemented!() }
50 //! # fn send_payment(
51 //! # &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>
52 //! # ) -> Result<PaymentId, PaymentSendFailure> { unimplemented!() }
53 //! # fn retry_payment(
54 //! # &self, route: &Route, payment_id: PaymentId
55 //! # ) -> Result<(), PaymentSendFailure> { unimplemented!() }
58 //! # struct FakeRouter {};
59 //! # impl Router for FakeRouter {
61 //! # &self, payer: &PublicKey, params: &RouteParameters,
62 //! # first_hops: Option<&[&ChannelDetails]>
63 //! # ) -> Result<Route, LightningError> { unimplemented!() }
66 //! # struct FakeLogger {};
67 //! # impl Logger for FakeLogger {
68 //! # fn log(&self, record: &Record) { unimplemented!() }
72 //! let event_handler = |event: &Event| {
74 //! Event::PaymentPathFailed { .. } => println!("payment failed after retries"),
75 //! Event::PaymentSent { .. } => println!("payment successful"),
79 //! # let payer = FakePayer {};
80 //! # let router = FakeRouter {};
81 //! # let logger = FakeLogger {};
82 //! let invoice_payer = InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
84 //! let invoice = "...";
85 //! let invoice = invoice.parse::<Invoice>().unwrap();
86 //! invoice_payer.pay_invoice(&invoice).unwrap();
88 //! # let event_provider = FakeEventProvider {};
90 //! event_provider.process_pending_events(&invoice_payer);
97 //! The [`Route`] is computed before each payment attempt. Any updates affecting path finding such
98 //! as updates to the network graph or changes to channel scores should be applied prior to
99 //! retries, typically by way of composing [`EventHandler`]s accordingly.
103 use bitcoin_hashes::Hash;
105 use lightning::ln::{PaymentHash, PaymentSecret};
106 use lightning::ln::channelmanager::{ChannelDetails, PaymentId, PaymentSendFailure};
107 use lightning::ln::msgs::LightningError;
108 use lightning::routing::router::{Payee, Route, RouteParameters};
109 use lightning::util::events::{Event, EventHandler};
110 use lightning::util::logger::Logger;
112 use secp256k1::key::PublicKey;
114 use std::collections::hash_map::{self, HashMap};
116 use std::sync::Mutex;
118 /// A utility for paying [`Invoice]`s.
119 pub struct InvoicePayer<P: Deref, R, L: Deref, E>
130 payment_cache: Mutex<HashMap<PaymentHash, usize>>,
131 retry_attempts: RetryAttempts,
134 /// A trait defining behavior of an [`Invoice`] payer.
136 /// Returns the payer's node id.
137 fn node_id(&self) -> PublicKey;
139 /// Returns the payer's channels.
140 fn first_hops(&self) -> Vec<ChannelDetails>;
142 /// Sends a payment over the Lightning Network using the given [`Route`].
144 &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>
145 ) -> Result<PaymentId, PaymentSendFailure>;
147 /// Retries a failed payment path for the [`PaymentId`] using the given [`Route`].
148 fn retry_payment(&self, route: &Route, payment_id: PaymentId) -> Result<(), PaymentSendFailure>;
151 /// A trait defining behavior for routing an [`Invoice`] payment.
153 /// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
155 &self, payer: &PublicKey, params: &RouteParameters, first_hops: Option<&[&ChannelDetails]>
156 ) -> Result<Route, LightningError>;
159 /// Number of attempts to retry payment path failures for an [`Invoice`].
160 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
161 pub struct RetryAttempts(pub usize);
163 /// An error that may occur when making a payment.
164 #[derive(Clone, Debug)]
165 pub enum PaymentError {
166 /// An error resulting from the provided [`Invoice`] or payment hash.
167 Invoice(&'static str),
168 /// An error occurring when finding a route.
169 Routing(LightningError),
170 /// An error occurring when sending a payment.
171 Sending(PaymentSendFailure),
174 impl<P: Deref, R, L: Deref, E> InvoicePayer<P, R, L, E>
181 /// Creates an invoice payer that retries failed payment paths.
183 /// Will forward any [`Event::PaymentPathFailed`] events to the decorated `event_handler` once
184 /// `retry_attempts` has been exceeded for a given [`Invoice`].
186 payer: P, router: R, logger: L, event_handler: E, retry_attempts: RetryAttempts
193 payment_cache: Mutex::new(HashMap::new()),
198 /// Pays the given [`Invoice`], caching it for later use in case a retry is needed.
199 pub fn pay_invoice(&self, invoice: &Invoice) -> Result<PaymentId, PaymentError> {
200 if invoice.amount_milli_satoshis().is_none() {
201 Err(PaymentError::Invoice("amount missing"))
203 self.pay_invoice_internal(invoice, None)
207 /// Pays the given zero-value [`Invoice`] using the given amount, caching it for later use in
208 /// case a retry is needed.
209 pub fn pay_zero_value_invoice(
210 &self, invoice: &Invoice, amount_msats: u64
211 ) -> Result<PaymentId, PaymentError> {
212 if invoice.amount_milli_satoshis().is_some() {
213 Err(PaymentError::Invoice("amount unexpected"))
215 self.pay_invoice_internal(invoice, Some(amount_msats))
219 fn pay_invoice_internal(
220 &self, invoice: &Invoice, amount_msats: Option<u64>
221 ) -> Result<PaymentId, PaymentError> {
222 debug_assert!(invoice.amount_milli_satoshis().is_some() ^ amount_msats.is_some());
223 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
224 let mut payment_cache = self.payment_cache.lock().unwrap();
225 match payment_cache.entry(payment_hash) {
226 hash_map::Entry::Vacant(entry) => {
227 let payer = self.payer.node_id();
228 let mut payee = Payee::new(invoice.recover_payee_pub_key())
229 .with_route_hints(invoice.route_hints());
230 if let Some(features) = invoice.features() {
231 payee = payee.with_features(features.clone());
233 let params = RouteParameters {
235 final_value_msat: invoice.amount_milli_satoshis().or(amount_msats).unwrap(),
236 final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
238 let first_hops = self.payer.first_hops();
239 let route = self.router.find_route(
242 Some(&first_hops.iter().collect::<Vec<_>>()),
243 ).map_err(|e| PaymentError::Routing(e))?;
245 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
246 let payment_secret = Some(invoice.payment_secret().clone());
247 let payment_id = self.payer.send_payment(&route, payment_hash, &payment_secret)
248 .map_err(|e| PaymentError::Sending(e))?;
252 hash_map::Entry::Occupied(_) => Err(PaymentError::Invoice("payment pending")),
257 &self, payment_id: PaymentId, params: &RouteParameters
258 ) -> Result<(), PaymentError> {
259 let payer = self.payer.node_id();
260 let first_hops = self.payer.first_hops();
261 let route = self.router.find_route(
262 &payer, ¶ms, Some(&first_hops.iter().collect::<Vec<_>>())
263 ).map_err(|e| PaymentError::Routing(e))?;
264 self.payer.retry_payment(&route, payment_id).map_err(|e| PaymentError::Sending(e))
267 /// Removes the payment cached by the given payment hash.
269 /// Should be called once a payment has failed or succeeded if not using [`InvoicePayer`] as an
270 /// [`EventHandler`]. Otherwise, calling this method is unnecessary.
271 pub fn remove_cached_payment(&self, payment_hash: &PaymentHash) {
272 self.payment_cache.lock().unwrap().remove(payment_hash);
276 impl<P: Deref, R, L: Deref, E> EventHandler for InvoicePayer<P, R, L, E>
283 fn handle_event(&self, event: &Event) {
285 Event::PaymentPathFailed { payment_id, payment_hash, rejected_by_dest, retry, .. } => {
286 let mut payment_cache = self.payment_cache.lock().unwrap();
288 let entry = payment_cache.entry(*payment_hash);
290 hash_map::Entry::Occupied(_) => break entry,
291 hash_map::Entry::Vacant(entry) => entry.insert(0),
294 if let hash_map::Entry::Occupied(mut entry) = entry {
295 let max_payment_attempts = self.retry_attempts.0 + 1;
296 let attempts = entry.get_mut();
299 if *rejected_by_dest {
300 log_trace!(self.logger, "Payment {} rejected by destination; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
301 } else if payment_id.is_none() {
302 log_trace!(self.logger, "Payment {} has no id; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
303 } else if *attempts >= max_payment_attempts {
304 log_trace!(self.logger, "Payment {} exceeded maximum attempts; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
305 } else if retry.is_none() {
306 log_trace!(self.logger, "Payment {} missing retry params; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
307 } else if self.retry_payment(*payment_id.as_ref().unwrap(), retry.as_ref().unwrap()).is_err() {
308 log_trace!(self.logger, "Error retrying payment {}; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
310 log_trace!(self.logger, "Payment {} failed; retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
314 // Either the payment was rejected, the maximum attempts were exceeded, or an
315 // error occurred when attempting to retry.
321 Event::PaymentSent { payment_hash, .. } => {
322 let mut payment_cache = self.payment_cache.lock().unwrap();
323 let attempts = payment_cache
324 .remove(payment_hash)
325 .map_or(1, |attempts| attempts + 1);
326 log_trace!(self.logger, "Payment {} succeeded (attempts: {})", log_bytes!(payment_hash.0), attempts);
331 // Delegate to the decorated event handler unless the payment is retried.
332 self.event_handler.handle_event(event)
339 use crate::{InvoiceBuilder, Currency};
340 use bitcoin_hashes::sha256::Hash as Sha256;
341 use lightning::ln::PaymentPreimage;
342 use lightning::ln::features::{ChannelFeatures, NodeFeatures};
343 use lightning::ln::msgs::{ErrorAction, LightningError};
344 use lightning::routing::router::{Route, RouteHop};
345 use lightning::util::test_utils::TestLogger;
346 use lightning::util::errors::APIError;
347 use lightning::util::events::Event;
348 use secp256k1::{SecretKey, PublicKey, Secp256k1};
350 fn invoice(payment_preimage: PaymentPreimage) -> Invoice {
351 let payment_hash = Sha256::hash(&payment_preimage.0);
352 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
353 InvoiceBuilder::new(Currency::Bitcoin)
354 .description("test".into())
355 .payment_hash(payment_hash)
356 .payment_secret(PaymentSecret([0; 32]))
358 .min_final_cltv_expiry(144)
359 .amount_milli_satoshis(128)
360 .build_signed(|hash| {
361 Secp256k1::new().sign_recoverable(hash, &private_key)
366 fn zero_value_invoice(payment_preimage: PaymentPreimage) -> Invoice {
367 let payment_hash = Sha256::hash(&payment_preimage.0);
368 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
369 InvoiceBuilder::new(Currency::Bitcoin)
370 .description("test".into())
371 .payment_hash(payment_hash)
372 .payment_secret(PaymentSecret([0; 32]))
374 .min_final_cltv_expiry(144)
375 .build_signed(|hash| {
376 Secp256k1::new().sign_recoverable(hash, &private_key)
382 fn pays_invoice_on_first_attempt() {
383 let event_handled = core::cell::RefCell::new(false);
384 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
386 let payment_preimage = PaymentPreimage([1; 32]);
387 let invoice = invoice(payment_preimage);
388 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
390 let payer = TestPayer::new();
391 let router = TestRouter {};
392 let logger = TestLogger::new();
394 InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
396 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
397 assert_eq!(*payer.attempts.borrow(), 1);
399 invoice_payer.handle_event(&Event::PaymentSent {
400 payment_id, payment_preimage, payment_hash
402 assert_eq!(*event_handled.borrow(), true);
403 assert_eq!(*payer.attempts.borrow(), 1);
407 fn pays_invoice_on_retry() {
408 let event_handled = core::cell::RefCell::new(false);
409 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
411 let payment_preimage = PaymentPreimage([1; 32]);
412 let invoice = invoice(payment_preimage);
413 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
414 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
416 let payer = TestPayer::new()
417 .expect_value_msat(final_value_msat)
418 .expect_value_msat(final_value_msat / 2);
419 let router = TestRouter {};
420 let logger = TestLogger::new();
422 InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
424 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
425 assert_eq!(*payer.attempts.borrow(), 1);
427 let event = Event::PaymentPathFailed {
430 network_update: None,
431 rejected_by_dest: false,
432 all_paths_failed: false,
433 path: TestRouter::path_for_value(final_value_msat),
434 short_channel_id: None,
435 retry: Some(TestRouter::retry_for_invoice(&invoice)),
437 invoice_payer.handle_event(&event);
438 assert_eq!(*event_handled.borrow(), false);
439 assert_eq!(*payer.attempts.borrow(), 2);
441 invoice_payer.handle_event(&Event::PaymentSent {
442 payment_id, payment_preimage, payment_hash
444 assert_eq!(*event_handled.borrow(), true);
445 assert_eq!(*payer.attempts.borrow(), 2);
449 fn retries_payment_path_for_unknown_payment() {
450 let event_handled = core::cell::RefCell::new(false);
451 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
453 let payment_preimage = PaymentPreimage([1; 32]);
454 let invoice = invoice(payment_preimage);
455 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
456 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
458 let payer = TestPayer::new();
459 let router = TestRouter {};
460 let logger = TestLogger::new();
462 InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
464 let payment_id = Some(PaymentId([1; 32]));
465 let event = Event::PaymentPathFailed {
468 network_update: None,
469 rejected_by_dest: false,
470 all_paths_failed: false,
471 path: TestRouter::path_for_value(final_value_msat),
472 short_channel_id: None,
473 retry: Some(TestRouter::retry_for_invoice(&invoice)),
475 invoice_payer.handle_event(&event);
476 assert_eq!(*event_handled.borrow(), false);
477 assert_eq!(*payer.attempts.borrow(), 1);
479 invoice_payer.handle_event(&event);
480 assert_eq!(*event_handled.borrow(), false);
481 assert_eq!(*payer.attempts.borrow(), 2);
483 invoice_payer.handle_event(&Event::PaymentSent {
484 payment_id, payment_preimage, payment_hash
486 assert_eq!(*event_handled.borrow(), true);
487 assert_eq!(*payer.attempts.borrow(), 2);
491 fn fails_paying_invoice_after_max_retries() {
492 let event_handled = core::cell::RefCell::new(false);
493 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
495 let payment_preimage = PaymentPreimage([1; 32]);
496 let invoice = invoice(payment_preimage);
497 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
499 let payer = TestPayer::new()
500 .expect_value_msat(final_value_msat)
501 .expect_value_msat(final_value_msat / 2)
502 .expect_value_msat(final_value_msat / 2);
503 let router = TestRouter {};
504 let logger = TestLogger::new();
506 InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
508 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
509 assert_eq!(*payer.attempts.borrow(), 1);
511 let event = Event::PaymentPathFailed {
513 payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
514 network_update: None,
515 rejected_by_dest: false,
516 all_paths_failed: true,
517 path: TestRouter::path_for_value(final_value_msat),
518 short_channel_id: None,
519 retry: Some(TestRouter::retry_for_invoice(&invoice)),
521 invoice_payer.handle_event(&event);
522 assert_eq!(*event_handled.borrow(), false);
523 assert_eq!(*payer.attempts.borrow(), 2);
525 let event = Event::PaymentPathFailed {
527 payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
528 network_update: None,
529 rejected_by_dest: false,
530 all_paths_failed: false,
531 path: TestRouter::path_for_value(final_value_msat / 2),
532 short_channel_id: None,
533 retry: Some(RouteParameters {
534 final_value_msat: final_value_msat / 2, ..TestRouter::retry_for_invoice(&invoice)
537 invoice_payer.handle_event(&event);
538 assert_eq!(*event_handled.borrow(), false);
539 assert_eq!(*payer.attempts.borrow(), 3);
541 invoice_payer.handle_event(&event);
542 assert_eq!(*event_handled.borrow(), true);
543 assert_eq!(*payer.attempts.borrow(), 3);
547 fn fails_paying_invoice_with_missing_retry_params() {
548 let event_handled = core::cell::RefCell::new(false);
549 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
551 let payer = TestPayer::new();
552 let router = TestRouter {};
553 let logger = TestLogger::new();
555 InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
557 let payment_preimage = PaymentPreimage([1; 32]);
558 let invoice = invoice(payment_preimage);
559 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
560 assert_eq!(*payer.attempts.borrow(), 1);
562 let event = Event::PaymentPathFailed {
564 payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
565 network_update: None,
566 rejected_by_dest: false,
567 all_paths_failed: false,
569 short_channel_id: None,
572 invoice_payer.handle_event(&event);
573 assert_eq!(*event_handled.borrow(), true);
574 assert_eq!(*payer.attempts.borrow(), 1);
578 fn fails_paying_invoice_after_retry_error() {
579 let event_handled = core::cell::RefCell::new(false);
580 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
582 let payment_preimage = PaymentPreimage([1; 32]);
583 let invoice = invoice(payment_preimage);
584 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
586 let payer = TestPayer::new()
588 .expect_value_msat(final_value_msat);
589 let router = TestRouter {};
590 let logger = TestLogger::new();
592 InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
594 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
595 assert_eq!(*payer.attempts.borrow(), 1);
597 let event = Event::PaymentPathFailed {
599 payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
600 network_update: None,
601 rejected_by_dest: false,
602 all_paths_failed: false,
603 path: TestRouter::path_for_value(final_value_msat / 2),
604 short_channel_id: None,
605 retry: Some(TestRouter::retry_for_invoice(&invoice)),
607 invoice_payer.handle_event(&event);
608 assert_eq!(*event_handled.borrow(), true);
609 assert_eq!(*payer.attempts.borrow(), 2);
613 fn fails_paying_invoice_after_rejected_by_payee() {
614 let event_handled = core::cell::RefCell::new(false);
615 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
617 let payer = TestPayer::new();
618 let router = TestRouter {};
619 let logger = TestLogger::new();
621 InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
623 let payment_preimage = PaymentPreimage([1; 32]);
624 let invoice = invoice(payment_preimage);
625 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
626 assert_eq!(*payer.attempts.borrow(), 1);
628 let event = Event::PaymentPathFailed {
630 payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
631 network_update: None,
632 rejected_by_dest: true,
633 all_paths_failed: false,
635 short_channel_id: None,
636 retry: Some(TestRouter::retry_for_invoice(&invoice)),
638 invoice_payer.handle_event(&event);
639 assert_eq!(*event_handled.borrow(), true);
640 assert_eq!(*payer.attempts.borrow(), 1);
644 fn fails_repaying_invoice_with_pending_payment() {
645 let event_handled = core::cell::RefCell::new(false);
646 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
648 let payer = TestPayer::new();
649 let router = TestRouter {};
650 let logger = TestLogger::new();
652 InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
654 let payment_preimage = PaymentPreimage([1; 32]);
655 let invoice = invoice(payment_preimage);
656 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
658 // Cannot repay an invoice pending payment.
659 match invoice_payer.pay_invoice(&invoice) {
660 Err(PaymentError::Invoice("payment pending")) => {},
661 Err(_) => panic!("unexpected error"),
662 Ok(_) => panic!("expected invoice error"),
665 // Can repay an invoice once cleared from cache.
666 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
667 invoice_payer.remove_cached_payment(&payment_hash);
668 assert!(invoice_payer.pay_invoice(&invoice).is_ok());
670 // Cannot retry paying an invoice if cleared from cache.
671 invoice_payer.remove_cached_payment(&payment_hash);
672 let event = Event::PaymentPathFailed {
675 network_update: None,
676 rejected_by_dest: false,
677 all_paths_failed: false,
679 short_channel_id: None,
680 retry: Some(TestRouter::retry_for_invoice(&invoice)),
682 invoice_payer.handle_event(&event);
683 assert_eq!(*event_handled.borrow(), true);
687 fn fails_paying_invoice_with_routing_errors() {
688 let payer = TestPayer::new();
689 let router = FailingRouter {};
690 let logger = TestLogger::new();
692 InvoicePayer::new(&payer, router, &logger, |_: &_| {}, RetryAttempts(0));
694 let payment_preimage = PaymentPreimage([1; 32]);
695 let invoice = invoice(payment_preimage);
696 match invoice_payer.pay_invoice(&invoice) {
697 Err(PaymentError::Routing(_)) => {},
698 Err(_) => panic!("unexpected error"),
699 Ok(_) => panic!("expected routing error"),
704 fn fails_paying_invoice_with_sending_errors() {
705 let payer = TestPayer::new().fails_on_attempt(1);
706 let router = TestRouter {};
707 let logger = TestLogger::new();
709 InvoicePayer::new(&payer, router, &logger, |_: &_| {}, RetryAttempts(0));
711 let payment_preimage = PaymentPreimage([1; 32]);
712 let invoice = invoice(payment_preimage);
713 match invoice_payer.pay_invoice(&invoice) {
714 Err(PaymentError::Sending(_)) => {},
715 Err(_) => panic!("unexpected error"),
716 Ok(_) => panic!("expected sending error"),
721 fn pays_zero_value_invoice_using_amount() {
722 let event_handled = core::cell::RefCell::new(false);
723 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
725 let payment_preimage = PaymentPreimage([1; 32]);
726 let invoice = zero_value_invoice(payment_preimage);
727 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
728 let final_value_msat = 100;
730 let payer = TestPayer::new().expect_value_msat(final_value_msat);
731 let router = TestRouter {};
732 let logger = TestLogger::new();
734 InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
737 Some(invoice_payer.pay_zero_value_invoice(&invoice, final_value_msat).unwrap());
738 assert_eq!(*payer.attempts.borrow(), 1);
740 invoice_payer.handle_event(&Event::PaymentSent {
741 payment_id, payment_preimage, payment_hash
743 assert_eq!(*event_handled.borrow(), true);
744 assert_eq!(*payer.attempts.borrow(), 1);
748 fn fails_paying_zero_value_invoice_with_amount() {
749 let event_handled = core::cell::RefCell::new(false);
750 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
752 let payer = TestPayer::new();
753 let router = TestRouter {};
754 let logger = TestLogger::new();
756 InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
758 let payment_preimage = PaymentPreimage([1; 32]);
759 let invoice = invoice(payment_preimage);
761 // Cannot repay an invoice pending payment.
762 match invoice_payer.pay_zero_value_invoice(&invoice, 100) {
763 Err(PaymentError::Invoice("amount unexpected")) => {},
764 Err(_) => panic!("unexpected error"),
765 Ok(_) => panic!("expected invoice error"),
772 fn route_for_value(final_value_msat: u64) -> Route {
776 pubkey: PublicKey::from_slice(&hex::decode("02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619").unwrap()[..]).unwrap(),
777 channel_features: ChannelFeatures::empty(),
778 node_features: NodeFeatures::empty(),
779 short_channel_id: 0, fee_msat: final_value_msat / 2, cltv_expiry_delta: 144
782 pubkey: PublicKey::from_slice(&hex::decode("0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c").unwrap()[..]).unwrap(),
783 channel_features: ChannelFeatures::empty(),
784 node_features: NodeFeatures::empty(),
785 short_channel_id: 1, fee_msat: final_value_msat / 2, cltv_expiry_delta: 144
792 fn path_for_value(final_value_msat: u64) -> Vec<RouteHop> {
793 TestRouter::route_for_value(final_value_msat).paths[0].clone()
796 fn retry_for_invoice(invoice: &Invoice) -> RouteParameters {
797 let mut payee = Payee::new(invoice.recover_payee_pub_key())
798 .with_route_hints(invoice.route_hints());
799 if let Some(features) = invoice.features() {
800 payee = payee.with_features(features.clone());
802 let final_value_msat = invoice.amount_milli_satoshis().unwrap() / 2;
806 final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
811 impl Router for TestRouter {
815 params: &RouteParameters,
816 _first_hops: Option<&[&ChannelDetails]>,
817 ) -> Result<Route, LightningError> {
819 payee: Some(params.payee.clone()), ..Self::route_for_value(params.final_value_msat)
824 struct FailingRouter;
826 impl Router for FailingRouter {
830 _params: &RouteParameters,
831 _first_hops: Option<&[&ChannelDetails]>,
832 ) -> Result<Route, LightningError> {
833 Err(LightningError { err: String::new(), action: ErrorAction::IgnoreError })
838 expectations: core::cell::RefCell<std::collections::VecDeque<u64>>,
839 attempts: core::cell::RefCell<usize>,
840 failing_on_attempt: Option<usize>,
846 expectations: core::cell::RefCell::new(std::collections::VecDeque::new()),
847 attempts: core::cell::RefCell::new(0),
848 failing_on_attempt: None,
852 fn expect_value_msat(self, value_msat: u64) -> Self {
853 self.expectations.borrow_mut().push_back(value_msat);
857 fn fails_on_attempt(self, attempt: usize) -> Self {
859 expectations: core::cell::RefCell::new(self.expectations.borrow().clone()),
860 attempts: core::cell::RefCell::new(0),
861 failing_on_attempt: Some(attempt),
865 fn check_attempts(&self) -> bool {
866 let mut attempts = self.attempts.borrow_mut();
868 match self.failing_on_attempt {
870 Some(attempt) if attempt != *attempts => true,
875 fn check_value_msats(&self, route: &Route) {
876 let expected_value_msats = self.expectations.borrow_mut().pop_front();
877 if let Some(expected_value_msats) = expected_value_msats {
878 let actual_value_msats = route.get_total_amount();
879 assert_eq!(actual_value_msats, expected_value_msats);
884 impl Drop for TestPayer {
886 if std::thread::panicking() {
890 if !self.expectations.borrow().is_empty() {
891 panic!("Unsatisfied payment expectations: {:?}", self.expectations.borrow());
896 impl Payer for TestPayer {
897 fn node_id(&self) -> PublicKey {
898 let secp_ctx = Secp256k1::new();
899 PublicKey::from_secret_key(&secp_ctx, &SecretKey::from_slice(&[42; 32]).unwrap())
902 fn first_hops(&self) -> Vec<ChannelDetails> {
909 _payment_hash: PaymentHash,
910 _payment_secret: &Option<PaymentSecret>
911 ) -> Result<PaymentId, PaymentSendFailure> {
912 if self.check_attempts() {
913 self.check_value_msats(route);
914 Ok(PaymentId([1; 32]))
916 Err(PaymentSendFailure::ParameterError(APIError::MonitorUpdateFailed))
921 &self, route: &Route, _payment_id: PaymentId
922 ) -> Result<(), PaymentSendFailure> {
923 if self.check_attempts() {
924 self.check_value_msats(route);
927 Err(PaymentSendFailure::ParameterError(APIError::MonitorUpdateFailed))