feat: add ProbeHandle and probe success/failure events

Author: pwltr

.gitignore

@@ -29,6 +29,9 @@ swift.swiftdoc
 *.a
 *.d
 
+# macOS Finder metadata (icon positions, view options)
+.DS_Store
+
 # IDE and local files
 .idea
 .build

bindings/ldk_node.udl

@@ -235,9 +235,9 @@ interface Bolt11Payment {
 	[Throws=NodeError]
 	PaymentId send_using_amount([ByRef]Bolt11Invoice invoice, u64 amount_msat, RouteParametersConfig? route_parameters);
 	[Throws=NodeError]
-	void send_probes([ByRef]Bolt11Invoice invoice, RouteParametersConfig? route_parameters);
+	sequence<ProbeHandle> send_probes([ByRef]Bolt11Invoice invoice, RouteParametersConfig? route_parameters);
 	[Throws=NodeError]
-	void send_probes_using_amount([ByRef]Bolt11Invoice invoice, u64 amount_msat, RouteParametersConfig? route_parameters);
+	sequence<ProbeHandle> send_probes_using_amount([ByRef]Bolt11Invoice invoice, u64 amount_msat, RouteParametersConfig? route_parameters);
 	[Throws=NodeError]
 	void claim_for_hash(PaymentHash payment_hash, u64 claimable_amount_msat, PaymentPreimage preimage);
 	[Throws=NodeError]
@@ -295,7 +295,7 @@ interface SpontaneousPayment {
 	[Throws=NodeError]
 	PaymentId send_with_preimage_and_custom_tlvs(u64 amount_msat, PublicKey node_id, sequence<CustomTlvRecord> custom_tlvs, PaymentPreimage preimage, RouteParametersConfig? route_parameters);
 	[Throws=NodeError]
-	void send_probes(u64 amount_msat, PublicKey node_id);
+	sequence<ProbeHandle> send_probes(u64 amount_msat, PublicKey node_id);
 };
 
 interface OnchainPayment {
@@ -518,6 +518,8 @@ interface Event {
 	PaymentClaimable(PaymentId payment_id, PaymentHash payment_hash, u64 claimable_amount_msat, u32? claim_deadline, sequence<CustomTlvRecord> custom_records);
 	PaymentForwarded(ChannelId prev_channel_id, ChannelId next_channel_id, UserChannelId?
 	prev_user_channel_id, UserChannelId? next_user_channel_id, PublicKey? prev_node_id, PublicKey? next_node_id, u64? total_fee_earned_msat, u64? skimmed_fee_msat, boolean claim_from_onchain_tx, u64? outbound_amount_forwarded_msat);
+	ProbeSuccessful(PaymentId payment_id, PaymentHash payment_hash);
+	ProbeFailed(PaymentId payment_id, PaymentHash payment_hash, u64? short_channel_id);
 	ChannelPending(ChannelId channel_id, UserChannelId user_channel_id, ChannelId former_temporary_channel_id, PublicKey counterparty_node_id, OutPoint funding_txo);
 	ChannelReady(ChannelId channel_id, UserChannelId user_channel_id, PublicKey? counterparty_node_id, OutPoint? funding_txo);
 	ChannelClosed(ChannelId channel_id, UserChannelId user_channel_id, PublicKey? counterparty_node_id, ClosureReason? reason);
@@ -621,6 +623,11 @@ dictionary RouteParametersConfig {
 	u8 max_channel_saturation_power_of_half;
 };
 
+dictionary ProbeHandle {
+	PaymentHash payment_hash;
+	PaymentId payment_id;
+};
+
 dictionary CustomTlvRecord {
 	u64 type_num;
 	sequence<u8> value;

bindings/swift/Sources/LDKNode/LDKNode.swift

@@ -418,6 +418,22 @@ pub enum Event {
 		/// Custom TLV records attached to the payment
 		custom_records: Vec<CustomTlvRecord>,
 	},
+	/// A sent payment probe was successful.
+	ProbeSuccessful {
+		/// A local identifier used to track the probe.
+		payment_id: PaymentId,
+		/// The hash of the probe payment.
+		payment_hash: PaymentHash,
+	},
+	/// A sent payment probe has failed.
+	ProbeFailed {
+		/// A local identifier used to track the probe.
+		payment_id: PaymentId,
+		/// The hash of the probe payment.
+		payment_hash: PaymentHash,
+		/// The channel responsible for the failed probe, if known.
+		short_channel_id: Option<u64>,
+	},
 	/// A channel has been created and is pending confirmation on-chain.
 	ChannelPending {
 		/// The `channel_id` of the channel.
@@ -944,6 +960,15 @@ impl_writeable_tlv_based_enum!(Event,
 		(6, new_total_onchain_balance_sats, required),
 		(8, old_total_lightning_balance_sats, required),
 		(10, new_total_lightning_balance_sats, required),
+	},
+	(18, ProbeSuccessful) => {
+		(0, payment_hash, required),
+		(2, payment_id, required),
+	},
+	(19, ProbeFailed) => {
+		(0, payment_hash, required),
+		(1, short_channel_id, option),
+		(3, payment_id, required),
 	}
 );
 
@@ -1779,8 +1804,26 @@ where
 
 			LdkEvent::PaymentPathSuccessful { .. } => {},
 			LdkEvent::PaymentPathFailed { .. } => {},
-			LdkEvent::ProbeSuccessful { .. } => {},
-			LdkEvent::ProbeFailed { .. } => {},
+			LdkEvent::ProbeSuccessful { payment_id, payment_hash, .. } => {
+				let event = Event::ProbeSuccessful { payment_id, payment_hash };
+				match self.event_queue.add_event(event).await {
+					Ok(_) => {},
+					Err(e) => {
+						log_error!(self.logger, "Failed to push probe event: {}", e);
+						return Err(ReplayEvent());
+					},
+				}
+			},
+			LdkEvent::ProbeFailed { payment_id, payment_hash, short_channel_id, .. } => {
+				let event = Event::ProbeFailed { payment_id, payment_hash, short_channel_id };
+				match self.event_queue.add_event(event).await {
+					Ok(_) => {},
+					Err(e) => {
+						log_error!(self.logger, "Failed to push probe event: {}", e);
+						return Err(ReplayEvent());
+					},
+				}
+			},
 			LdkEvent::HTLCHandlingFailed { failure_type, .. } => {
 				if let Some(liquidity_source) = self.liquidity_source.as_ref() {
 					liquidity_source.handle_htlc_handling_failed(failure_type).await;
@@ -2573,4 +2616,40 @@ mod tests {
 		}
 		assert_eq!(event_queue.next_event(), None);
 	}
+
+	#[tokio::test]
+	async fn probe_events_persistence_roundtrip() {
+		let store: Arc<DynStore> = Arc::new(InMemoryStore::new());
+		let logger = Arc::new(TestLogger::new());
+		let event_queue = Arc::new(EventQueue::new(Arc::clone(&store), Arc::clone(&logger)));
+
+		assert_eq!(event_queue.next_event(), None);
+
+		let payment_hash = PaymentHash([7u8; 32]);
+		let payment_id = PaymentId(payment_hash.0);
+		let expected_event =
+			Event::ProbeFailed { payment_id, payment_hash, short_channel_id: Some(42) };
+
+		event_queue.add_event(expected_event.clone()).await.unwrap();
+
+		// Check we get the expected event and that it is returned until handled.
+		assert_eq!(event_queue.next_event_async().await, expected_event);
+		assert_eq!(event_queue.next_event(), Some(expected_event.clone()));
+
+		// Check we can read back what we persisted.
+		let persisted_bytes = KVStore::read(
+			&*store,
+			EVENT_QUEUE_PERSISTENCE_PRIMARY_NAMESPACE,
+			EVENT_QUEUE_PERSISTENCE_SECONDARY_NAMESPACE,
+			EVENT_QUEUE_PERSISTENCE_KEY,
+		)
+		.await
+		.unwrap();
+		let deser_event_queue =
+			EventQueue::read(&mut &persisted_bytes[..], (Arc::clone(&store), logger)).unwrap();
+		assert_eq!(deser_event_queue.next_event_async().await, expected_event);
+
+		event_queue.event_handled().await.unwrap();
+		assert_eq!(event_queue.next_event(), None);
+	}
 }

src/event.rs

@@ -96,6 +96,7 @@ pub mod logger;
 mod message_handler;
 pub mod payment;
 mod peer_store;
+mod probe_handle;
 mod runtime;
 mod scoring;
 mod tx_broadcaster;
@@ -161,6 +162,7 @@ use payment::{
 	UnifiedQrPayment,
 };
 use peer_store::{PeerInfo, PeerStore};
+pub use probe_handle::ProbeHandle;
 use rand::Rng;
 use runtime::Runtime;
 use types::{

src/lib.rs

@@ -38,6 +38,7 @@ use crate::payment::store::{
 use crate::peer_store::{PeerInfo, PeerStore};
 use crate::runtime::Runtime;
 use crate::types::{ChannelManager, PaymentStore, Router};
+use crate::ProbeHandle;
 #[cfg(not(feature = "uniffi"))]
 type Bolt11Invoice = LdkBolt11Invoice;
 #[cfg(feature = "uniffi")]
@@ -834,9 +835,13 @@ impl Bolt11Payment {
 	///
 	/// If `route_parameters` are provided they will override the default as well as the
 	/// node-wide parameters configured via [`Config::route_parameters`] on a per-field basis.
+	///
+	/// Returns one [`ProbeHandle`] per probe path. Use [`ProbeHandle::payment_id`] (and/or
+	/// [`ProbeHandle::payment_hash`]) to match [`crate::Event::ProbeSuccessful`] /
+	/// [`crate::Event::ProbeFailed`]. These values are **not** the invoice payment hash.
 	pub fn send_probes(
 		&self, invoice: &Bolt11Invoice, route_parameters: Option<RouteParametersConfig>,
-	) -> Result<(), Error> {
+	) -> Result<Vec<ProbeHandle>, Error> {
 		if !*self.is_running.read().unwrap() {
 			return Err(Error::NotRunning);
 		}
@@ -870,12 +875,16 @@ impl Bolt11Payment {
 
 		self.channel_manager
 			.send_preflight_probes(route_params, liquidity_limit_multiplier)
+			.map(|pairs| {
+				pairs
+					.into_iter()
+					.map(|(payment_hash, payment_id)| ProbeHandle { payment_hash, payment_id })
+					.collect()
+			})
 			.map_err(|e| {
 				log_error!(self.logger, "Failed to send payment probes: {:?}", e);
 				Error::ProbeSendingFailed
-			})?;
-
-		Ok(())
+			})
 	}
 
 	/// Sends payment probes over all paths of a route that would be used to pay the given
@@ -887,11 +896,11 @@ impl Bolt11Payment {
 	/// If `route_parameters` are provided they will override the default as well as the
 	/// node-wide parameters configured via [`Config::route_parameters`] on a per-field basis.
 	///
-	/// See [`Self::send_probes`] for more information.
+	/// See [`Self::send_probes`] for return value semantics and correlation with probe events.
 	pub fn send_probes_using_amount(
 		&self, invoice: &Bolt11Invoice, amount_msat: u64,
 		route_parameters: Option<RouteParametersConfig>,
-	) -> Result<(), Error> {
+	) -> Result<Vec<ProbeHandle>, Error> {
 		if !*self.is_running.read().unwrap() {
 			return Err(Error::NotRunning);
 		}
@@ -932,12 +941,16 @@ impl Bolt11Payment {
 
 		self.channel_manager
 			.send_preflight_probes(route_params, liquidity_limit_multiplier)
+			.map(|pairs| {
+				pairs
+					.into_iter()
+					.map(|(payment_hash, payment_id)| ProbeHandle { payment_hash, payment_id })
+					.collect()
+			})
 			.map_err(|e| {
 				log_error!(self.logger, "Failed to send payment probes: {:?}", e);
 				Error::ProbeSendingFailed
-			})?;
-
-		Ok(())
+			})
 	}
 
 	/// Estimates the routing fees for a given invoice.

src/payment/bolt11.rs

@@ -20,6 +20,7 @@ use crate::error::Error;
 use crate::logger::{log_error, log_info, LdkLogger, Logger};
 use crate::payment::store::{PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus};
 use crate::types::{ChannelManager, CustomTlvRecord, KeysManager, PaymentStore};
+use crate::ProbeHandle;
 
 // The default `final_cltv_expiry_delta` we apply when not set.
 const LDK_DEFAULT_FINAL_CLTV_EXPIRY_DELTA: u32 = 144;
@@ -191,10 +192,13 @@ impl SpontaneousPayment {
 	/// Sends payment probes over all paths of a route that would be used to pay the given
 	/// amount to the given `node_id`.
 	///
-	/// See [`Bolt11Payment::send_probes`] for more information.
+	/// See [`Bolt11Payment::send_probes`] for semantics and how returned [`ProbeHandle`] values
+	/// correlate with [`crate::Event::ProbeSuccessful`] / [`crate::Event::ProbeFailed`].
 	///
 	/// [`Bolt11Payment::send_probes`]: crate::payment::Bolt11Payment
-	pub fn send_probes(&self, amount_msat: u64, node_id: PublicKey) -> Result<(), Error> {
+	pub fn send_probes(
+		&self, amount_msat: u64, node_id: PublicKey,
+	) -> Result<Vec<ProbeHandle>, Error> {
 		if !*self.is_running.read().unwrap() {
 			return Err(Error::NotRunning);
 		}
@@ -208,11 +212,15 @@ impl SpontaneousPayment {
 				LDK_DEFAULT_FINAL_CLTV_EXPIRY_DELTA,
 				liquidity_limit_multiplier,
 			)
+			.map(|pairs| {
+				pairs
+					.into_iter()
+					.map(|(payment_hash, payment_id)| ProbeHandle { payment_hash, payment_id })
+					.collect()
+			})
 			.map_err(|e| {
 				log_error!(self.logger, "Failed to send payment probes: {:?}", e);
 				Error::ProbeSendingFailed
-			})?;
-
-		Ok(())
+			})
 	}
 }

src/payment/spontaneous.rs

@@ -0,0 +1,29 @@
+// This file is Copyright its original authors, visible in version control history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
+// http://opensource.org/licenses/MIT>, at your option. You may not use this file except in
+// accordance with one or both of these licenses.
+
+//! Handle returned when sending pre-flight probes.
+//!
+//! UniFFI uses `dictionary ProbeHandle` in `bindings/ldk_node.udl`; this module defines the Rust
+//! struct with the same fields. With `feature = "uniffi"`, `lib.rs` must `pub use` this type
+//! **before** `uniffi::include_scaffolding!` so the generated `FfiConverter` impl applies here (same
+//! pattern as [`crate::SpendableUtxo`], [`crate::PeerDetails`], etc.).
+
+use lightning::ln::channelmanager::PaymentId;
+use lightning_types::payment::PaymentHash;
+
+/// Identifies one outbound probe; match against [`crate::Event::ProbeSuccessful`] /
+/// [`crate::Event::ProbeFailed`] using [`Self::payment_id`] and/or [`Self::payment_hash`].
+///
+/// The [`PaymentHash`] is **not** the BOLT11 invoice payment hash; LDK generates a synthetic hash
+/// per probe.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct ProbeHandle {
+	/// Synthetic probe payment hash (not the BOLT11 invoice payment hash).
+	pub payment_hash: PaymentHash,
+	/// Local id for this probe; matches probe [`crate::Event`] variants.
+	pub payment_id: PaymentId,
+}