_ Git - rust-lightning/blob - lightning/src/ln/outbound_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 //! Utilities to send payments and manage outbound payment information.
  11
  12 use bitcoin::hashes::Hash;
  13 use bitcoin::hashes::sha256::Hash as Sha256;
  14 use bitcoin::secp256k1::{self, Secp256k1, SecretKey};
  15
  16 use crate::chain::keysinterface::{EntropySource, NodeSigner, Recipient};
  17 use crate::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
  18 use crate::ln::channelmanager::{HTLCSource, IDEMPOTENCY_TIMEOUT_TICKS, MIN_HTLC_RELAY_HOLDING_CELL_MILLIS, PaymentId};
  19 use crate::ln::msgs::DecodeError;
  20 use crate::ln::onion_utils::HTLCFailReason;
  21 use crate::routing::router::{PaymentParameters, Route, RouteHop, RouteParameters, RoutePath};
  22 use crate::util::errors::APIError;
  23 use crate::util::events;
  24 use crate::util::logger::Logger;
  25 use crate::util::time::Time;
  26 #[cfg(all(not(feature = "no-std"), test))]
  27 use crate::util::time::tests::SinceEpoch;
  28
  29 use core::cmp;
  30 use core::fmt::{self, Display, Formatter};
  31 use core::ops::Deref;
  32 use core::time::Duration;
  33
  34 use crate::prelude::*;
  35 use crate::sync::Mutex;
  36
  37 /// Stores the session_priv for each part of a payment that is still pending. For versions 0.0.102
  38 /// and later, also stores information for retrying the payment.
  39 pub(crate) enum PendingOutboundPayment {
  40         Legacy {
  41                 session_privs: HashSet<[u8; 32]>,
  42         },
  43         Retryable {
  44                 retry_strategy: Retry,
  45                 attempts: PaymentAttempts,
  46                 route_params: Option<RouteParameters>,
  47                 session_privs: HashSet<[u8; 32]>,
  48                 payment_hash: PaymentHash,
  49                 payment_secret: Option<PaymentSecret>,
  50                 pending_amt_msat: u64,
  51                 /// Used to track the fee paid. Only present if the payment was serialized on 0.0.103+.
  52                 pending_fee_msat: Option<u64>,
  53                 /// The total payment amount across all paths, used to verify that a retry is not overpaying.
  54                 total_msat: u64,
  55                 /// Our best known block height at the time this payment was initiated.
  56                 starting_block_height: u32,
  57         },
  58         /// When a pending payment is fulfilled, we continue tracking it until all pending HTLCs have
  59         /// been resolved. This ensures we don't look up pending payments in ChannelMonitors on restart
  60         /// and add a pending payment that was already fulfilled.
  61         Fulfilled {
  62                 session_privs: HashSet<[u8; 32]>,
  63                 payment_hash: Option<PaymentHash>,
  64                 timer_ticks_without_htlcs: u8,
  65         },
  66         /// When a payer gives up trying to retry a payment, they inform us, letting us generate a
  67         /// `PaymentFailed` event when all HTLCs have irrevocably failed. This avoids a number of race
  68         /// conditions in MPP-aware payment retriers (1), where the possibility of multiple
  69         /// `PaymentPathFailed` events with `all_paths_failed` can be pending at once, confusing a
  70         /// downstream event handler as to when a payment has actually failed.
  71         ///
  72         /// (1) <https://github.com/lightningdevkit/rust-lightning/issues/1164>
  73         Abandoned {
  74                 session_privs: HashSet<[u8; 32]>,
  75                 payment_hash: PaymentHash,
  76         },
  77 }
  78
  79 impl PendingOutboundPayment {
  80         fn increment_attempts(&mut self) {
  81                 if let PendingOutboundPayment::Retryable { attempts, .. } = self {
  82                         attempts.count += 1;
  83                 }
  84         }
  85         fn is_retryable_now(&self) -> bool {
  86                 if let PendingOutboundPayment::Retryable { retry_strategy, attempts, .. } = self {
  87                         return retry_strategy.is_retryable_now(&attempts)
  88                 }
  89                 false
  90         }
  91         pub fn insert_previously_failed_scid(&mut self, scid: u64) {
  92                 if let PendingOutboundPayment::Retryable { route_params: Some(params), .. } = self {
  93                         params.payment_params.previously_failed_channels.push(scid);
  94                 }
  95         }
  96         pub(super) fn is_fulfilled(&self) -> bool {
  97                 match self {
  98                         PendingOutboundPayment::Fulfilled { .. } => true,
  99                         _ => false,
 100                 }
 101         }
 102         pub(super) fn abandoned(&self) -> bool {
 103                 match self {
 104                         PendingOutboundPayment::Abandoned { .. } => true,
 105                         _ => false,
 106                 }
 107         }
 108         fn get_pending_fee_msat(&self) -> Option<u64> {
 109                 match self {
 110                         PendingOutboundPayment::Retryable { pending_fee_msat, .. } => pending_fee_msat.clone(),
 111                         _ => None,
 112                 }
 113         }
 114
 115         fn payment_hash(&self) -> Option<PaymentHash> {
 116                 match self {
 117                         PendingOutboundPayment::Legacy { .. } => None,
 118                         PendingOutboundPayment::Retryable { payment_hash, .. } => Some(*payment_hash),
 119                         PendingOutboundPayment::Fulfilled { payment_hash, .. } => *payment_hash,
 120                         PendingOutboundPayment::Abandoned { payment_hash, .. } => Some(*payment_hash),
 121                 }
 122         }
 123
 124         fn mark_fulfilled(&mut self) {
 125                 let mut session_privs = HashSet::new();
 126                 core::mem::swap(&mut session_privs, match self {
 127                         PendingOutboundPayment::Legacy { session_privs } |
 128                                 PendingOutboundPayment::Retryable { session_privs, .. } |
 129                                 PendingOutboundPayment::Fulfilled { session_privs, .. } |
 130                                 PendingOutboundPayment::Abandoned { session_privs, .. }
 131                         => session_privs,
 132                 });
 133                 let payment_hash = self.payment_hash();
 134                 *self = PendingOutboundPayment::Fulfilled { session_privs, payment_hash, timer_ticks_without_htlcs: 0 };
 135         }
 136
 137         fn mark_abandoned(&mut self) -> Result<(), ()> {
 138                 let mut session_privs = HashSet::new();
 139                 let our_payment_hash;
 140                 core::mem::swap(&mut session_privs, match self {
 141                         PendingOutboundPayment::Legacy { .. } |
 142                                 PendingOutboundPayment::Fulfilled { .. } =>
 143                                 return Err(()),
 144                                 PendingOutboundPayment::Retryable { session_privs, payment_hash, .. } |
 145                                         PendingOutboundPayment::Abandoned { session_privs, payment_hash, .. } => {
 146                                                 our_payment_hash = *payment_hash;
 147                                                 session_privs
 148                                         },
 149                 });
 150                 *self = PendingOutboundPayment::Abandoned { session_privs, payment_hash: our_payment_hash };
 151                 Ok(())
 152         }
 153
 154         /// panics if path is None and !self.is_fulfilled
 155         fn remove(&mut self, session_priv: &[u8; 32], path: Option<&Vec<RouteHop>>) -> bool {
 156                 let remove_res = match self {
 157                         PendingOutboundPayment::Legacy { session_privs } |
 158                                 PendingOutboundPayment::Retryable { session_privs, .. } |
 159                                 PendingOutboundPayment::Fulfilled { session_privs, .. } |
 160                                 PendingOutboundPayment::Abandoned { session_privs, .. } => {
 161                                         session_privs.remove(session_priv)
 162                                 }
 163                 };
 164                 if remove_res {
 165                         if let PendingOutboundPayment::Retryable { ref mut pending_amt_msat, ref mut pending_fee_msat, .. } = self {
 166                                 let path = path.expect("Fulfilling a payment should always come with a path");
 167                                 let path_last_hop = path.last().expect("Outbound payments must have had a valid path");
 168                                 *pending_amt_msat -= path_last_hop.fee_msat;
 169                                 if let Some(fee_msat) = pending_fee_msat.as_mut() {
 170                                         *fee_msat -= path.get_path_fees();
 171                                 }
 172                         }
 173                 }
 174                 remove_res
 175         }
 176
 177         pub(super) fn insert(&mut self, session_priv: [u8; 32], path: &Vec<RouteHop>) -> bool {
 178                 let insert_res = match self {
 179                         PendingOutboundPayment::Legacy { session_privs } |
 180                                 PendingOutboundPayment::Retryable { session_privs, .. } => {
 181                                         session_privs.insert(session_priv)
 182                                 }
 183                         PendingOutboundPayment::Fulfilled { .. } => false,
 184                         PendingOutboundPayment::Abandoned { .. } => false,
 185                 };
 186                 if insert_res {
 187                         if let PendingOutboundPayment::Retryable { ref mut pending_amt_msat, ref mut pending_fee_msat, .. } = self {
 188                                 let path_last_hop = path.last().expect("Outbound payments must have had a valid path");
 189                                 *pending_amt_msat += path_last_hop.fee_msat;
 190                                 if let Some(fee_msat) = pending_fee_msat.as_mut() {
 191                                         *fee_msat += path.get_path_fees();
 192                                 }
 193                         }
 194                 }
 195                 insert_res
 196         }
 197
 198         pub(super) fn remaining_parts(&self) -> usize {
 199                 match self {
 200                         PendingOutboundPayment::Legacy { session_privs } |
 201                                 PendingOutboundPayment::Retryable { session_privs, .. } |
 202                                 PendingOutboundPayment::Fulfilled { session_privs, .. } |
 203                                 PendingOutboundPayment::Abandoned { session_privs, .. } => {
 204                                         session_privs.len()
 205                                 }
 206                 }
 207         }
 208 }
 209
 210 /// Strategies available to retry payment path failures.
 211 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 212 pub enum Retry {
 213         /// Max number of attempts to retry payment.
 214         ///
 215         /// Note that this is the number of *path* failures, not full payment retries. For multi-path
 216         /// payments, if this is less than the total number of paths, we will never even retry all of the
 217         /// payment's paths.
 218         Attempts(usize),
 219         #[cfg(not(feature = "no-std"))]
 220         /// Time elapsed before abandoning retries for a payment.
 221         Timeout(core::time::Duration),
 222 }
 223
 224 impl Retry {
 225         pub(crate) fn is_retryable_now(&self, attempts: &PaymentAttempts) -> bool {
 226                 match (self, attempts) {
 227                         (Retry::Attempts(max_retry_count), PaymentAttempts { count, .. }) => {
 228                                 max_retry_count > count
 229                         },
 230                         #[cfg(all(not(feature = "no-std"), not(test)))]
 231                         (Retry::Timeout(max_duration), PaymentAttempts { first_attempted_at, .. }) =>
 232                                 *max_duration >= std::time::Instant::now().duration_since(*first_attempted_at),
 233                         #[cfg(all(not(feature = "no-std"), test))]
 234                         (Retry::Timeout(max_duration), PaymentAttempts { first_attempted_at, .. }) =>
 235                                 *max_duration >= SinceEpoch::now().duration_since(*first_attempted_at),
 236                 }
 237         }
 238 }
 239
 240 pub(crate) type PaymentAttempts = PaymentAttemptsUsingTime<ConfiguredTime>;
 241
 242 /// Storing minimal payment attempts information required for determining if a outbound payment can
 243 /// be retried.
 244 pub(crate) struct PaymentAttemptsUsingTime<T: Time> {
 245         /// This count will be incremented only after the result of the attempt is known. When it's 0,
 246         /// it means the result of the first attempt is not known yet.
 247         pub(crate) count: usize,
 248         /// This field is only used when retry is `Retry::Timeout` which is only build with feature std
 249         first_attempted_at: T
 250 }
 251
 252 #[cfg(not(any(feature = "no-std", test)))]
 253 type ConfiguredTime = std::time::Instant;
 254 #[cfg(feature = "no-std")]
 255 type ConfiguredTime = crate::util::time::Eternity;
 256 #[cfg(all(not(feature = "no-std"), test))]
 257 type ConfiguredTime = SinceEpoch;
 258
 259 impl<T: Time> PaymentAttemptsUsingTime<T> {
 260         pub(crate) fn new() -> Self {
 261                 PaymentAttemptsUsingTime {
 262                         count: 0,
 263                         first_attempted_at: T::now()
 264                 }
 265         }
 266 }
 267
 268 impl<T: Time> Display for PaymentAttemptsUsingTime<T> {
 269         fn fmt(&self, f: &mut Formatter) -> Result<(), fmt::Error> {
 270                 #[cfg(feature = "no-std")]
 271                 return write!(f, "attempts: {}", self.count);
 272                 #[cfg(not(feature = "no-std"))]
 273                 return write!(
 274                         f,
 275                         "attempts: {}, duration: {}s",
 276                         self.count,
 277                         T::now().duration_since(self.first_attempted_at).as_secs()
 278                 );
 279         }
 280 }
 281
 282 /// If a payment fails to send, it can be in one of several states. This enum is returned as the
 283 /// Err() type describing which state the payment is in, see the description of individual enum
 284 /// states for more.
 285 #[derive(Clone, Debug)]
 286 pub enum PaymentSendFailure {
 287         /// A parameter which was passed to send_payment was invalid, preventing us from attempting to
 288         /// send the payment at all.
 289         ///
 290         /// You can freely resend the payment in full (with the parameter error fixed).
 291         ///
 292         /// Because the payment failed outright, no payment tracking is done, you do not need to call
 293         /// [`ChannelManager::abandon_payment`] and [`ChannelManager::retry_payment`] will *not* work
 294         /// for this payment.
 295         ///
 296         /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
 297         /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment
 298         ParameterError(APIError),
 299         /// A parameter in a single path which was passed to send_payment was invalid, preventing us
 300         /// from attempting to send the payment at all.
 301         ///
 302         /// You can freely resend the payment in full (with the parameter error fixed).
 303         ///
 304         /// The results here are ordered the same as the paths in the route object which was passed to
 305         /// send_payment.
 306         ///
 307         /// Because the payment failed outright, no payment tracking is done, you do not need to call
 308         /// [`ChannelManager::abandon_payment`] and [`ChannelManager::retry_payment`] will *not* work
 309         /// for this payment.
 310         ///
 311         /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
 312         /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment
 313         PathParameterError(Vec<Result<(), APIError>>),
 314         /// All paths which were attempted failed to send, with no channel state change taking place.
 315         /// You can freely resend the payment in full (though you probably want to do so over different
 316         /// paths than the ones selected).
 317         ///
 318         /// Because the payment failed outright, no payment tracking is done, you do not need to call
 319         /// [`ChannelManager::abandon_payment`] and [`ChannelManager::retry_payment`] will *not* work
 320         /// for this payment.
 321         ///
 322         /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
 323         /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment
 324         AllFailedResendSafe(Vec<APIError>),
 325         /// Indicates that a payment for the provided [`PaymentId`] is already in-flight and has not
 326         /// yet completed (i.e. generated an [`Event::PaymentSent`]) or been abandoned (via
 327         /// [`ChannelManager::abandon_payment`]).
 328         ///
 329         /// [`PaymentId`]: crate::ln::channelmanager::PaymentId
 330         /// [`Event::PaymentSent`]: crate::util::events::Event::PaymentSent
 331         /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
 332         DuplicatePayment,
 333         /// Some paths which were attempted failed to send, though possibly not all. At least some
 334         /// paths have irrevocably committed to the HTLC and retrying the payment in full would result
 335         /// in over-/re-payment.
 336         ///
 337         /// The results here are ordered the same as the paths in the route object which was passed to
 338         /// send_payment, and any `Err`s which are not [`APIError::MonitorUpdateInProgress`] can be
 339         /// safely retried via [`ChannelManager::retry_payment`].
 340         ///
 341         /// Any entries which contain `Err(APIError::MonitorUpdateInprogress)` or `Ok(())` MUST NOT be
 342         /// retried as they will result in over-/re-payment. These HTLCs all either successfully sent
 343         /// (in the case of `Ok(())`) or will send once a [`MonitorEvent::Completed`] is provided for
 344         /// the next-hop channel with the latest update_id.
 345         ///
 346         /// [`ChannelManager::retry_payment`]: crate::ln::channelmanager::ChannelManager::retry_payment
 347         /// [`MonitorEvent::Completed`]: crate::chain::channelmonitor::MonitorEvent::Completed
 348         PartialFailure {
 349                 /// The errors themselves, in the same order as the route hops.
 350                 results: Vec<Result<(), APIError>>,
 351                 /// If some paths failed without irrevocably committing to the new HTLC(s), this will
 352                 /// contain a [`RouteParameters`] object which can be used to calculate a new route that
 353                 /// will pay all remaining unpaid balance.
 354                 failed_paths_retry: Option<RouteParameters>,
 355                 /// The payment id for the payment, which is now at least partially pending.
 356                 payment_id: PaymentId,
 357         },
 358 }
 359
 360 pub(super) struct OutboundPayments {
 361         pub(super) pending_outbound_payments: Mutex<HashMap<PaymentId, PendingOutboundPayment>>,
 362 }
 363
 364 impl OutboundPayments {
 365         pub(super) fn new() -> Self {
 366                 Self {
 367                         pending_outbound_payments: Mutex::new(HashMap::new())
 368                 }
 369         }
 370
 371         pub(super) fn send_payment_with_route<ES: Deref, NS: Deref, F>(
 372                 &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>,
 373                 payment_id: PaymentId, entropy_source: &ES, node_signer: &NS, best_block_height: u32,
 374                 send_payment_along_path: F
 375         ) -> Result<(), PaymentSendFailure>
 376         where
 377                 ES::Target: EntropySource,
 378                 NS::Target: NodeSigner,
 379                 F: Fn(&Vec<RouteHop>, &Option<PaymentParameters>, &PaymentHash, &Option<PaymentSecret>, u64,
 380                    u32, PaymentId, &Option<PaymentPreimage>, [u8; 32]) -> Result<(), APIError>
 381         {
 382                 let onion_session_privs = self.add_new_pending_payment(payment_hash, *payment_secret, payment_id, route, Retry::Attempts(0), None, entropy_source, best_block_height)?;
 383                 self.send_payment_internal(route, payment_hash, payment_secret, None, payment_id, None,
 384                         onion_session_privs, node_signer, best_block_height, send_payment_along_path)
 385                         .map_err(|e| { self.remove_outbound_if_all_failed(payment_id, &e); e })
 386         }
 387
 388         pub(super) fn send_spontaneous_payment<ES: Deref, NS: Deref, F>(
 389                 &self, route: &Route, payment_preimage: Option<PaymentPreimage>, payment_id: PaymentId,
 390                 entropy_source: &ES, node_signer: &NS, best_block_height: u32, send_payment_along_path: F
 391         ) -> Result<PaymentHash, PaymentSendFailure>
 392         where
 393                 ES::Target: EntropySource,
 394                 NS::Target: NodeSigner,
 395                 F: Fn(&Vec<RouteHop>, &Option<PaymentParameters>, &PaymentHash, &Option<PaymentSecret>, u64,
 396                    u32, PaymentId, &Option<PaymentPreimage>, [u8; 32]) -> Result<(), APIError>
 397         {
 398                 let preimage = match payment_preimage {
 399                         Some(p) => p,
 400                         None => PaymentPreimage(entropy_source.get_secure_random_bytes()),
 401                 };
 402                 let payment_hash = PaymentHash(Sha256::hash(&preimage.0).into_inner());
 403                 let onion_session_privs = self.add_new_pending_payment(payment_hash, None, payment_id, &route, Retry::Attempts(0), None, entropy_source, best_block_height)?;
 404
 405                 match self.send_payment_internal(route, payment_hash, &None, Some(preimage), payment_id, None, onion_session_privs, node_signer, best_block_height, send_payment_along_path) {
 406                         Ok(()) => Ok(payment_hash),
 407                         Err(e) => {
 408                                 self.remove_outbound_if_all_failed(payment_id, &e);
 409                                 Err(e)
 410                         }
 411                 }
 412         }
 413
 414         pub(super) fn retry_payment_with_route<ES: Deref, NS: Deref, F>(
 415                 &self, route: &Route, payment_id: PaymentId, entropy_source: &ES, node_signer: &NS, best_block_height: u32,
 416                 send_payment_along_path: F
 417         ) -> Result<(), PaymentSendFailure>
 418         where
 419                 ES::Target: EntropySource,
 420                 NS::Target: NodeSigner,
 421                 F: Fn(&Vec<RouteHop>, &Option<PaymentParameters>, &PaymentHash, &Option<PaymentSecret>, u64,
 422                    u32, PaymentId, &Option<PaymentPreimage>, [u8; 32]) -> Result<(), APIError>
 423         {
 424                 const RETRY_OVERFLOW_PERCENTAGE: u64 = 10;
 425                 for path in route.paths.iter() {
 426                         if path.len() == 0 {
 427                                 return Err(PaymentSendFailure::ParameterError(APIError::APIMisuseError {
 428                                         err: "length-0 path in route".to_string()
 429                                 }))
 430                         }
 431                 }
 432
 433                 let mut onion_session_privs = Vec::with_capacity(route.paths.len());
 434                 for _ in 0..route.paths.len() {
 435                         onion_session_privs.push(entropy_source.get_secure_random_bytes());
 436                 }
 437
 438                 let (total_msat, payment_hash, payment_secret) = {
 439                         let mut outbounds = self.pending_outbound_payments.lock().unwrap();
 440                         match outbounds.get_mut(&payment_id) {
 441                                 Some(payment) => {
 442                                         let res = match payment {
 443                                                 PendingOutboundPayment::Retryable {
 444                                                         total_msat, payment_hash, payment_secret, pending_amt_msat, ..
 445                                                 } => {
 446                                                         let retry_amt_msat: u64 = route.paths.iter().map(|path| path.last().unwrap().fee_msat).sum();
 447                                                         if retry_amt_msat + *pending_amt_msat > *total_msat * (100 + RETRY_OVERFLOW_PERCENTAGE) / 100 {
 448                                                                 return Err(PaymentSendFailure::ParameterError(APIError::APIMisuseError {
 449                                                                         err: format!("retry_amt_msat of {} will put pending_amt_msat (currently: {}) more than 10% over total_payment_amt_msat of {}", retry_amt_msat, pending_amt_msat, total_msat).to_string()
 450                                                                 }))
 451                                                         }
 452                                                         (*total_msat, *payment_hash, *payment_secret)
 453                                                 },
 454                                                 PendingOutboundPayment::Legacy { .. } => {
 455                                                         return Err(PaymentSendFailure::ParameterError(APIError::APIMisuseError {
 456                                                                 err: "Unable to retry payments that were initially sent on LDK versions prior to 0.0.102".to_string()
 457                                                         }))
 458                                                 },
 459                                                 PendingOutboundPayment::Fulfilled { .. } => {
 460                                                         return Err(PaymentSendFailure::ParameterError(APIError::APIMisuseError {
 461                                                                 err: "Payment already completed".to_owned()
 462                                                         }));
 463                                                 },
 464                                                 PendingOutboundPayment::Abandoned { .. } => {
 465                                                         return Err(PaymentSendFailure::ParameterError(APIError::APIMisuseError {
 466                                                                 err: "Payment already abandoned (with some HTLCs still pending)".to_owned()
 467                                                         }));
 468                                                 },
 469                                         };
 470                                         for (path, session_priv_bytes) in route.paths.iter().zip(onion_session_privs.iter()) {
 471                                                 assert!(payment.insert(*session_priv_bytes, path));
 472                                         }
 473                                         res
 474                                 },
 475                                 None =>
 476                                         return Err(PaymentSendFailure::ParameterError(APIError::APIMisuseError {
 477                                                 err: format!("Payment with ID {} not found", log_bytes!(payment_id.0)),
 478                                         })),
 479                         }
 480                 };
 481                 self.send_payment_internal(route, payment_hash, &payment_secret, None, payment_id, Some(total_msat), onion_session_privs, node_signer, best_block_height, send_payment_along_path)
 482         }
 483
 484         pub(super) fn send_probe<ES: Deref, NS: Deref, F>(
 485                 &self, hops: Vec<RouteHop>, probing_cookie_secret: [u8; 32], entropy_source: &ES,
 486                 node_signer: &NS, best_block_height: u32, send_payment_along_path: F
 487         ) -> Result<(PaymentHash, PaymentId), PaymentSendFailure>
 488         where
 489                 ES::Target: EntropySource,
 490                 NS::Target: NodeSigner,
 491                 F: Fn(&Vec<RouteHop>, &Option<PaymentParameters>, &PaymentHash, &Option<PaymentSecret>, u64,
 492                    u32, PaymentId, &Option<PaymentPreimage>, [u8; 32]) -> Result<(), APIError>
 493         {
 494                 let payment_id = PaymentId(entropy_source.get_secure_random_bytes());
 495
 496                 let payment_hash = probing_cookie_from_id(&payment_id, probing_cookie_secret);
 497
 498                 if hops.len() < 2 {
 499                         return Err(PaymentSendFailure::ParameterError(APIError::APIMisuseError {
 500                                 err: "No need probing a path with less than two hops".to_string()
 501                         }))
 502                 }
 503
 504                 let route = Route { paths: vec![hops], payment_params: None };
 505                 let onion_session_privs = self.add_new_pending_payment(payment_hash, None, payment_id, &route, Retry::Attempts(0), None, entropy_source, best_block_height)?;
 506
 507                 match self.send_payment_internal(&route, payment_hash, &None, None, payment_id, None, onion_session_privs, node_signer, best_block_height, send_payment_along_path) {
 508                         Ok(()) => Ok((payment_hash, payment_id)),
 509                         Err(e) => {
 510                                 self.remove_outbound_if_all_failed(payment_id, &e);
 511                                 Err(e)
 512                         }
 513                 }
 514         }
 515
 516         #[cfg(test)]
 517         pub(super) fn test_add_new_pending_payment<ES: Deref>(
 518                 &self, payment_hash: PaymentHash, payment_secret: Option<PaymentSecret>, payment_id: PaymentId,
 519                 route: &Route, retry_strategy: Retry, entropy_source: &ES, best_block_height: u32
 520         ) -> Result<Vec<[u8; 32]>, PaymentSendFailure> where ES::Target: EntropySource {
 521                 self.add_new_pending_payment(payment_hash, payment_secret, payment_id, route, retry_strategy, None, entropy_source, best_block_height)
 522         }
 523
 524         pub(super) fn add_new_pending_payment<ES: Deref>(
 525                 &self, payment_hash: PaymentHash, payment_secret: Option<PaymentSecret>, payment_id: PaymentId,
 526                 route: &Route, retry_strategy: Retry, route_params: Option<RouteParameters>,
 527                 entropy_source: &ES, best_block_height: u32
 528         ) -> Result<Vec<[u8; 32]>, PaymentSendFailure> where ES::Target: EntropySource {
 529                 let mut onion_session_privs = Vec::with_capacity(route.paths.len());
 530                 for _ in 0..route.paths.len() {
 531                         onion_session_privs.push(entropy_source.get_secure_random_bytes());
 532                 }
 533
 534                 let mut pending_outbounds = self.pending_outbound_payments.lock().unwrap();
 535                 match pending_outbounds.entry(payment_id) {
 536                         hash_map::Entry::Occupied(_) => Err(PaymentSendFailure::DuplicatePayment),
 537                         hash_map::Entry::Vacant(entry) => {
 538                                 let payment = entry.insert(PendingOutboundPayment::Retryable {
 539                                         retry_strategy,
 540                                         attempts: PaymentAttempts::new(),
 541                                         route_params,
 542                                         session_privs: HashSet::new(),
 543                                         pending_amt_msat: 0,
 544                                         pending_fee_msat: Some(0),
 545                                         payment_hash,
 546                                         payment_secret,
 547                                         starting_block_height: best_block_height,
 548                                         total_msat: route.get_total_amount(),
 549                                 });
 550
 551                                 for (path, session_priv_bytes) in route.paths.iter().zip(onion_session_privs.iter()) {
 552                                         assert!(payment.insert(*session_priv_bytes, path));
 553                                 }
 554
 555                                 Ok(onion_session_privs)
 556                         },
 557                 }
 558         }
 559
 560         fn send_payment_internal<NS: Deref, F>(
 561                 &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>,
 562                 keysend_preimage: Option<PaymentPreimage>, payment_id: PaymentId, recv_value_msat: Option<u64>,
 563                 onion_session_privs: Vec<[u8; 32]>, node_signer: &NS, best_block_height: u32,
 564                 send_payment_along_path: F
 565         ) -> Result<(), PaymentSendFailure>
 566         where
 567                 NS::Target: NodeSigner,
 568                 F: Fn(&Vec<RouteHop>, &Option<PaymentParameters>, &PaymentHash, &Option<PaymentSecret>, u64,
 569                    u32, PaymentId, &Option<PaymentPreimage>, [u8; 32]) -> Result<(), APIError>
 570         {
 571                 if route.paths.len() < 1 {
 572                         return Err(PaymentSendFailure::ParameterError(APIError::InvalidRoute{err: "There must be at least one path to send over"}));
 573                 }
 574                 if payment_secret.is_none() && route.paths.len() > 1 {
 575                         return Err(PaymentSendFailure::ParameterError(APIError::APIMisuseError{err: "Payment secret is required for multi-path payments".to_string()}));
 576                 }
 577                 let mut total_value = 0;
 578                 let our_node_id = node_signer.get_node_id(Recipient::Node).unwrap(); // TODO no unwrap
 579                 let mut path_errs = Vec::with_capacity(route.paths.len());
 580                 'path_check: for path in route.paths.iter() {
 581                         if path.len() < 1 || path.len() > 20 {
 582                                 path_errs.push(Err(APIError::InvalidRoute{err: "Path didn't go anywhere/had bogus size"}));
 583                                 continue 'path_check;
 584                         }
 585                         for (idx, hop) in path.iter().enumerate() {
 586                                 if idx != path.len() - 1 && hop.pubkey == our_node_id {
 587                                         path_errs.push(Err(APIError::InvalidRoute{err: "Path went through us but wasn't a simple rebalance loop to us"}));
 588                                         continue 'path_check;
 589                                 }
 590                         }
 591                         total_value += path.last().unwrap().fee_msat;
 592                         path_errs.push(Ok(()));
 593                 }
 594                 if path_errs.iter().any(|e| e.is_err()) {
 595                         return Err(PaymentSendFailure::PathParameterError(path_errs));
 596                 }
 597                 if let Some(amt_msat) = recv_value_msat {
 598                         debug_assert!(amt_msat >= total_value);
 599                         total_value = amt_msat;
 600                 }
 601
 602                 let cur_height = best_block_height + 1;
 603                 let mut results = Vec::new();
 604                 debug_assert_eq!(route.paths.len(), onion_session_privs.len());
 605                 for (path, session_priv) in route.paths.iter().zip(onion_session_privs.into_iter()) {
 606                         let mut path_res = send_payment_along_path(&path, &route.payment_params, &payment_hash, payment_secret, total_value, cur_height, payment_id, &keysend_preimage, session_priv);
 607                         match path_res {
 608                                 Ok(_) => {},
 609                                 Err(APIError::MonitorUpdateInProgress) => {
 610                                         // While a MonitorUpdateInProgress is an Err(_), the payment is still
 611                                         // considered "in flight" and we shouldn't remove it from the
 612                                         // PendingOutboundPayment set.
 613                                 },
 614                                 Err(_) => {
 615                                         let mut pending_outbounds = self.pending_outbound_payments.lock().unwrap();
 616                                         if let Some(payment) = pending_outbounds.get_mut(&payment_id) {
 617                                                 let removed = payment.remove(&session_priv, Some(path));
 618                                                 debug_assert!(removed, "This can't happen as the payment has an entry for this path added by callers");
 619                                         } else {
 620                                                 debug_assert!(false, "This can't happen as the payment was added by callers");
 621                                                 path_res = Err(APIError::APIMisuseError { err: "Internal error: payment disappeared during processing. Please report this bug!".to_owned() });
 622                                         }
 623                                 }
 624                         }
 625                         results.push(path_res);
 626                 }
 627                 let mut has_ok = false;
 628                 let mut has_err = false;
 629                 let mut pending_amt_unsent = 0;
 630                 let mut max_unsent_cltv_delta = 0;
 631                 for (res, path) in results.iter().zip(route.paths.iter()) {
 632                         if res.is_ok() { has_ok = true; }
 633                         if res.is_err() { has_err = true; }
 634                         if let &Err(APIError::MonitorUpdateInProgress) = res {
 635                                 // MonitorUpdateInProgress is inherently unsafe to retry, so we call it a
 636                                 // PartialFailure.
 637                                 has_err = true;
 638                                 has_ok = true;
 639                         } else if res.is_err() {
 640                                 pending_amt_unsent += path.last().unwrap().fee_msat;
 641                                 max_unsent_cltv_delta = cmp::max(max_unsent_cltv_delta, path.last().unwrap().cltv_expiry_delta);
 642                         }
 643                 }
 644                 if has_err && has_ok {
 645                         Err(PaymentSendFailure::PartialFailure {
 646                                 results,
 647                                 payment_id,
 648                                 failed_paths_retry: if pending_amt_unsent != 0 {
 649                                         if let Some(payment_params) = &route.payment_params {
 650                                                 Some(RouteParameters {
 651                                                         payment_params: payment_params.clone(),
 652                                                         final_value_msat: pending_amt_unsent,
 653                                                         final_cltv_expiry_delta: max_unsent_cltv_delta,
 654                                                 })
 655                                         } else { None }
 656                                 } else { None },
 657                         })
 658                 } else if has_err {
 659                         Err(PaymentSendFailure::AllFailedResendSafe(results.drain(..).map(|r| r.unwrap_err()).collect()))
 660                 } else {
 661                         Ok(())
 662                 }
 663         }
 664
 665         #[cfg(test)]
 666         pub(super) fn test_send_payment_internal<NS: Deref, F>(
 667                 &self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>,
 668                 keysend_preimage: Option<PaymentPreimage>, payment_id: PaymentId, recv_value_msat: Option<u64>,
 669                 onion_session_privs: Vec<[u8; 32]>, node_signer: &NS, best_block_height: u32,
 670                 send_payment_along_path: F
 671         ) -> Result<(), PaymentSendFailure>
 672         where
 673                 NS::Target: NodeSigner,
 674                 F: Fn(&Vec<RouteHop>, &Option<PaymentParameters>, &PaymentHash, &Option<PaymentSecret>, u64,
 675                    u32, PaymentId, &Option<PaymentPreimage>, [u8; 32]) -> Result<(), APIError>
 676         {
 677                 self.send_payment_internal(route, payment_hash, payment_secret, keysend_preimage, payment_id,
 678                         recv_value_msat, onion_session_privs, node_signer, best_block_height,
 679                         send_payment_along_path)
 680                         .map_err(|e| { self.remove_outbound_if_all_failed(payment_id, &e); e })
 681         }
 682
 683         // If we failed to send any paths, we should remove the new PaymentId from the
 684         // `pending_outbound_payments` map, as the user isn't expected to `abandon_payment`.
 685         fn remove_outbound_if_all_failed(&self, payment_id: PaymentId, err: &PaymentSendFailure) {
 686                 if let &PaymentSendFailure::AllFailedResendSafe(_) = err {
 687                         let removed = self.pending_outbound_payments.lock().unwrap().remove(&payment_id).is_some();
 688                         debug_assert!(removed, "We should always have a pending payment to remove here");
 689                 }
 690         }
 691
 692         pub(super) fn claim_htlc<L: Deref>(
 693                 &self, payment_id: PaymentId, payment_preimage: PaymentPreimage, session_priv: SecretKey,
 694                 path: Vec<RouteHop>, from_onchain: bool, pending_events: &Mutex<Vec<events::Event>>, logger: &L
 695         ) where L::Target: Logger {
 696                 let mut session_priv_bytes = [0; 32];
 697                 session_priv_bytes.copy_from_slice(&session_priv[..]);
 698                 let mut outbounds = self.pending_outbound_payments.lock().unwrap();
 699                 let mut pending_events = pending_events.lock().unwrap();
 700                 if let hash_map::Entry::Occupied(mut payment) = outbounds.entry(payment_id) {
 701                         if !payment.get().is_fulfilled() {
 702                                 let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0).into_inner());
 703                                 let fee_paid_msat = payment.get().get_pending_fee_msat();
 704                                 pending_events.push(
 705                                         events::Event::PaymentSent {
 706                                                 payment_id: Some(payment_id),
 707                                                 payment_preimage,
 708                                                 payment_hash,
 709                                                 fee_paid_msat,
 710                                         }
 711                                 );
 712                                 payment.get_mut().mark_fulfilled();
 713                         }
 714
 715                         if from_onchain {
 716                                 // We currently immediately remove HTLCs which were fulfilled on-chain.
 717                                 // This could potentially lead to removing a pending payment too early,
 718                                 // with a reorg of one block causing us to re-add the fulfilled payment on
 719                                 // restart.
 720                                 // TODO: We should have a second monitor event that informs us of payments
 721                                 // irrevocably fulfilled.
 722                                 if payment.get_mut().remove(&session_priv_bytes, Some(&path)) {
 723                                         let payment_hash = Some(PaymentHash(Sha256::hash(&payment_preimage.0).into_inner()));
 724                                         pending_events.push(
 725                                                 events::Event::PaymentPathSuccessful {
 726                                                         payment_id,
 727                                                         payment_hash,
 728                                                         path,
 729                                                 }
 730                                         );
 731                                 }
 732                         }
 733                 } else {
 734                         log_trace!(logger, "Received duplicative fulfill for HTLC with payment_preimage {}", log_bytes!(payment_preimage.0));
 735                 }
 736         }
 737
 738         pub(super) fn finalize_claims(&self, sources: Vec<HTLCSource>, pending_events: &Mutex<Vec<events::Event>>) {
 739                 let mut outbounds = self.pending_outbound_payments.lock().unwrap();
 740                 let mut pending_events = pending_events.lock().unwrap();
 741                 for source in sources {
 742                         if let HTLCSource::OutboundRoute { session_priv, payment_id, path, .. } = source {
 743                                 let mut session_priv_bytes = [0; 32];
 744                                 session_priv_bytes.copy_from_slice(&session_priv[..]);
 745                                 if let hash_map::Entry::Occupied(mut payment) = outbounds.entry(payment_id) {
 746                                         assert!(payment.get().is_fulfilled());
 747                                         if payment.get_mut().remove(&session_priv_bytes, None) {
 748                                                 pending_events.push(
 749                                                         events::Event::PaymentPathSuccessful {
 750                                                                 payment_id,
 751                                                                 payment_hash: payment.get().payment_hash(),
 752                                                                 path,
 753                                                         }
 754                                                 );
 755                                         }
 756                                 }
 757                         }
 758                 }
 759         }
 760
 761         pub(super) fn remove_stale_resolved_payments(&self, pending_events: &Mutex<Vec<events::Event>>) {
 762                 // If an outbound payment was completed, and no pending HTLCs remain, we should remove it
 763                 // from the map. However, if we did that immediately when the last payment HTLC is claimed,
 764                 // this could race the user making a duplicate send_payment call and our idempotency
 765                 // guarantees would be violated. Instead, we wait a few timer ticks to do the actual
 766                 // removal. This should be more than sufficient to ensure the idempotency of any
 767                 // `send_payment` calls that were made at the same time the `PaymentSent` event was being
 768                 // processed.
 769                 let mut pending_outbound_payments = self.pending_outbound_payments.lock().unwrap();
 770                 let pending_events = pending_events.lock().unwrap();
 771                 pending_outbound_payments.retain(|payment_id, payment| {
 772                         if let PendingOutboundPayment::Fulfilled { session_privs, timer_ticks_without_htlcs, .. } = payment {
 773                                 let mut no_remaining_entries = session_privs.is_empty();
 774                                 if no_remaining_entries {
 775                                         for ev in pending_events.iter() {
 776                                                 match ev {
 777                                                         events::Event::PaymentSent { payment_id: Some(ev_payment_id), .. } |
 778                                                                 events::Event::PaymentPathSuccessful { payment_id: ev_payment_id, .. } |
 779                                                                 events::Event::PaymentPathFailed { payment_id: Some(ev_payment_id), .. } => {
 780                                                                         if payment_id == ev_payment_id {
 781                                                                                 no_remaining_entries = false;
 782                                                                                 break;
 783                                                                         }
 784                                                                 },
 785                                                         _ => {},
 786                                                 }
 787                                         }
 788                                 }
 789                                 if no_remaining_entries {
 790                                         *timer_ticks_without_htlcs += 1;
 791                                         *timer_ticks_without_htlcs <= IDEMPOTENCY_TIMEOUT_TICKS
 792                                 } else {
 793                                         *timer_ticks_without_htlcs = 0;
 794                                         true
 795                                 }
 796                         } else { true }
 797                 });
 798         }
 799
 800         pub(super) fn fail_htlc<L: Deref>(
 801                 &self, source: &HTLCSource, payment_hash: &PaymentHash, onion_error: &HTLCFailReason,
 802                 path: &Vec<RouteHop>, session_priv: &SecretKey, payment_id: &PaymentId,
 803                 payment_params: &Option<PaymentParameters>, probing_cookie_secret: [u8; 32],
 804                 secp_ctx: &Secp256k1<secp256k1::All>, pending_events: &Mutex<Vec<events::Event>>, logger: &L
 805         ) where L::Target: Logger {
 806                 #[cfg(test)]
 807                 let (network_update, short_channel_id, payment_retryable, onion_error_code, onion_error_data) = onion_error.decode_onion_failure(secp_ctx, logger, &source);
 808                 #[cfg(not(test))]
 809                 let (network_update, short_channel_id, payment_retryable, _, _) = onion_error.decode_onion_failure(secp_ctx, logger, &source);
 810
 811                 let mut session_priv_bytes = [0; 32];
 812                 session_priv_bytes.copy_from_slice(&session_priv[..]);
 813                 let mut outbounds = self.pending_outbound_payments.lock().unwrap();
 814                 let mut all_paths_failed = false;
 815                 let mut full_failure_ev = None;
 816                 let mut pending_retry_ev = None;
 817                 let attempts_remaining = if let hash_map::Entry::Occupied(mut payment) = outbounds.entry(*payment_id) {
 818                         if !payment.get_mut().remove(&session_priv_bytes, Some(&path)) {
 819                                 log_trace!(logger, "Received duplicative fail for HTLC with payment_hash {}", log_bytes!(payment_hash.0));
 820                                 return
 821                         }
 822                         if payment.get().is_fulfilled() {
 823                                 log_trace!(logger, "Received failure of HTLC with payment_hash {} after payment completion", log_bytes!(payment_hash.0));
 824                                 return
 825                         }
 826                         let is_retryable_now = payment.get().is_retryable_now();
 827                         if let Some(scid) = short_channel_id {
 828                                 payment.get_mut().insert_previously_failed_scid(scid);
 829                         }
 830                         if payment.get().remaining_parts() == 0 {
 831                                 all_paths_failed = true;
 832                                 if payment.get().abandoned() {
 833                                         full_failure_ev = Some(events::Event::PaymentFailed {
 834                                                 payment_id: *payment_id,
 835                                                 payment_hash: payment.get().payment_hash().expect("PendingOutboundPayments::RetriesExceeded always has a payment hash set"),
 836                                         });
 837                                         payment.remove();
 838                                 }
 839                         }
 840                         is_retryable_now
 841                 } else {
 842                         log_trace!(logger, "Received duplicative fail for HTLC with payment_hash {}", log_bytes!(payment_hash.0));
 843                         return
 844                 };
 845                 core::mem::drop(outbounds);
 846                 let mut retry = if let Some(payment_params_data) = payment_params {
 847                         let path_last_hop = path.last().expect("Outbound payments must have had a valid path");
 848                         Some(RouteParameters {
 849                                 payment_params: payment_params_data.clone(),
 850                                 final_value_msat: path_last_hop.fee_msat,
 851                                 final_cltv_expiry_delta: path_last_hop.cltv_expiry_delta,
 852                         })
 853                 } else { None };
 854                 log_trace!(logger, "Failing outbound payment HTLC with payment_hash {}", log_bytes!(payment_hash.0));
 855
 856                 let path_failure = {
 857                         if payment_is_probe(payment_hash, &payment_id, probing_cookie_secret) {
 858                                 if !payment_retryable {
 859                                         events::Event::ProbeSuccessful {
 860                                                 payment_id: *payment_id,
 861                                                 payment_hash: payment_hash.clone(),
 862                                                 path: path.clone(),
 863                                         }
 864                                 } else {
 865                                         events::Event::ProbeFailed {
 866                                                 payment_id: *payment_id,
 867                                                 payment_hash: payment_hash.clone(),
 868                                                 path: path.clone(),
 869                                                 short_channel_id,
 870                                         }
 871                                 }
 872                         } else {
 873                                 // TODO: If we decided to blame ourselves (or one of our channels) in
 874                                 // process_onion_failure we should close that channel as it implies our
 875                                 // next-hop is needlessly blaming us!
 876                                 if let Some(scid) = short_channel_id {
 877                                         retry.as_mut().map(|r| r.payment_params.previously_failed_channels.push(scid));
 878                                 }
 879                                 if payment_retryable && attempts_remaining && retry.is_some() {
 880                                         debug_assert!(full_failure_ev.is_none());
 881                                         pending_retry_ev = Some(events::Event::PendingHTLCsForwardable {
 882                                                 time_forwardable: Duration::from_millis(MIN_HTLC_RELAY_HOLDING_CELL_MILLIS),
 883                                         });
 884                                 }
 885                                 events::Event::PaymentPathFailed {
 886                                         payment_id: Some(*payment_id),
 887                                         payment_hash: payment_hash.clone(),
 888                                         payment_failed_permanently: !payment_retryable,
 889                                         network_update,
 890                                         all_paths_failed,
 891                                         path: path.clone(),
 892                                         short_channel_id,
 893                                         retry,
 894                                         #[cfg(test)]
 895                                         error_code: onion_error_code,
 896                                         #[cfg(test)]
 897                                         error_data: onion_error_data
 898                                 }
 899                         }
 900                 };
 901                 let mut pending_events = pending_events.lock().unwrap();
 902                 pending_events.push(path_failure);
 903                 if let Some(ev) = full_failure_ev { pending_events.push(ev); }
 904                 if let Some(ev) = pending_retry_ev { pending_events.push(ev); }
 905         }
 906
 907         pub(super) fn abandon_payment(&self, payment_id: PaymentId) -> Option<events::Event> {
 908                 let mut failed_ev = None;
 909                 let mut outbounds = self.pending_outbound_payments.lock().unwrap();
 910                 if let hash_map::Entry::Occupied(mut payment) = outbounds.entry(payment_id) {
 911                         if let Ok(()) = payment.get_mut().mark_abandoned() {
 912                                 if payment.get().remaining_parts() == 0 {
 913                                         failed_ev = Some(events::Event::PaymentFailed {
 914                                                 payment_id,
 915                                                 payment_hash: payment.get().payment_hash().expect("PendingOutboundPayments::RetriesExceeded always has a payment hash set"),
 916                                         });
 917                                         payment.remove();
 918                                 }
 919                         }
 920                 }
 921                 failed_ev
 922         }
 923
 924         #[cfg(test)]
 925         pub fn has_pending_payments(&self) -> bool {
 926                 !self.pending_outbound_payments.lock().unwrap().is_empty()
 927         }
 928
 929         #[cfg(test)]
 930         pub fn clear_pending_payments(&self) {
 931                 self.pending_outbound_payments.lock().unwrap().clear()
 932         }
 933 }
 934
 935 /// Returns whether a payment with the given [`PaymentHash`] and [`PaymentId`] is, in fact, a
 936 /// payment probe.
 937 pub(super) fn payment_is_probe(payment_hash: &PaymentHash, payment_id: &PaymentId,
 938         probing_cookie_secret: [u8; 32]) -> bool
 939 {
 940         let target_payment_hash = probing_cookie_from_id(payment_id, probing_cookie_secret);
 941         target_payment_hash == *payment_hash
 942 }
 943
 944 /// Returns the 'probing cookie' for the given [`PaymentId`].
 945 fn probing_cookie_from_id(payment_id: &PaymentId, probing_cookie_secret: [u8; 32]) -> PaymentHash {
 946         let mut preimage = [0u8; 64];
 947         preimage[..32].copy_from_slice(&probing_cookie_secret);
 948         preimage[32..].copy_from_slice(&payment_id.0);
 949         PaymentHash(Sha256::hash(&preimage).into_inner())
 950 }
 951
 952 impl_writeable_tlv_based_enum_upgradable!(PendingOutboundPayment,
 953         (0, Legacy) => {
 954                 (0, session_privs, required),
 955         },
 956         (1, Fulfilled) => {
 957                 (0, session_privs, required),
 958                 (1, payment_hash, option),
 959                 (3, timer_ticks_without_htlcs, (default_value, 0)),
 960         },
 961         (2, Retryable) => {
 962                 (0, session_privs, required),
 963                 (1, pending_fee_msat, option),
 964                 (2, payment_hash, required),
 965                 (not_written, retry_strategy, (static_value, Retry::Attempts(0))),
 966                 (4, payment_secret, option),
 967                 (not_written, attempts, (static_value, PaymentAttempts::new())),
 968                 (6, total_msat, required),
 969                 (not_written, route_params, (static_value, None)),
 970                 (8, pending_amt_msat, required),
 971                 (10, starting_block_height, required),
 972         },
 973         (3, Abandoned) => {
 974                 (0, session_privs, required),
 975                 (2, payment_hash, required),
 976         },
 977 );