Unify blinding nomenclature to call them "paths" not "routes".

Currently the `onion_message` module exposes the blinded route
object as *both* `BlindedRoute` and `BlindedPath`. This is somewhat
confusing, and given they are really paths, not routes (at least in
the sense that a route could be multi-path, though for OMs they are
not), here we unify to only call them paths.

Author: TheBlueMatt

lightning/src/onion_message/blinded_route.rs

@@ -29,7 +29,7 @@ use crate::prelude::*;
 /// Onion messages can be sent and received to blinded routes, which serve to hide the identity of
 /// the recipient.
 #[derive(Clone, Debug, PartialEq)]
-pub struct BlindedRoute {
+pub struct BlindedPath {
 	/// To send to a blinded route, the sender first finds a route to the unblinded
 	/// `introduction_node_id`, which can unblind its [`encrypted_payload`] to find out the onion
 	/// message's next hop and forward it along.
@@ -57,7 +57,7 @@ pub struct BlindedHop {
 	pub(crate) encrypted_payload: Vec<u8>,
 }
 
-impl BlindedRoute {
+impl BlindedPath {
 	/// Create a blinded route to be forwarded along `node_pks`. The last node pubkey in `node_pks`
 	/// will be the destination node.
 	///
@@ -71,7 +71,7 @@ impl BlindedRoute {
 		let blinding_secret = SecretKey::from_slice(&blinding_secret_bytes[..]).expect("RNG is busted");
 		let introduction_node_id = node_pks[0];
 
-		Ok(BlindedRoute {
+		Ok(BlindedPath {
 			introduction_node_id,
 			blinding_point: PublicKey::from_secret_key(secp_ctx, &blinding_secret),
 			blinded_hops: blinded_hops(secp_ctx, node_pks, &blinding_secret).map_err(|_| ())?,
@@ -156,7 +156,7 @@ fn encrypt_payload<P: Writeable>(payload: P, encrypted_tlvs_ss: [u8; 32]) -> Vec
 	writer.0
 }
 
-impl Writeable for BlindedRoute {
+impl Writeable for BlindedPath {
 	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
 		self.introduction_node_id.write(w)?;
 		self.blinding_point.write(w)?;
@@ -168,7 +168,7 @@ impl Writeable for BlindedRoute {
 	}
 }
 
-impl Readable for BlindedRoute {
+impl Readable for BlindedPath {
 	fn read<R: io::Read>(r: &mut R) -> Result<Self, DecodeError> {
 		let introduction_node_id = Readable::read(r)?;
 		let blinding_point = Readable::read(r)?;
@@ -178,7 +178,7 @@ impl Readable for BlindedRoute {
 		for _ in 0..num_hops {
 			blinded_hops.push(Readable::read(r)?);
 		}
-		Ok(BlindedRoute {
+		Ok(BlindedPath {
 			introduction_node_id,
 			blinding_point,
 			blinded_hops,

lightning/src/onion_message/functional_tests.rs

@@ -12,7 +12,7 @@
 use crate::chain::keysinterface::{KeysInterface, Recipient};
 use crate::ln::features::InitFeatures;
 use crate::ln::msgs::{self, DecodeError, OnionMessageHandler};
-use super::{BlindedRoute, CustomOnionMessageContents, CustomOnionMessageHandler, Destination, OnionMessageContents, OnionMessenger, SendError};
+use super::{BlindedPath, CustomOnionMessageContents, CustomOnionMessageHandler, Destination, OnionMessageContents, OnionMessenger, SendError};
 use crate::util::ser::{Writeable, Writer};
 use crate::util::test_utils;
 
@@ -136,9 +136,9 @@ fn two_unblinded_two_blinded() {
 	let test_msg = OnionMessageContents::Custom(TestCustomMessage {});
 
 	let secp_ctx = Secp256k1::new();
-	let blinded_route = BlindedRoute::new(&[nodes[3].get_node_pk(), nodes[4].get_node_pk()], &*nodes[4].keys_manager, &secp_ctx).unwrap();
+	let blinded_route = BlindedPath::new(&[nodes[3].get_node_pk(), nodes[4].get_node_pk()], &*nodes[4].keys_manager, &secp_ctx).unwrap();
 
-	nodes[0].messenger.send_onion_message(&[nodes[1].get_node_pk(), nodes[2].get_node_pk()], Destination::BlindedRoute(blinded_route), test_msg, None).unwrap();
+	nodes[0].messenger.send_onion_message(&[nodes[1].get_node_pk(), nodes[2].get_node_pk()], Destination::BlindedPath(blinded_route), test_msg, None).unwrap();
 	pass_along_path(&nodes, None);
 }
 
@@ -148,9 +148,9 @@ fn three_blinded_hops() {
 	let test_msg = OnionMessageContents::Custom(TestCustomMessage {});
 
 	let secp_ctx = Secp256k1::new();
-	let blinded_route = BlindedRoute::new(&[nodes[1].get_node_pk(), nodes[2].get_node_pk(), nodes[3].get_node_pk()], &*nodes[3].keys_manager, &secp_ctx).unwrap();
+	let blinded_route = BlindedPath::new(&[nodes[1].get_node_pk(), nodes[2].get_node_pk(), nodes[3].get_node_pk()], &*nodes[3].keys_manager, &secp_ctx).unwrap();
 
-	nodes[0].messenger.send_onion_message(&[], Destination::BlindedRoute(blinded_route), test_msg, None).unwrap();
+	nodes[0].messenger.send_onion_message(&[], Destination::BlindedPath(blinded_route), test_msg, None).unwrap();
 	pass_along_path(&nodes, None);
 }
 
@@ -174,14 +174,14 @@ fn we_are_intro_node() {
 	let test_msg = TestCustomMessage {};
 
 	let secp_ctx = Secp256k1::new();
-	let blinded_route = BlindedRoute::new(&[nodes[0].get_node_pk(), nodes[1].get_node_pk(), nodes[2].get_node_pk()], &*nodes[2].keys_manager, &secp_ctx).unwrap();
+	let blinded_route = BlindedPath::new(&[nodes[0].get_node_pk(), nodes[1].get_node_pk(), nodes[2].get_node_pk()], &*nodes[2].keys_manager, &secp_ctx).unwrap();
 
-	nodes[0].messenger.send_onion_message(&[], Destination::BlindedRoute(blinded_route), OnionMessageContents::Custom(test_msg.clone()), None).unwrap();
+	nodes[0].messenger.send_onion_message(&[], Destination::BlindedPath(blinded_route), OnionMessageContents::Custom(test_msg.clone()), None).unwrap();
 	pass_along_path(&nodes, None);
 
 	// Try with a two-hop blinded route where we are the introduction node.
-	let blinded_route = BlindedRoute::new(&[nodes[0].get_node_pk(), nodes[1].get_node_pk()], &*nodes[1].keys_manager, &secp_ctx).unwrap();
-	nodes[0].messenger.send_onion_message(&[], Destination::BlindedRoute(blinded_route), OnionMessageContents::Custom(test_msg), None).unwrap();
+	let blinded_route = BlindedPath::new(&[nodes[0].get_node_pk(), nodes[1].get_node_pk()], &*nodes[1].keys_manager, &secp_ctx).unwrap();
+	nodes[0].messenger.send_onion_message(&[], Destination::BlindedPath(blinded_route), OnionMessageContents::Custom(test_msg), None).unwrap();
 	nodes.remove(2);
 	pass_along_path(&nodes, None);
 }
@@ -194,16 +194,16 @@ fn invalid_blinded_route_error() {
 
 	// 0 hops
 	let secp_ctx = Secp256k1::new();
-	let mut blinded_route = BlindedRoute::new(&[nodes[1].get_node_pk(), nodes[2].get_node_pk()], &*nodes[2].keys_manager, &secp_ctx).unwrap();
+	let mut blinded_route = BlindedPath::new(&[nodes[1].get_node_pk(), nodes[2].get_node_pk()], &*nodes[2].keys_manager, &secp_ctx).unwrap();
 	blinded_route.blinded_hops.clear();
-	let err = nodes[0].messenger.send_onion_message(&[], Destination::BlindedRoute(blinded_route), OnionMessageContents::Custom(test_msg.clone()), None).unwrap_err();
+	let err = nodes[0].messenger.send_onion_message(&[], Destination::BlindedPath(blinded_route), OnionMessageContents::Custom(test_msg.clone()), None).unwrap_err();
 	assert_eq!(err, SendError::TooFewBlindedHops);
 
 	// 1 hop
-	let mut blinded_route = BlindedRoute::new(&[nodes[1].get_node_pk(), nodes[2].get_node_pk()], &*nodes[2].keys_manager, &secp_ctx).unwrap();
+	let mut blinded_route = BlindedPath::new(&[nodes[1].get_node_pk(), nodes[2].get_node_pk()], &*nodes[2].keys_manager, &secp_ctx).unwrap();
 	blinded_route.blinded_hops.remove(0);
 	assert_eq!(blinded_route.blinded_hops.len(), 1);
-	let err = nodes[0].messenger.send_onion_message(&[], Destination::BlindedRoute(blinded_route), OnionMessageContents::Custom(test_msg), None).unwrap_err();
+	let err = nodes[0].messenger.send_onion_message(&[], Destination::BlindedPath(blinded_route), OnionMessageContents::Custom(test_msg), None).unwrap_err();
 	assert_eq!(err, SendError::TooFewBlindedHops);
 }
 
@@ -214,19 +214,19 @@ fn reply_path() {
 	let secp_ctx = Secp256k1::new();
 
 	// Destination::Node
-	let reply_path = BlindedRoute::new(&[nodes[2].get_node_pk(), nodes[1].get_node_pk(), nodes[0].get_node_pk()], &*nodes[0].keys_manager, &secp_ctx).unwrap();
+	let reply_path = BlindedPath::new(&[nodes[2].get_node_pk(), nodes[1].get_node_pk(), nodes[0].get_node_pk()], &*nodes[0].keys_manager, &secp_ctx).unwrap();
 	nodes[0].messenger.send_onion_message(&[nodes[1].get_node_pk(), nodes[2].get_node_pk()], Destination::Node(nodes[3].get_node_pk()), OnionMessageContents::Custom(test_msg.clone()), Some(reply_path)).unwrap();
 	pass_along_path(&nodes, None);
 	// Make sure the last node successfully decoded the reply path.
 	nodes[3].logger.assert_log_contains(
 		"lightning::onion_message::messenger".to_string(),
 		format!("Received an onion message with path_id None and a reply_path").to_string(), 1);
 
-	// Destination::BlindedRoute
-	let blinded_route = BlindedRoute::new(&[nodes[1].get_node_pk(), nodes[2].get_node_pk(), nodes[3].get_node_pk()], &*nodes[3].keys_manager, &secp_ctx).unwrap();
-	let reply_path = BlindedRoute::new(&[nodes[2].get_node_pk(), nodes[1].get_node_pk(), nodes[0].get_node_pk()], &*nodes[0].keys_manager, &secp_ctx).unwrap();
+	// Destination::BlindedPath
+	let blinded_route = BlindedPath::new(&[nodes[1].get_node_pk(), nodes[2].get_node_pk(), nodes[3].get_node_pk()], &*nodes[3].keys_manager, &secp_ctx).unwrap();
+	let reply_path = BlindedPath::new(&[nodes[2].get_node_pk(), nodes[1].get_node_pk(), nodes[0].get_node_pk()], &*nodes[0].keys_manager, &secp_ctx).unwrap();
 
-	nodes[0].messenger.send_onion_message(&[], Destination::BlindedRoute(blinded_route), OnionMessageContents::Custom(test_msg), Some(reply_path)).unwrap();
+	nodes[0].messenger.send_onion_message(&[], Destination::BlindedPath(blinded_route), OnionMessageContents::Custom(test_msg), Some(reply_path)).unwrap();
 	pass_along_path(&nodes, None);
 	nodes[3].logger.assert_log_contains(
 		"lightning::onion_message::messenger".to_string(),

lightning/src/onion_message/messenger.rs

@@ -20,7 +20,7 @@ use crate::ln::features::{InitFeatures, NodeFeatures};
 use crate::ln::msgs::{self, OnionMessageHandler};
 use crate::ln::onion_utils;
 use crate::ln::peer_handler::IgnoringMessageHandler;
-use super::blinded_route::{BlindedRoute, ForwardTlvs, ReceiveTlvs};
+use super::blinded_route::{BlindedPath, ForwardTlvs, ReceiveTlvs};
 pub use super::packet::{CustomOnionMessageContents, OnionMessageContents};
 use super::packet::{BIG_PACKET_HOP_DATA_LEN, ForwardControlTlvs, Packet, Payload, ReceiveControlTlvs, SMALL_PACKET_HOP_DATA_LEN};
 use super::utils;
@@ -46,7 +46,7 @@ use crate::prelude::*;
 /// # use lightning::chain::keysinterface::{InMemorySigner, KeysManager, KeysInterface};
 /// # use lightning::ln::msgs::DecodeError;
 /// # use lightning::ln::peer_handler::IgnoringMessageHandler;
-/// # use lightning::onion_message::{BlindedRoute, CustomOnionMessageContents, Destination, OnionMessageContents, OnionMessenger};
+/// # use lightning::onion_message::{BlindedPath, CustomOnionMessageContents, Destination, OnionMessageContents, OnionMessenger};
 /// # use lightning::util::logger::{Logger, Record};
 /// # use lightning::util::ser::{Writeable, Writer};
 /// # use lightning::io;
@@ -92,14 +92,14 @@ use crate::prelude::*;
 /// // Create a blinded route to yourself, for someone to send an onion message to.
 /// # let your_node_id = hop_node_id1;
 /// let hops = [hop_node_id3, hop_node_id4, your_node_id];
-/// let blinded_route = BlindedRoute::new(&hops, &keys_manager, &secp_ctx).unwrap();
+/// let blinded_route = BlindedPath::new(&hops, &keys_manager, &secp_ctx).unwrap();
 ///
 /// // Send a custom onion message to a blinded route.
 /// # let intermediate_hops = [hop_node_id1, hop_node_id2];
 /// let reply_path = None;
 /// # let your_custom_message = YourCustomMessage {};
 /// let message = OnionMessageContents::Custom(your_custom_message);
-/// onion_messenger.send_onion_message(&intermediate_hops, Destination::BlindedRoute(blinded_route), message, reply_path);
+/// onion_messenger.send_onion_message(&intermediate_hops, Destination::BlindedPath(blinded_route), message, reply_path);
 /// ```
 ///
 /// [offers]: <https://github.com/lightning/bolts/pull/798>
@@ -123,14 +123,14 @@ pub enum Destination {
 	/// We're sending this onion message to a node.
 	Node(PublicKey),
 	/// We're sending this onion message to a blinded route.
-	BlindedRoute(BlindedRoute),
+	BlindedPath(BlindedPath),
 }
 
 impl Destination {
 	pub(super) fn num_hops(&self) -> usize {
 		match self {
 			Destination::Node(_) => 1,
-			Destination::BlindedRoute(BlindedRoute { blinded_hops, .. }) => blinded_hops.len(),
+			Destination::BlindedPath(BlindedPath { blinded_hops, .. }) => blinded_hops.len(),
 		}
 	}
 }
@@ -145,7 +145,7 @@ pub enum SendError {
 	/// Because implementations such as Eclair will drop onion messages where the message packet
 	/// exceeds 32834 bytes, we refuse to send messages where the packet exceeds this size.
 	TooBigPacket,
-	/// The provided [`Destination`] was an invalid [`BlindedRoute`], due to having fewer than two
+	/// The provided [`Destination`] was an invalid [`BlindedPath`], due to having fewer than two
 	/// blinded hops.
 	TooFewBlindedHops,
 	/// Our next-hop peer was offline or does not support onion message forwarding.
@@ -162,7 +162,7 @@ pub enum SendError {
 	/// advance the blinded route to make the second hop the new introduction node. Either
 	/// [`KeysInterface::ecdh`] failed, we failed to tweak the current blinding point to get the
 	/// new blinding point, or we were attempting to send to ourselves.
-	BlindedRouteAdvanceFailed,
+	BlindedPathAdvanceFailed,
 }
 
 /// Handler for custom onion messages. If you are using [`SimpleArcOnionMessenger`],
@@ -207,8 +207,8 @@ impl<K: Deref, L: Deref, CMH: Deref> OnionMessenger<K, L, CMH>
 
 	/// Send an onion message with contents `message` to `destination`, routing it through `intermediate_nodes`.
 	/// See [`OnionMessenger`] for example usage.
-	pub fn send_onion_message<T: CustomOnionMessageContents>(&self, intermediate_nodes: &[PublicKey], mut destination: Destination, message: OnionMessageContents<T>, reply_path: Option<BlindedRoute>) -> Result<(), SendError> {
-		if let Destination::BlindedRoute(BlindedRoute { ref blinded_hops, .. }) = destination {
+	pub fn send_onion_message<T: CustomOnionMessageContents>(&self, intermediate_nodes: &[PublicKey], mut destination: Destination, message: OnionMessageContents<T>, reply_path: Option<BlindedPath>) -> Result<(), SendError> {
+		if let Destination::BlindedPath(BlindedPath { ref blinded_hops, .. }) = destination {
 			if blinded_hops.len() < 2 {
 				return Err(SendError::TooFewBlindedHops);
 			}
@@ -219,12 +219,12 @@ impl<K: Deref, L: Deref, CMH: Deref> OnionMessenger<K, L, CMH>
 		// If we are sending straight to a blinded route and we are the introduction node, we need to
 		// advance the blinded route by 1 hop so the second hop is the new introduction node.
 		if intermediate_nodes.len() == 0 {
-			if let Destination::BlindedRoute(ref mut blinded_route) = destination {
+			if let Destination::BlindedPath(ref mut blinded_route) = destination {
 				let our_node_id = self.keys_manager.get_node_id(Recipient::Node)
 					.map_err(|()| SendError::GetNodeIdFailed)?;
 				if blinded_route.introduction_node_id == our_node_id {
 					blinded_route.advance_by_one(&self.keys_manager, &self.secp_ctx)
-						.map_err(|()| SendError::BlindedRouteAdvanceFailed)?;
+						.map_err(|()| SendError::BlindedPathAdvanceFailed)?;
 				}
 			}
 		}
@@ -236,7 +236,7 @@ impl<K: Deref, L: Deref, CMH: Deref> OnionMessenger<K, L, CMH>
 		} else {
 			match destination {
 				Destination::Node(pk) => (pk, PublicKey::from_secret_key(&self.secp_ctx, &blinding_secret)),
-				Destination::BlindedRoute(BlindedRoute { introduction_node_id, blinding_point, .. }) =>
+				Destination::BlindedPath(BlindedPath { introduction_node_id, blinding_point, .. }) =>
 					(introduction_node_id, blinding_point),
 			}
 		};
@@ -476,13 +476,13 @@ pub type SimpleRefOnionMessenger<'a, 'b, L> = OnionMessenger<&'a KeysManager, &'
 /// `unblinded_path` to the given `destination`.
 fn packet_payloads_and_keys<T: CustomOnionMessageContents, S: secp256k1::Signing + secp256k1::Verification>(
 	secp_ctx: &Secp256k1<S>, unblinded_path: &[PublicKey], destination: Destination,
-	message: OnionMessageContents<T>, mut reply_path: Option<BlindedRoute>, session_priv: &SecretKey
+	message: OnionMessageContents<T>, mut reply_path: Option<BlindedPath>, session_priv: &SecretKey
 ) -> Result<(Vec<(Payload<T>, [u8; 32])>, Vec<onion_utils::OnionKeys>), secp256k1::Error> {
 	let num_hops = unblinded_path.len() + destination.num_hops();
 	let mut payloads = Vec::with_capacity(num_hops);
 	let mut onion_packet_keys = Vec::with_capacity(num_hops);
 
-	let (mut intro_node_id_blinding_pt, num_blinded_hops) = if let Destination::BlindedRoute(BlindedRoute {
+	let (mut intro_node_id_blinding_pt, num_blinded_hops) = if let Destination::BlindedPath(BlindedPath {
 		introduction_node_id, blinding_point, blinded_hops }) = &destination {
 		(Some((*introduction_node_id, *blinding_point)), blinded_hops.len()) } else { (None, 0) };
 	let num_unblinded_hops = num_hops - num_blinded_hops;

lightning/src/onion_message/mod.rs

@@ -18,7 +18,7 @@
 //! information on its usage.
 //!
 //! [offers]: <https://github.com/lightning/bolts/pull/798>
-//! [blinded routes]: crate::onion_message::BlindedRoute
+//! [blinded routes]: crate::onion_message::BlindedPath
 
 mod blinded_route;
 mod messenger;
@@ -28,6 +28,6 @@ mod utils;
 mod functional_tests;
 
 // Re-export structs so they can be imported with just the `onion_message::` module prefix.
-pub use self::blinded_route::{BlindedRoute, BlindedRoute as BlindedPath, BlindedHop};
+pub use self::blinded_route::{BlindedPath, BlindedHop};
 pub use self::messenger::{CustomOnionMessageContents, CustomOnionMessageHandler, Destination, OnionMessageContents, OnionMessenger, SendError, SimpleArcOnionMessenger, SimpleRefOnionMessenger};
 pub(crate) use self::packet::Packet;

lightning/src/onion_message/packet.rs

@@ -14,7 +14,7 @@ use bitcoin::secp256k1::ecdh::SharedSecret;
 
 use crate::ln::msgs::DecodeError;
 use crate::ln::onion_utils;
-use super::blinded_route::{BlindedRoute, ForwardTlvs, ReceiveTlvs};
+use super::blinded_route::{BlindedPath, ForwardTlvs, ReceiveTlvs};
 use super::messenger::CustomOnionMessageHandler;
 use crate::util::chacha20poly1305rfc::{ChaChaPolyReadAdapter, ChaChaPolyWriteAdapter};
 use crate::util::ser::{BigSize, FixedLengthReader, LengthRead, LengthReadable, LengthReadableArgs, Readable, ReadableArgs, Writeable, Writer};
@@ -99,7 +99,7 @@ pub(super) enum Payload<T: CustomOnionMessageContents> {
 	/// This payload is for the final hop.
 	Receive {
 		control_tlvs: ReceiveControlTlvs,
-		reply_path: Option<BlindedRoute>,
+		reply_path: Option<BlindedPath>,
 		message: OnionMessageContents<T>,
 	}
 }
@@ -204,7 +204,7 @@ impl<H: CustomOnionMessageHandler> ReadableArgs<(SharedSecret, &H)> for Payload<
 
 		let v: BigSize = Readable::read(r)?;
 		let mut rd = FixedLengthReader::new(r, v.0);
-		let mut reply_path: Option<BlindedRoute> = None;
+		let mut reply_path: Option<BlindedPath> = None;
 		let mut read_adapter: Option<ChaChaPolyReadAdapter<ControlTlvs>> = None;
 		let rho = onion_utils::gen_rho_from_shared_secret(&encrypted_tlvs_ss.secret_bytes());
 		let mut message_type: Option<u64> = None;

lightning/src/onion_message/utils.rs

@@ -16,7 +16,7 @@ use bitcoin::secp256k1::{self, PublicKey, Secp256k1, SecretKey, Scalar};
 use bitcoin::secp256k1::ecdh::SharedSecret;
 
 use crate::ln::onion_utils;
-use super::blinded_route::BlindedRoute;
+use super::blinded_route::BlindedPath;
 use super::messenger::Destination;
 
 use crate::prelude::*;
@@ -87,7 +87,7 @@ pub(super) fn construct_keys_callback<T: secp256k1::Signing + secp256k1::Verific
 			Destination::Node(pk) => {
 				build_keys!(pk, false, None);
 			},
-			Destination::BlindedRoute(BlindedRoute { blinded_hops, .. }) => {
+			Destination::BlindedPath(BlindedPath { blinded_hops, .. }) => {
 				for hop in blinded_hops {
 					build_keys_in_loop!(hop.blinded_node_id, true, Some(hop.encrypted_payload));
 				}