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,22 @@ 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.
+	NegativeLogSuccessProbability,
+
+	/// Uses `2 * failure_probability`, which increases the cost linearly as `success_probability`
+	/// decreases.
+	TwiceFailureProbability,
+}
 
 /// Accounting for channel liquidity balance uncertainty.
 ///
@@ -590,6 +612,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,7 +675,8 @@ 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 {
@@ -662,11 +686,21 @@ impl<L: Deref<Target = u64>, T: Time, U: Deref<Target = T>> DirectedChannelLiqui
 		} 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 => {
+					approx::negative_log10_times_1024(numerator, denominator)
+						.saturating_mul(params.liquidity_penalty_multiplier_msat) / 1024
+				},
+				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)
+		.min(max_penalty_msat)
 	}
 
 	/// Returns the lower bound of the channel liquidity balance in this direction.
@@ -738,13 +772,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) {
@@ -1056,7 +1088,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};
@@ -1745,6 +1777,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();
@@ -1861,6 +1919,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();
@@ -1912,6 +1971,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();
@@ -1936,6 +1996,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();
@@ -1973,6 +2034,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();
@@ -2002,6 +2064,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();