Send static invoice in response to offer paths

As an async recipient, we need to interactively build a static invoice that an
always-online node will serve to payers on our behalf.

As part of this process, the static invoice server sends us blinded message
paths to include in our offer so they'll receive invoice requests from senders
trying to pay us while we're offline. On receipt of these paths, create an
offer and static invoice and send the invoice back to the server so they can
provide the invoice to payers, as well as caching the offer as pending.

Author: valentinewallace

lightning/src/blinded_path/message.rs

@@ -23,6 +23,7 @@ use crate::ln::channelmanager::PaymentId;
 use crate::ln::msgs::DecodeError;
 use crate::ln::onion_utils;
 use crate::offers::nonce::Nonce;
+use crate::offers::offer::OfferId;
 use crate::onion_message::packet::ControlTlvs;
 use crate::routing::gossip::{NodeId, ReadOnlyNetworkGraph};
 use crate::sign::{EntropySource, NodeSigner, Recipient};
@@ -419,6 +420,25 @@ pub enum AsyncPaymentsContext {
 		/// [`OfferPaths`]: crate::onion_message::async_payments::OfferPaths
 		path_absolute_expiry: core::time::Duration,
 	},
+	/// Context used by a reply path to a [`ServeStaticInvoice`] message, provided back to us in
+	/// corresponding [`StaticInvoicePersisted`] messages.
+	///
+	/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+	/// [`StaticInvoicePersisted`]: crate::onion_message::async_payments::StaticInvoicePersisted
+	StaticInvoicePersisted {
+		/// The id of the offer in the cache corresponding to the [`StaticInvoice`] that has been
+		/// persisted. This invoice is now ready to be provided by the static invoice server in response
+		/// to [`InvoiceRequest`]s, so the corresponding offer can be marked as ready to receive
+		/// payments.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		offer_id: OfferId,
+		/// The time as duration since the Unix epoch at which this path expires and messages sent over
+		/// it should be ignored. If we receive confirmation of an invoice over this path after its
+		/// expiry, it may be outdated and a new invoice update should be sent instead.
+		path_absolute_expiry: core::time::Duration,
+	},
 	/// Context contained within the reply [`BlindedMessagePath`] we put in outbound
 	/// [`HeldHtlcAvailable`] messages, provided back to us in corresponding [`ReleaseHeldHtlc`]
 	/// messages.
@@ -504,6 +524,10 @@ impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
 	(2, OfferPaths) => {
 		(0, path_absolute_expiry, required),
 	},
+	(3, StaticInvoicePersisted) => {
+		(0, offer_id, required),
+		(2, path_absolute_expiry, required),
+	},
 );
 
 /// Contains a simple nonce for use in a blinded path's context.

lightning/src/ln/channelmanager.rs

