From: Jeffrey Czyz <jkczyz@gmail.com>
Date: Thu, 30 May 2024 19:38:15 +0000 (-0500)
Subject: Clarify docs regarding one-hop blinded paths
X-Git-Tag: v0.0.124-beta~93^2
X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=commitdiff_plain;h=c17a026b0716a1226f1803f31645b9707eaf36f3;p=rust-lightning

Clarify docs regarding one-hop blinded paths

The docs assumed ChannelManager is parameterized by DefaultRouter, which
may not be the case. Clarify the behavior is specific to using
DefaultRouter.
---

diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
index 7e81730ce..992fd3c6f 100644
--- a/lightning/src/ln/channelmanager.rs
+++ b/lightning/src/ln/channelmanager.rs
@@ -8261,10 +8261,8 @@ macro_rules! create_offer_builder { ($self: ident, $builder: ty) => {
 	///
 	/// Uses [`MessageRouter`] to construct a [`BlindedPath`] for the offer based on the given
 	/// `absolute_expiry` according to [`MAX_SHORT_LIVED_RELATIVE_EXPIRY`]. See those docs for
-	/// privacy implications. However, if one is not found, uses a one-hop [`BlindedPath`] with
-	/// [`ChannelManager::get_our_node_id`] as the introduction node instead. In the latter case,
-	/// the node must be announced, otherwise, there is no way to find a path to the introduction
-	/// node in order to send the [`InvoiceRequest`].
+	/// privacy implications as well as those of the parameterized [`Router`], which implements
+	/// [`MessageRouter`].
 	///
 	/// Also, uses a derived signing pubkey in the offer for recipient privacy.
 	///
@@ -8329,10 +8327,8 @@ macro_rules! create_refund_builder { ($self: ident, $builder: ty) => {
 	///
 	/// Uses [`MessageRouter`] to construct a [`BlindedPath`] for the refund based on the given
 	/// `absolute_expiry` according to [`MAX_SHORT_LIVED_RELATIVE_EXPIRY`]. See those docs for
-	/// privacy implications. However, if one is not found, uses a one-hop [`BlindedPath`] with
-	/// [`ChannelManager::get_our_node_id`] as the introduction node instead. In the latter case,
-	/// the node must be announced, otherwise, there is no way to find a path to the introduction
-	/// node in order to send the [`Bolt12Invoice`].
+	/// privacy implications as well as those of the parameterized [`Router`], which implements
+	/// [`MessageRouter`].
 	///
 	/// Also, uses a derived payer id in the refund for payer privacy.
 	///
@@ -8431,10 +8427,9 @@ where
 	///
 	/// # Privacy
 	///
-	/// Uses a one-hop [`BlindedPath`] for the reply path with [`ChannelManager::get_our_node_id`]
-	/// as the introduction node and a derived payer id for payer privacy. As such, currently, the
-	/// node must be announced. Otherwise, there is no way to find a path to the introduction node
-	/// in order to send the [`Bolt12Invoice`].
+	/// For payer privacy, uses a derived payer id and uses [`MessageRouter::create_blinded_paths`]
+	/// to construct a [`BlindedPath`] for the reply path. For further privacy implications, see the
+	/// docs of the parameterized [`Router`], which implements [`MessageRouter`].
 	///
 	/// # Limitations
 	///
diff --git a/lightning/src/onion_message/messenger.rs b/lightning/src/onion_message/messenger.rs
index 5ceb0683c..ee49d00e9 100644
--- a/lightning/src/onion_message/messenger.rs
+++ b/lightning/src/onion_message/messenger.rs
@@ -456,6 +456,13 @@ pub trait MessageRouter {
 }
 
 /// A [`MessageRouter`] that can only route to a directly connected [`Destination`].
+///
+/// # Privacy
+///
+/// Creating [`BlindedPath`]s may affect privacy since, if a suitable path cannot be found, it will
+/// create a one-hop path using the recipient as the introduction node if it is a announced node.
+/// Otherwise, there is no way to find a path to the introduction node in order to send a message,
+/// and thus an `Err` is returned.
 pub struct DefaultMessageRouter<G: Deref<Target=NetworkGraph<L>>, L: Deref, ES: Deref>
 where
 	L::Target: Logger,
diff --git a/lightning/src/routing/router.rs b/lightning/src/routing/router.rs
index c105e9146..5b202604e 100644
--- a/lightning/src/routing/router.rs
+++ b/lightning/src/routing/router.rs
@@ -36,6 +36,11 @@ use core::{cmp, fmt};
 use core::ops::Deref;
 
 /// A [`Router`] implemented using [`find_route`].
+///
+/// # Privacy
+///
+/// Implements [`MessageRouter`] by delegating to [`DefaultMessageRouter`]. See those docs for
+/// privacy implications.
 pub struct DefaultRouter<G: Deref<Target = NetworkGraph<L>> + Clone, L: Deref, ES: Deref, S: Deref, SP: Sized, Sc: ScoreLookUp<ScoreParams = SP>> where
 	L::Target: Logger,
 	S::Target: for <'a> LockableScore<'a, ScoreLookUp = Sc>,