Expose pending payments through ChannelManager

Adds a new method, `list_recent_payments ` to `ChannelManager` that
returns an array of `RecentPaymentDetails` containing the payment
status (Fulfilled/Retryable/Abandoned) and its total amount across all
paths.

Author: jurvis

lightning/src/ln/channelmanager.rs

@@ -1131,6 +1131,36 @@ impl ChannelDetails {
 	}
 }
 
+/// Used by [`ChannelManager::list_recent_payments`] to express the status of recent payments.
+/// These include payments that have yet to find a successful path, or have unresolved HTLCs.
+#[derive(Debug, PartialEq)]
+pub enum RecentPaymentDetails {
+	/// When a payment is still being sent and awaiting successful delivery.
+	Pending {
+		/// Hash of the payment that is currently being sent but has yet to be fulfilled or
+		/// abandoned.
+		payment_hash: PaymentHash,
+		/// Total amount (in msat) across all paths for this payment, not just the amount currently
+		/// inflight.
+		total_msat: u64,
+	},
+	/// When a pending payment is fulfilled, we continue tracking it until all pending HTLCs have
+	/// been resolved. Upon receiving [`Event::PaymentSent`], we delay for a few minutes before the
+	/// payment is removed from tracking.
+	Fulfilled {
+		/// Hash of the payment that was claimed. `None` for serializations of [`ChannelManager`]
+		/// made before LDK version 0.0.104.
+		payment_hash: Option<PaymentHash>,
+	},
+	/// After a payment is explicitly abandoned by calling [`ChannelManager::abandon_payment`], it
+	/// is marked as abandoned until an [`Event::PaymentFailed`] is generated. A payment could also
+	/// be marked as abandoned if pathfinding fails repeatedly or retries have been exhausted.
+	Abandoned {
+		/// Hash of the payment that we have given up trying to send.
+		payment_hash: PaymentHash,
+	},
+}
+
 /// Route hints used in constructing invoices for [phantom node payents].
 ///
 /// [phantom node payments]: crate::chain::keysinterface::PhantomKeysManager
@@ -1668,6 +1698,32 @@ where
 		self.list_channels_with_filter(|&(_, ref channel)| channel.is_live())
 	}
 
