Add a InflightHtlcs struct for tracking inflight HTLC information

Allows users to query for liquidity information without needing to know
about the ordering we use to determine the direction a HTLC travels
within a channel.

Author: jurvis

lightning-invoice/src/payment.rs

@@ -48,7 +48,7 @@
 //! # use lightning::util::logger::{Logger, Record};
 //! # use lightning::util::ser::{Writeable, Writer};
 //! # use lightning_invoice::Invoice;
-//! # use lightning_invoice::payment::{InvoicePayer, Payer, Retry, Router};
+//! # use lightning_invoice::payment::{InvoicePayer, Payer, Retry, Router, InflightHtlcs};
 //! # use secp256k1::PublicKey;
 //! # use std::cell::RefCell;
 //! # use std::ops::Deref;
@@ -83,7 +83,7 @@
 //! # impl Router for FakeRouter {
 //! # 	fn find_route(
 //! # 		&self, payer: &PublicKey, params: &RouteParameters, payment_hash: &PaymentHash,
-//! # 		first_hops: Option<&[&ChannelDetails]>, inflight_htlc_map: HashMap<(u64, bool), u64>
+//! # 		first_hops: Option<&[&ChannelDetails]>, _inflight_htlcs: InflightHtlcs
 //! # 	) -> Result<Route, LightningError> { unimplemented!() }
 //! #
 //! #   fn notify_payment_path_failed(&self, path: Vec<&RouteHop>, short_channel_id: u64) {  unimplemented!() }
