Util for blinded paths to configure an async recipient

As part of serving static invoices to payers on behalf of often-offline
recipients, these recipients need a way to contact the static invoice server to
retrieve blinded paths to include in their offers.

Add a utility to create blinded paths for this purpose as a static invoice
server. The recipient will be configured with the resulting paths and use them
to request offer paths on startup.

Author: valentinewallace

lightning/src/blinded_path/message.rs

@@ -405,6 +405,24 @@ pub enum OffersContext {
 /// [`AsyncPaymentsMessage`]: crate::onion_message::async_payments::AsyncPaymentsMessage
 #[derive(Clone, Debug)]
 pub enum AsyncPaymentsContext {
+	/// Context used by a [`BlindedMessagePath`] provided out-of-band to an async recipient, where the
+	/// context is provided back to the static invoice server in corresponding [`OfferPathsRequest`]s.
+	///
+	/// [`OfferPathsRequest`]: crate::onion_message::async_payments::OfferPathsRequest
+	OfferPathsRequest {
+		/// An identifier for the async recipient that is requesting blinded paths to include in their
+		/// [`Offer::paths`]. This ID will be surfaced when the async recipient eventually sends a
+		/// corresponding [`ServeStaticInvoice`] message, and can be used to rate limit the recipient.
+		///
+		/// [`Offer::paths`]: crate::offers::offer::Offer::paths
+		/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+		recipient_id: Vec<u8>,
+		/// An optional field indicating the time as duration since the Unix epoch at which this path
+		/// expires and messages sent over it should be ignored.
+		///
+		/// Useful to timeout async recipients that are no longer supported as clients.
+		path_absolute_expiry: Option<core::time::Duration>,
+	},
 	/// Context used by a reply path to an [`OfferPathsRequest`], provided back to us as an async
 	/// recipient in corresponding [`OfferPaths`] messages from the static invoice server.
 	///
@@ -528,6 +546,10 @@ impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
 		(0, offer_id, required),
 		(2, path_absolute_expiry, required),
 	},
+	(4, OfferPathsRequest) => {
+		(0, recipient_id, required),
+		(2, path_absolute_expiry, option),
+	},
 );
 
 /// Contains a simple nonce for use in a blinded path's context.

lightning/src/ln/channelmanager.rs

@@ -11499,6 +11499,34 @@ where
 		inbound_payment::get_payment_preimage(payment_hash, payment_secret, expanded_key)
 	}
 
+	/// [`BlindedMessagePath`]s for an async recipient to communicate with this node and interactively
+	/// build [`Offer`]s and [`StaticInvoice`]s for receiving async payments.
+	///
+	/// ## Usage
+	/// 1. Static invoice server calls [`Self::blinded_paths_for_async_recipient`]
+	/// 2. Static invoice server communicates the resulting paths out-of-band to the async recipient,
+	///    who calls [`Self::set_paths_to_static_invoice_server`] to configure themselves with these
+	///    paths
+	/// 3. Async recipient automatically sends [`OfferPathsRequest`]s over the configured paths, and
+	///    uses the resulting paths from the server's [`OfferPaths`] response to build their async
+	///    receive offer
+	///
+	/// If `relative_expiry` is unset, the [`BlindedMessagePath`]s will never expire.
+	///
+	/// Returns the paths that the recipient should be configured with via
+	/// [`Self::set_paths_to_static_invoice_server`].
+	///
+	/// The provided `recipient_id` must uniquely identify the recipient, and will be surfaced later
+	/// when the recipient provides us with a static invoice to persist and serve to payers on their
+	/// behalf.
+	#[cfg(async_payments)]
+	pub fn blinded_paths_for_async_recipient(
+		&self, recipient_id: Vec<u8>, relative_expiry: Option<Duration>,
+	) -> Result<Vec<BlindedMessagePath>, ()> {
+		let peers = self.get_peers_for_blinded_path();
+		self.flow.blinded_paths_for_async_recipient(recipient_id, relative_expiry, peers)
+	}
+
 	#[cfg(any(test, async_payments))]
 	pub(super) fn duration_since_epoch(&self) -> Duration {
 		#[cfg(not(feature = "std"))]

lightning/src/offers/flow.rs

@@ -250,6 +250,34 @@ impl<MR: Deref> OffersMessageFlow<MR>
 where
 	MR::Target: MessageRouter,
 {
+	/// [`BlindedMessagePath`]s for an async recipient to communicate with this node and interactively
+	/// build [`Offer`]s and [`StaticInvoice`]s for receiving async payments.
+	///
+	/// If `relative_expiry` is unset, the [`BlindedMessagePath`]s will never expire.
+	///
+	/// Returns the paths that the recipient should be configured with via
+	/// [`Self::set_paths_to_static_invoice_server`].
+	///
+	/// Errors if blinded path creation fails or the provided `recipient_id` is larger than 1KiB.
+	#[cfg(async_payments)]
+	pub(crate) fn blinded_paths_for_async_recipient(
+		&self, recipient_id: Vec<u8>, relative_expiry: Option<Duration>,
+		peers: Vec<MessageForwardNode>,
+	) -> Result<Vec<BlindedMessagePath>, ()> {
+		if recipient_id.len() > 1024 {
+			return Err(());
+		}
+
+		let path_absolute_expiry =
+			relative_expiry.map(|exp| exp.saturating_add(self.duration_since_epoch()));
+
+		let context = MessageContext::AsyncPayments(AsyncPaymentsContext::OfferPathsRequest {
+			recipient_id,
+			path_absolute_expiry,
+		});
+		self.create_blinded_paths(peers, context)
+	}
+
 	/// Creates a collection of blinded paths by delegating to [`MessageRouter`] based on
 	/// the path's intended lifetime.
 	///