Generalize BlindedPath::introduction_node_id field

Allow using either a node id or a directed short channel id in blinded
paths. This allows for a more compact representation of blinded paths,
which is advantageous for reducing offer QR code size.

Follow-up commits will implement handling the directed short channel id
case in OnionMessenger as it requires resolving the introduction node in
MessageRouter.

Author: jkczyz

fuzz/src/router.rs

@@ -11,7 +11,7 @@ use bitcoin::blockdata::constants::ChainHash;
 use bitcoin::blockdata::script::Builder;
 use bitcoin::blockdata::transaction::TxOut;
 
-use lightning::blinded_path::{BlindedHop, BlindedPath};
+use lightning::blinded_path::{BlindedHop, BlindedPath, IntroductionNode};
 use lightning::chain::transaction::OutPoint;
 use lightning::ln::ChannelId;
 use lightning::ln::channelmanager::{self, ChannelDetails, ChannelCounterparty};
@@ -363,7 +363,7 @@ pub fn do_test<Out: test_logger::Output>(data: &[u8], out: Out) {
 						});
 					}
 					(payinfo, BlindedPath {
-						introduction_node_id: hop.src_node_id,
+						introduction_node: IntroductionNode::NodeId(hop.src_node_id),
 						blinding_point: dummy_pk,
 						blinded_hops,
 					})

lightning/src/blinded_path/message.rs

@@ -3,7 +3,7 @@ use bitcoin::secp256k1::{self, PublicKey, Secp256k1, SecretKey};
 #[allow(unused_imports)]
 use crate::prelude::*;
 
-use crate::blinded_path::{BlindedHop, BlindedPath};
+use crate::blinded_path::{BlindedHop, BlindedPath, IntroductionNode};
 use crate::blinded_path::utils;
 use crate::io;
 use crate::io::Cursor;
@@ -96,7 +96,7 @@ pub(crate) fn advance_path_by_one<NS: Deref, T: secp256k1::Signing + secp256k1::
 		Ok(ChaChaPolyReadAdapter {
 			readable: ControlTlvs::Forward(ForwardTlvs { next_hop, next_blinding_override })
 		}) => {
-			let mut next_node_id = match next_hop {
+			let next_node_id = match next_hop {
 				NextHop::NodeId(pubkey) => pubkey,
 				NextHop::ShortChannelId(_) => todo!(),
 			};
@@ -108,7 +108,7 @@ pub(crate) fn advance_path_by_one<NS: Deref, T: secp256k1::Signing + secp256k1::
 				}
 			};
 			mem::swap(&mut path.blinding_point, &mut new_blinding_point);
-			mem::swap(&mut path.introduction_node_id, &mut next_node_id);
+			path.introduction_node = IntroductionNode::NodeId(next_node_id);
 			Ok(())
 		},
 		_ => Err(())

lightning/src/blinded_path/mod.rs

