Merge pull request #1407 from jkczyz/0.0.106-bindings

[0.0.106-bindings] Restrict ChannelInfo::as_directed_from visibility

Author: TheBlueMatt

lightning-invoice/src/payment.rs

@@ -142,7 +142,7 @@ use crate::prelude::*;
 use lightning::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
 use lightning::ln::channelmanager::{ChannelDetails, PaymentId, PaymentSendFailure};
 use lightning::ln::msgs::LightningError;
-use lightning::routing::scoring::{LockableScore, Score};
+use lightning::routing::scoring::{LockableScore, MultiThreadedLockableScore, Score};
 use lightning::routing::router::{PaymentParameters, Route, RouteParameters};
 use lightning::util::events::{Event, EventHandler};
 use lightning::util::logger::Logger;
@@ -160,16 +160,15 @@ use std::time::SystemTime;
 /// See [module-level documentation] for details.
 ///
 /// [module-level documentation]: crate::payment
-pub struct InvoicePayer<P: Deref, R, S: Deref, L: Deref, E: EventHandler>
+pub struct InvoicePayer<P: Deref, S: Score, R: Deref, SR: Deref<Target = MultiThreadedLockableScore<S>>, L: Deref, E: EventHandler>
 where
 	P::Target: Payer,
-	R: for <'a> Router<<<S as Deref>::Target as LockableScore<'a>>::Locked>,
-	S::Target: for <'a> LockableScore<'a>,
+	R::Target: Router<S>,
 	L::Target: Logger,
 {
 	payer: P,
 	router: R,
-	scorer: S,
+	scorer: SR,
 	logger: L,
 	event_handler: E,
 	/// Caches the overall attempts at making a payment, which is updated prior to retrying.
@@ -230,19 +229,18 @@ pub enum PaymentError {
 	Sending(PaymentSendFailure),
 }
 
-impl<P: Deref, R, S: Deref, L: Deref, E: EventHandler> InvoicePayer<P, R, S, L, E>
+impl<P: Deref, S: Score, R: Deref, SR: Deref<Target = MultiThreadedLockableScore<S>>, L: Deref, E: EventHandler> InvoicePayer<P, S, R, SR, L, E>
 where
 	P::Target: Payer,
-	R: for <'a> Router<<<S as Deref>::Target as LockableScore<'a>>::Locked>,
-	S::Target: for <'a> LockableScore<'a>,
+	R::Target: Router<S>,
 	L::Target: Logger,
 {
 	/// Creates an invoice payer that retries failed payment paths.
 	///
 	/// Will forward any [`Event::PaymentPathFailed`] events to the decorated `event_handler` once
 	/// `retry_attempts` has been exceeded for a given [`Invoice`].
 	pub fn new(
-		payer: P, router: R, scorer: S, logger: L, event_handler: E, retry_attempts: RetryAttempts
+		payer: P, router: R, scorer: SR, logger: L, event_handler: E, retry_attempts: RetryAttempts
 	) -> Self {
 		Self {
 			payer,
@@ -468,11 +466,10 @@ fn has_expired(route_params: &RouteParameters) -> bool {
 	} else { false }
 }
 
-impl<P: Deref, R, S: Deref, L: Deref, E: EventHandler> EventHandler for InvoicePayer<P, R, S, L, E>
+impl<P: Deref, S: Score, R: Deref, SR: Deref<Target = MultiThreadedLockableScore<S>>, L: Deref, E: EventHandler> EventHandler for InvoicePayer<P, S, R, SR, L, E>
 where
 	P::Target: Payer,
-	R: for <'a> Router<<<S as Deref>::Target as LockableScore<'a>>::Locked>,
-	S::Target: for <'a> LockableScore<'a>,
+	R::Target: Router<S>,
 	L::Target: Logger,
 {
 	fn handle_event(&self, event: &Event) {

lightning/src/routing/network_graph.rs

@@ -685,7 +685,7 @@ pub struct ChannelInfo {
 impl ChannelInfo {
 	/// Returns a [`DirectedChannelInfo`] for the channel directed to the given `target` from a
 	/// returned `source`, or `None` if `target` is not one of the channel's counterparties.
-	pub fn as_directed_to(&self, target: &NodeId) -> Option<(DirectedChannelInfo, &NodeId)> {
+	pub(crate) fn as_directed_to(&self, target: &NodeId) -> Option<(DirectedChannelInfo, &NodeId)> {
 		let (direction, source) = {
 			if target == &self.node_one {
 				(self.two_to_one.as_ref(), &self.node_two)
@@ -700,7 +700,7 @@ impl ChannelInfo {
 
 	/// Returns a [`DirectedChannelInfo`] for the channel directed from the given `source` to a
 	/// returned `target`, or `None` if `source` is not one of the channel's counterparties.
-	pub fn as_directed_from(&self, source: &NodeId) -> Option<(DirectedChannelInfo, &NodeId)> {
+	pub(crate) fn as_directed_from(&self, source: &NodeId) -> Option<(DirectedChannelInfo, &NodeId)> {
 		let (direction, target) = {
 			if source == &self.node_one {
 				(self.one_to_two.as_ref(), &self.node_two)

lightning/src/routing/scoring.rs

@@ -230,6 +230,7 @@ impl ReadableArgs<u64> for FixedPenaltyScorer {
 	}
 }
 
+#[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
@@ -247,12 +248,22 @@ impl ReadableArgs<u64> for FixedPenaltyScorer {
 	since = "0.0.105",
 	note = "ProbabilisticScorer should be used instead of Scorer.",
 )]
-pub type Scorer = ScorerUsingTime::<ConfiguredTime>;
-
-#[cfg(not(feature = "no-std"))]
-type ConfiguredTime = std::time::Instant;
+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
@@ -481,6 +492,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
@@ -503,7 +539,7 @@ 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.
 ///