_ 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 use std::time::{Duration, SystemTime};
 118
 119 /// A utility for paying [`Invoice]`s.
 120 pub struct InvoicePayer<P: Deref, R, L: Deref, E>
 121 where
 122         P::Target: Payer,
 123         R: Router,
 124         L::Target: Logger,
 125         E: EventHandler,
 126 {
 127         payer: P,
 128         router: R,
 129         logger: L,
 130         event_handler: E,
 131         payment_cache: Mutex<HashMap<PaymentHash, usize>>,
 132         retry_attempts: RetryAttempts,
 133 }
 134
 135 /// A trait defining behavior of an [`Invoice`] payer.
 136 pub trait Payer {
 137         /// Returns the payer's node id.
 138         fn node_id(&self) -> PublicKey;
 139
 140         /// Returns the payer's channels.
 141         fn first_hops(&self) -> Vec<ChannelDetails>;
 142
 143         /// Sends a payment over the Lightning Network using the given [`Route`].
 144         fn send_payment(
 145                 &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>
 146         ) -> Result<PaymentId, PaymentSendFailure>;
 147
 148         /// Retries a failed payment path for the [`PaymentId`] using the given [`Route`].
 149         fn retry_payment(&self, route: &Route, payment_id: PaymentId) -> Result<(), PaymentSendFailure>;
 150 }
 151
 152 /// A trait defining behavior for routing an [`Invoice`] payment.
 153 pub trait Router {
 154         /// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
 155         fn find_route(
 156                 &self, payer: &PublicKey, params: &RouteParameters, first_hops: Option<&[&ChannelDetails]>
 157         ) -> Result<Route, LightningError>;
 158 }
 159
 160 /// Number of attempts to retry payment path failures for an [`Invoice`].
 161 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 162 pub struct RetryAttempts(pub usize);
 163
 164 /// An error that may occur when making a payment.
 165 #[derive(Clone, Debug)]
 166 pub enum PaymentError {
 167         /// An error resulting from the provided [`Invoice`] or payment hash.
 168         Invoice(&'static str),
 169         /// An error occurring when finding a route.
 170         Routing(LightningError),
 171         /// An error occurring when sending a payment.
 172         Sending(PaymentSendFailure),
 173 }
 174
 175 impl<P: Deref, R, L: Deref, E> InvoicePayer<P, R, L, E>
 176 where
 177         P::Target: Payer,
 178         R: Router,
 179         L::Target: Logger,
 180         E: EventHandler,
 181 {
 182         /// Creates an invoice payer that retries failed payment paths.
 183         ///
 184         /// Will forward any [`Event::PaymentPathFailed`] events to the decorated `event_handler` once
 185         /// `retry_attempts` has been exceeded for a given [`Invoice`].
 186         pub fn new(
 187                 payer: P, router: R, logger: L, event_handler: E, retry_attempts: RetryAttempts
 188         ) -> Self {
 189                 Self {
 190                         payer,
 191                         router,
 192                         logger,
 193                         event_handler,
 194                         payment_cache: Mutex::new(HashMap::new()),
 195                         retry_attempts,
 196                 }
 197         }
 198
 199         /// Pays the given [`Invoice`], caching it for later use in case a retry is needed.
 200         pub fn pay_invoice(&self, invoice: &Invoice) -> Result<PaymentId, PaymentError> {
 201                 if invoice.amount_milli_satoshis().is_none() {
 202                         Err(PaymentError::Invoice("amount missing"))
 203                 } else {
 204                         self.pay_invoice_internal(invoice, None)
 205                 }
 206         }
 207
 208         /// Pays the given zero-value [`Invoice`] using the given amount, caching it for later use in
 209         /// case a retry is needed.
 210         pub fn pay_zero_value_invoice(
 211                 &self, invoice: &Invoice, amount_msats: u64
 212         ) -> Result<PaymentId, PaymentError> {
 213                 if invoice.amount_milli_satoshis().is_some() {
 214                         Err(PaymentError::Invoice("amount unexpected"))
 215                 } else {
 216                         self.pay_invoice_internal(invoice, Some(amount_msats))
 217                 }
 218         }
 219
 220         fn pay_invoice_internal(
 221                 &self, invoice: &Invoice, amount_msats: Option<u64>
 222         ) -> Result<PaymentId, PaymentError> {
 223                 debug_assert!(invoice.amount_milli_satoshis().is_some() ^ amount_msats.is_some());
 224                 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
 225                 let mut payment_cache = self.payment_cache.lock().unwrap();
 226                 match payment_cache.entry(payment_hash) {
 227                         hash_map::Entry::Vacant(entry) => {
 228                                 let payer = self.payer.node_id();
 229                                 let mut payee = Payee::new(invoice.recover_payee_pub_key())
 230                                         .with_expiry_time(expiry_time_from_unix_epoch(&invoice).as_secs())
 231                                         .with_route_hints(invoice.route_hints());
 232                                 if let Some(features) = invoice.features() {
 233                                         payee = payee.with_features(features.clone());
 234                                 }
 235                                 let params = RouteParameters {
 236                                         payee,
 237                                         final_value_msat: invoice.amount_milli_satoshis().or(amount_msats).unwrap(),
 238                                         final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
 239                                 };
 240                                 let first_hops = self.payer.first_hops();
 241                                 let route = self.router.find_route(
 242                                         &payer,
 243                                         &params,
 244                                         Some(&first_hops.iter().collect::<Vec<_>>()),
 245                                 ).map_err(|e| PaymentError::Routing(e))?;
 246
 247                                 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
 248                                 let payment_secret = Some(invoice.payment_secret().clone());
 249                                 let payment_id = self.payer.send_payment(&route, payment_hash, &payment_secret)
 250                                         .map_err(|e| PaymentError::Sending(e))?;
 251                                 entry.insert(0);
 252                                 Ok(payment_id)
 253                         },
 254                         hash_map::Entry::Occupied(_) => Err(PaymentError::Invoice("payment pending")),
 255                 }
 256         }
 257
 258         fn retry_payment(
 259                 &self, payment_id: PaymentId, params: &RouteParameters
 260         ) -> Result<(), PaymentError> {
 261                 let payer = self.payer.node_id();
 262                 let first_hops = self.payer.first_hops();
 263                 let route = self.router.find_route(
 264                         &payer, &params, Some(&first_hops.iter().collect::<Vec<_>>())
 265                 ).map_err(|e| PaymentError::Routing(e))?;
 266                 self.payer.retry_payment(&route, payment_id).map_err(|e| PaymentError::Sending(e))
 267         }
 268
 269         /// Removes the payment cached by the given payment hash.
 270         ///
 271         /// Should be called once a payment has failed or succeeded if not using [`InvoicePayer`] as an
 272         /// [`EventHandler`]. Otherwise, calling this method is unnecessary.
 273         pub fn remove_cached_payment(&self, payment_hash: &PaymentHash) {
 274                 self.payment_cache.lock().unwrap().remove(payment_hash);
 275         }
 276 }
 277
 278 fn expiry_time_from_unix_epoch(invoice: &Invoice) -> Duration {
 279         invoice.timestamp().duration_since(SystemTime::UNIX_EPOCH).unwrap() + invoice.expiry_time()
 280 }
 281
 282 fn has_expired(params: &RouteParameters) -> bool {
 283         let expiry_time = Duration::from_secs(params.payee.expiry_time.unwrap());
 284         Invoice::is_expired_from_epoch(&SystemTime::UNIX_EPOCH, expiry_time)
 285 }
 286
 287 impl<P: Deref, R, L: Deref, E> EventHandler for InvoicePayer<P, R, L, E>
 288 where
 289         P::Target: Payer,
 290         R: Router,
 291         L::Target: Logger,
 292         E: EventHandler,
 293 {
 294         fn handle_event(&self, event: &Event) {
 295                 match event {
 296                         Event::PaymentPathFailed { payment_id, payment_hash, rejected_by_dest, retry, .. } => {
 297                                 let mut payment_cache = self.payment_cache.lock().unwrap();
 298                                 let entry = loop {
 299                                         let entry = payment_cache.entry(*payment_hash);
 300                                         match entry {
 301                                                 hash_map::Entry::Occupied(_) => break entry,
 302                                                 hash_map::Entry::Vacant(entry) => entry.insert(0),
 303                                         };
 304                                 };
 305                                 if let hash_map::Entry::Occupied(mut entry) = entry {
 306                                         let max_payment_attempts = self.retry_attempts.0 + 1;
 307                                         let attempts = entry.get_mut();
 308                                         *attempts += 1;
 309
 310                                         if *rejected_by_dest {
 311                                                 log_trace!(self.logger, "Payment {} rejected by destination; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
 312                                         } else if payment_id.is_none() {
 313                                                 log_trace!(self.logger, "Payment {} has no id; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
 314                                         } else if *attempts >= max_payment_attempts {
 315                                                 log_trace!(self.logger, "Payment {} exceeded maximum attempts; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
 316                                         } else if retry.is_none() {
 317                                                 log_trace!(self.logger, "Payment {} missing retry params; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
 318                                         } else if has_expired(retry.as_ref().unwrap()) {
 319                                                 log_trace!(self.logger, "Invoice expired for payment {}; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
 320                                         } else if self.retry_payment(*payment_id.as_ref().unwrap(), retry.as_ref().unwrap()).is_err() {
 321                                                 log_trace!(self.logger, "Error retrying payment {}; not retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
 322                                         } else {
 323                                                 log_trace!(self.logger, "Payment {} failed; retrying (attempts: {})", log_bytes!(payment_hash.0), attempts);
 324                                                 return;
 325                                         }
 326
 327                                         // Either the payment was rejected, the maximum attempts were exceeded, or an
 328                                         // error occurred when attempting to retry.
 329                                         entry.remove();
 330                                 } else {
 331                                         unreachable!();
 332                                 }
 333                         },
 334                         Event::PaymentSent { payment_hash, .. } => {
 335                                 let mut payment_cache = self.payment_cache.lock().unwrap();
 336                                 let attempts = payment_cache
 337                                         .remove(payment_hash)
 338                                         .map_or(1, |attempts| attempts + 1);
 339                                 log_trace!(self.logger, "Payment {} succeeded (attempts: {})", log_bytes!(payment_hash.0), attempts);
 340                         },
 341                         _ => {},
 342                 }
 343
 344                 // Delegate to the decorated event handler unless the payment is retried.
 345                 self.event_handler.handle_event(event)
 346         }
 347 }
 348
 349 #[cfg(test)]
 350 mod tests {
 351         use super::*;
 352         use crate::{DEFAULT_EXPIRY_TIME, InvoiceBuilder, Currency};
 353         use bitcoin_hashes::sha256::Hash as Sha256;
 354         use lightning::ln::PaymentPreimage;
 355         use lightning::ln::features::{ChannelFeatures, NodeFeatures};
 356         use lightning::ln::msgs::{ErrorAction, LightningError};
 357         use lightning::routing::router::{Route, RouteHop};
 358         use lightning::util::test_utils::TestLogger;
 359         use lightning::util::errors::APIError;
 360         use lightning::util::events::Event;
 361         use secp256k1::{SecretKey, PublicKey, Secp256k1};
 362         use std::time::{SystemTime, Duration};
 363
 364         fn invoice(payment_preimage: PaymentPreimage) -> Invoice {
 365                 let payment_hash = Sha256::hash(&payment_preimage.0);
 366                 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
 367                 InvoiceBuilder::new(Currency::Bitcoin)
 368                         .description("test".into())
 369                         .payment_hash(payment_hash)
 370                         .payment_secret(PaymentSecret([0; 32]))
 371                         .current_timestamp()
 372                         .min_final_cltv_expiry(144)
 373                         .amount_milli_satoshis(128)
 374                         .build_signed(|hash| {
 375                                 Secp256k1::new().sign_recoverable(hash, &private_key)
 376                         })
 377                         .unwrap()
 378         }
 379
 380         fn zero_value_invoice(payment_preimage: PaymentPreimage) -> Invoice {
 381                 let payment_hash = Sha256::hash(&payment_preimage.0);
 382                 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
 383                 InvoiceBuilder::new(Currency::Bitcoin)
 384                         .description("test".into())
 385                         .payment_hash(payment_hash)
 386                         .payment_secret(PaymentSecret([0; 32]))
 387                         .current_timestamp()
 388                         .min_final_cltv_expiry(144)
 389                         .build_signed(|hash| {
 390                                 Secp256k1::new().sign_recoverable(hash, &private_key)
 391                         })
 392                         .unwrap()
 393         }
 394
 395         fn expired_invoice(payment_preimage: PaymentPreimage) -> Invoice {
 396                 let payment_hash = Sha256::hash(&payment_preimage.0);
 397                 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
 398                 let timestamp = SystemTime::now()
 399                         .checked_sub(Duration::from_secs(DEFAULT_EXPIRY_TIME * 2))
 400                         .unwrap();
 401                 InvoiceBuilder::new(Currency::Bitcoin)
 402                         .description("test".into())
 403                         .payment_hash(payment_hash)
 404                         .payment_secret(PaymentSecret([0; 32]))
 405                         .timestamp(timestamp)
 406                         .min_final_cltv_expiry(144)
 407                         .amount_milli_satoshis(128)
 408                         .build_signed(|hash| {
 409                                 Secp256k1::new().sign_recoverable(hash, &private_key)
 410                         })
 411                         .unwrap()
 412         }
 413
 414         #[test]
 415         fn pays_invoice_on_first_attempt() {
 416                 let event_handled = core::cell::RefCell::new(false);
 417                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 418
 419                 let payment_preimage = PaymentPreimage([1; 32]);
 420                 let invoice = invoice(payment_preimage);
 421                 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
 422
 423                 let payer = TestPayer::new();
 424                 let router = TestRouter {};
 425                 let logger = TestLogger::new();
 426                 let invoice_payer =
 427                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
 428
 429                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 430                 assert_eq!(*payer.attempts.borrow(), 1);
 431
 432                 invoice_payer.handle_event(&Event::PaymentSent {
 433                         payment_id, payment_preimage, payment_hash, fee_paid_msat: None
 434                 });
 435                 assert_eq!(*event_handled.borrow(), true);
 436                 assert_eq!(*payer.attempts.borrow(), 1);
 437         }
 438
 439         #[test]
 440         fn pays_invoice_on_retry() {
 441                 let event_handled = core::cell::RefCell::new(false);
 442                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 443
 444                 let payment_preimage = PaymentPreimage([1; 32]);
 445                 let invoice = invoice(payment_preimage);
 446                 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
 447                 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
 448
 449                 let payer = TestPayer::new()
 450                         .expect_value_msat(final_value_msat)
 451                         .expect_value_msat(final_value_msat / 2);
 452                 let router = TestRouter {};
 453                 let logger = TestLogger::new();
 454                 let invoice_payer =
 455                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 456
 457                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 458                 assert_eq!(*payer.attempts.borrow(), 1);
 459
 460                 let event = Event::PaymentPathFailed {
 461                         payment_id,
 462                         payment_hash,
 463                         network_update: None,
 464                         rejected_by_dest: false,
 465                         all_paths_failed: false,
 466                         path: TestRouter::path_for_value(final_value_msat),
 467                         short_channel_id: None,
 468                         retry: Some(TestRouter::retry_for_invoice(&invoice)),
 469                 };
 470                 invoice_payer.handle_event(&event);
 471                 assert_eq!(*event_handled.borrow(), false);
 472                 assert_eq!(*payer.attempts.borrow(), 2);
 473
 474                 invoice_payer.handle_event(&Event::PaymentSent {
 475                         payment_id, payment_preimage, payment_hash, fee_paid_msat: None
 476                 });
 477                 assert_eq!(*event_handled.borrow(), true);
 478                 assert_eq!(*payer.attempts.borrow(), 2);
 479         }
 480
 481         #[test]
 482         fn retries_payment_path_for_unknown_payment() {
 483                 let event_handled = core::cell::RefCell::new(false);
 484                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 485
 486                 let payment_preimage = PaymentPreimage([1; 32]);
 487                 let invoice = invoice(payment_preimage);
 488                 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
 489                 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
 490
 491                 let payer = TestPayer::new();
 492                 let router = TestRouter {};
 493                 let logger = TestLogger::new();
 494                 let invoice_payer =
 495                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 496
 497                 let payment_id = Some(PaymentId([1; 32]));
 498                 let event = Event::PaymentPathFailed {
 499                         payment_id,
 500                         payment_hash,
 501                         network_update: None,
 502                         rejected_by_dest: false,
 503                         all_paths_failed: false,
 504                         path: TestRouter::path_for_value(final_value_msat),
 505                         short_channel_id: None,
 506                         retry: Some(TestRouter::retry_for_invoice(&invoice)),
 507                 };
 508                 invoice_payer.handle_event(&event);
 509                 assert_eq!(*event_handled.borrow(), false);
 510                 assert_eq!(*payer.attempts.borrow(), 1);
 511
 512                 invoice_payer.handle_event(&event);
 513                 assert_eq!(*event_handled.borrow(), false);
 514                 assert_eq!(*payer.attempts.borrow(), 2);
 515
 516                 invoice_payer.handle_event(&Event::PaymentSent {
 517                         payment_id, payment_preimage, payment_hash, fee_paid_msat: None
 518                 });
 519                 assert_eq!(*event_handled.borrow(), true);
 520                 assert_eq!(*payer.attempts.borrow(), 2);
 521         }
 522
 523         #[test]
 524         fn fails_paying_invoice_after_max_retries() {
 525                 let event_handled = core::cell::RefCell::new(false);
 526                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 527
 528                 let payment_preimage = PaymentPreimage([1; 32]);
 529                 let invoice = invoice(payment_preimage);
 530                 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
 531
 532                 let payer = TestPayer::new()
 533                         .expect_value_msat(final_value_msat)
 534                         .expect_value_msat(final_value_msat / 2)
 535                         .expect_value_msat(final_value_msat / 2);
 536                 let router = TestRouter {};
 537                 let logger = TestLogger::new();
 538                 let invoice_payer =
 539                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 540
 541                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 542                 assert_eq!(*payer.attempts.borrow(), 1);
 543
 544                 let event = Event::PaymentPathFailed {
 545                         payment_id,
 546                         payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
 547                         network_update: None,
 548                         rejected_by_dest: false,
 549                         all_paths_failed: true,
 550                         path: TestRouter::path_for_value(final_value_msat),
 551                         short_channel_id: None,
 552                         retry: Some(TestRouter::retry_for_invoice(&invoice)),
 553                 };
 554                 invoice_payer.handle_event(&event);
 555                 assert_eq!(*event_handled.borrow(), false);
 556                 assert_eq!(*payer.attempts.borrow(), 2);
 557
 558                 let event = Event::PaymentPathFailed {
 559                         payment_id,
 560                         payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
 561                         network_update: None,
 562                         rejected_by_dest: false,
 563                         all_paths_failed: false,
 564                         path: TestRouter::path_for_value(final_value_msat / 2),
 565                         short_channel_id: None,
 566                         retry: Some(RouteParameters {
 567                                 final_value_msat: final_value_msat / 2, ..TestRouter::retry_for_invoice(&invoice)
 568                         }),
 569                 };
 570                 invoice_payer.handle_event(&event);
 571                 assert_eq!(*event_handled.borrow(), false);
 572                 assert_eq!(*payer.attempts.borrow(), 3);
 573
 574                 invoice_payer.handle_event(&event);
 575                 assert_eq!(*event_handled.borrow(), true);
 576                 assert_eq!(*payer.attempts.borrow(), 3);
 577         }
 578
 579         #[test]
 580         fn fails_paying_invoice_with_missing_retry_params() {
 581                 let event_handled = core::cell::RefCell::new(false);
 582                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 583
 584                 let payer = TestPayer::new();
 585                 let router = TestRouter {};
 586                 let logger = TestLogger::new();
 587                 let invoice_payer =
 588                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 589
 590                 let payment_preimage = PaymentPreimage([1; 32]);
 591                 let invoice = invoice(payment_preimage);
 592                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 593                 assert_eq!(*payer.attempts.borrow(), 1);
 594
 595                 let event = Event::PaymentPathFailed {
 596                         payment_id,
 597                         payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
 598                         network_update: None,
 599                         rejected_by_dest: false,
 600                         all_paths_failed: false,
 601                         path: vec![],
 602                         short_channel_id: None,
 603                         retry: None,
 604                 };
 605                 invoice_payer.handle_event(&event);
 606                 assert_eq!(*event_handled.borrow(), true);
 607                 assert_eq!(*payer.attempts.borrow(), 1);
 608         }
 609
 610         #[test]
 611         fn fails_paying_invoice_after_expiration() {
 612                 let event_handled = core::cell::RefCell::new(false);
 613                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 614
 615                 let payer = TestPayer::new();
 616                 let router = TestRouter {};
 617                 let logger = TestLogger::new();
 618                 let invoice_payer =
 619                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 620
 621                 let payment_preimage = PaymentPreimage([1; 32]);
 622                 let invoice = expired_invoice(payment_preimage);
 623                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 624                 assert_eq!(*payer.attempts.borrow(), 1);
 625
 626                 let event = Event::PaymentPathFailed {
 627                         payment_id,
 628                         payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
 629                         network_update: None,
 630                         rejected_by_dest: false,
 631                         all_paths_failed: false,
 632                         path: vec![],
 633                         short_channel_id: None,
 634                         retry: Some(TestRouter::retry_for_invoice(&invoice)),
 635                 };
 636                 invoice_payer.handle_event(&event);
 637                 assert_eq!(*event_handled.borrow(), true);
 638                 assert_eq!(*payer.attempts.borrow(), 1);
 639         }
 640
 641         #[test]
 642         fn fails_paying_invoice_after_retry_error() {
 643                 let event_handled = core::cell::RefCell::new(false);
 644                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 645
 646                 let payment_preimage = PaymentPreimage([1; 32]);
 647                 let invoice = invoice(payment_preimage);
 648                 let final_value_msat = invoice.amount_milli_satoshis().unwrap();
 649
 650                 let payer = TestPayer::new()
 651                         .fails_on_attempt(2)
 652                         .expect_value_msat(final_value_msat);
 653                 let router = TestRouter {};
 654                 let logger = TestLogger::new();
 655                 let invoice_payer =
 656                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 657
 658                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 659                 assert_eq!(*payer.attempts.borrow(), 1);
 660
 661                 let event = Event::PaymentPathFailed {
 662                         payment_id,
 663                         payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
 664                         network_update: None,
 665                         rejected_by_dest: false,
 666                         all_paths_failed: false,
 667                         path: TestRouter::path_for_value(final_value_msat / 2),
 668                         short_channel_id: None,
 669                         retry: Some(TestRouter::retry_for_invoice(&invoice)),
 670                 };
 671                 invoice_payer.handle_event(&event);
 672                 assert_eq!(*event_handled.borrow(), true);
 673                 assert_eq!(*payer.attempts.borrow(), 2);
 674         }
 675
 676         #[test]
 677         fn fails_paying_invoice_after_rejected_by_payee() {
 678                 let event_handled = core::cell::RefCell::new(false);
 679                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 680
 681                 let payer = TestPayer::new();
 682                 let router = TestRouter {};
 683                 let logger = TestLogger::new();
 684                 let invoice_payer =
 685                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(2));
 686
 687                 let payment_preimage = PaymentPreimage([1; 32]);
 688                 let invoice = invoice(payment_preimage);
 689                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 690                 assert_eq!(*payer.attempts.borrow(), 1);
 691
 692                 let event = Event::PaymentPathFailed {
 693                         payment_id,
 694                         payment_hash: PaymentHash(invoice.payment_hash().clone().into_inner()),
 695                         network_update: None,
 696                         rejected_by_dest: true,
 697                         all_paths_failed: false,
 698                         path: vec![],
 699                         short_channel_id: None,
 700                         retry: Some(TestRouter::retry_for_invoice(&invoice)),
 701                 };
 702                 invoice_payer.handle_event(&event);
 703                 assert_eq!(*event_handled.borrow(), true);
 704                 assert_eq!(*payer.attempts.borrow(), 1);
 705         }
 706
 707         #[test]
 708         fn fails_repaying_invoice_with_pending_payment() {
 709                 let event_handled = core::cell::RefCell::new(false);
 710                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 711
 712                 let payer = TestPayer::new();
 713                 let router = TestRouter {};
 714                 let logger = TestLogger::new();
 715                 let invoice_payer =
 716                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
 717
 718                 let payment_preimage = PaymentPreimage([1; 32]);
 719                 let invoice = invoice(payment_preimage);
 720                 let payment_id = Some(invoice_payer.pay_invoice(&invoice).unwrap());
 721
 722                 // Cannot repay an invoice pending payment.
 723                 match invoice_payer.pay_invoice(&invoice) {
 724                         Err(PaymentError::Invoice("payment pending")) => {},
 725                         Err(_) => panic!("unexpected error"),
 726                         Ok(_) => panic!("expected invoice error"),
 727                 }
 728
 729                 // Can repay an invoice once cleared from cache.
 730                 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
 731                 invoice_payer.remove_cached_payment(&payment_hash);
 732                 assert!(invoice_payer.pay_invoice(&invoice).is_ok());
 733
 734                 // Cannot retry paying an invoice if cleared from cache.
 735                 invoice_payer.remove_cached_payment(&payment_hash);
 736                 let event = Event::PaymentPathFailed {
 737                         payment_id,
 738                         payment_hash,
 739                         network_update: None,
 740                         rejected_by_dest: false,
 741                         all_paths_failed: false,
 742                         path: vec![],
 743                         short_channel_id: None,
 744                         retry: Some(TestRouter::retry_for_invoice(&invoice)),
 745                 };
 746                 invoice_payer.handle_event(&event);
 747                 assert_eq!(*event_handled.borrow(), true);
 748         }
 749
 750         #[test]
 751         fn fails_paying_invoice_with_routing_errors() {
 752                 let payer = TestPayer::new();
 753                 let router = FailingRouter {};
 754                 let logger = TestLogger::new();
 755                 let invoice_payer =
 756                         InvoicePayer::new(&payer, router, &logger, |_: &_| {}, RetryAttempts(0));
 757
 758                 let payment_preimage = PaymentPreimage([1; 32]);
 759                 let invoice = invoice(payment_preimage);
 760                 match invoice_payer.pay_invoice(&invoice) {
 761                         Err(PaymentError::Routing(_)) => {},
 762                         Err(_) => panic!("unexpected error"),
 763                         Ok(_) => panic!("expected routing error"),
 764                 }
 765         }
 766
 767         #[test]
 768         fn fails_paying_invoice_with_sending_errors() {
 769                 let payer = TestPayer::new().fails_on_attempt(1);
 770                 let router = TestRouter {};
 771                 let logger = TestLogger::new();
 772                 let invoice_payer =
 773                         InvoicePayer::new(&payer, router, &logger, |_: &_| {}, RetryAttempts(0));
 774
 775                 let payment_preimage = PaymentPreimage([1; 32]);
 776                 let invoice = invoice(payment_preimage);
 777                 match invoice_payer.pay_invoice(&invoice) {
 778                         Err(PaymentError::Sending(_)) => {},
 779                         Err(_) => panic!("unexpected error"),
 780                         Ok(_) => panic!("expected sending error"),
 781                 }
 782         }
 783
 784         #[test]
 785         fn pays_zero_value_invoice_using_amount() {
 786                 let event_handled = core::cell::RefCell::new(false);
 787                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 788
 789                 let payment_preimage = PaymentPreimage([1; 32]);
 790                 let invoice = zero_value_invoice(payment_preimage);
 791                 let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
 792                 let final_value_msat = 100;
 793
 794                 let payer = TestPayer::new().expect_value_msat(final_value_msat);
 795                 let router = TestRouter {};
 796                 let logger = TestLogger::new();
 797                 let invoice_payer =
 798                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
 799
 800                 let payment_id =
 801                         Some(invoice_payer.pay_zero_value_invoice(&invoice, final_value_msat).unwrap());
 802                 assert_eq!(*payer.attempts.borrow(), 1);
 803
 804                 invoice_payer.handle_event(&Event::PaymentSent {
 805                         payment_id, payment_preimage, payment_hash, fee_paid_msat: None
 806                 });
 807                 assert_eq!(*event_handled.borrow(), true);
 808                 assert_eq!(*payer.attempts.borrow(), 1);
 809         }
 810
 811         #[test]
 812         fn fails_paying_zero_value_invoice_with_amount() {
 813                 let event_handled = core::cell::RefCell::new(false);
 814                 let event_handler = |_: &_| { *event_handled.borrow_mut() = true; };
 815
 816                 let payer = TestPayer::new();
 817                 let router = TestRouter {};
 818                 let logger = TestLogger::new();
 819                 let invoice_payer =
 820                         InvoicePayer::new(&payer, router, &logger, event_handler, RetryAttempts(0));
 821
 822                 let payment_preimage = PaymentPreimage([1; 32]);
 823                 let invoice = invoice(payment_preimage);
 824
 825                 // Cannot repay an invoice pending payment.
 826                 match invoice_payer.pay_zero_value_invoice(&invoice, 100) {
 827                         Err(PaymentError::Invoice("amount unexpected")) => {},
 828                         Err(_) => panic!("unexpected error"),
 829                         Ok(_) => panic!("expected invoice error"),
 830                 }
 831         }
 832
 833         struct TestRouter;
 834
 835         impl TestRouter {
 836                 fn route_for_value(final_value_msat: u64) -> Route {
 837                         Route {
 838                                 paths: vec![
 839                                         vec![RouteHop {
 840                                                 pubkey: PublicKey::from_slice(&hex::decode("02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619").unwrap()[..]).unwrap(),
 841                                                 channel_features: ChannelFeatures::empty(),
 842                                                 node_features: NodeFeatures::empty(),
 843                                                 short_channel_id: 0, fee_msat: final_value_msat / 2, cltv_expiry_delta: 144
 844                                         }],
 845                                         vec![RouteHop {
 846                                                 pubkey: PublicKey::from_slice(&hex::decode("0324653eac434488002cc06bbfb7f10fe18991e35f9fe4302dbea6d2353dc0ab1c").unwrap()[..]).unwrap(),
 847                                                 channel_features: ChannelFeatures::empty(),
 848                                                 node_features: NodeFeatures::empty(),
 849                                                 short_channel_id: 1, fee_msat: final_value_msat / 2, cltv_expiry_delta: 144
 850                                         }],
 851                                 ],
 852                                 payee: None,
 853                         }
 854                 }
 855
 856                 fn path_for_value(final_value_msat: u64) -> Vec<RouteHop> {
 857                         TestRouter::route_for_value(final_value_msat).paths[0].clone()
 858                 }
 859
 860                 fn retry_for_invoice(invoice: &Invoice) -> RouteParameters {
 861                         let mut payee = Payee::new(invoice.recover_payee_pub_key())
 862                                 .with_expiry_time(expiry_time_from_unix_epoch(invoice).as_secs())
 863                                 .with_route_hints(invoice.route_hints());
 864                         if let Some(features) = invoice.features() {
 865                                 payee = payee.with_features(features.clone());
 866                         }
 867                         let final_value_msat = invoice.amount_milli_satoshis().unwrap() / 2;
 868                         RouteParameters {
 869                                 payee,
 870                                 final_value_msat,
 871                                 final_cltv_expiry_delta: invoice.min_final_cltv_expiry() as u32,
 872                         }
 873                 }
 874         }
 875
 876         impl Router for TestRouter {
 877                 fn find_route(
 878                         &self,
 879                         _payer: &PublicKey,
 880                         params: &RouteParameters,
 881                         _first_hops: Option<&[&ChannelDetails]>,
 882                 ) -> Result<Route, LightningError> {
 883                         Ok(Route {
 884                                 payee: Some(params.payee.clone()), ..Self::route_for_value(params.final_value_msat)
 885                         })
 886                 }
 887         }
 888
 889         struct FailingRouter;
 890
 891         impl Router for FailingRouter {
 892                 fn find_route(
 893                         &self,
 894                         _payer: &PublicKey,
 895                         _params: &RouteParameters,
 896                         _first_hops: Option<&[&ChannelDetails]>,
 897                 ) -> Result<Route, LightningError> {
 898                         Err(LightningError { err: String::new(), action: ErrorAction::IgnoreError })
 899                 }
 900         }
 901
 902         struct TestPayer {
 903                 expectations: core::cell::RefCell<std::collections::VecDeque<u64>>,
 904                 attempts: core::cell::RefCell<usize>,
 905                 failing_on_attempt: Option<usize>,
 906         }
 907
 908         impl TestPayer {
 909                 fn new() -> Self {
 910                         Self {
 911                                 expectations: core::cell::RefCell::new(std::collections::VecDeque::new()),
 912                                 attempts: core::cell::RefCell::new(0),
 913                                 failing_on_attempt: None,
 914                         }
 915                 }
 916
 917                 fn expect_value_msat(self, value_msat: u64) -> Self {
 918                         self.expectations.borrow_mut().push_back(value_msat);
 919                         self
 920                 }
 921
 922                 fn fails_on_attempt(self, attempt: usize) -> Self {
 923                         Self {
 924                                 expectations: core::cell::RefCell::new(self.expectations.borrow().clone()),
 925                                 attempts: core::cell::RefCell::new(0),
 926                                 failing_on_attempt: Some(attempt),
 927                         }
 928                 }
 929
 930                 fn check_attempts(&self) -> bool {
 931                         let mut attempts = self.attempts.borrow_mut();
 932                         *attempts += 1;
 933                         match self.failing_on_attempt {
 934                                 None => true,
 935                                 Some(attempt) if attempt != *attempts => true,
 936                                 Some(_) => false,
 937                         }
 938                 }
 939
 940                 fn check_value_msats(&self, route: &Route) {
 941                         let expected_value_msats = self.expectations.borrow_mut().pop_front();
 942                         if let Some(expected_value_msats) = expected_value_msats {
 943                                 let actual_value_msats = route.get_total_amount();
 944                                 assert_eq!(actual_value_msats, expected_value_msats);
 945                         }
 946                 }
 947         }
 948
 949         impl Drop for TestPayer {
 950                 fn drop(&mut self) {
 951                         if std::thread::panicking() {
 952                                 return;
 953                         }
 954
 955                         if !self.expectations.borrow().is_empty() {
 956                                 panic!("Unsatisfied payment expectations: {:?}", self.expectations.borrow());
 957                         }
 958                 }
 959         }
 960
 961         impl Payer for TestPayer {
 962                 fn node_id(&self) -> PublicKey {
 963                         let secp_ctx = Secp256k1::new();
 964                         PublicKey::from_secret_key(&secp_ctx, &SecretKey::from_slice(&[42; 32]).unwrap())
 965                 }
 966
 967                 fn first_hops(&self) -> Vec<ChannelDetails> {
 968                         Vec::new()
 969                 }
 970
 971                 fn send_payment(
 972                         &self,
 973                         route: &Route,
 974                         _payment_hash: PaymentHash,
 975                         _payment_secret: &Option<PaymentSecret>
 976                 ) -> Result<PaymentId, PaymentSendFailure> {
 977                         if self.check_attempts() {
 978                                 self.check_value_msats(route);
 979                                 Ok(PaymentId([1; 32]))
 980                         } else {
 981                                 Err(PaymentSendFailure::ParameterError(APIError::MonitorUpdateFailed))
 982                         }
 983                 }
 984
 985                 fn retry_payment(
 986                         &self, route: &Route, _payment_id: PaymentId
 987                 ) -> Result<(), PaymentSendFailure> {
 988                         if self.check_attempts() {
 989                                 self.check_value_msats(route);
 990                                 Ok(())
 991                         } else {
 992                                 Err(PaymentSendFailure::ParameterError(APIError::MonitorUpdateFailed))
 993                         }
 994                 }
 995         }
 996 }