X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Frouting%2Fscoring.rs;h=f0acb82bc77ac45b6b2689a2ae6ff05bfb4311b8;hb=34205af801f321140b90e42d15486415e9cecd0f;hp=9f3b7806a991681259deb4ae8655cc060a730382;hpb=2e730cdc9c4eeec3d514ccbe6cb5976f0d8fa40f;p=rust-lightning

diff --git a/lightning/src/routing/scoring.rs b/lightning/src/routing/scoring.rs
index 9f3b7806a..f0acb82bc 100644
--- a/lightning/src/routing/scoring.rs
+++ b/lightning/src/routing/scoring.rs
@@ -189,6 +189,33 @@ impl<'a, S: Writeable> Writeable for MutexGuard<'a, S> {
 	}
 }
 
+/// [`Score`] implementation that uses a fixed penalty.
+pub struct FixedPenaltyScorer {
+	penalty_msat: u64,
+}
+
+impl_writeable_tlv_based!(FixedPenaltyScorer, {
+	(0, penalty_msat, required),
+});
+
+impl FixedPenaltyScorer {
+	/// Creates a new scorer using `penalty_msat`.
+	pub fn with_penalty(penalty_msat: u64) -> Self {
+		Self { penalty_msat }
+	}
+}
+
+impl Score for FixedPenaltyScorer {
+	fn channel_penalty_msat(&self, _: u64, _: u64, _: u64, _: &NodeId, _: &NodeId) -> u64 {
+		self.penalty_msat
+	}
+
+	fn payment_path_failed(&mut self, _path: &[&RouteHop], _short_channel_id: u64) {}
+
+	fn payment_path_successful(&mut self, _path: &[&RouteHop]) {}
+}
+
+#[cfg(not(feature = "no-std"))]
 /// [`Score`] implementation that provides reasonable default behavior.
 ///
 /// Used to apply a fixed penalty to each channel, thus avoiding long paths when shorter paths with
@@ -202,12 +229,26 @@ impl<'a, S: Writeable> Writeable for MutexGuard<'a, S> {
 /// behavior.
 ///
 /// [module-level documentation]: crate::routing::scoring
-pub type Scorer = ScorerUsingTime::<ConfiguredTime>;
-
-#[cfg(not(feature = "no-std"))]
-type ConfiguredTime = std::time::Instant;
+#[deprecated(
+	since = "0.0.105",
+	note = "ProbabilisticScorer should be used instead of Scorer.",
+)]
+pub type Scorer = ScorerUsingTime::<std::time::Instant>;
 #[cfg(feature = "no-std")]
-type ConfiguredTime = time::Eternity;
+/// [`Score`] implementation that provides reasonable default behavior.
+///
+/// Used to apply a fixed penalty to each channel, thus avoiding long paths when shorter paths with
+/// slightly higher fees are available. Will further penalize channels that fail to relay payments.
+///
+/// See [module-level documentation] for usage and [`ScoringParameters`] for customization.
+///
+/// # Note
+///
+/// Mixing the `no-std` feature between serialization and deserialization results in undefined
+/// behavior.
+///
+/// [module-level documentation]: crate::routing::scoring
+pub type Scorer = ScorerUsingTime::<time::Eternity>;
 
 // Note that ideally we'd hide ScorerUsingTime from public view by sealing it as well, but rustdoc
 // doesn't handle this well - instead exposing a `Scorer` which has no trait implementation(s) or
@@ -216,7 +257,6 @@ type ConfiguredTime = time::Eternity;
 /// [`Score`] implementation.
 ///
 /// (C-not exported) generally all users should use the [`Scorer`] type alias.
-#[doc(hidden)]
 pub struct ScorerUsingTime<T: Time> {
 	params: ScoringParameters,
 	// TODO: Remove entries of closed channels.
@@ -301,18 +341,6 @@ impl<T: Time> ScorerUsingTime<T> {
 			channel_failures: HashMap::new(),
 		}
 	}
-
-	/// Creates a new scorer using `penalty_msat` as a fixed channel penalty.
-	#[cfg(any(test, feature = "fuzztarget", feature = "_test_utils"))]
-	pub fn with_fixed_penalty(penalty_msat: u64) -> Self {
-		Self::new(ScoringParameters {
-			base_penalty_msat: penalty_msat,
-			failure_penalty_msat: 0,
-			failure_penalty_half_life: Duration::from_secs(0),
-			overuse_penalty_start_1024th: 1024,
-			overuse_penalty_msat_per_1024th: 0,
-		})
-	}
 }
 
 impl<T: Time> ChannelFailure<T> {
@@ -448,6 +476,31 @@ impl<T: Time> Readable for ChannelFailure<T> {
 	}
 }
 
+#[cfg(not(feature = "no-std"))]
+/// [`Score`] implementation using channel success probability distributions.
+///
+/// Based on *Optimally Reliable & Cheap Payment Flows on the Lightning Network* by Rene Pickhardt
+/// and Stefan Richter [[1]]. Given the uncertainty of channel liquidity balances, probability
+/// distributions are defined based on knowledge learned from successful and unsuccessful attempts.
+/// Then the negative `log10` of the success probability is used to determine the cost of routing a
+/// specific HTLC amount through a channel.
+///
+/// Knowledge about channel liquidity balances takes the form of upper and lower bounds on the
+/// possible liquidity. Certainty of the bounds is decreased over time using a decay function. See
+/// [`ProbabilisticScoringParameters`] for details.
+///
+/// Since the scorer aims to learn the current channel liquidity balances, it works best for nodes
+/// with high payment volume or that actively probe the [`NetworkGraph`]. Nodes with low payment
+/// volume are more likely to experience failed payment paths, which would need to be retried.
+///
+/// # Note
+///
+/// Mixing the `no-std` feature between serialization and deserialization results in undefined
+/// behavior.
+///
+/// [1]: https://arxiv.org/abs/2107.05322
+pub type ProbabilisticScorer<G> = ProbabilisticScorerUsingTime::<G, std::time::Instant>;
+#[cfg(feature = "no-std")]
 /// [`Score`] implementation using channel success probability distributions.
 ///
 /// Based on *Optimally Reliable & Cheap Payment Flows on the Lightning Network* by Rene Pickhardt
@@ -470,12 +523,11 @@ impl<T: Time> Readable for ChannelFailure<T> {
 /// behavior.
 ///
 /// [1]: https://arxiv.org/abs/2107.05322
-pub type ProbabilisticScorer<G> = ProbabilisticScorerUsingTime::<G, ConfiguredTime>;
+pub type ProbabilisticScorer<G> = ProbabilisticScorerUsingTime::<G, time::Eternity>;
 
 /// Probabilistic [`Score`] implementation.
 ///
 /// (C-not exported) generally all users should use the [`ProbabilisticScorer`] type alias.
-#[doc(hidden)]
 pub struct ProbabilisticScorerUsingTime<G: Deref<Target = NetworkGraph>, T: Time> {
 	params: ProbabilisticScoringParameters,
 	network_graph: G,