@@ -13426,7 +13426,34 @@ where
 	fn handle_offer_paths(
 		&self, _message: OfferPaths, _context: AsyncPaymentsContext, _responder: Option<Responder>,
 	) -> Option<(ServeStaticInvoice, ResponseInstruction)> {
-		None
+		#[cfg(async_payments)]
+		{
+			let responder = match _responder {
+				Some(responder) => responder,
+				None => return None,
+			};
+			let (serve_static_invoice, reply_context) = match self.flow.handle_offer_paths(
+				_message,
+				_context,
+				responder.clone(),
+				self.get_peers_for_blinded_path(),
+				self.list_usable_channels(),
+				&*self.entropy_source,
+				&*self.router,
+			) {
+				Some((msg, ctx)) => (msg, ctx),
+				None => return None,
+			};
+
+			// We cached a new pending offer, so persist the cache.
+			let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
+
+			let response_instructions = responder.respond_with_reply_path(reply_context);
+			return Some((serve_static_invoice, response_instructions));
+		}
+
+		#[cfg(not(async_payments))]
+		return None;
 	}
 
 	fn handle_serve_static_invoice(

lightning/src/ln/inbound_payment.rs

@@ -214,7 +214,7 @@ pub fn create_from_hash(
 }
 
 #[cfg(async_payments)]
-pub(super) fn create_for_spontaneous_payment(
+pub(crate) fn create_for_spontaneous_payment(
 	keys: &ExpandedKey, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32,
 	current_time: u64, min_final_cltv_expiry_delta: Option<u16>,
 ) -> Result<PaymentSecret, ()> {

lightning/src/offers/async_receive_offer_cache.rs

@@ -186,6 +186,10 @@ const MAX_UPDATE_ATTEMPTS: u8 = 3;
 #[cfg(async_payments)]
 const OFFER_REFRESH_THRESHOLD: Duration = Duration::from_secs(2 * 60 * 60);
 
+// Require offer paths that we receive to last at least 3 months.
+#[cfg(async_payments)]
+const MIN_OFFER_PATHS_RELATIVE_EXPIRY_SECS: u64 = 3 * 30 * 24 * 60 * 60;
+
 #[cfg(async_payments)]
 impl AsyncReceiveOfferCache {
 	/// Remove expired offers from the cache, returning whether new offers are needed.
@@ -214,6 +218,71 @@ impl AsyncReceiveOfferCache {
 			&& self.offer_paths_request_attempts < MAX_UPDATE_ATTEMPTS
 	}
 
+	/// Returns whether the new paths we've just received from the static invoice server should be used
+	/// to build a new offer.
+	pub(super) fn should_build_offer_with_paths(
+		&self, offer_paths: &[BlindedMessagePath], offer_paths_absolute_expiry_secs: Option<u64>,
+		duration_since_epoch: Duration,
+	) -> bool {
+		if self.needs_new_offer_idx(duration_since_epoch).is_none() {
+			return false;
+		}
+
+		// Require the offer that would be built using these paths to last at least
+		// MIN_OFFER_PATHS_RELATIVE_EXPIRY_SECS.
+		let min_offer_paths_absolute_expiry =
+			duration_since_epoch.as_secs().saturating_add(MIN_OFFER_PATHS_RELATIVE_EXPIRY_SECS);
+		let offer_paths_absolute_expiry = offer_paths_absolute_expiry_secs.unwrap_or(u64::MAX);
+		if offer_paths_absolute_expiry < min_offer_paths_absolute_expiry {
+			return false;
+		}
+
+		// Check that we don't have any current offers that already contain these paths
+		self.offers_with_idx().all(|(_, offer)| offer.offer.paths() != offer_paths)
+	}
+
+	/// We've sent a static invoice to the static invoice server for persistence. Cache the
+	/// corresponding pending offer so we can retry persisting a corresponding invoice with the server
+	/// until it succeeds.
+	///
+	/// We need to keep retrying an invoice for this particular offer until it succeeds to prevent
+	/// edge cases where we send invoices from different offers competing for the same slot on the
+	/// server's end, receive messages out-of-order, and end up returning an offer to the user where
+	/// the server just deleted and replaced the corresponding invoice. See `OFFER_REFRESH_THRESHOLD`.
+	pub(super) fn cache_pending_offer(
+		&mut self, offer: Offer, offer_paths_absolute_expiry_secs: Option<u64>, offer_nonce: Nonce,
+		update_static_invoice_path: Responder, duration_since_epoch: Duration,
+	) -> Result<u8, ()> {
+		self.prune_expired_offers(duration_since_epoch, false);
+
+		if !self.should_build_offer_with_paths(
+			offer.paths(),
+			offer_paths_absolute_expiry_secs,
+			duration_since_epoch,
+		) {
+			return Err(());
+		}
+
+		let idx = match self.needs_new_offer_idx(duration_since_epoch) {
+			Some(idx) => idx,
+			None => return Err(()),
+		};
+
+		match self.offers.get_mut(idx) {
+			Some(offer_opt) => {
+				*offer_opt = Some(AsyncReceiveOffer {
+					offer,
+					offer_nonce,
+					status: OfferStatus::Pending,
+					update_static_invoice_path,
+				});
+			},
+			None => return Err(()),
+		}
+
+		Ok(idx.try_into().map_err(|_| ())?)
+	}
+
 	/// If we have any empty slots in the cache or offers where the offer can and should be replaced
 	/// with a fresh offer, here we return the index of the slot that needs a new offer. The index is
 	/// used for setting [`ServeStaticInvoice::invoice_slot`] when sending the corresponding new

lightning/src/offers/flow.rs

@@ -66,7 +66,10 @@ use {
 	crate::offers::offer::Amount,
 	crate::offers::signer,
 	crate::offers::static_invoice::{StaticInvoice, StaticInvoiceBuilder},
-	crate::onion_message::async_payments::{HeldHtlcAvailable, OfferPathsRequest},
+	crate::onion_message::async_payments::{
+		HeldHtlcAvailable, OfferPaths, OfferPathsRequest, ServeStaticInvoice,
+	},
+	crate::onion_message::messenger::Responder,
 };
 
 #[cfg(feature = "dnssec")]
@@ -1189,6 +1192,156 @@ where
 		Ok(())
 	}
 
+	/// 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.
+	///
+	/// Returns `None` if we have enough offers cached already, verification of `message` fails, or we
+	/// fail to create blinded paths.
+	#[cfg(async_payments)]
+	pub(crate) fn handle_offer_paths<ES: Deref, R: Deref>(
+		&self, message: OfferPaths, context: AsyncPaymentsContext, responder: Responder,
+		peers: Vec<MessageForwardNode>, usable_channels: Vec<ChannelDetails>, entropy: ES,
+		router: R,
+	) -> Option<(ServeStaticInvoice, MessageContext)>
+	where
+		ES::Target: EntropySource,
+		R::Target: Router,
+	{
+		let duration_since_epoch = self.duration_since_epoch();
+		match context {
+			AsyncPaymentsContext::OfferPaths { path_absolute_expiry } => {
+				if duration_since_epoch > path_absolute_expiry {
+					return None;
+				}
+			},
+			_ => return None,
+		}
+
+		{
+			// Only respond with `ServeStaticInvoice` if we actually need a new offer built.
+			let mut cache = self.async_receive_offer_cache.lock().unwrap();
+			cache.prune_expired_offers(duration_since_epoch, false);
+			if !cache.should_build_offer_with_paths(
+				&message.paths[..],
+				message.paths_absolute_expiry,
+				duration_since_epoch,
+			) {
+				return None;
+			}
+		}
+
+		let (mut offer_builder, offer_nonce) =
+			match self.create_async_receive_offer_builder(&*entropy, message.paths) {
+				Ok((builder, nonce)) => (builder, nonce),
+				Err(_) => return None, // Only reachable if OfferPaths::paths is empty
+			};
+		if let Some(paths_absolute_expiry) = message.paths_absolute_expiry {
+			offer_builder =
+				offer_builder.absolute_expiry(Duration::from_secs(paths_absolute_expiry));
+		}
+		let (offer_id, offer) = match offer_builder.build() {
+			Ok(offer) => (offer.id(), offer),
+			Err(_) => {
+				debug_assert!(false);
+				return None;
+			},
+		};
+
+		let (invoice, forward_invoice_request_path) = match self.create_static_invoice_for_server(
+			&offer,
+			offer_nonce,
+			peers,
+			usable_channels,
+			&*entropy,
+			router,
+		) {
+			Ok(res) => res,
+			Err(()) => return None,
+		};
+
+		let res = self.async_receive_offer_cache.lock().unwrap().cache_pending_offer(
+			offer,
+			message.paths_absolute_expiry,
+			offer_nonce,
+			responder,
+			duration_since_epoch,
+		);
+
+		let invoice_slot = match res {
+			Ok(idx) => idx,
+			Err(()) => return None,
+		};
+
+		let reply_path_context = {
+			let path_absolute_expiry =
+				duration_since_epoch.saturating_add(TEMP_REPLY_PATH_RELATIVE_EXPIRY);
+			MessageContext::AsyncPayments(AsyncPaymentsContext::StaticInvoicePersisted {
+				offer_id,
+				path_absolute_expiry,
+			})
+		};
+
+		let serve_invoice_message =
+			ServeStaticInvoice { invoice, forward_invoice_request_path, invoice_slot };
+		Some((serve_invoice_message, reply_path_context))
+	}
+
+	/// Creates a [`StaticInvoice`] and a blinded path for the server to forward invoice requests from
+	/// payers to our node.
+	#[cfg(async_payments)]
+	fn create_static_invoice_for_server<ES: Deref, R: Deref>(
+		&self, offer: &Offer, offer_nonce: Nonce, peers: Vec<MessageForwardNode>,
+		usable_channels: Vec<ChannelDetails>, entropy: ES, router: R,
+	) -> Result<(StaticInvoice, BlindedMessagePath), ()>
+	where
+		ES::Target: EntropySource,
+		R::Target: Router,
+	{
+		let expanded_key = &self.inbound_payment_key;
+		let duration_since_epoch = self.duration_since_epoch();
+		let secp_ctx = &self.secp_ctx;
+
+		let offer_relative_expiry = offer
+			.absolute_expiry()
+			.map(|exp| exp.saturating_sub(duration_since_epoch).as_secs())
+			.map(|exp_u64| exp_u64.try_into().unwrap_or(u32::MAX))
+			.unwrap_or(u32::MAX);
+
+		// Set the invoice to expire at the same time as the offer. We aim to update this invoice as
+		// often as possible, so there shouldn't be any reason to have it expire earlier than the
+		// offer.
+		let payment_secret = inbound_payment::create_for_spontaneous_payment(
+			expanded_key,
+			None, // The async receive offers we create are always amount-less
+			offer_relative_expiry,
+			duration_since_epoch.as_secs(),
+			None,
+		)?;
+
+		let invoice = self
+			.create_static_invoice_builder(
+				&router,
+				&*entropy,
+				&offer,
+				offer_nonce,
+				payment_secret,
+				offer_relative_expiry,
+				usable_channels,
+				peers.clone(),
+			)
+			.and_then(|builder| builder.build_and_sign(secp_ctx))
+			.map_err(|_| ())?;
+
+		let nonce = Nonce::from_entropy_source(&*entropy);
+		let context = MessageContext::Offers(OffersContext::InvoiceRequest { nonce });
+		let forward_invoice_request_path = self
+			.create_blinded_paths(peers, context)
+			.and_then(|paths| paths.into_iter().next().ok_or(()))?;
+
+		Ok((invoice, forward_invoice_request_path))
+	}
+
 	/// Get the `AsyncReceiveOfferCache` for persistence.
 	pub(crate) fn writeable_async_receive_offer_cache(&self) -> impl Writeable + '_ {
 		&self.async_receive_offer_cache