Add source and target functions to CandidateRouteHop

    - Make methods public and add docs

Author: jbesraa

lightning/src/routing/gossip.rs

@@ -977,7 +977,8 @@ impl Readable for ChannelInfo {
 /// source node to a target node.
 #[derive(Clone)]
 pub struct DirectedChannelInfo<'a> {
-	channel: &'a ChannelInfo,
+	/// Provides information about a channel between two nodes.
+	pub channel: &'a ChannelInfo,
 	direction: &'a ChannelUpdateInfo,
 	htlc_maximum_msat: u64,
 	effective_capacity: EffectiveCapacity,

lightning/src/routing/router.rs

@@ -978,42 +978,78 @@ impl cmp::PartialOrd for RouteGraphNode {
 ///
 /// Used to construct a [`PathBuildingHop`] and to estimate [`EffectiveCapacity`].
 #[derive(Clone, Debug)]
-enum CandidateRouteHop<'a> {
+pub enum CandidateRouteHop<'a> {
 	/// A hop from the payer, where the outbound liquidity is known.
 	FirstHop {
+		/// The channel details of the first hop.
+		/// `get_outbound_payment_scid` is assumed to always return Some(scid) - this assumption is checked in
+		/// `find_route` method.
 		details: &'a ChannelDetails,
+		/// The node id of the payer.
+		/// Can be accessed via `source` method.
+		node_id: NodeId
 	},
 	/// A hop found in the [`ReadOnlyNetworkGraph`], where the channel capacity may be unknown.
 	PublicHop {
+		/// The channel info of the hop.
 		info: DirectedChannelInfo<'a>,
+		/// The short_channel_id of the channel.
 		short_channel_id: u64,
+		/// The node id of the current hop in route.
+		source_node_id: NodeId,
+		/// The node id of next hop in route.
+		target_node_id: NodeId,
 	},
 	/// A hop to the payee found in the BOLT 11 payment invoice, though not necessarily a direct
 	/// channel.
 	PrivateHop {
+		/// Hint provides information about a private hop, needed while routing through a private
+		/// channel.
 		hint: &'a RouteHintHop,
+		/// The node id of the next hop in route.
+		target_node_id: NodeId
 	},
 	/// The payee's identity is concealed behind blinded paths provided in a BOLT 12 invoice.
 	Blinded {
+		/// Hint provides information about a blinded hop, needed while routing through a blinded
+		/// channel.
+		/// `BlindedPayInfo` provides information needed about the
+		/// payment while routing through a blinded
+		/// path.
+		/// `BlindedPath` is the blinded path to the destination.
 		hint: &'a (BlindedPayInfo, BlindedPath),
+		/// The index of the hint in the original list of blinded hints.
+		/// Provided to uniquely identify a hop as we are
+		/// route building.
 		hint_idx: usize,
 	},
 	/// Similar to [`Self::Blinded`], but the path here has 1 blinded hop. `BlindedPayInfo` provided
 	/// for 1-hop blinded paths is ignored because it is meant to apply to the hops *between* the
 	/// introduction node and the destination. Useful for tracking that we need to include a blinded
 	/// path at the end of our [`Route`].
 	OneHopBlinded {
+		/// Hint provides information about a single blinded hop, needed while routing through a blinded
+		/// channel.
+		/// `BlindedPayInfo` is ignored here.
+		/// `BlindedPath` is the blinded path to the destination.
 		hint: &'a (BlindedPayInfo, BlindedPath),
+		/// The index of the hint in the original list of blinded hints.
+		/// Provided to uniquely identify a hop as we are
+		/// route building.
 		hint_idx: usize,
 	},
 }
 
 impl<'a> CandidateRouteHop<'a> {
-	fn short_channel_id(&self) -> Option<u64> {
+	/// Returns short_channel_id if known.
+	/// For `FirstHop` we assume `get_outbound_payment_scid` is always set, this assumption is checked in
+	/// `find_route` method.
+	/// For `Blinded` and `OneHopBlinded` we return None because we don't know the channel id.
+	pub fn short_channel_id(&self) -> Option<u64> {
 		match self {
-			CandidateRouteHop::FirstHop { details } => Some(details.get_outbound_payment_scid().unwrap()),
+			CandidateRouteHop::FirstHop { details, .. } => Some(details.get_outbound_payment_scid().unwrap()),
 			CandidateRouteHop::PublicHop { short_channel_id, .. } => Some(*short_channel_id),
-			CandidateRouteHop::PrivateHop { hint } => Some(hint.short_channel_id),
+			CandidateRouteHop::PrivateHop { hint, .. } => Some(hint.short_channel_id),
 			CandidateRouteHop::Blinded { .. } => None,
 			CandidateRouteHop::OneHopBlinded { .. } => None,
 		}
@@ -1022,7 +1058,7 @@ impl<'a> CandidateRouteHop<'a> {
 	// NOTE: This may alloc memory so avoid calling it in a hot code path.
 	fn features(&self) -> ChannelFeatures {
 		match self {
-			CandidateRouteHop::FirstHop { details } => details.counterparty.features.to_context(),
+			CandidateRouteHop::FirstHop { details, .. } => details.counterparty.features.to_context(),
 			CandidateRouteHop::PublicHop { info, .. } => info.channel().features.clone(),
 			CandidateRouteHop::PrivateHop { .. } => ChannelFeatures::empty(),
 			CandidateRouteHop::Blinded { .. } => ChannelFeatures::empty(),
@@ -1034,17 +1070,17 @@ impl<'a> CandidateRouteHop<'a> {
 		match self {
 			CandidateRouteHop::FirstHop { .. } => 0,
 			CandidateRouteHop::PublicHop { info, .. } => info.direction().cltv_expiry_delta as u32,
-			CandidateRouteHop::PrivateHop { hint } => hint.cltv_expiry_delta as u32,
+			CandidateRouteHop::PrivateHop { hint, .. } => hint.cltv_expiry_delta as u32,
 			CandidateRouteHop::Blinded { hint, .. } => hint.0.cltv_expiry_delta as u32,
 			CandidateRouteHop::OneHopBlinded { .. } => 0,
 		}
 	}
 
 	fn htlc_minimum_msat(&self) -> u64 {
 		match self {
-			CandidateRouteHop::FirstHop { details } => details.next_outbound_htlc_minimum_msat,
+			CandidateRouteHop::FirstHop { details, .. } => details.next_outbound_htlc_minimum_msat,
 			CandidateRouteHop::PublicHop { info, .. } => info.direction().htlc_minimum_msat,
-			CandidateRouteHop::PrivateHop { hint } => hint.htlc_minimum_msat.unwrap_or(0),
+			CandidateRouteHop::PrivateHop { hint, .. } => hint.htlc_minimum_msat.unwrap_or(0),
 			CandidateRouteHop::Blinded { hint, .. } => hint.0.htlc_minimum_msat,
 			CandidateRouteHop::OneHopBlinded { .. } => 0,
 		}
@@ -1056,7 +1092,7 @@ impl<'a> CandidateRouteHop<'a> {
 				base_msat: 0, proportional_millionths: 0,
 			},
 			CandidateRouteHop::PublicHop { info, .. } => info.direction().fees,
-			CandidateRouteHop::PrivateHop { hint } => hint.fees,
+			CandidateRouteHop::PrivateHop { hint, .. } => hint.fees,
 			CandidateRouteHop::Blinded { hint, .. } => {
 				RoutingFees {
 					base_msat: hint.0.fee_base_msat,
@@ -1070,13 +1106,13 @@ impl<'a> CandidateRouteHop<'a> {
 
 	fn effective_capacity(&self) -> EffectiveCapacity {
 		match self {
-			CandidateRouteHop::FirstHop { details } => EffectiveCapacity::ExactLiquidity {
+			CandidateRouteHop::FirstHop { details, .. } => EffectiveCapacity::ExactLiquidity {
 				liquidity_msat: details.next_outbound_htlc_limit_msat,
 			},
 			CandidateRouteHop::PublicHop { info, .. } => info.effective_capacity(),
-			CandidateRouteHop::PrivateHop { hint: RouteHintHop { htlc_maximum_msat: Some(max), .. }} =>
+			CandidateRouteHop::PrivateHop { hint: RouteHintHop { htlc_maximum_msat: Some(max), .. }, ..} =>
 				EffectiveCapacity::HintMaxHTLC { amount_msat: *max },
-			CandidateRouteHop::PrivateHop { hint: RouteHintHop { htlc_maximum_msat: None, .. }} =>
+			CandidateRouteHop::PrivateHop { hint: RouteHintHop { htlc_maximum_msat: None, .. }, ..} =>
 				EffectiveCapacity::Infinite,
 			CandidateRouteHop::Blinded { hint, .. } =>
 				EffectiveCapacity::HintMaxHTLC { amount_msat: hint.0.htlc_maximum_msat },
@@ -1099,6 +1135,26 @@ impl<'a> CandidateRouteHop<'a> {
 			_ => None,
 		}
 	}
+	/// Returns the source node id of this hop.
+	pub fn source(&self) -> NodeId {
+		match self {
+			CandidateRouteHop::FirstHop { node_id, .. } => *node_id,
+			CandidateRouteHop::PublicHop { info, .. } => info.channel.node_one.into(),
+			CandidateRouteHop::PrivateHop { hint, .. } => hint.src_node_id.into(),
+			CandidateRouteHop::Blinded { hint, .. } => hint.1.introduction_node_id.into(),
+			CandidateRouteHop::OneHopBlinded { hint, .. } => hint.1.introduction_node_id.into()
+		}
+	}
+	/// Returns the target node id of this hop, if known.
+ 	pub fn target(&self) -> Option<NodeId> {
+		match self {
+			CandidateRouteHop::FirstHop { details, .. } => Some(details.counterparty.node_id.into()),
+			CandidateRouteHop::PublicHop { info, .. } => Some(info.channel.node_two.into()),
+			CandidateRouteHop::PrivateHop { target_node_id, .. } => Some(*target_node_id),
+			CandidateRouteHop::Blinded { hint, .. } => Some(hint.1.blinding_point.into()),
+			CandidateRouteHop::OneHopBlinded { hint, .. } => Some(hint.1.blinding_point.into())
+		}
+	}
 }
 
 #[derive(Clone, Copy, Eq, Hash, Ord, PartialOrd, PartialEq)]
@@ -1142,7 +1198,7 @@ fn iter_equal<I1: Iterator, I2: Iterator>(mut iter_a: I1, mut iter_b: I2)
 /// Fee values should be updated only in the context of the whole path, see update_value_and_recompute_fees.
 /// These fee values are useful to choose hops as we traverse the graph "payee-to-payer".
 #[derive(Clone)]
-struct PathBuildingHop<'a> {
+pub struct PathBuildingHop<'a> {
 	// Note that this should be dropped in favor of loading it from CandidateRouteHop, but doing so
 	// is a larger refactor and will require careful performance analysis.
 	node_id: NodeId,
@@ -1960,7 +2016,7 @@ where L::Target: Logger {
 			if !skip_node {
 				if let Some(first_channels) = first_hop_targets.get(&$node_id) {
 					for details in first_channels {
-						let candidate = CandidateRouteHop::FirstHop { details };
+						let candidate = CandidateRouteHop::FirstHop { details, node_id: our_node_id };
 						add_entry!(candidate, our_node_id, $node_id, $fee_to_target_msat,
 							$next_hops_value_contribution,
 							$next_hops_path_htlc_minimum_msat, $next_hops_path_penalty_msat,
@@ -2015,7 +2071,7 @@ where L::Target: Logger {
 		// place where it could be added.
 		payee_node_id_opt.map(|payee| first_hop_targets.get(&payee).map(|first_channels| {
 			for details in first_channels {
-				let candidate = CandidateRouteHop::FirstHop { details };
+				let candidate = CandidateRouteHop::FirstHop { details, node_id: our_node_id };
 				let added = add_entry!(candidate, our_node_id, payee, 0, path_value_msat,
 									0, 0u64, 0, 0).is_some();
 				log_trace!(logger, "{} direct route to payee via {}",
@@ -2062,7 +2118,7 @@ where L::Target: Logger {
 				sort_first_hop_channels(first_channels, &used_liquidities, recommended_value_msat,
 					our_node_pubkey);
 				for details in first_channels {
-					let first_hop_candidate = CandidateRouteHop::FirstHop { details };
+					let first_hop_candidate = CandidateRouteHop::FirstHop { details, node_id: our_node_id};
 					let blinded_path_fee = match compute_fees(path_contribution_msat, candidate.fees()) {
 						Some(fee) => fee,
 						None => continue
@@ -2108,7 +2164,7 @@ where L::Target: Logger {
 							info,
 							short_channel_id: hop.short_channel_id,
 						})
-						.unwrap_or_else(|| CandidateRouteHop::PrivateHop { hint: hop });
+						.unwrap_or_else(|| CandidateRouteHop::PrivateHop { hint: hop, target_node_id: target });
 
 					if let Some(hop_used_msat) = add_entry!(candidate, source, target,
 						aggregate_next_hops_fee_msat, aggregate_path_contribution_msat,
@@ -2148,7 +2204,7 @@ where L::Target: Logger {
 						sort_first_hop_channels(first_channels, &used_liquidities,
 							recommended_value_msat, our_node_pubkey);
 						for details in first_channels {
-							let first_hop_candidate = CandidateRouteHop::FirstHop { details };
+							let first_hop_candidate = CandidateRouteHop::FirstHop { details, node_id: our_node_id};
 							add_entry!(first_hop_candidate, our_node_id, NodeId::from_pubkey(&prev_hop_id),
 								aggregate_next_hops_fee_msat, aggregate_path_contribution_msat,
 								aggregate_next_hops_path_htlc_minimum_msat, aggregate_next_hops_path_penalty_msat,
@@ -2189,7 +2245,7 @@ where L::Target: Logger {
 							sort_first_hop_channels(first_channels, &used_liquidities,
 								recommended_value_msat, our_node_pubkey);
 							for details in first_channels {
-								let first_hop_candidate = CandidateRouteHop::FirstHop { details };
+								let first_hop_candidate = CandidateRouteHop::FirstHop { details, node_id: our_node_id};
 								add_entry!(first_hop_candidate, our_node_id,
 									NodeId::from_pubkey(&hop.src_node_id),
 									aggregate_next_hops_fee_msat,