Add preflight probing capabilities

We add a `ChannelManager::send_preflight_probes` method that can be used
to send pre-flight probes given some [`RouteParameters`]. Additionally,
we add convenience methods in for spontaneous probes and send pre-flight
probes for a given invoice.

As pre-flight probes might take up some of the available liquidity, we
here introduce that channels whose available liquidity is less than the
required amount times
`UserConfig::preflight_probing_liquidity_limit_multiplier` won't be used
to send pre-flight probes.

This commit is a more or less a carbon copy of the pre-flight
probing code recently added to LDK Node.

Author: tnull

lightning-invoice/src/payment.rs

@@ -17,7 +17,7 @@ use lightning::chain;
 use lightning::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
 use lightning::sign::{NodeSigner, SignerProvider, EntropySource};
 use lightning::ln::PaymentHash;
-use lightning::ln::channelmanager::{ChannelManager, PaymentId, Retry, RetryableSendFailure, RecipientOnionFields};
+use lightning::ln::channelmanager::{ChannelManager, PaymentId, Retry, RetryableSendFailure, RecipientOnionFields, ProbeSendFailure};
 use lightning::routing::router::{PaymentParameters, RouteParameters, Router};
 use lightning::util::logger::Logger;
 
@@ -163,6 +163,46 @@ fn pay_invoice_using_amount<P: Deref>(
 	payer.send_payment(payment_hash, recipient_onion, payment_id, route_params, retry_strategy)
 }
 
+/// Sends payment probes over all paths of a route that would be used to pay the given invoice.
+///
+/// See [`ChannelManager::send_preflight_probes`] for more information.
+pub fn preflight_probe_invoice<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref>(
+	invoice: &Bolt11Invoice, channelmanager: &ChannelManager<M, T, ES, NS, SP, F, R, L>
+) -> Result<(), PaymentError>
+where
+		M::Target: chain::Watch<<SP::Target as SignerProvider>::Signer>,
+		T::Target: BroadcasterInterface,
+		ES::Target: EntropySource,
+		NS::Target: NodeSigner,
+		SP::Target: SignerProvider,
+		F::Target: FeeEstimator,
+		R::Target: Router,
+		L::Target: Logger,
+{
+	let amount_msat = if let Some(invoice_amount_msat) = invoice.amount_milli_satoshis() {
+		invoice_amount_msat
+	} else {
+		return Err(PaymentError::Invoice("Failed to send probe as no amount was given in the invoice."));
+	};
+
+	let expiry_time = invoice.duration_since_epoch().saturating_add(invoice.expiry_time());
+	let mut payment_params = PaymentParameters::from_node_id(
+		invoice.recover_payee_pub_key(),
+		invoice.min_final_cltv_expiry_delta() as u32,
+		)
+		.with_expiry_time(expiry_time.as_secs())
+		.with_route_hints(invoice.route_hints())
+		.map_err(|_| PaymentError::Invoice("Failed to send probe as given route hints are invalid"))?;
+	if let Some(features) = invoice.features() {
+		payment_params = payment_params
+			.with_bolt11_features(features.clone())
+			.map_err(|_| PaymentError::Invoice("Failed to send probe as given features are invalid"))?;
+	}
+	let route_params = RouteParameters { payment_params, final_value_msat: amount_msat };
+
+	channelmanager.send_preflight_probes(route_params).map_err(PaymentError::ProbeSending)
+}
+
 fn expiry_time_from_unix_epoch(invoice: &Bolt11Invoice) -> Duration {
 	invoice.signed_invoice.raw_invoice.data.timestamp.0 + invoice.expiry_time()
 }
@@ -174,6 +214,8 @@ pub enum PaymentError {
 	Invoice(&'static str),
 	/// An error occurring when sending a payment.
 	Sending(RetryableSendFailure),
+	/// An error occurring when sending a payment probe.
+	ProbeSending(ProbeSendFailure),
 }
 
 /// A trait defining behavior of a [`Bolt11Invoice`] payer.

lightning/src/ln/channelmanager.rs

@@ -77,7 +77,7 @@ use core::time::Duration;
 use core::ops::Deref;
 
 // Re-export this for use in the public API.
-pub use crate::ln::outbound_payment::{PaymentSendFailure, Retry, RetryableSendFailure, RecipientOnionFields};
+pub use crate::ln::outbound_payment::{PaymentSendFailure, ProbeSendFailure, Retry, RetryableSendFailure, RecipientOnionFields};
 use crate::ln::script::ShutdownScript;
 
 // We hold various information about HTLC relay in the HTLC objects in Channel itself:
@@ -3452,6 +3452,88 @@ where
 		outbound_payment::payment_is_probe(payment_hash, payment_id, self.probing_cookie_secret)
 	}
 
