X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;ds=sidebyside;f=lightning%2Fsrc%2Frouting%2Fscoring.rs;h=578d29858b415ad3697b711d1d27ca72701d7b61;hb=9f1660e25db7e2aed650a3510a6b821bd01452a9;hp=6b399dec663860621c7039dfd64accf56cfff8c1;hpb=5009528df56f3303e22e45131e4ad8e17ef8cc48;p=rust-lightning

diff --git a/lightning/src/routing/scoring.rs b/lightning/src/routing/scoring.rs
index 6b399dec6..578d29858 100644
--- a/lightning/src/routing/scoring.rs
+++ b/lightning/src/routing/scoring.rs
@@ -215,6 +215,7 @@ impl Score for FixedPenaltyScorer {
 	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
@@ -232,9 +233,21 @@ impl Score for FixedPenaltyScorer {
 	since = "0.0.105",
 	note = "ProbabilisticScorer should be used instead of Scorer.",
 )]
-#[cfg(not(feature = "no-std"))]
 pub type Scorer = ScorerUsingTime::<std::time::Instant>;
 #[cfg(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
+/// 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
@@ -463,6 +476,7 @@ 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
@@ -485,9 +499,30 @@ impl<T: Time> Readable for ChannelFailure<T> {
 /// behavior.
 ///
 /// [1]: https://arxiv.org/abs/2107.05322
-#[cfg(not(feature = "no-std"))]
 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
+/// 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, time::Eternity>;
 
 /// Probabilistic [`Score`] implementation.
@@ -809,11 +844,8 @@ impl<G: Deref<Target = NetworkGraph>, T: Time> Writeable for ProbabilisticScorer
 	}
 }
 
-impl<G, T> ReadableArgs<(ProbabilisticScoringParameters, G)> for ProbabilisticScorerUsingTime<G, T>
-where
-	G: Deref<Target = NetworkGraph>,
-	T: Time,
-{
+impl<G: Deref<Target = NetworkGraph>, T: Time>
+ReadableArgs<(ProbabilisticScoringParameters, G)> for ProbabilisticScorerUsingTime<G, T> {
 	#[inline]
 	fn read<R: Read>(
 		r: &mut R, args: (ProbabilisticScoringParameters, G)