Option for including an amount penalty

TODO: fill in with details

Author: jkczyz

lightning/src/routing/scoring.rs

@@ -555,6 +555,12 @@ pub struct ProbabilisticScoringParameters {
 	/// When built with the `no-std` feature, time will never elapse. Therefore, the channel
 	/// liquidity knowledge will never decay except when the bounds cross.
 	pub liquidity_offset_half_life: Duration,
+
+	/// Whether an additional penalty should be calculated based on the payment amount in order to
+	/// provide higher penalties for large payments.
+	///
+	/// Default value: false
+	pub include_amount_penalty: bool,
 }
 
 /// Accounting for channel liquidity balance uncertainty.
@@ -608,6 +614,7 @@ impl Default for ProbabilisticScoringParameters {
 			base_penalty_msat: 500,
 			liquidity_penalty_multiplier_msat: 40_000,
 			liquidity_offset_half_life: Duration::from_secs(3600),
+			include_amount_penalty: false,
 		}
 	}
 }
@@ -665,11 +672,17 @@ impl<T: Time> ChannelLiquidity<T> {
 	}
 }
 
+/// Bounds `-log10` to avoid excessive liquidity penalties for payments with low success
+/// probabilities.
+const NEGATIVE_LOG10_UPPER_BOUND: u64 = 2;
+
+/// The divisor used when computing the amount penalty.
+const AMOUNT_PENALTY_DIVISOR: u64 = 1024;
+
 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 {
-		let max_penalty_msat = liquidity_penalty_multiplier_msat.saturating_mul(2);
+	fn penalty_msat(&self, amount_msat: u64, params: ProbabilisticScoringParameters) -> u64 {
 		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 <= min_liquidity_msat {
@@ -681,15 +694,36 @@ impl<L: Deref<Target = u64>, T: Time, U: Deref<Target = T>> DirectedChannelLiqui
 				// Avoid using the failed channel on retry.
 				u64::max_value()
 			} else {
-				max_penalty_msat
+				let negative_log10_times_1024 = NEGATIVE_LOG10_UPPER_BOUND * 1024;
+				self.combined_penalty_msat(amount_msat, negative_log10_times_1024, params)
 			}
 		} else {
 			let numerator = (max_liquidity_msat - amount_msat).saturating_add(1);
 			let denominator = (max_liquidity_msat - min_liquidity_msat).saturating_add(1);
-			let penalty_msat = approx::negative_log10_times_1024(numerator, denominator)
-				.saturating_mul(liquidity_penalty_multiplier_msat) / 1024;
-			// Upper bound the penalty to ensure some channel is selected.
-			penalty_msat.min(max_penalty_msat)
+			let negative_log10_times_1024 =
+				approx::negative_log10_times_1024(numerator, denominator);
+			self.combined_penalty_msat(amount_msat, negative_log10_times_1024, params)
+		}
+	}
+
+	#[inline]
+	fn combined_penalty_msat(
+		&self, amount_msat: u64, negative_log10_times_1024: u64,
+		params: ProbabilisticScoringParameters
+	) -> u64 {
+		// Upper bound the liquidity penalty to ensure some channel is selected.
+		let multiplier_msat = params.liquidity_penalty_multiplier_msat;
+		let max_penalty_msat = multiplier_msat.saturating_mul(NEGATIVE_LOG10_UPPER_BOUND);
+		let penalty_msat = (negative_log10_times_1024.saturating_mul(multiplier_msat) / 1024)
+			.min(max_penalty_msat)
+			.saturating_add(params.base_penalty_msat);
+
+		if params.include_amount_penalty {
+			let amount_penalty = negative_log10_times_1024.saturating_mul(amount_msat) / 1024
+				/ AMOUNT_PENALTY_DIVISOR;
+			penalty_msat.saturating_add(amount_penalty)
+		} else {
+			penalty_msat
 		}
 	}
 
@@ -762,14 +796,12 @@ 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)
-			.saturating_add(self.params.base_penalty_msat)
+			.penalty_msat(amount_msat, self.params)
 	}
 
 	fn payment_path_failed(&mut self, path: &[&RouteHop], short_channel_id: u64) {
@@ -1884,6 +1916,7 @@ mod tests {
 			base_penalty_msat: 0,
 			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 +1969,7 @@ mod tests {
 			base_penalty_msat: 0,
 			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();
@@ -1961,6 +1995,7 @@ mod tests {
 			base_penalty_msat: 0,
 			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 +2034,7 @@ mod tests {
 			base_penalty_msat: 0,
 			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();
@@ -2029,6 +2065,7 @@ mod tests {
 			base_penalty_msat: 0,
 			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();
@@ -2073,6 +2110,29 @@ mod tests {
 		assert_eq!(scorer.channel_penalty_msat(42, 128, 1_024, &source, &target), 558);
 	}
 
+	#[test]
+	fn adds_amount_penalty_to_liquidity_penalty() {
+		let network_graph = network_graph();
+		let source = source_node_id();
+		let target = target_node_id();
+
+		let params = ProbabilisticScoringParameters {
+			liquidity_penalty_multiplier_msat: 1_000,
+			include_amount_penalty: false,
+			..Default::default()
+		};
+		let scorer = ProbabilisticScorer::new(params, &network_graph);
+		assert_eq!(scorer.channel_penalty_msat(42, 512_000, 1_024_000, &source, &target), 800);
+
+		let params = ProbabilisticScoringParameters {
+			liquidity_penalty_multiplier_msat: 1_000,
+			include_amount_penalty: true,
+			..Default::default()
+		};
+		let scorer = ProbabilisticScorer::new(params, &network_graph);
+		assert_eq!(scorer.channel_penalty_msat(42, 512_000, 1_024_000, &source, &target), 950);
+	}
+
 	#[test]
 	fn calculates_log10_without_overflowing_u64_max_value() {
 		let network_graph = network_graph();