_ Git - rust-lightning/blob - lightning-invoice/src/payment.rs

   1 // This file is Copyright its original authors, visible in version control
   2 // history.
   3 //
   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
   8 // licenses.
   9
  10 //! A module for paying Lightning invoices.
  11 //!
  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`].
  16 //!
  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.
  22 //!
  23 //! # Example
  24 //!
  25 //! ```
  26 //! # extern crate lightning;
  27 //! # extern crate lightning_invoice;
  28 //! # extern crate secp256k1;
  29 //! #
  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;
  40 //! #
  41 //! # struct FakeEventProvider {}
  42 //! # impl EventsProvider for FakeEventProvider {
  43 //! #     fn process_pending_events<H: Deref>(&self, handler: H) where H::Target: EventHandler {}
  44 //! # }
  45 //! #
  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!() }
  56 //! # }
  57 //! #
  58 //! # struct FakeRouter {};
  59 //! # impl Router for FakeRouter {
  60 //! #     fn find_route(
  61 //! #         &self, payer: &PublicKey, params: &RouteParameters,
  62 //! #         first_hops: Option<&[&ChannelDetails]>
  63 //! #     ) -> Result<Route, LightningError> { unimplemented!() }
  64 //! # }
  65 //! #
  66 //! # struct FakeLogger {};
  67 //! # impl Logger for FakeLogger {
  68 //! #     fn log(&self, record: &Record) { unimplemented!() }
  69 //! # }
  70 //! #
  71 //! # fn main() {
  72 //! let event_handler = |event: &Event| {
  73 //!     match event {
  74 //!         Event::PaymentPathFailed { .. } => println!("payment failed after retries"),
  75 //!         Event::PaymentSent { .. } => println!("payment successful"),
  76 //!         _ => {},
  77 //!     }
  78 //! };
  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));
  83 //!
  84 //! let invoice = "...";
  85 //! let invoice = invoice.parse::<Invoice>().unwrap();
  86 //! invoice_payer.pay_invoice(&invoice).unwrap();
  87 //!
  88 //! # let event_provider = FakeEventProvider {};
  89 //! loop {
  90 //!     event_provider.process_pending_events(&invoice_payer);
  91 //! }
  92 //! # }
  93 //! ```
  94 //!
  95 //! # Note
  96 //!
  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.
 100
 101 use crate::Invoice;
 102
 103 use bitcoin_hashes::Hash;
 104
 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;
 111
 112 use secp256k1::key::PublicKey;
 113
 114 use std::collections::hash_map::{self, HashMap};
 115 use std::ops::Deref;
 116 use std::sync::Mutex;
 117
 118 /// A utility for paying [`Invoice]`s.
 119 pub struct InvoicePayer<P: Deref, R, L: Deref, E>
 120 where
 121         P::Target: Payer,
 122         R: Router,
 123         L::Target: Logger,
 124         E: EventHandler,
 125 {
 126         payer: P,
 127         router: R,
 128         logger: L,
 129         event_handler: E,
 130         payment_cache: Mutex<HashMap<PaymentHash, usize>>,
 131         retry_attempts: RetryAttempts,
 132 }
 133
 134 /// A trait defining behavior of an [`Invoice`] payer.
 135 pub trait Payer {
 136         /// Returns the payer's node id.
 137         fn node_id(&self) -> PublicKey;
 138
 139         /// Returns the payer's channels.
 140         fn first_hops(&self) -> Vec<ChannelDetails>;
 141
 142         /// Sends a payment over the Lightning Network using the given [`Route`].
 143         fn send_payment(
 144                 &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>
 145         ) -> Result<PaymentId, PaymentSendFailure>;
 146
 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>;
 149 }
 150
 151 /// A trait defining behavior for routing an [`Invoice`] payment.
 152 pub trait Router {
 153         /// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
 154         fn find_route(
 155                 &self, payer: &PublicKey, params: &RouteParameters, first_hops: Option<&[&ChannelDetails]>
 156         ) -> Result<Route, LightningError>;
 157 }
 158
 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);
 162
 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),
 172 }
 173
 174 impl<P: Deref, R, L: Deref, E> InvoicePayer<P, R, L, E>
 175 where
 176         P::Target: Payer,
 177         R: Router,
 178         L::Target: Logger,
 179         E: EventHandler,
 180 {
 181         /// Creates an invoice payer that retries failed payment paths.
 182         ///
 183         /// Will forward any [`Event::PaymentPathFailed`] events to the decorated `event_handler` once
 184         /// `retry_attempts` has been exceeded for a given [`Invoice`].
 185         pub fn new(
 186                 payer: P, router: R, logger: L, event_handler: E, retry_attempts: RetryAttempts
 187         ) -> Self {
 188                 Self {
 189                         payer,
 190                         router,
 191                         logger,
 192                         event_handler,
 193                         payment_cache: Mutex::new(HashMap::new()),
 194                         retry_attempts,
 195                 }
 196         }
 197
 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"))
 202                 } else {
 203                         self.pay_invoice_internal(invoice, None)
 204                 }
 205         }
 206
 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"))
 214                 } else {
 215                         self.pay_invoice_internal(invoice, Some(amount_msats))
 216                 }
 217         }
 218
 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());
 232                                 }
 233                                 let params = RouteParameters {
 234                                         payee,
 235                                         final_value_msat: invoice.amount_milli_satoshis().or(amount_msats).unwrap(),
 236                                         final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
 237                                 };
 238                                 let first_hops = self.payer.first_hops();
 239                                 let route = self.router.find_route(
 240                                         &payer,
 241                                         &params,
 242                                         Some(&first_hops.iter().collect::<Vec<_>>()),
 243                                 ).map_err(|e| PaymentError::Routing(e))?;
 244
 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))?;
 249                                 entry.insert(0);
 250                                 Ok(payment_id)
 251                         },
 252                         hash_map::Entry::Occupied(_) => Err(PaymentError::Invoice("payment pending")),
 253                 }
 254         }
 255
 256         fn retry_payment(
 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, &params, 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))
 265         }
 266
 267         /// Removes the payment cached by the given payment hash.
 268         ///
 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);
 273         }
 274 }
 275
 276 impl<P: Deref, R, L: Deref, E> EventHandler for InvoicePayer<P, R, L, E>
 277 where
 278         P::Target: Payer,
 279         R: Router,
 280         L::Target: Logger,
 281         E: EventHandler,
 282 {
 283         fn handle_event(&self, event: &Event) {
 284                 match event {
 285                         Event::PaymentPathFailed { payment_id, payment_hash, rejected_by_dest, retry, .. } => {
 286                                 let mut payment_cache = self.payment_cache.lock().unwrap();
 287                                 let entry = loop {
 288                                         let entry = payment_cache.entry(*payment_hash);
 289                                         match entry {
 290                                                 hash_map::Entry::Occupied(_) => break entry,
 291                                                 hash_map::Entry::Vacant(entry) => entry.insert(0),
 292                                         };
 293                                 };
 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();
 297                                         *attempts += 1;
 298
 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);
 309                                         } else {
 310                                                 log_trace!(self.logger, "Payment {} failed; retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
 311                                                 return;
 312                                         }
 313
 314                                         // Either the payment was rejected, the maximum attempts were exceeded, or an
 315                                         // error occurred when attempting to retry.
 316                                         entry.remove();
 317                                 } else {
 318                                         unreachable!();
 319                                 }
 320                         },
 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);
 327                         },
 328                         _ => {},
 329                 }
 330
 331                 // Delegate to the decorated event handler unless the payment is retried.
 332                 self.event_handler.handle_event(event)
 333         }
 334 }
 335
 336 #[cfg(test)]
 337 mod tests {
 338         use super::*;
 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};
 349
 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]))
 357                         .current_timestamp()
 358                         .min_final_cltv_expiry(144)
 359                         .amount_milli_satoshis(128)
 360                         .build_signed(|hash| {
 361                                 Secp256k1::new().sign_recoverable(hash, &private_key)
 362                         })
 363                         .unwrap()
 364         }
 365
 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]))
 373                         .current_timestamp()
 374                         .min_final_cltv_expiry(144)
 375                         .build_signed(|hash| {
 376                                 Secp256k1::new().sign_recoverable(hash, &private_key)
 377                         })
 378                         .unwrap()
 379         }
 380
 381         #[test]
 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; };
 385
 386                 let payment_preimage = PaymentPreimage([1; 32]);
 387                 let invoice = invoice(payment_preimage);
 388                 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
 389
 390                 let payer = TestPayer::new();
 391                 let router = TestRouter {};
 392                 let logger = TestLogger::new();
 393                 let invoice_payer =
 394                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
 395
 396                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 397                 assert_eq!(*payer.attempts.borrow(), 1);
 398
 399                 invoice_payer.handle_event(&Event::PaymentSent {
 400                         payment_id, payment_preimage, payment_hash
 401                 });
 402                 assert_eq!(*event_handled.borrow(), true);
 403                 assert_eq!(*payer.attempts.borrow(), 1);
 404         }
 405
 406         #[test]
 407         fn pays_invoice_on_retry() {
 408                 let event_handled = core::cell::RefCell::new(false);
 409                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 410
 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();
 415
 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();
 421                 let invoice_payer =
 422                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 423
 424                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 425                 assert_eq!(*payer.attempts.borrow(), 1);
 426
 427                 let event = Event::PaymentPathFailed {
 428                         payment_id,
 429                         payment_hash,
 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)),
 436                 };
 437                 invoice_payer.handle_event(&event);
 438                 assert_eq!(*event_handled.borrow(), false);
 439                 assert_eq!(*payer.attempts.borrow(), 2);
 440
 441                 invoice_payer.handle_event(&Event::PaymentSent {
 442                         payment_id, payment_preimage, payment_hash
 443                 });
 444                 assert_eq!(*event_handled.borrow(), true);
 445                 assert_eq!(*payer.attempts.borrow(), 2);
 446         }
 447
 448         #[test]
 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; };
 452
 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();
 457
 458                 let payer = TestPayer::new();
 459                 let router = TestRouter {};
 460                 let logger = TestLogger::new();
 461                 let invoice_payer =
 462                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 463
 464                 let payment_id = Some(PaymentId([1; 32]));
 465                 let event = Event::PaymentPathFailed {
 466                         payment_id,
 467                         payment_hash,
 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)),
 474                 };
 475                 invoice_payer.handle_event(&event);
 476                 assert_eq!(*event_handled.borrow(), false);
 477                 assert_eq!(*payer.attempts.borrow(), 1);
 478
 479                 invoice_payer.handle_event(&event);
 480                 assert_eq!(*event_handled.borrow(), false);
 481                 assert_eq!(*payer.attempts.borrow(), 2);
 482
 483                 invoice_payer.handle_event(&Event::PaymentSent {
 484                         payment_id, payment_preimage, payment_hash
 485                 });
 486                 assert_eq!(*event_handled.borrow(), true);
 487                 assert_eq!(*payer.attempts.borrow(), 2);
 488         }
 489
 490         #[test]
 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; };
 494
 495                 let payment_preimage = PaymentPreimage([1; 32]);
 496                 let invoice = invoice(payment_preimage);
 497                 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
 498
 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();
 505                 let invoice_payer =
 506                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 507
 508                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 509                 assert_eq!(*payer.attempts.borrow(), 1);
 510
 511                 let event = Event::PaymentPathFailed {
 512                         payment_id,
 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)),
 520                 };
 521                 invoice_payer.handle_event(&event);
 522                 assert_eq!(*event_handled.borrow(), false);
 523                 assert_eq!(*payer.attempts.borrow(), 2);
 524
 525                 let event = Event::PaymentPathFailed {
 526                         payment_id,
 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)
 535                         }),
 536                 };
 537                 invoice_payer.handle_event(&event);
 538                 assert_eq!(*event_handled.borrow(), false);
 539                 assert_eq!(*payer.attempts.borrow(), 3);
 540
 541                 invoice_payer.handle_event(&event);
 542                 assert_eq!(*event_handled.borrow(), true);
 543                 assert_eq!(*payer.attempts.borrow(), 3);
 544         }
 545
 546         #[test]
 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; };
 550
 551                 let payer = TestPayer::new();
 552                 let router = TestRouter {};
 553                 let logger = TestLogger::new();
 554                 let invoice_payer =
 555                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 556
 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);
 561
 562                 let event = Event::PaymentPathFailed {
 563                         payment_id,
 564                         payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
 565                         network_update: None,
 566                         rejected_by_dest: false,
 567                         all_paths_failed: false,
 568                         path: vec![],
 569                         short_channel_id: None,
 570                         retry: None,
 571                 };
 572                 invoice_payer.handle_event(&event);
 573                 assert_eq!(*event_handled.borrow(), true);
 574                 assert_eq!(*payer.attempts.borrow(), 1);
 575         }
 576
 577         #[test]
 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; };
 581
 582                 let payment_preimage = PaymentPreimage([1; 32]);
 583                 let invoice = invoice(payment_preimage);
 584                 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
 585
 586                 let payer = TestPayer::new()
 587                         .fails_on_attempt(2)
 588                         .expect_value_msat(final_value_msat);
 589                 let router = TestRouter {};
 590                 let logger = TestLogger::new();
 591                 let invoice_payer =
 592                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 593
 594                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 595                 assert_eq!(*payer.attempts.borrow(), 1);
 596
 597                 let event = Event::PaymentPathFailed {
 598                         payment_id,
 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)),
 606                 };
 607                 invoice_payer.handle_event(&event);
 608                 assert_eq!(*event_handled.borrow(), true);
 609                 assert_eq!(*payer.attempts.borrow(), 2);
 610         }
 611
 612         #[test]
 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; };
 616
 617                 let payer = TestPayer::new();
 618                 let router = TestRouter {};
 619                 let logger = TestLogger::new();
 620                 let invoice_payer =
 621                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 622
 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);
 627
 628                 let event = Event::PaymentPathFailed {
 629                         payment_id,
 630                         payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
 631                         network_update: None,
 632                         rejected_by_dest: true,
 633                         all_paths_failed: false,
 634                         path: vec![],
 635                         short_channel_id: None,
 636                         retry: Some(TestRouter::retry_for_invoice(&invoice)),
 637                 };
 638                 invoice_payer.handle_event(&event);
 639                 assert_eq!(*event_handled.borrow(), true);
 640                 assert_eq!(*payer.attempts.borrow(), 1);
 641         }
 642
 643         #[test]
 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; };
 647
 648                 let payer = TestPayer::new();
 649                 let router = TestRouter {};
 650                 let logger = TestLogger::new();
 651                 let invoice_payer =
 652                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
 653
 654                 let payment_preimage = PaymentPreimage([1; 32]);
 655                 let invoice = invoice(payment_preimage);
 656                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 657
 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"),
 663                 }
 664
 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());
 669
 670                 // Cannot retry paying an invoice if cleared from cache.
 671                 invoice_payer.remove_cached_payment(&payment_hash);
 672                 let event = Event::PaymentPathFailed {
 673                         payment_id,
 674                         payment_hash,
 675                         network_update: None,
 676                         rejected_by_dest: false,
 677                         all_paths_failed: false,
 678                         path: vec![],
 679                         short_channel_id: None,
 680                         retry: Some(TestRouter::retry_for_invoice(&invoice)),
 681                 };
 682                 invoice_payer.handle_event(&event);
 683                 assert_eq!(*event_handled.borrow(), true);
 684         }
 685
 686         #[test]
 687         fn fails_paying_invoice_with_routing_errors() {
 688                 let payer = TestPayer::new();
 689                 let router = FailingRouter {};
 690                 let logger = TestLogger::new();
 691                 let invoice_payer =
 692                         InvoicePayer::new(&payer, router, &logger, |_: &_| {}, RetryAttempts(0));
 693
 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"),
 700                 }
 701         }
 702
 703         #[test]
 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();
 708                 let invoice_payer =
 709                         InvoicePayer::new(&payer, router, &logger, |_: &_| {}, RetryAttempts(0));
 710
 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"),
 717                 }
 718         }
 719
 720         #[test]
 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; };
 724
 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;
 729
 730                 let payer = TestPayer::new().expect_value_msat(final_value_msat);
 731                 let router = TestRouter {};
 732                 let logger = TestLogger::new();
 733                 let invoice_payer =
 734                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
 735
 736                 let payment_id =
 737                         Some(invoice_payer.pay_zero_value_invoice(&invoice, final_value_msat).unwrap());
 738                 assert_eq!(*payer.attempts.borrow(), 1);
 739
 740                 invoice_payer.handle_event(&Event::PaymentSent {
 741                         payment_id, payment_preimage, payment_hash
 742                 });
 743                 assert_eq!(*event_handled.borrow(), true);
 744                 assert_eq!(*payer.attempts.borrow(), 1);
 745         }
 746
 747         #[test]
 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; };
 751
 752                 let payer = TestPayer::new();
 753                 let router = TestRouter {};
 754                 let logger = TestLogger::new();
 755                 let invoice_payer =
 756                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
 757
 758                 let payment_preimage = PaymentPreimage([1; 32]);
 759                 let invoice = invoice(payment_preimage);
 760
 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"),
 766                 }
 767         }
 768
 769         struct TestRouter;
 770
 771         impl TestRouter {
 772                 fn route_for_value(final_value_msat: u64) -> Route {
 773                         Route {
 774                                 paths: vec![
 775                                         vec![RouteHop {
 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
 780                                         }],
 781                                         vec![RouteHop {
 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
 786                                         }],
 787                                 ],
 788                                 payee: None,
 789                         }
 790                 }
 791
 792                 fn path_for_value(final_value_msat: u64) -> Vec<RouteHop> {
 793                         TestRouter::route_for_value(final_value_msat).paths[0].clone()
 794                 }
 795
 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());
 801                         }
 802                         let final_value_msat = invoice.amount_milli_satoshis().unwrap() / 2;
 803                         RouteParameters {
 804                                 payee,
 805                                 final_value_msat,
 806                                 final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
 807                         }
 808                 }
 809         }
 810
 811         impl Router for TestRouter {
 812                 fn find_route(
 813                         &self,
 814                         _payer: &PublicKey,
 815                         params: &RouteParameters,
 816                         _first_hops: Option<&[&ChannelDetails]>,
 817                 ) -> Result<Route, LightningError> {
 818                         Ok(Route {
 819                                 payee: Some(params.payee.clone()), ..Self::route_for_value(params.final_value_msat)
 820                         })
 821                 }
 822         }
 823
 824         struct FailingRouter;
 825
 826         impl Router for FailingRouter {
 827                 fn find_route(
 828                         &self,
 829                         _payer: &PublicKey,
 830                         _params: &RouteParameters,
 831                         _first_hops: Option<&[&ChannelDetails]>,
 832                 ) -> Result<Route, LightningError> {
 833                         Err(LightningError { err: String::new(), action: ErrorAction::IgnoreError })
 834                 }
 835         }
 836
 837         struct TestPayer {
 838                 expectations: core::cell::RefCell<std::collections::VecDeque<u64>>,
 839                 attempts: core::cell::RefCell<usize>,
 840                 failing_on_attempt: Option<usize>,
 841         }
 842
 843         impl TestPayer {
 844                 fn new() -> Self {
 845                         Self {
 846                                 expectations: core::cell::RefCell::new(std::collections::VecDeque::new()),
 847                                 attempts: core::cell::RefCell::new(0),
 848                                 failing_on_attempt: None,
 849                         }
 850                 }
 851
 852                 fn expect_value_msat(self, value_msat: u64) -> Self {
 853                         self.expectations.borrow_mut().push_back(value_msat);
 854                         self
 855                 }
 856
 857                 fn fails_on_attempt(self, attempt: usize) -> Self {
 858                         Self {
 859                                 expectations: core::cell::RefCell::new(self.expectations.borrow().clone()),
 860                                 attempts: core::cell::RefCell::new(0),
 861                                 failing_on_attempt: Some(attempt),
 862                         }
 863                 }
 864
 865                 fn check_attempts(&self) -> bool {
 866                         let mut attempts = self.attempts.borrow_mut();
 867                         *attempts += 1;
 868                         match self.failing_on_attempt {
 869                                 None => true,
 870                                 Some(attempt) if attempt != *attempts => true,
 871                                 Some(_) => false,
 872                         }
 873                 }
 874
 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);
 880                         }
 881                 }
 882         }
 883
 884         impl Drop for TestPayer {
 885                 fn drop(&mut self) {
 886                         if std::thread::panicking() {
 887                                 return;
 888                         }
 889
 890                         if !self.expectations.borrow().is_empty() {
 891                                 panic!("Unsatisfied payment expectations: {:?}", self.expectations.borrow());
 892                         }
 893                 }
 894         }
 895
 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())
 900                 }
 901
 902                 fn first_hops(&self) -> Vec<ChannelDetails> {
 903                         Vec::new()
 904                 }
 905
 906                 fn send_payment(
 907                         &self,
 908                         route: &Route,
 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]))
 915                         } else {
 916                                 Err(PaymentSendFailure::ParameterError(APIError::MonitorUpdateFailed))
 917                         }
 918                 }
 919
 920                 fn retry_payment(
 921                         &self, route: &Route, _payment_id: PaymentId
 922                 ) -> Result<(), PaymentSendFailure> {
 923                         if self.check_attempts() {
 924                                 self.check_value_msats(route);
 925                                 Ok(())
 926                         } else {
 927                                 Err(PaymentSendFailure::ParameterError(APIError::MonitorUpdateFailed))
 928                         }
 929                 }
 930         }
 931 }