Groundwork for refactoring PaymentParams::Hints to ::Payee

Minor changes in preparation for supporting route blinding in
PaymentParameters. In the next commit, we'll be moving more
unblinded-payee-specific fields from the top level parameters into the clear
enum variant.

diff --git a/lightning/src/routing/router.rs b/lightning/src/routing/router.rs
index 39a7e69edb06a0e9888bfe8472d014c0fd5223ae..06a36a03a73368347dd4ef8ddff6b3b6fca11fb8 100644 (file)
--- a/lightning/src/routing/router.rs
+++ b/lightning/src/routing/router.rs
@@ -490,7 +490,7 @@ const MEDIAN_HOP_CLTV_EXPIRY_DELTA: u32 = 40;
 // down from (1300-93) / 61 = 19.78... to arrive at a conservative estimate of 19.
 const MAX_PATH_LENGTH_ESTIMATE: u8 = 19;
 
-/// The recipient of a payment.
+/// Information used to route a payment.
 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
 pub struct PaymentParameters {
        /// The node id of the payee.
@@ -504,8 +504,8 @@ pub struct PaymentParameters {
        /// [`for_keysend`]: Self::for_keysend
        pub features: Option<InvoiceFeatures>,
 
-       /// Hints for routing to the payee, containing channels connecting the payee to public nodes.
-       pub route_hints: Hints,
+       /// Information about the payee, such as their features and route hints for their channels.
+       pub payee: Payee,
 
        /// Expiration of a payment to the payee, in seconds relative to the UNIX epoch.
        pub expiry_time: Option<u64>,
@@ -546,9 +546,9 @@ impl Writeable for PaymentParameters {
        fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
                let mut clear_hints = &vec![];
                let mut blinded_hints = &vec![];
-               match &self.route_hints {
-                       Hints::Clear(hints) => clear_hints = hints,
-                       Hints::Blinded(hints) => blinded_hints = hints,
+               match &self.payee {
+                       Payee::Clear { route_hints, .. } => clear_hints = route_hints,
+                       Payee::Blinded { route_hints } => blinded_hints = route_hints,
                }
                write_tlv_fields!(writer, {
                        (0, self.payee_pubkey, required),
@@ -582,18 +582,18 @@ impl ReadableArgs<u32> for PaymentParameters {
                });
                let clear_route_hints = route_hints.unwrap_or(vec![]);
                let blinded_route_hints = blinded_route_hints.unwrap_or(vec![]);
-               let route_hints = if blinded_route_hints.len() != 0 {
+               let payee = if blinded_route_hints.len() != 0 {
                        if clear_route_hints.len() != 0 { return Err(DecodeError::InvalidValue) }
-                       Hints::Blinded(blinded_route_hints)
+                       Payee::Blinded { route_hints: blinded_route_hints }
                } else {
-                       Hints::Clear(clear_route_hints)
+                       Payee::Clear { route_hints: clear_route_hints }
                };
                Ok(Self {
                        payee_pubkey: _init_tlv_based_struct_field!(payee_pubkey, required),
                        max_total_cltv_expiry_delta: _init_tlv_based_struct_field!(max_total_cltv_expiry_delta, (default_value, unused)),
                        features,
                        max_path_count: _init_tlv_based_struct_field!(max_path_count, (default_value, unused)),
-                       route_hints,
+                       payee,
                        max_channel_saturation_power_of_half: _init_tlv_based_struct_field!(max_channel_saturation_power_of_half, (default_value, unused)),
                        expiry_time,
                        previously_failed_channels: previously_failed_channels.unwrap_or(Vec::new()),
@@ -612,7 +612,7 @@ impl PaymentParameters {
                Self {
                        payee_pubkey,
                        features: None,
-                       route_hints: Hints::Clear(vec![]),
+                       payee: Payee::Clear { route_hints: vec![] },
                        expiry_time: None,
                        max_total_cltv_expiry_delta: DEFAULT_MAX_TOTAL_CLTV_EXPIRY_DELTA,
                        max_path_count: DEFAULT_MAX_PATH_COUNT,
@@ -641,7 +641,7 @@ impl PaymentParameters {
        ///
        /// This is not exported to bindings users since bindings don't support move semantics
        pub fn with_route_hints(self, route_hints: Vec<RouteHint>) -> Self {
-               Self { route_hints: Hints::Clear(route_hints), ..self }
+               Self { payee: Payee::Clear { route_hints }, ..self }
        }
 
        /// Includes a payment expiration in seconds relative to the UNIX epoch.
@@ -673,14 +673,22 @@ impl PaymentParameters {
        }
 }
 
-/// Routing hints for the tail of the route.
+/// The recipient of a payment, differing based on whether they've hidden their identity with route
+/// blinding.
 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
-pub enum Hints {
+pub enum Payee {
        /// The recipient provided blinded paths and payinfo to reach them. The blinded paths themselves
        /// will be included in the final [`Route`].
-       Blinded(Vec<(BlindedPayInfo, BlindedPath)>),
+       Blinded {
+               /// Aggregated routing info and blinded paths, for routing to the payee without knowing their
+               /// node id.
+               route_hints: Vec<(BlindedPayInfo, BlindedPath)>,
+       },
        /// The recipient included these route hints in their BOLT11 invoice.
-       Clear(Vec<RouteHint>),
+       Clear {
+               /// Hints for routing to the payee, containing channels connecting the payee to public nodes.
+               route_hints: Vec<RouteHint>,
+       },
 }
 
 /// A list of hops along a payment path terminating with a channel to the recipient.
@@ -1131,9 +1139,9 @@ where L::Target: Logger {
                return Err(LightningError{err: "Cannot send a payment of 0 msat".to_owned(), action: ErrorAction::IgnoreError});
        }
 
-       match &payment_params.route_hints {
-               Hints::Clear(hints) => {
-                       for route in hints.iter() {
+       match &payment_params.payee {
+               Payee::Clear { route_hints } => {
+                       for route in route_hints.iter() {
                                for hop in &route.0 {
                                        if hop.src_node_id == payment_params.payee_pubkey {
                                                return Err(LightningError{err: "Route hint cannot have the payee as the source.".to_owned(), action: ErrorAction::IgnoreError});
@@ -1664,8 +1672,8 @@ where L::Target: Logger {
                // If a caller provided us with last hops, add them to routing targets. Since this happens
                // earlier than general path finding, they will be somewhat prioritized, although currently
                // it matters only if the fees are exactly the same.
-               let route_hints = match &payment_params.route_hints {
-                       Hints::Clear(hints) => hints,
+               let route_hints = match &payment_params.payee {
+                       Payee::Clear { route_hints } => route_hints,
                        _ => return Err(LightningError{err: "Routing to blinded paths isn't supported yet".to_owned(), action: ErrorAction::IgnoreError}),
                };
                for route in route_hints.iter().filter(|route| !route.0.is_empty()) {