@@ -29,11 +29,11 @@ use crate::prelude::*;
 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
 pub struct BlindedPath {
 	/// To send to a blinded path, the sender first finds a route to the unblinded
-	/// `introduction_node_id`, which can unblind its [`encrypted_payload`] to find out the onion
+	/// `introduction_node`, which can unblind its [`encrypted_payload`] to find out the onion
 	/// message or payment's next hop and forward it along.
 	///
 	/// [`encrypted_payload`]: BlindedHop::encrypted_payload
-	pub introduction_node_id: PublicKey,
+	pub introduction_node: IntroductionNode,
 	/// Used by the introduction node to decrypt its [`encrypted_payload`] to forward the onion
 	/// message or payment.
 	///
@@ -43,6 +43,29 @@ pub struct BlindedPath {
 	pub blinded_hops: Vec<BlindedHop>,
 }
 
+/// The unblinded node in a [`BlindedPath`].
+#[derive(Clone, Debug, Hash, PartialEq, Eq)]
+pub enum IntroductionNode {
+	/// The node id of the introduction node.
+	NodeId(PublicKey),
+	/// The short channel id of the channel leading to the introduction node. The [`Direction`]
+	/// identifies which side of the channel is the introduction node.
+	DirectedShortChannelId(Direction, u64),
+}
+
+/// The side of a channel that is the [`IntroductionNode`] in a [`BlindedPath`]. [BOLT 7] defines
+/// which nodes is which in the [`ChannelAnnouncement`] message.
+///
+/// [BOLT 7]: https://github.com/lightning/bolts/blob/master/07-routing-gossip.md#the-channel_announcement-message
+/// [`ChannelAnnouncement`]: crate::ln::msgs::ChannelAnnouncement
+#[derive(Clone, Debug, Hash, PartialEq, Eq)]
+pub enum Direction {
+	/// The lesser node id when compared lexicographically in ascending order.
+	NodeOne,
+	/// The greater node id when compared lexicographically in ascending order.
+	NodeTwo,
+}
+
 /// An encrypted payload and node id corresponding to a hop in a payment or onion message path, to
 /// be encoded in the sender's onion packet. These hops cannot be identified by outside observers
 /// and thus can be used to hide the identity of the recipient.
@@ -75,10 +98,10 @@ impl BlindedPath {
 		if node_pks.is_empty() { return Err(()) }
 		let blinding_secret_bytes = entropy_source.get_secure_random_bytes();
 		let blinding_secret = SecretKey::from_slice(&blinding_secret_bytes[..]).expect("RNG is busted");
-		let introduction_node_id = node_pks[0];
+		let introduction_node = IntroductionNode::NodeId(node_pks[0]);
 
 		Ok(BlindedPath {
-			introduction_node_id,
+			introduction_node,
 			blinding_point: PublicKey::from_secret_key(secp_ctx, &blinding_secret),
 			blinded_hops: message::blinded_hops(secp_ctx, node_pks, &blinding_secret).map_err(|_| ())?,
 		})
@@ -112,33 +135,59 @@ impl BlindedPath {
 		payee_tlvs: payment::ReceiveTlvs, htlc_maximum_msat: u64, min_final_cltv_expiry_delta: u16,
 		entropy_source: &ES, secp_ctx: &Secp256k1<T>
 	) -> Result<(BlindedPayInfo, Self), ()> {
+		let introduction_node = IntroductionNode::NodeId(
+			intermediate_nodes.first().map_or(payee_node_id, |n| n.node_id)
+		);
 		let blinding_secret_bytes = entropy_source.get_secure_random_bytes();
 		let blinding_secret = SecretKey::from_slice(&blinding_secret_bytes[..]).expect("RNG is busted");
 
 		let blinded_payinfo = payment::compute_payinfo(
 			intermediate_nodes, &payee_tlvs, htlc_maximum_msat, min_final_cltv_expiry_delta
 		)?;
 		Ok((blinded_payinfo, BlindedPath {
-			introduction_node_id: intermediate_nodes.first().map_or(payee_node_id, |n| n.node_id),
+			introduction_node,
 			blinding_point: PublicKey::from_secret_key(secp_ctx, &blinding_secret),
 			blinded_hops: payment::blinded_hops(
 				secp_ctx, intermediate_nodes, payee_node_id, payee_tlvs, &blinding_secret
 			).map_err(|_| ())?,
 		}))
 	}
 
-	/// Returns the introduction [`NodeId`] of the blinded path.
+	/// Returns the introduction [`NodeId`] of the blinded path, if it is publicly reachable (i.e.,
+	/// it is found in the network graph).
 	pub fn public_introduction_node_id<'a>(
 		&self, network_graph: &'a ReadOnlyNetworkGraph
 	) -> Option<&'a NodeId> {
-		let node_id = NodeId::from_pubkey(&self.introduction_node_id);
-		network_graph.nodes().get_key_value(&node_id).map(|(key, _)| key)
+		match &self.introduction_node {
+			IntroductionNode::NodeId(pubkey) => {
+				let node_id = NodeId::from_pubkey(pubkey);
+				network_graph.nodes().get_key_value(&node_id).map(|(key, _)| key)
+			},
+			IntroductionNode::DirectedShortChannelId(direction, scid) => {
+				network_graph
+					.channel(*scid)
+					.map(|c| match direction {
+						Direction::NodeOne => &c.node_one,
+						Direction::NodeTwo => &c.node_two,
+					})
+			},
+		}
 	}
 }
 
 impl Writeable for BlindedPath {
 	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
-		self.introduction_node_id.write(w)?;
+		match &self.introduction_node {
+			IntroductionNode::NodeId(pubkey) => pubkey.write(w)?,
+			IntroductionNode::DirectedShortChannelId(direction, scid) => {
+				match direction {
+					Direction::NodeOne => 0u8.write(w)?,
+					Direction::NodeTwo => 1u8.write(w)?,
+				}
+				scid.write(w)?;
+			},
+		}
+
 		self.blinding_point.write(w)?;
 		(self.blinded_hops.len() as u8).write(w)?;
 		for hop in &self.blinded_hops {
@@ -150,7 +199,17 @@ impl Writeable for BlindedPath {
 
 impl Readable for BlindedPath {
 	fn read<R: io::Read>(r: &mut R) -> Result<Self, DecodeError> {
-		let introduction_node_id = Readable::read(r)?;
+		let mut first_byte: u8 = Readable::read(r)?;
+		let introduction_node = match first_byte {
+			0 => IntroductionNode::DirectedShortChannelId(Direction::NodeOne, Readable::read(r)?),
+			1 => IntroductionNode::DirectedShortChannelId(Direction::NodeTwo, Readable::read(r)?),
+			2|3 => {
+				use io::Read;
+				let mut pubkey_read = core::slice::from_mut(&mut first_byte).chain(r.by_ref());
+				IntroductionNode::NodeId(Readable::read(&mut pubkey_read)?)
+			},
+			_ => return Err(DecodeError::InvalidValue),
+		};
 		let blinding_point = Readable::read(r)?;
 		let num_hops: u8 = Readable::read(r)?;
 		if num_hops == 0 { return Err(DecodeError::InvalidValue) }
@@ -159,7 +218,7 @@ impl Readable for BlindedPath {
 			blinded_hops.push(Readable::read(r)?);
 		}
 		Ok(BlindedPath {
-			introduction_node_id,
+			introduction_node,
 			blinding_point,
 			blinded_hops,
 		})
@@ -171,3 +230,12 @@ impl_writeable!(BlindedHop, {
 	encrypted_payload
 });
 
+impl Direction {
+	/// Returns the [`NodeId`] from the inputs corresponding to the direction.
+	pub fn select_node_id<'a>(&self, node_a: &'a NodeId, node_b: &'a NodeId) -> &'a NodeId {
+		match self {
+			Direction::NodeOne => core::cmp::min(node_a, node_b),
+			Direction::NodeTwo => core::cmp::max(node_a, node_b),
+		}
+	}
+}

lightning/src/ln/offers_tests.rs

@@ -42,7 +42,7 @@
 
 use bitcoin::network::constants::Network;
 use core::time::Duration;
-use crate::blinded_path::BlindedPath;
+use crate::blinded_path::{BlindedPath, IntroductionNode};
 use crate::events::{Event, MessageSendEventsProvider, PaymentPurpose};
 use crate::ln::channelmanager::{PaymentId, RecentPaymentDetails, Retry, self};
 use crate::ln::functional_test_utils::*;
@@ -260,8 +260,8 @@ fn prefers_non_tor_nodes_in_blinded_paths() {
 	assert_ne!(offer.signing_pubkey(), bob_id);
 	assert!(!offer.paths().is_empty());
 	for path in offer.paths() {
-		assert_ne!(path.introduction_node_id, bob_id);
-		assert_ne!(path.introduction_node_id, charlie_id);
+		assert_ne!(path.introduction_node, IntroductionNode::NodeId(bob_id));
+		assert_ne!(path.introduction_node, IntroductionNode::NodeId(charlie_id));
 	}
 
 	// Use a one-hop blinded path when Bob is announced and all his peers are Tor-only.
@@ -275,7 +275,7 @@ fn prefers_non_tor_nodes_in_blinded_paths() {
 	assert_ne!(offer.signing_pubkey(), bob_id);
 	assert!(!offer.paths().is_empty());
 	for path in offer.paths() {
-		assert_eq!(path.introduction_node_id, bob_id);
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(bob_id));
 	}
 }
 
@@ -325,7 +325,7 @@ fn prefers_more_connected_nodes_in_blinded_paths() {
 	assert_ne!(offer.signing_pubkey(), bob_id);
 	assert!(!offer.paths().is_empty());
 	for path in offer.paths() {
-		assert_eq!(path.introduction_node_id, nodes[4].node.get_our_node_id());
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(nodes[4].node.get_our_node_id()));
 	}
 }
 
@@ -374,7 +374,7 @@ fn creates_and_pays_for_offer_using_two_hop_blinded_path() {
 	assert_ne!(offer.signing_pubkey(), alice_id);
 	assert!(!offer.paths().is_empty());
 	for path in offer.paths() {
-		assert_eq!(path.introduction_node_id, bob_id);
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(bob_id));
 	}
 
 	let payment_id = PaymentId([1; 32]);
@@ -395,7 +395,7 @@ fn creates_and_pays_for_offer_using_two_hop_blinded_path() {
 	let (invoice_request, reply_path) = extract_invoice_request(alice, &onion_message);
 	assert_eq!(invoice_request.amount_msats(), None);
 	assert_ne!(invoice_request.payer_id(), david_id);
-	assert_eq!(reply_path.unwrap().introduction_node_id, charlie_id);
+	assert_eq!(reply_path.unwrap().introduction_node, IntroductionNode::NodeId(charlie_id));
 
 	let onion_message = alice.onion_messenger.next_onion_message_for_peer(charlie_id).unwrap();
 	charlie.onion_messenger.handle_onion_message(&alice_id, &onion_message);
@@ -408,7 +408,7 @@ fn creates_and_pays_for_offer_using_two_hop_blinded_path() {
 	assert_ne!(invoice.signing_pubkey(), alice_id);
 	assert!(!invoice.payment_paths().is_empty());
 	for (_, path) in invoice.payment_paths() {
-		assert_eq!(path.introduction_node_id, bob_id);
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(bob_id));
 	}
 
 	route_bolt12_payment(david, &[charlie, bob, alice], &invoice);
@@ -469,7 +469,7 @@ fn creates_and_pays_for_refund_using_two_hop_blinded_path() {
 	assert_ne!(refund.payer_id(), david_id);
 	assert!(!refund.paths().is_empty());
 	for path in refund.paths() {
-		assert_eq!(path.introduction_node_id, charlie_id);
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(charlie_id));
 	}
 	expect_recent_payment!(david, RecentPaymentDetails::AwaitingInvoice, payment_id);
 
@@ -488,7 +488,7 @@ fn creates_and_pays_for_refund_using_two_hop_blinded_path() {
 	assert_ne!(invoice.signing_pubkey(), alice_id);
 	assert!(!invoice.payment_paths().is_empty());
 	for (_, path) in invoice.payment_paths() {
-		assert_eq!(path.introduction_node_id, bob_id);
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(bob_id));
 	}
 
 	route_bolt12_payment(david, &[charlie, bob, alice], &invoice);
@@ -522,7 +522,7 @@ fn creates_and_pays_for_offer_using_one_hop_blinded_path() {
 	assert_ne!(offer.signing_pubkey(), alice_id);
 	assert!(!offer.paths().is_empty());
 	for path in offer.paths() {
-		assert_eq!(path.introduction_node_id, alice_id);
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(alice_id));
 	}
 
 	let payment_id = PaymentId([1; 32]);
@@ -535,7 +535,7 @@ fn creates_and_pays_for_offer_using_one_hop_blinded_path() {
 	let (invoice_request, reply_path) = extract_invoice_request(alice, &onion_message);
 	assert_eq!(invoice_request.amount_msats(), None);
 	assert_ne!(invoice_request.payer_id(), bob_id);
-	assert_eq!(reply_path.unwrap().introduction_node_id, bob_id);
+	assert_eq!(reply_path.unwrap().introduction_node, IntroductionNode::NodeId(bob_id));
 
 	let onion_message = alice.onion_messenger.next_onion_message_for_peer(bob_id).unwrap();
 	bob.onion_messenger.handle_onion_message(&alice_id, &onion_message);
@@ -545,7 +545,7 @@ fn creates_and_pays_for_offer_using_one_hop_blinded_path() {
 	assert_ne!(invoice.signing_pubkey(), alice_id);
 	assert!(!invoice.payment_paths().is_empty());
 	for (_, path) in invoice.payment_paths() {
-		assert_eq!(path.introduction_node_id, alice_id);
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(alice_id));
 	}
 
 	route_bolt12_payment(bob, &[alice], &invoice);
@@ -585,7 +585,7 @@ fn creates_and_pays_for_refund_using_one_hop_blinded_path() {
 	assert_ne!(refund.payer_id(), bob_id);
 	assert!(!refund.paths().is_empty());
 	for path in refund.paths() {
-		assert_eq!(path.introduction_node_id, bob_id);
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(bob_id));
 	}
 	expect_recent_payment!(bob, RecentPaymentDetails::AwaitingInvoice, payment_id);
 
@@ -599,7 +599,7 @@ fn creates_and_pays_for_refund_using_one_hop_blinded_path() {
 	assert_ne!(invoice.signing_pubkey(), alice_id);
 	assert!(!invoice.payment_paths().is_empty());
 	for (_, path) in invoice.payment_paths() {
-		assert_eq!(path.introduction_node_id, alice_id);
+		assert_eq!(path.introduction_node, IntroductionNode::NodeId(alice_id));
 	}
 
 	route_bolt12_payment(bob, &[alice], &invoice);

lightning/src/offers/invoice.rs

@@ -1455,7 +1455,7 @@ mod tests {
 
 	use core::time::Duration;
 
-	use crate::blinded_path::{BlindedHop, BlindedPath};
+	use crate::blinded_path::{BlindedHop, BlindedPath, IntroductionNode};
 	use crate::sign::KeyMaterial;
 	use crate::ln::features::{Bolt12InvoiceFeatures, InvoiceRequestFeatures, OfferFeatures};
 	use crate::ln::inbound_payment::ExpandedKey;
@@ -1804,7 +1804,7 @@ mod tests {
 		let secp_ctx = Secp256k1::new();
 
 		let blinded_path = BlindedPath {
-			introduction_node_id: pubkey(40),
+			introduction_node: IntroductionNode::NodeId(pubkey(40)),
 			blinding_point: pubkey(41),
 			blinded_hops: vec![
 				BlindedHop { blinded_node_id: pubkey(42), encrypted_payload: vec![0; 43] },