_ Git - rust-lightning/blob - lightning/src/routing/mod.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 //! Structs and impls for receiving messages about the network and storing the topology live here.
  11
  12 pub mod network_graph;
  13 pub mod router;
  14 pub mod scorer;
  15
  16 use routing::network_graph::NodeId;
  17 use routing::router::RouteHop;
  18
  19 use core::cell::{RefCell, RefMut};
  20 use core::ops::DerefMut;
  21 use sync::{Mutex, MutexGuard};
  22
  23 /// An interface used to score payment channels for path finding.
  24 ///
  25 ///     Scoring is in terms of fees willing to be paid in order to avoid routing through a channel.
  26 pub trait Score {
  27         /// Returns the fee in msats willing to be paid to avoid routing `send_amt_msat` through the
  28         /// given channel in the direction from `source` to `target`.
  29         ///
  30         /// The channel's capacity (less any other MPP parts which are also being considered for use in
  31         /// the same payment) is given by `channel_capacity_msat`. It may be guessed from various
  32         /// sources or assumed from no data at all.
  33         ///
  34         /// For hints provided in the invoice, we assume the channel has sufficient capacity to accept
  35         /// the invoice's full amount, and provide a `channel_capacity_msat` of `None`. In all other
  36         /// cases it is set to `Some`, even if we're guessing at the channel value.
  37         ///
  38         /// Your code should be overflow-safe through a `channel_capacity_msat` of 21 million BTC.
  39         fn channel_penalty_msat(&self, short_channel_id: u64, send_amt_msat: u64, channel_capacity_msat: Option<u64>, source: &NodeId, target: &NodeId) -> u64;
  40
  41         /// Handles updating channel penalties after failing to route through a channel.
  42         fn payment_path_failed(&mut self, path: &[&RouteHop], short_channel_id: u64);
  43 }
  44
  45 /// A scorer that is accessed under a lock.
  46 ///
  47 /// Needed so that calls to [`Score::channel_penalty_msat`] in [`find_route`] can be made while
  48 /// having shared ownership of a scorer but without requiring internal locking in [`Score`]
  49 /// implementations. Internal locking would be detrimental to route finding performance and could
  50 /// result in [`Score::channel_penalty_msat`] returning a different value for the same channel.
  51 ///
  52 /// [`find_route`]: crate::routing::router::find_route
  53 pub trait LockableScore<'a> {
  54         /// The locked [`Score`] type.
  55         type Locked: 'a + Score;
  56
  57         /// Returns the locked scorer.
  58         fn lock(&'a self) -> Self::Locked;
  59 }
  60
  61 impl<'a, T: 'a + Score> LockableScore<'a> for Mutex<T> {
  62         type Locked = MutexGuard<'a, T>;
  63
  64         fn lock(&'a self) -> MutexGuard<'a, T> {
  65                 Mutex::lock(self).unwrap()
  66         }
  67 }
  68
  69 impl<'a, T: 'a + Score> LockableScore<'a> for RefCell<T> {
  70         type Locked = RefMut<'a, T>;
  71
  72         fn lock(&'a self) -> RefMut<'a, T> {
  73                 self.borrow_mut()
  74         }
  75 }
  76
  77 impl<S: Score, T: DerefMut<Target=S>> Score for T {
  78         fn channel_penalty_msat(&self, short_channel_id: u64, send_amt_msat: u64, channel_capacity_msat: Option<u64>, source: &NodeId, target: &NodeId) -> u64 {
  79                 self.deref().channel_penalty_msat(short_channel_id, send_amt_msat, channel_capacity_msat, source, target)
  80         }
  81
  82         fn payment_path_failed(&mut self, path: &[&RouteHop], short_channel_id: u64) {
  83                 self.deref_mut().payment_path_failed(path, short_channel_id)
  84         }
  85 }