Add a base penalty to ProbabilisticScorer

ProbabilisticScorer tends to prefer longer routes to shorter ones. Make
the default scoring behavior include a customizable base penalty to
avoid longer routes.

Author: jkczyz

lightning/src/routing/scoring.rs

@@ -516,27 +516,32 @@ pub struct ProbabilisticScorerUsingTime<G: Deref<Target = NetworkGraph>, T: Time
 }
 
 /// Parameters for configuring [`ProbabilisticScorer`].
+///
+/// Used to configure a base penalty and a liquidity penalty, the sum of which is the channel
+/// penalty (i.e., the amount in msats willing to be paid to avoid routing through the channel).
 #[derive(Clone, Copy)]
 pub struct ProbabilisticScoringParameters {
-	/// The function calculating the cost of routing an amount through a channel.
+	/// A fixed penalty in msats to apply to each channel.
 	///
-	/// 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: 500 msat
+	pub base_penalty_msat: u64,
+
+	/// The function calculating the cost of routing an amount through a channel.
 	///
-	/// 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`].
+	/// The cost is multiplied by [`liquidity_penalty_multiplier_msat`] to determine the liquidity
+	/// penalty, which is limited to `2 * liquidity_penalty_multiplier_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.
+	/// A multiplier used in conjunction with [`cost_function`] to determine the liquidity 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`.
+	/// The liquidity penalty is effectively limited to `2 * liquidity_penalty_multiplier_msat`.
 	///
 	/// Default value: 10,000 msat
 	///
@@ -633,6 +638,7 @@ impl Default for ProbabilisticScoringParameters {
 			cost_function: ProbabilisticScoringCostFunction::NegativeLogSuccessProbability,
 			liquidity_penalty_multiplier_msat: 10_000,
 			liquidity_offset_half_life: Duration::from_secs(3600),
+			base_penalty_msat: 500,
 		}
 	}
 }
@@ -795,6 +801,7 @@ impl<G: Deref<Target = NetworkGraph>, T: Time> Score for ProbabilisticScorerUsin
 			.unwrap_or(&ChannelLiquidity::new())
 			.as_directed(source, target, capacity_msat, self.params.liquidity_offset_half_life)
 			.penalty_msat(amount_msat, &self.params)
+			.saturating_add(self.params.base_penalty_msat)
 	}
 
 	fn payment_path_failed(&mut self, path: &[&RouteHop], short_channel_id: u64) {
@@ -1775,7 +1782,7 @@ mod tests {
 	fn increased_penalty_nearing_liquidity_upper_bound() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
-			liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
+			base_penalty_msat: 0, liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
 		};
 		let scorer = ProbabilisticScorer::new(params, &network_graph);
 		let source = source_node_id();
@@ -1799,6 +1806,7 @@ mod tests {
 	fn increased_penalty_linearly_nearing_liquidity_upper_bound() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
+			base_penalty_msat: 0,
 			cost_function: ProbabilisticScoringCostFunction::TwiceFailureProbability,
 			liquidity_penalty_multiplier_msat: 1_000,
 			..Default::default()
@@ -1826,7 +1834,7 @@ mod tests {
 		let last_updated = SinceEpoch::now();
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
-			liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
+			base_penalty_msat: 0, liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
 		};
 		let scorer = ProbabilisticScorer::new(params, &network_graph)
 			.with_channel(42,
@@ -1846,7 +1854,7 @@ mod tests {
 	fn does_not_further_penalize_own_channel() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
-			liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
+			base_penalty_msat: 0, liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
 		};
 		let mut scorer = ProbabilisticScorer::new(params, &network_graph);
 		let sender = sender_node_id();
@@ -1867,7 +1875,7 @@ mod tests {
 	fn sets_liquidity_lower_bound_on_downstream_failure() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
-			liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
+			base_penalty_msat: 0, liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
 		};
 		let mut scorer = ProbabilisticScorer::new(params, &network_graph);
 		let source = source_node_id();
@@ -1889,7 +1897,7 @@ mod tests {
 	fn sets_liquidity_upper_bound_on_failure() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
-			liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
+			base_penalty_msat: 0, liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
 		};
 		let mut scorer = ProbabilisticScorer::new(params, &network_graph);
 		let source = source_node_id();
@@ -1911,7 +1919,7 @@ mod tests {
 	fn reduces_liquidity_upper_bound_along_path_on_success() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
-			liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
+			base_penalty_msat: 0, liquidity_penalty_multiplier_msat: 1_000, ..Default::default()
 		};
 		let mut scorer = ProbabilisticScorer::new(params, &network_graph);
 		let sender = sender_node_id();
@@ -1935,6 +1943,7 @@ mod tests {
 	fn decays_liquidity_bounds_over_time() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
+			base_penalty_msat: 0,
 			liquidity_penalty_multiplier_msat: 1_000,
 			liquidity_offset_half_life: Duration::from_secs(10),
 			..Default::default()
@@ -1987,6 +1996,7 @@ mod tests {
 	fn decays_liquidity_bounds_without_shift_overflow() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
+			base_penalty_msat: 0,
 			liquidity_penalty_multiplier_msat: 1_000,
 			liquidity_offset_half_life: Duration::from_secs(10),
 			..Default::default()
@@ -2012,6 +2022,7 @@ mod tests {
 	fn restricts_liquidity_bounds_after_decay() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
+			base_penalty_msat: 0,
 			liquidity_penalty_multiplier_msat: 1_000,
 			liquidity_offset_half_life: Duration::from_secs(10),
 			..Default::default()
@@ -2050,6 +2061,7 @@ mod tests {
 	fn restores_persisted_liquidity_bounds() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
+			base_penalty_msat: 0,
 			liquidity_penalty_multiplier_msat: 1_000,
 			liquidity_offset_half_life: Duration::from_secs(10),
 			..Default::default()
@@ -2080,6 +2092,7 @@ mod tests {
 	fn decays_persisted_liquidity_bounds() {
 		let network_graph = network_graph();
 		let params = ProbabilisticScoringParameters {
+			base_penalty_msat: 0,
 			liquidity_penalty_multiplier_msat: 1_000,
 			liquidity_offset_half_life: Duration::from_secs(10),
 			..Default::default()
@@ -2107,4 +2120,23 @@ mod tests {
 		SinceEpoch::advance(Duration::from_secs(10));
 		assert_eq!(deserialized_scorer.channel_penalty_msat(42, 500, 1_000, &source, &target), 371);
 	}
+
+	#[test]
+	fn adds_base_penalty_to_liquidity_penalty() {
+		let network_graph = network_graph();
+		let source = source_node_id();
+		let target = target_node_id();
+
+		let params = ProbabilisticScoringParameters {
+			base_penalty_msat: 0, ..Default::default()
+		};
+		let scorer = ProbabilisticScorer::new(params, &network_graph);
+		assert_eq!(scorer.channel_penalty_msat(42, 128, 1_024, &source, &target), 585);
+
+		let params = ProbabilisticScoringParameters {
+			base_penalty_msat: 500, ..Default::default()
+		};
+		let scorer = ProbabilisticScorer::new(params, &network_graph);
+		assert_eq!(scorer.channel_penalty_msat(42, 128, 1_024, &source, &target), 1085);
+	}
 }