Linear cost function ProbabilisticScorer option

Without recent knowledge of channel liquidity balances,
ProbabilisticScorer tends to give low penalties unless the payment
amount is a large portion of a channel's capacity. Provide an option
that gives a linear penalty increase as the success probability
decreases, which may be useful in such scenarios.

Author: jkczyz

lightning/src/routing/scoring.rs

@@ -506,19 +506,29 @@ pub struct ProbabilisticScorerUsingTime<G: Deref<Target = NetworkGraph>, T: Time
 /// Parameters for configuring [`ProbabilisticScorer`].
 #[derive(Clone, Copy)]
 pub struct ProbabilisticScoringParameters {
-	/// A multiplier used to determine the amount in msats willing to be paid to avoid routing
-	/// through a channel, as per multiplying by the negative `log10` of the channel's success
-	/// probability for a payment.
+	/// The function calculating the cost of routing an amount through a channel.
 	///
-	/// The success probability is determined by the effective channel capacity, the payment amount,
-	/// and knowledge learned from prior successful and unsuccessful payments. The lower bound of
-	/// the success probability is 0.01, effectively limiting the penalty to the range
-	/// `0..=2*liquidity_penalty_multiplier_msat`. The knowledge learned is decayed over time based
-	/// on [`liquidity_offset_half_life`].
+	/// The cost is multiplied by [`liquidity_penalty_multiplier_msat`] to determine the channel
+	/// penalty (i.e., the amount msats willing to be paid to avoid routing through the channel).
+	/// Penalties are limited to `2 * liquidity_penalty_multiplier_msat`.
 	///
-	/// Default value: 10,000 msat
+	/// The cost is based in part by the knowledge learned from prior successful and unsuccessful
+	/// payments. This knowledge is decayed over time based on [`liquidity_offset_half_life`].
+	///
+	/// Default value: [`ProbabilisticScoringCostFunction::NegativeLogSuccessProbability`]
 	///
+	/// [`liquidity_penalty_multiplier_msat`]: Self::liquidity_penalty_multiplier_msat
 	/// [`liquidity_offset_half_life`]: Self::liquidity_offset_half_life
+	pub cost_function: ProbabilisticScoringCostFunction,
+
+	/// A multiplier used in conjunction with [`cost_function`] to determine the channel penalty.
+	///
+	/// The channel penalty is the amount in msats willing to be paid to avoid routing through a
+	/// channel. It is effectively limited to `2 * liquidity_penalty_multiplier_msat`.
+	///
+	/// Default value: 10,000 msat
+	///
+	/// [`cost_function`]: Self::cost_function
 	pub liquidity_penalty_multiplier_msat: u64,
 
 	/// The time required to elapse before any knowledge learned about channel liquidity balances is
@@ -537,10 +547,28 @@ pub struct ProbabilisticScoringParameters {
 	pub liquidity_offset_half_life: Duration,
 }
 
-impl_writeable_tlv_based!(ProbabilisticScoringParameters, {
-	(0, liquidity_penalty_multiplier_msat, required),
-	(2, liquidity_offset_half_life, required),
-});
+/// A function calculating the cost of routing an amount through a channel.
+///
+/// Costs are calculated in terms of a payment `success_probability`, which is determined by the
+/// effective channel capacity, the payment amount, and knowledge learned from prior successful and
+/// unsuccessful payments. Some cost functions may instead use the `failure_probability`, which is
+/// simply `1.0 - success_probability`. The `success_probability` has a lower bound of `0.01`.
+#[derive(Clone, Copy)]
+pub enum ProbabilisticScoringCostFunction {
+	/// Uses `-log10(success_probability)`, which slowly increases the cost as `success_probability`
+	/// decreases before rapidly increasing.
+	///
+	/// This effectively linearizes penalties across multiple hops as a result of the log product
+	/// property (i.e., a penalty can be reasoned about in terms of the success probability of an
+	/// entire path). However, this may result in low penalties when the channel liquidity balance
+	/// uncertainty is high as payments are less likely to be close to the bounds (i.e., success
+	/// probability is unlikely to be low).
+	NegativeLogSuccessProbability,
+
+	/// Uses `2 * failure_probability`, which increases the cost linearly as `success_probability`
+	/// decreases.
+	TwiceFailureProbability,
+}
 
 /// Accounting for channel liquidity balance uncertainty.
 ///
@@ -590,6 +618,7 @@ impl<G: Deref<Target = NetworkGraph>, T: Time> ProbabilisticScorerUsingTime<G, T
 impl Default for ProbabilisticScoringParameters {
 	fn default() -> Self {
 		Self {
+			cost_function: ProbabilisticScoringCostFunction::NegativeLogSuccessProbability,
 			liquidity_penalty_multiplier_msat: 10_000,
 			liquidity_offset_half_life: Duration::from_secs(3600),
 		}
@@ -652,21 +681,32 @@ impl<T: Time> ChannelLiquidity<T> {
 impl<L: Deref<Target = u64>, T: Time, U: Deref<Target = T>> DirectedChannelLiquidity<L, T, U> {
 	/// Returns a penalty for routing the given HTLC `amount_msat` through the channel in this
 	/// direction.
-	fn penalty_msat(&self, amount_msat: u64, liquidity_penalty_multiplier_msat: u64) -> u64 {
+	fn penalty_msat(&self, amount_msat: u64, params: &ProbabilisticScoringParameters) -> u64 {
+		let max_penalty_msat = params.liquidity_penalty_multiplier_msat.saturating_mul(2);
 		let max_liquidity_msat = self.max_liquidity_msat();
 		let min_liquidity_msat = core::cmp::min(self.min_liquidity_msat(), max_liquidity_msat);
 		if amount_msat > max_liquidity_msat {
-			u64::max_value()
+			max_penalty_msat
 		} else if amount_msat <= min_liquidity_msat {
 			0
 		} else {
 			let numerator = max_liquidity_msat + 1 - amount_msat;
 			let denominator = max_liquidity_msat + 1 - min_liquidity_msat;
-			approx::negative_log10_times_1024(numerator, denominator)
-				.saturating_mul(liquidity_penalty_multiplier_msat) / 1024
+			match params.cost_function {
+				ProbabilisticScoringCostFunction::NegativeLogSuccessProbability => {
+					let penalty_msat = approx::negative_log10_times_1024(numerator, denominator)
+						.saturating_mul(params.liquidity_penalty_multiplier_msat) / 1024;
+					// Upper bound the penalty to ensure some channel is selected.
+					penalty_msat.min(max_penalty_msat)
+				},
+				ProbabilisticScoringCostFunction::TwiceFailureProbability => {
+					// Avoid floating-point operations by multiplying the coefficient through:
+					// 2 * liquidity_penalty_multiplier_msat * (1 - success_probability)
+					let coefficient = max_penalty_msat;
+					coefficient.saturating_sub(coefficient.saturating_mul(numerator) / denominator)
+				},
+			}
 		}
-		// Upper bound the penalty to ensure some channel is selected.
-		.min(2 * liquidity_penalty_multiplier_msat)
 	}
 
 	/// Returns the lower bound of the channel liquidity balance in this direction.
@@ -738,13 +778,11 @@ impl<G: Deref<Target = NetworkGraph>, T: Time> Score for ProbabilisticScorerUsin
 		&self, short_channel_id: u64, amount_msat: u64, capacity_msat: u64, source: &NodeId,
 		target: &NodeId
 	) -> u64 {
-		let liquidity_penalty_multiplier_msat = self.params.liquidity_penalty_multiplier_msat;
-		let liquidity_offset_half_life = self.params.liquidity_offset_half_life;
 		self.channel_liquidities
 			.get(&short_channel_id)
 			.unwrap_or(&ChannelLiquidity::new())
-			.as_directed(source, target, capacity_msat, liquidity_offset_half_life)
-			.penalty_msat(amount_msat, liquidity_penalty_multiplier_msat)
+			.as_directed(source, target, capacity_msat, self.params.liquidity_offset_half_life)
+			.penalty_msat(amount_msat, &self.params)
 	}
 
 	fn payment_path_failed(&mut self, path: &[&RouteHop], short_channel_id: u64) {
@@ -1053,7 +1091,7 @@ pub(crate) use self::time::Time;
 
 #[cfg(test)]
 mod tests {
-	use super::{ChannelLiquidity, ProbabilisticScoringParameters, ProbabilisticScorerUsingTime, ScoringParameters, ScorerUsingTime, Time};
+	use super::{ChannelLiquidity, ProbabilisticScoringCostFunction, ProbabilisticScoringParameters, ProbabilisticScorerUsingTime, ScoringParameters, ScorerUsingTime, Time};
 	use super::time::Eternity;
 
 	use ln::features::{ChannelFeatures, NodeFeatures};
@@ -1742,6 +1780,32 @@ mod tests {
 		assert_eq!(scorer.channel_penalty_msat(42, 896, 1_024, &source, &target), 903);
 	}
 
+	#[test]
+	fn increased_penalty_linearly_nearing_liquidity_upper_bound() {
+		let network_graph = network_graph();
+		let params = ProbabilisticScoringParameters {
+			cost_function: ProbabilisticScoringCostFunction::TwiceFailureProbability,
+			liquidity_penalty_multiplier_msat: 1_000,
+			..Default::default()
+		};
+		let scorer = ProbabilisticScorer::new(params, &network_graph);
+		let source = source_node_id();
+		let target = target_node_id();
+
+		assert_eq!(scorer.channel_penalty_msat(42, 1_024, 1_024_000, &source, &target), 2);
+		assert_eq!(scorer.channel_penalty_msat(42, 10_240, 1_024_000, &source, &target), 20);
+		assert_eq!(scorer.channel_penalty_msat(42, 102_400, 1_024_000, &source, &target), 200);
+		assert_eq!(scorer.channel_penalty_msat(42, 1_024_000, 1_024_000, &source, &target), 2_000);
+
+		assert_eq!(scorer.channel_penalty_msat(42, 125, 1_000, &source, &target), 250);
+		assert_eq!(scorer.channel_penalty_msat(42, 250, 1_000, &source, &target), 500);
+		assert_eq!(scorer.channel_penalty_msat(42, 375, 1_000, &source, &target), 750);
+		assert_eq!(scorer.channel_penalty_msat(42, 500, 1_000, &source, &target), 1_000);
+		assert_eq!(scorer.channel_penalty_msat(42, 625, 1_000, &source, &target), 1_249);
+		assert_eq!(scorer.channel_penalty_msat(42, 750, 1_000, &source, &target), 1_499);
+		assert_eq!(scorer.channel_penalty_msat(42, 875, 1_000, &source, &target), 1_749);
+	}
+
 	#[test]
 	fn constant_penalty_outside_liquidity_bounds() {
 		let last_updated = SinceEpoch::now();
@@ -1858,6 +1922,7 @@ mod tests {
 		let params = ProbabilisticScoringParameters {
 			liquidity_penalty_multiplier_msat: 1_000,
 			liquidity_offset_half_life: Duration::from_secs(10),
+			..Default::default()
 		};
 		let mut scorer = ProbabilisticScorer::new(params, &network_graph);
 		let source = source_node_id();
@@ -1909,6 +1974,7 @@ mod tests {
 		let params = ProbabilisticScoringParameters {
 			liquidity_penalty_multiplier_msat: 1_000,
 			liquidity_offset_half_life: Duration::from_secs(10),
+			..Default::default()
 		};
 		let mut scorer = ProbabilisticScorer::new(params, &network_graph);
 		let source = source_node_id();
@@ -1933,6 +1999,7 @@ mod tests {
 		let params = ProbabilisticScoringParameters {
 			liquidity_penalty_multiplier_msat: 1_000,
 			liquidity_offset_half_life: Duration::from_secs(10),
+			..Default::default()
 		};
 		let mut scorer = ProbabilisticScorer::new(params, &network_graph);
 		let source = source_node_id();
@@ -1970,6 +2037,7 @@ mod tests {
 		let params = ProbabilisticScoringParameters {
 			liquidity_penalty_multiplier_msat: 1_000,
 			liquidity_offset_half_life: Duration::from_secs(10),
+			..Default::default()
 		};
 		let mut scorer = ProbabilisticScorer::new(params, &network_graph);
 		let source = source_node_id();
@@ -1999,6 +2067,7 @@ mod tests {
 		let params = ProbabilisticScoringParameters {
 			liquidity_penalty_multiplier_msat: 1_000,
 			liquidity_offset_half_life: Duration::from_secs(10),
+			..Default::default()
 		};
 		let mut scorer = ProbabilisticScorer::new(params, &network_graph);
 		let source = source_node_id();