f - rearrange docs

lightningdevkit · May 31, 2024 · ffbe363 · ffbe363
1 parent f228988
commit ffbe363
Show file tree

Hide file tree

Showing 3 changed files with 19 additions and 22 deletions.
diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
@@ -8563,14 +8563,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.
-	///
-	/// The [`Router`] used to parameterized [`ChannelManager`] may also affect privacy since it
-	/// implements [`MessageRouter`]. If parameterized with [`DefaultRouter`], it will delegate to
-	/// [`DefaultMessageRouter`]. In that case, it may return a one-hop [`BlindedPath`] with
-	/// [`ChannelManager::get_our_node_id`] as the introduction node if no other path can be found
-	/// *and* the node is announced. Otherwise, there is no way to find a path to the introduction
-	/// 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.
 	///
@@ -8584,7 +8578,6 @@ macro_rules! create_offer_builder { ($self: ident, $builder: ty) => {
 	/// Errors if the parameterized [`Router`] is unable to create a blinded path for the offer.
 	///
 	/// [`Offer`]: crate::offers::offer::Offer
-	/// [`DefaultMessageRouter`]: crate::onion_message::messenger::DefaultMessageRouter
 	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 	pub fn create_offer_builder(
 		&$self, absolute_expiry: Option<Duration>
@@ -8636,14 +8629,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.
-	///
-	/// The [`Router`] used to parameterized [`ChannelManager`] may also affect privacy since it
-	/// implements [`MessageRouter`]. If parameterized with [`DefaultRouter`], it will delegate to
-	/// [`DefaultMessageRouter`]. In that case, it may return a one-hop [`BlindedPath`] with
-	/// [`ChannelManager::get_our_node_id`] as the introduction node if no other path can be found
-	/// *and* the node is announced. Otherwise, there is no way to find a path to the introduction
-	/// 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.
 	///
@@ -8660,7 +8647,6 @@ macro_rules! create_refund_builder { ($self: ident, $builder: ty) => {
 	/// - the parameterized [`Router`] is unable to create a blinded path for the refund.
 	///
 	/// [`Refund`]: crate::offers::refund::Refund
-	/// [`DefaultMessageRouter`]: crate::onion_message::messenger::DefaultMessageRouter
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 	/// [`Bolt12Invoice::payment_paths`]: crate::offers::invoice::Bolt12Invoice::payment_paths
 	/// [Avoiding Duplicate Payments]: #avoiding-duplicate-payments
@@ -8743,10 +8729,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
@@ -371,6 +371,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
@@ -35,6 +35,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>,