From 9973331d8ef5a71a56f78c4d7788f54e2f201cad Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Wed, 6 Dec 2023 01:22:07 +0000 Subject: [PATCH] Rewrite docs in `CandidateRouteHop` to be somewhat more descriptive --- lightning/src/routing/router.rs | 92 +++++++++++++++++++-------------- 1 file changed, 53 insertions(+), 39 deletions(-) diff --git a/lightning/src/routing/router.rs b/lightning/src/routing/router.rs index b4cbf3cb2..6300763e2 100644 --- a/lightning/src/routing/router.rs +++ b/lightning/src/routing/router.rs @@ -938,6 +938,10 @@ impl Readable for RouteHint { } /// A channel descriptor for a hop along a payment path. +/// +/// While this generally comes from BOLT 11's `r` field, this struct includes more fields than are +/// available in BOLT 11. Thus, encoding and decoding this via `lightning-invoice` is lossy, as +/// fields not supported in BOLT 11 will be stripped. #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)] pub struct RouteHintHop { /// The node_id of the non-target end of the route @@ -1009,63 +1013,73 @@ pub enum CandidateRouteHop<'a> { /// A hop from the payer, where the outbound liquidity is known. FirstHop { /// Channel details of the first hop - /// [`ChannelDetails::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 + /// [`ChannelDetails::get_outbound_payment_scid`] MUST be `Some` (indicating the channel + /// has been funded and is able to pay), and accessor methods may panic otherwise. + /// + /// [`find_route`] validates this prior to constructing a [`CandidateRouteHop`]. + details: &'a ChannelDetails, + /// The node id of the payer, which is also the source side of this candidate route hop. + node_id: NodeId, }, - /// A hop found in the [`ReadOnlyNetworkGraph`], - /// where the channel capacity may be unknown. + /// A hop found in the [`ReadOnlyNetworkGraph`]. PublicHop { - /// channel info of the hop. + /// Information about the channel, including potentially its capacity and + /// direction-specific information. info: DirectedChannelInfo<'a>, - /// short_channel_id of the channel. + /// The short channel ID of the channel, i.e. the identifier by which we refer to this + /// channel. short_channel_id: u64, }, - /// A hop to the payee found in the BOLT 11 payment invoice, - /// though not necessarily a direct - /// channel. + /// A private hop communicated by the payee, generally via a BOLT 11 invoice. + /// + /// Because BOLT 11 route hints can take multiple hops to get to the destination, this may not + /// terminate at the payee. PrivateHop { - /// Hint provides information about a private hop, - /// needed while routing through a private - /// channel. + /// Information about the private hop communicated via BOLT 11. hint: &'a RouteHintHop, - /// Node id of the next hop in route. + /// Node id of the next hop in BOLT 11 route hint. target_node_id: NodeId }, - /// The payee's identity is concealed behind - /// blinded paths provided in a BOLT 12 invoice. + /// A blinded path which starts with an introduction point and ultimately terminates with the + /// payee. + /// + /// Because we don't know the payee's identity, [`CandidateRouteHop::target`] will return + /// `None` in this state. + /// + /// Because blinded paths are "all or nothing", and we cannot use just one part of a blinded + /// path, the full path is treated as a single [`CandidateRouteHop`]. Blinded { - /// Hint provides information about a blinded hop, - /// needed while routing through a blinded path. - /// `BlindedPayInfo` provides information needed about the - /// payment while routing through a blinded path. - /// `BlindedPath` is the blinded path to the destination. + /// Information about the blinded path including the fee, HTLC amount limits, and + /// cryptographic material required to build an HTLC through the given path. hint: &'a (BlindedPayInfo, BlindedPath), /// Index of the hint in the original list of blinded hints. - /// Provided to uniquely identify a hop as we are - /// route building. + /// + /// This is used to build a [`CandidateHopId`] that uniquely identifies this blinded path, + /// even though we don't have a short channel ID for this hop. 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`]. + /// Similar to [`Self::Blinded`], but the path here only has one hop. + /// + /// While we treat this similarly to [`CandidateRouteHop::Blinded`] in many respects (e.g. + /// returning `None` from [`CandidateRouteHop::target`]), in this case we do actually know the + /// payee's identity - it's the introduction point! + /// + /// [`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. + /// + /// This primarily exists to track that we need to included a blinded path at the end of our + /// [`Route`], even though it doesn't actually add an additional hop in the payment. OneHopBlinded { - /// Hint provides information about a single blinded hop, - /// needed while routing through a one hop blinded path. - /// `BlindedPayInfo` is ignored here. - /// `BlindedPath` is the blinded path to the destination. + /// Information about the blinded path including the fee, HTLC amount limits, and + /// cryptographic material required to build an HTLC terminating with the given path. + /// + /// Note that the [`BlindedPayInfo`] is ignored here. hint: &'a (BlindedPayInfo, BlindedPath), /// Index of the hint in the original list of blinded hints. - /// Provided to uniquely identify a hop as we are route building. + /// + /// This is used to build a [`CandidateHopId`] that uniquely identifies this blinded path, + /// even though we don't have a short channel ID for this hop. hint_idx: usize, }, } -- 2.39.5