Send offer paths in response to requests

As part of serving static invoices to payers on behalf of often-offline
recipients, we need to provide the async recipient with blinded message paths
to include in their offers.

Support responding to inbound requests for offer paths from async recipients.

Author: valentinewallace

lightning/src/blinded_path/message.rs

@@ -35,6 +35,7 @@ use bitcoin::hashes::sha256::Hash as Sha256;
 
 use core::mem;
 use core::ops::Deref;
+use core::time::Duration;
 
 /// A blinded path to be used for sending or receiving a message, hiding the identity of the
 /// recipient.
@@ -342,6 +343,43 @@ pub enum OffersContext {
 		/// [`Offer`]: crate::offers::offer::Offer
 		nonce: Nonce,
 	},
+	/// Context used by a [`BlindedMessagePath`] within the [`Offer`] of an async recipient.
+	///
+	/// This variant is received by the static invoice server when handling an [`InvoiceRequest`] on
+	/// behalf of said async recipient.
+	///
+	/// [`Offer`]: crate::offers::offer::Offer
+	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+	StaticInvoiceRequested {
+		/// An identifier for the async recipient for whom we as a static invoice server are serving
+		/// [`StaticInvoice`]s. Used paired with the
+		/// [`OffersContext::StaticInvoiceRequested::invoice_id`] when looking up a corresponding
+		/// [`StaticInvoice`] to return to the payer if the recipient is offline. This id was previously
+		/// provided via [`AsyncPaymentsContext::ServeStaticInvoice::recipient_id`].
+		///
+		/// Also useful for rate limiting the number of [`InvoiceRequest`]s we will respond to on
+		/// recipient's behalf.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		recipient_id: Vec<u8>,
+
+		/// A random unique identifier for a specific [`StaticInvoice`] that the recipient previously
+		/// requested be served on their behalf. Useful when paired with the
+		/// [`OffersContext::StaticInvoiceRequested::recipient_id`] to pull that specific invoice from
+		/// the database when payers send an [`InvoiceRequest`]. This id was previously
+		/// provided via [`AsyncPaymentsContext::ServeStaticInvoice::invoice_id`].
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		invoice_id: u128,
+
+		/// 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: Duration,
+	},
 	/// Context used by a [`BlindedMessagePath`] within a [`Refund`] or as a reply path for an
 	/// [`InvoiceRequest`].
 	///
@@ -438,6 +476,38 @@ pub enum AsyncPaymentsContext {
 		/// [`OfferPaths`]: crate::onion_message::async_payments::OfferPaths
 		path_absolute_expiry: core::time::Duration,
 	},
+	/// Context used by a reply path to an [`OfferPaths`] message, provided back to us as the static
+	/// invoice server in corresponding [`ServeStaticInvoice`] messages.
+	///
+	/// [`OfferPaths`]: crate::onion_message::async_payments::OfferPaths
+	/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+	ServeStaticInvoice {
+		/// An identifier for the async recipient that is requesting that a [`StaticInvoice`] be served
+		/// on their behalf.
+		///
+		/// Useful for retrieving the invoice when payers send an [`InvoiceRequest`] to us as the static
+		/// invoice server. Also useful to rate limit the invoices being persisted on behalf of a
+		/// particular recipient. This id will be provided back to us as the static invoice server via
+		/// [`OffersContext::StaticInvoiceRequested::recipient_id`]
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		recipient_id: Vec<u8>,
+		/// A random unique identifier for the specific [`StaticInvoice`] that the recipient is
+		/// requesting be served on their behalf. Useful when surfaced alongside the above
+		/// `recipient_id` when payers send an [`InvoiceRequest`], to pull the specific static invoice
+		/// from the database. This id will be provided back to us as the static invoice server via
+		/// [`OffersContext::StaticInvoiceRequested::invoice_id`]
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		invoice_id: u128,
+		/// 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: core::time::Duration,
+	},
 	/// Context used by a reply path to a [`ServeStaticInvoice`] message, provided back to us in
 	/// corresponding [`StaticInvoicePersisted`] messages.
 	///
@@ -526,6 +596,11 @@ impl_writeable_tlv_based_enum!(OffersContext,
 		(1, nonce, required),
 		(2, hmac, required)
 	},
+	(3, StaticInvoiceRequested) => {
+		(0, recipient_id, required),
+		(2, invoice_id, required),
+		(4, path_absolute_expiry, required),
+	},
 );
 
 impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
@@ -550,6 +625,11 @@ impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
 		(0, recipient_id, required),
 		(2, path_absolute_expiry, required),
 	},