@@ -278,7 +278,7 @@ pub trait Router {
 	/// Finds a [`Route`] between `payer` and `payee` for a payment with the given values.
 	fn find_route(
 		&self, payer: &PublicKey, route_params: &RouteParameters, payment_hash: &PaymentHash,
-		first_hops: Option<&[&ChannelDetails]>, inflight_htlc_map: HashMap<(u64, bool), u64>
+		first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InflightHtlcs
 	) -> Result<Route, LightningError>;
 	/// Lets the router know that payment through a specific path has failed.
 	fn notify_payment_path_failed(&self, path: Vec<&RouteHop>, short_channel_id: u64);
@@ -455,7 +455,7 @@ where
 		let inflight_htlcs = self.create_inflight_map();
 		let route = self.router.find_route(
 			&payer, &params, &payment_hash, Some(&first_hops.iter().collect::<Vec<_>>()),
-			inflight_htlcs
+			InflightHtlcs::new(Some(inflight_htlcs))
 		).map_err(|e| PaymentError::Routing(e))?;
 
 		match send_payment(&route) {
@@ -560,7 +560,7 @@ where
 
 		let route = self.router.find_route(
 			&payer, &params, &payment_hash, Some(&first_hops.iter().collect::<Vec<_>>()),
-			inflight_htlcs
+			InflightHtlcs::new(Some(inflight_htlcs))
 		);
 
 		if route.is_err() {
@@ -740,6 +740,28 @@ where
 	}
 }
 
+/// Data structure used to track information about inflight HTLCs.
+pub struct InflightHtlcs {
+	/// A map with liquidity value (in msat) keyed by a short channel id and the direction the HTLC
+	/// is traveling in. The direction boolean is determined by checking if the HTLC source's public
+	/// key is less than its destination. See [`InflightHtlcs::used_liquidity_msat`] for more
+	/// details.
+	pub map: HashMap<(u64, bool), u64>
+}
+
+impl InflightHtlcs {
+	/// Creates a new instance with an optional map of liquidity information.
+	pub fn new(map: Option<HashMap<(u64, bool), u64>>) -> Self {
+		InflightHtlcs { map: map.unwrap_or(HashMap::new()) }
+	}
+
+	/// Returns liquidity in msat given the public key of the HTLC source, destination, and short
+	/// channel id.
+	pub fn used_liquidity_msat(&self, source: PublicKey, destination: PublicKey, channel_scid: u64) -> Option<&u64> {
+		self.map.get(&(channel_scid, source < destination))
+	}
+}
+
 #[cfg(test)]
 mod tests {
 	use super::*;
@@ -1817,7 +1839,7 @@ mod tests {
 	impl Router for TestRouter {
 		fn find_route(
 			&self, payer: &PublicKey, route_params: &RouteParameters, _payment_hash: &PaymentHash,
-			_first_hops: Option<&[&ChannelDetails]>, inflight_htlc_map: HashMap<(u64, bool), u64>
+			_first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InflightHtlcs
 		) -> Result<Route, LightningError> {
 			// Simulate calling the Scorer just as you would in find_route
 			let route = Self::route_for_value(route_params.final_value_msat);
@@ -1834,7 +1856,7 @@ mod tests {
 					// Since the path is reversed, the last element in our iteration is the first
 					// hop.
 					let mut locked_scorer = self.scorer.lock();
-					let scorer = AccountForInFlightHtlcs::new(locked_scorer.deref_mut(), inflight_htlc_map.clone());
+					let scorer = AccountForInFlightHtlcs::new(locked_scorer.deref_mut(), inflight_htlcs.map.clone());
 					if idx == path.len() - 1 {
 						scorer.channel_penalty_msat(hop.short_channel_id, &NodeId::from_pubkey(payer), &NodeId::from_pubkey(&hop.pubkey), usage);
 					} else {
@@ -1870,7 +1892,7 @@ mod tests {
 	impl Router for FailingRouter {
 		fn find_route(
 			&self, _payer: &PublicKey, _params: &RouteParameters, _payment_hash: &PaymentHash,
-			_first_hops: Option<&[&ChannelDetails]>, _inflight_htlc_map: HashMap<(u64, bool), u64>
+			_first_hops: Option<&[&ChannelDetails]>, _inflight_htlcs: InflightHtlcs
 		) -> Result<Route, LightningError> {
 			Err(LightningError { err: String::new(), action: ErrorAction::IgnoreError })
 		}
@@ -2132,7 +2154,7 @@ mod tests {
 	impl Router for ManualRouter {
 		fn find_route(
 			&self, _payer: &PublicKey, _params: &RouteParameters, _payment_hash: &PaymentHash,
-			_first_hops: Option<&[&ChannelDetails]>, _inflight_htlc_map: HashMap<(u64, bool), u64>
+			_first_hops: Option<&[&ChannelDetails]>, _inflight_htlcs: InflightHtlcs
 		) -> Result<Route, LightningError> {
 			self.0.borrow_mut().pop_front().unwrap()
 		}

lightning-invoice/src/utils.rs

@@ -1,7 +1,7 @@
 //! Convenient utilities to create an invoice.
 
 use {CreationError, Currency, Invoice, InvoiceBuilder, SignOrCreationError};
-use payment::{Payer, Router};
+use payment::{InflightHtlcs, Payer, Router};
 
 use crate::{prelude::*, Description, InvoiceDescription, Sha256};
 use bech32::ToBase32;
@@ -468,7 +468,7 @@ impl<G: Deref<Target = NetworkGraph<L>>, L: Deref, S: Deref> Router for DefaultR
 {
 	fn find_route(
 		&self, payer: &PublicKey, params: &RouteParameters, _payment_hash: &PaymentHash,
-		first_hops: Option<&[&ChannelDetails]>, inflight_htlc_map: HashMap<(u64, bool), u64>
+		first_hops: Option<&[&ChannelDetails]>, inflight_htlcs: InflightHtlcs
 	) -> Result<Route, LightningError> {
 		let random_seed_bytes = {
 			let mut locked_random_seed_bytes = self.random_seed_bytes.lock().unwrap();
@@ -478,7 +478,7 @@ impl<G: Deref<Target = NetworkGraph<L>>, L: Deref, S: Deref> Router for DefaultR
 
 		find_route(
 			payer, params, &self.network_graph, first_hops, &*self.logger,
-				&AccountForInFlightHtlcs::new(&mut self.scorer.lock(), inflight_htlc_map),
+				&AccountForInFlightHtlcs::new(&mut self.scorer.lock(), inflight_htlcs.map),
 				   &random_seed_bytes
 		)
 	}