Introduce PaymentParameters::max_total_routing_fee_msat

Currently, users have no means to upper-bound the total fees accruing
when finding a route. Here, we add a corresponding field to
`PaymentParameters` which will be used to limit the candidate set during
path finding in the following commits.

Author: tnull

lightning/src/routing/router.rs

@@ -537,6 +537,14 @@ pub struct PaymentParameters {
 	/// Default value: 2
 	pub max_channel_saturation_power_of_half: u8,
 
+	/// The maximum total fees, in millisatoshi, that may accrue during route finding.
+	///
+	/// This limit also applies to the total fees that may arise while retrying partially failed
+	/// payments.
+	///
+	/// Default value: `None`
+	pub max_total_routing_fee_msat: Option<u64>,
+
 	/// A list of SCIDs which this payment was previously attempted over and which caused the
 	/// payment to fail. Future attempts for the same payment shouldn't be relayed through any of
 	/// these SCIDs.
@@ -562,6 +570,7 @@ impl Writeable for PaymentParameters {
 			(7, self.previously_failed_channels, required_vec),
 			(8, *blinded_hints, optional_vec),
 			(9, self.payee.final_cltv_expiry_delta(), option),
+			(11, self.max_total_routing_fee_msat, option),
 		});
 		Ok(())
 	}
@@ -580,6 +589,7 @@ impl ReadableArgs<u32> for PaymentParameters {
 			(7, previously_failed_channels, optional_vec),
 			(8, blinded_route_hints, optional_vec),
 			(9, final_cltv_expiry_delta, (default_value, default_final_cltv_expiry_delta)),
+			(11, max_total_routing_fee_msat, option),
 		});
 		let blinded_route_hints = blinded_route_hints.unwrap_or(vec![]);
 		let payee = if blinded_route_hints.len() != 0 {
@@ -603,6 +613,7 @@ impl ReadableArgs<u32> for PaymentParameters {
 			max_channel_saturation_power_of_half: _init_tlv_based_struct_field!(max_channel_saturation_power_of_half, (default_value, unused)),
 			expiry_time,
 			previously_failed_channels: previously_failed_channels.unwrap_or(Vec::new()),
+			max_total_routing_fee_msat,
 		})
 	}
 }
@@ -621,6 +632,7 @@ impl PaymentParameters {
 			max_path_count: DEFAULT_MAX_PATH_COUNT,
 			max_channel_saturation_power_of_half: DEFAULT_MAX_CHANNEL_SATURATION_POW_HALF,
 			previously_failed_channels: Vec::new(),
+			max_total_routing_fee_msat: None,
 		}
 	}
 
@@ -658,6 +670,7 @@ impl PaymentParameters {
 			max_path_count: DEFAULT_MAX_PATH_COUNT,
 			max_channel_saturation_power_of_half: DEFAULT_MAX_CHANNEL_SATURATION_POW_HALF,
 			previously_failed_channels: Vec::new(),
+			max_total_routing_fee_msat: None,
 		}
 	}
 
@@ -733,6 +746,13 @@ impl PaymentParameters {
 	pub fn with_max_channel_saturation_power_of_half(self, max_channel_saturation_power_of_half: u8) -> Self {
 		Self { max_channel_saturation_power_of_half, ..self }
 	}
+
+	/// Includes a limit for the maximum total routing fees that may accrue during route finding.
+	///
+	/// This is not exported to bindings users since bindings don't support move semantics
+	pub fn with_max_total_routing_fee_msat(self, max_total_routing_fee_msat: u64) -> Self {
+		Self { max_total_routing_fee_msat: Some(max_total_routing_fee_msat), ..self }
+	}
 }
 
 /// The recipient of a payment, differing based on whether they've hidden their identity with route