+	(5, ServeStaticInvoice) => {
+		(0, recipient_id, required),
+		(2, invoice_id, required),
+		(4, path_absolute_expiry, required),
+	},
 );
 
 /// Contains a simple nonce for use in a blinded path's context.

lightning/src/ln/channelmanager.rs

@@ -13482,6 +13482,19 @@ where
 		&self, _message: OfferPathsRequest, _context: AsyncPaymentsContext,
 		_responder: Option<Responder>,
 	) -> Option<(OfferPaths, ResponseInstruction)> {
+		#[cfg(async_payments)]
+		{
+			let peers = self.get_peers_for_blinded_path();
+			let entropy = &*self.entropy_source;
+			let (message, reply_path_context) =
+				match self.flow.handle_offer_paths_request(_context, peers, entropy) {
+					Some(msg) => msg,
+					None => return None,
+				};
+			_responder.map(|resp| (message, resp.respond_with_reply_path(reply_path_context)))
+		}
+
+		#[cfg(not(async_payments))]
 		None
 	}
 

lightning/src/offers/flow.rs

@@ -246,6 +246,10 @@ const OFFERS_MESSAGE_REQUEST_LIMIT: usize = 10;
 #[cfg(async_payments)]
 const TEMP_REPLY_PATH_RELATIVE_EXPIRY: Duration = Duration::from_secs(7200);
 
+// Default to async receive offers and the paths used to update them lasting one year.
+#[cfg(async_payments)]
+const DEFAULT_ASYNC_RECEIVE_OFFER_EXPIRY: Duration = Duration::from_secs(365 * 24 * 60 * 60);
+
 impl<MR: Deref> OffersMessageFlow<MR>
 where
 	MR::Target: MessageRouter,
@@ -1309,6 +1313,69 @@ where
 		}
 	}
 
+	/// Handles an incoming [`OfferPathsRequest`] onion message from an often-offline recipient who
+	/// wants us (the static invoice server) to serve [`StaticInvoice`]s to payers on their behalf.
+	/// Sends out [`OfferPaths`] onion messages in response.
+	#[cfg(async_payments)]
+	pub(crate) fn handle_offer_paths_request<ES: Deref>(
+		&self, context: AsyncPaymentsContext, peers: Vec<MessageForwardNode>, entropy_source: ES,
+	) -> Option<(OfferPaths, MessageContext)>
+	where
+		ES::Target: EntropySource,
+	{
+		let duration_since_epoch = self.duration_since_epoch();
+
+		let recipient_id = match context {
+			AsyncPaymentsContext::OfferPathsRequest { recipient_id, path_absolute_expiry } => {
+				if duration_since_epoch > path_absolute_expiry {
+					return None;
+				}
+				recipient_id
+			},
+			_ => return None,
+		};
+
+		let mut random_bytes = [0u8; 16];
+		random_bytes.copy_from_slice(&entropy_source.get_secure_random_bytes()[..16]);
+		let invoice_id = u128::from_be_bytes(random_bytes);
+
+		// Create the blinded paths that will be included in the async recipient's offer.
+		let (offer_paths, paths_expiry) = {
+			let path_absolute_expiry =
+				duration_since_epoch.saturating_add(DEFAULT_ASYNC_RECEIVE_OFFER_EXPIRY);
+			let context = OffersContext::StaticInvoiceRequested {
+				recipient_id: recipient_id.clone(),
+				path_absolute_expiry,
+				invoice_id,
+			};
+			match self.create_blinded_paths_using_absolute_expiry(
+				context,
+				Some(path_absolute_expiry),
+				peers,
+			) {
+				Ok(paths) => (paths, path_absolute_expiry),
+				Err(()) => return None,
+			}
+		};
+
+		// Create a reply path so that the recipient can respond to our offer_paths message with the
+		// static invoice that they create. This path will also be used by the recipient to update said
+		// invoice.
+		let reply_path_context = {
+			let path_absolute_expiry =
+				duration_since_epoch.saturating_add(DEFAULT_ASYNC_RECEIVE_OFFER_EXPIRY);
+			MessageContext::AsyncPayments(AsyncPaymentsContext::ServeStaticInvoice {
+				recipient_id,
+				invoice_id,
+				path_absolute_expiry,
+			})
+		};
+
+		let offer_paths_om =
+			OfferPaths { paths: offer_paths, paths_absolute_expiry: Some(paths_expiry.as_secs()) };
+		return Some((offer_paths_om, reply_path_context));
+	}
+
 	/// Handles an incoming [`OfferPaths`] message from the static invoice server, sending out
 	/// [`ServeStaticInvoice`] onion messages in response if we've built a new async receive offer and
 	/// need the corresponding [`StaticInvoice`] to be persisted by the static invoice server.