+	/// Returns in an undefined order recent payments that -- if not fulfilled -- have yet to find a
+	/// successful path, or have unresolved HTLCs.
+	///
+	/// This can be useful for figuring out whether or not a payment needs to be retried.
+	/// In general, if it is not listed here, you should consider retrying it if not
+	/// [`RecentPaymentDetails::Fulfilled`].
+	pub fn list_recent_payments(&self) -> Vec<RecentPaymentDetails> {
+		self.pending_outbound_payments.pending_outbound_payments.lock().unwrap().iter()
+			.filter_map(|(_, pending_outbound_payment)| match pending_outbound_payment {
+				PendingOutboundPayment::Retryable { payment_hash, total_msat, .. } => {
+					Some(RecentPaymentDetails::Pending {
+						payment_hash: *payment_hash,
+						total_msat: *total_msat,
+					})
+				},
+				PendingOutboundPayment::Abandoned { payment_hash, .. } => {
+					Some(RecentPaymentDetails::Abandoned { payment_hash: *payment_hash })
+				},
+				PendingOutboundPayment::Fulfilled { payment_hash, .. } => {
+					Some(RecentPaymentDetails::Fulfilled { payment_hash: *payment_hash })
+				},
+				PendingOutboundPayment::Legacy { .. } => None
+			})
+			.collect()
+	}
+
 	/// Helper function that issues the channel close events
 	fn issue_channel_close_events(&self, channel: &Channel<<SP::Target as SignerProvider>::Signer>, closure_reason: ClosureReason) {
 		let mut pending_events_lock = self.pending_events.lock().unwrap();

lightning/src/ln/payment_tests.rs

@@ -16,7 +16,7 @@ use crate::chain::channelmonitor::{ANTI_REORG_DELAY, LATENCY_GRACE_PERIOD_BLOCKS
 use crate::chain::keysinterface::EntropySource;
 use crate::chain::transaction::OutPoint;
 use crate::ln::channel::EXPIRE_PREV_CONFIG_TICKS;
-use crate::ln::channelmanager::{BREAKDOWN_TIMEOUT, ChannelManager, MPP_TIMEOUT_TICKS, MIN_CLTV_EXPIRY_DELTA, PaymentId, PaymentSendFailure, IDEMPOTENCY_TIMEOUT_TICKS};
+use crate::ln::channelmanager::{BREAKDOWN_TIMEOUT, ChannelManager, MPP_TIMEOUT_TICKS, MIN_CLTV_EXPIRY_DELTA, PaymentId, PaymentSendFailure, IDEMPOTENCY_TIMEOUT_TICKS, RecentPaymentDetails};
 use crate::ln::msgs;
 use crate::ln::msgs::ChannelMessageHandler;
 use crate::routing::gossip::RoutingFees;
@@ -1267,7 +1267,11 @@ fn test_trivial_inflight_htlc_tracking(){
 	let (_, _, chan_2_id, _) = create_announced_chan_between_nodes(&nodes, 1, 2);
 
 	// Send and claim the payment. Inflight HTLCs should be empty.
-	send_payment(&nodes[0], &vec!(&nodes[1], &nodes[2])[..], 500000);
+	let (route, payment_hash, payment_preimage, payment_secret) = get_route_and_payment_hash!(nodes[0], nodes[2], 500000);
+	nodes[0].node.send_payment(&route, payment_hash, &Some(payment_secret), PaymentId(payment_hash.0)).unwrap();
+	check_added_monitors!(nodes[0], 1);
+	pass_along_route(&nodes[0], &[&vec!(&nodes[1], &nodes[2])[..]], 500000, payment_hash, payment_secret);
+	claim_payment(&nodes[0], &vec!(&nodes[1], &nodes[2])[..], payment_preimage);
 	{
 		let inflight_htlcs = node_chanmgrs[0].compute_inflight_htlcs();
 
@@ -1291,10 +1295,19 @@ fn test_trivial_inflight_htlc_tracking(){
 
 		assert_eq!(chan_1_used_liquidity, None);
 		assert_eq!(chan_2_used_liquidity, None);
+
+		let pending_payments = nodes[0].node.list_recent_payments();
+		assert_eq!(pending_payments.len(), 1);
+		assert_eq!(pending_payments[0], RecentPaymentDetails::Fulfilled { payment_hash: Some(payment_hash) });
+	}
+
+	// Remove fulfilled payment
+	for _ in 0..=IDEMPOTENCY_TIMEOUT_TICKS {
+		nodes[0].node.timer_tick_occurred();
 	}
 
 	// Send the payment, but do not claim it. Our inflight HTLCs should contain the pending payment.
-	let (payment_preimage, _,  _) = route_payment(&nodes[0], &vec!(&nodes[1], &nodes[2])[..], 500000);
+	let (payment_preimage, payment_hash,  _) = route_payment(&nodes[0], &vec!(&nodes[1], &nodes[2])[..], 500000);
 	{
 		let inflight_htlcs = node_chanmgrs[0].compute_inflight_htlcs();
 
@@ -1319,10 +1332,20 @@ fn test_trivial_inflight_htlc_tracking(){
 		// First hop accounts for expected 1000 msat fee
 		assert_eq!(chan_1_used_liquidity, Some(501000));
 		assert_eq!(chan_2_used_liquidity, Some(500000));
+
+		let pending_payments = nodes[0].node.list_recent_payments();
+		assert_eq!(pending_payments.len(), 1);
+		assert_eq!(pending_payments[0], RecentPaymentDetails::Pending { payment_hash, total_msat: 500000 });
 	}
 
 	// Now, let's claim the payment. This should result in the used liquidity to return `None`.
 	claim_payment(&nodes[0], &[&nodes[1], &nodes[2]], payment_preimage);
+
+	// Remove fulfilled payment
+	for _ in 0..=IDEMPOTENCY_TIMEOUT_TICKS {
+		nodes[0].node.timer_tick_occurred();
+	}
+
 	{
 		let inflight_htlcs = node_chanmgrs[0].compute_inflight_htlcs();
 
@@ -1346,6 +1369,9 @@ fn test_trivial_inflight_htlc_tracking(){
 
 		assert_eq!(chan_1_used_liquidity, None);
 		assert_eq!(chan_2_used_liquidity, None);
+
+		let pending_payments = nodes[0].node.list_recent_payments();
+		assert_eq!(pending_payments.len(), 0);
 	}
 }