+	/// Sends payment probes over all paths of a route that would be used to pay the given
+	/// amount to the given `node_id`.
+	///
+	/// See [`ChannelManager::send_preflight_probes`] for more information.
+	pub fn send_spontaneous_preflight_probes(
+		&self, amount_msat: u64, node_id: PublicKey, cltv_expiry_delta: u32
+	) -> Result<(), ProbeSendFailure> {
+		let payment_params =
+			PaymentParameters::from_node_id(node_id, cltv_expiry_delta);
+
+		let route_params = RouteParameters { payment_params, final_value_msat: amount_msat };
+
+		self.send_preflight_probes(route_params)
+	}
+
+	/// Sends payment probes over all paths of a route that would be used to pay a route found
+	/// according to the given [`RouteParameters`].
+	///
+	/// This may be used to send "pre-flight" probes, i.e., to train our scorer before conducting
+	/// the actual payment. Note this is only useful if there likely is sufficient time for the
+	/// probe to settle before sending out the actual payment, e.g., when waiting for user
+	/// confirmation in a wallet UI.
+	///
+	/// Otherwise, there is a chance the probe could take up some liquidity needed to complete the
+	/// actual payment. Users should therefore be cautious and might avoid sending probes if
+	/// liquidity is scarce and/or they don't expect the probe to return before they send the
+	/// payment. To mitigate this issue, channels with available liquidity less than the required
+	/// amount times [`UserConfig::preflight_probing_liquidity_limit_multiplier`] won't be used to send
+	/// pre-flight probes.
+	pub fn send_preflight_probes(&self, route_params: RouteParameters) -> Result<(), ProbeSendFailure> {
+		let payer = self.get_our_node_id();
+		let usable_channels = self.list_usable_channels();
+		let first_hops = usable_channels.iter().collect::<Vec<_>>();
+		let inflight_htlcs = self.compute_inflight_htlcs();
+
+		let route = self
+			.router
+			.find_route(&payer, &route_params, Some(&first_hops), inflight_htlcs)
+			.map_err(|e| {
+				log_error!(self.logger, "Failed to find path for payment probe: {:?}", e);
+				ProbeSendFailure::RouteNotFound
+			})?;
+
+		let mut used_liquidity_map = HashMap::with_capacity(first_hops.len());
+		for path in route.paths {
+			if path.hops.len() + path.blinded_tail.as_ref().map_or(0, |t| t.hops.len()) < 2 {
+				log_debug!(
+					self.logger,
+					"Skipped sending payment probe over path with less than two hops."
+				);
+				continue;
+			}
+
+			if let Some(first_path_hop) = path.hops.first() {
+				if let Some(first_hop) = first_hops.iter().find(|h| {
+					h.get_outbound_payment_scid() == Some(first_path_hop.short_channel_id)
+				}) {
+					let path_value = path.final_value_msat() + path.fee_msat();
+					let used_liquidity =
+						used_liquidity_map.entry(first_path_hop.short_channel_id).or_insert(0);
+
+					if first_hop.next_outbound_htlc_limit_msat
+						< (*used_liquidity + path_value)
+							* self.default_configuration.preflight_probing_liquidity_limit_multiplier
+					{
+						log_debug!(self.logger, "Skipped sending payment probe to avoid putting channel {} under the liquidity limit.", first_path_hop.short_channel_id);
+						continue;
+					} else {
+						*used_liquidity += path_value;
+					}
+				}
+			}
+
+			self.send_probe(path).map_err(|e| {
+				log_error!(self.logger, "Failed to send pre-flight probe: {:?}", e);
+				ProbeSendFailure::SendingFailed(e)
+			})?;
+		}
+
+		Ok(())
+	}
+
 	/// Handles the generation of a funding transaction, optionally (for tests) with a function
 	/// which checks the correctness of the funding transaction given the associated channel.
 	fn funding_transaction_generated_intern<FundingOutput: Fn(&OutboundV1Channel<SP>, &Transaction) -> Result<OutPoint, APIError>>(

lightning/src/ln/outbound_payment.rs

@@ -336,7 +336,7 @@ pub enum RetryableSendFailure {
 /// is in, see the description of individual enum states for more.
 ///
 /// [`ChannelManager::send_payment_with_route`]: crate::ln::channelmanager::ChannelManager::send_payment_with_route
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub enum PaymentSendFailure {
 	/// A parameter which was passed to send_payment was invalid, preventing us from attempting to
 	/// send the payment at all.
@@ -401,6 +401,18 @@ pub enum PaymentSendFailure {
 	},
 }
 
+/// Indicates that we failed to send a payment probe. Further errors may be surfaced later via
+/// [`Event::ProbeFailed`].
+///
+/// [`Event::ProbeFailed`]: crate::events::Event::ProbeFailed
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ProbeSendFailure {
+	/// We were unable to find a route to the destination.
+	RouteNotFound,
+	/// We failed to send the payment probes.
+	SendingFailed(PaymentSendFailure),
+}
+
 /// Information which is provided, encrypted, to the payment recipient when sending HTLCs.
 ///
 /// This should generally be constructed with data communicated to us from the recipient (via a

lightning/src/util/config.rs

@@ -764,6 +764,17 @@ pub struct UserConfig {
 	///
 	/// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
 	pub accept_mpp_keysend: bool,
+	/// The liquidity factor by which we filter our outgoing channels used for sending pre-flight probes.
+	///
+	/// Channels with available liquidity less than the required amount times this value won't be
+	/// used to send pre-flight probes.
+	///
+	/// See [`ChannelManager::send_preflight_probes`] for more information.
+	///
+	/// Default value: 3
+	///
+	/// [`ChannelManager::send_preflight_probes`]: crate::ln::channelmanager::ChannelManager::send_preflight_probes
+	pub preflight_probing_liquidity_limit_multiplier: u64,
 }
 
 impl Default for UserConfig {
@@ -777,6 +788,7 @@ impl Default for UserConfig {
 			manually_accept_inbound_channels: false,
 			accept_intercept_htlcs: false,
 			accept_mpp_keysend: false,
+			preflight_probing_liquidity_limit_multiplier: 3,
 		}
 	}
 }