Add async offer refresh readiness APIs

To enable suppoort for async payments via LSPS2 JIT channels, we expose
explicit async receive-offer refresh and readiness waiting so
integrators can sequence external setup before relying on a ready async
offer, instead of polling timer ticks.

Generated with AI assistance.

Co-Authored-By: HAL 9000

Author: tnull

lightning-liquidity/src/lsps2/router.rs

@@ -94,10 +94,11 @@ impl<R: Router, ES: EntropySource> LSPS2BOLT12Router<R, ES> {
 	fn registered_lsps2_params(
 		&self, payment_context: &PaymentContext,
 	) -> Vec<LSPS2Bolt12InvoiceParameters> {
-		// We intentionally only match `Bolt12Offer` here and not `AsyncBolt12Offer`, as LSPS2
-		// JIT channels are not applicable to async (always-online) BOLT12 offer flows.
+		// LSPS2 paths are applicable both to normal offers and async offers that resolve via a
+		// static invoice server. In both cases the intercept SCID lets the LSP intercept the HTLC
+		// and open the JIT channel before forwarding the payment.
 		match payment_context {
-			PaymentContext::Bolt12Offer(_) => {},
+			PaymentContext::Bolt12Offer(_) | PaymentContext::AsyncBolt12Offer(_) => {},
 			_ => return Vec::new(),
 		};
 

lightning/src/ln/channelmanager.rs

@@ -5857,30 +5857,46 @@ impl<
 		)
 	}
 
-	fn check_refresh_async_receive_offer_cache(&self, timer_tick_occurred: bool) {
+	fn check_refresh_async_receive_offer_cache(&self, timer_tick_occurred: bool) -> Result<(), ()> {
 		let peers = self.get_peers_for_blinded_path();
 		let channels = self.list_usable_channels();
 		let router = &self.router;
-		let refresh_res = self.flow.check_refresh_async_receive_offer_cache(
+		self.flow.check_refresh_async_receive_offer_cache(
 			peers,
 			channels,
 			router,
 			timer_tick_occurred,
-		);
-		match refresh_res {
-			Err(()) => {
-				log_error!(
-					self.logger,
-					"Failed to create blinded paths when requesting async receive offer paths"
-				);
-			},
-			Ok(()) => {},
-		}
+		)
 	}
 
 	#[cfg(test)]
 	pub(crate) fn test_check_refresh_async_receive_offers(&self) {
-		self.check_refresh_async_receive_offer_cache(false);
+		self.check_refresh_async_receive_offer_cache(false).unwrap();
+	}
+
+	/// Requests fresh async receive offer paths from the configured static invoice server, if any.
+	pub fn refresh_async_receive_offers(&self) -> Result<(), ()> {
+		self.check_refresh_async_receive_offer_cache(false).map_err(|()| {
+			log_error!(
+				self.logger,
+				"Failed to create blinded paths when requesting async receive offer paths"
+			);
+		})
+	}
+
+	/// Waits for an async receive offer to become ready after the interactive static-invoice
+	/// protocol completes.
+	#[cfg(feature = "std")]
+	pub fn await_async_receive_offer(&self, max_wait: Duration) -> Result<Offer, ()> {
+		if let Ok(offer) = self.get_async_receive_offer() {
+			return Ok(offer);
+		}
+
+		if !self.flow.wait_for_async_receive_offer_ready(max_wait) {
+			return Err(());
+		}
+
+		self.get_async_receive_offer()
 	}
 
 	/// Should be called after handling an [`Event::PersistStaticInvoice`], where the `Responder`
@@ -9101,7 +9117,12 @@ impl<
 			self.pending_outbound_payments
 				.remove_stale_payments(duration_since_epoch, &self.pending_events);
 
-			self.check_refresh_async_receive_offer_cache(true);
+			let _ = self.check_refresh_async_receive_offer_cache(true).map_err(|()| {
+				log_error!(
+					self.logger,
+					"Failed to create blinded paths when requesting async receive offer paths"
+				);
+			});
 
 			if self.check_free_holding_cells() {
 				// While we try to ensure we clear holding cells immediately, its possible we miss
@@ -15807,7 +15828,12 @@ impl<
 		// interactively building offers as soon as we can after startup. We can't start building offers
 		// until we have some peer connection(s) to receive onion messages over, so as a minor optimization
 		// refresh the cache when a peer connects.
-		self.check_refresh_async_receive_offer_cache(false);
+		let _ = self.check_refresh_async_receive_offer_cache(false).map_err(|()| {
+			log_error!(
+				self.logger,
+				"Failed to create blinded paths when requesting async receive offer paths"
+			);
+		});
 		res
 	}
 

lightning/src/offers/flow.rs

@@ -61,6 +61,8 @@ use crate::sync::{Mutex, RwLock};
 use crate::types::payment::{PaymentHash, PaymentSecret};
 use crate::util::logger::Logger;
 use crate::util::ser::Writeable;
+#[cfg(feature = "std")]
+use crate::util::wakers::Notifier;
 
 /// A BOLT12 offers code and flow utility provider, which facilitates
 /// BOLT12 builder generation and onion message handling.
@@ -87,6 +89,8 @@ pub struct OffersMessageFlow<MR: MessageRouter, L: Logger> {
 
 	pending_async_payments_messages: Mutex<Vec<(AsyncPaymentsMessage, MessageSendInstructions)>>,
 	async_receive_offer_cache: Mutex<AsyncReceiveOfferCache>,
+	#[cfg(feature = "std")]
+	async_receive_offer_ready_notifier: Notifier,
 
 	logger: L,
 }
@@ -116,6 +120,8 @@ impl<MR: MessageRouter, L: Logger> OffersMessageFlow<MR, L> {
 			pending_async_payments_messages: Mutex::new(Vec::new()),
 
 			async_receive_offer_cache: Mutex::new(AsyncReceiveOfferCache::new()),
+			#[cfg(feature = "std")]
+			async_receive_offer_ready_notifier: Notifier::new(),
 
 			logger,
 		}
@@ -1361,7 +1367,6 @@ impl<MR: MessageRouter, L: Logger> OffersMessageFlow<MR, L> {
 				Some(idx) => idx,
 				None => return Ok(()),
 			};
-
 		// If we need new offers, send out offer paths request messages to the static invoice server.
 		let context = MessageContext::AsyncPayments(AsyncPaymentsContext::OfferPaths {
 			path_absolute_expiry: duration_since_epoch
@@ -1475,7 +1480,6 @@ impl<MR: MessageRouter, L: Logger> OffersMessageFlow<MR, L> {
 			},
 			_ => return None,
 		};
-
 		// Create the blinded paths that will be included in the async recipient's offer.
 		let (offer_paths, paths_expiry) = {
 			let path_absolute_expiry =
@@ -1537,7 +1541,6 @@ impl<MR: MessageRouter, L: Logger> OffersMessageFlow<MR, L> {
 			},
 			_ => return None,
 		};
-
 		{
 			// Only respond with `ServeStaticInvoice` if we actually need a new offer built.
 			let mut cache = self.async_receive_offer_cache.lock().unwrap();
@@ -1569,7 +1572,6 @@ impl<MR: MessageRouter, L: Logger> OffersMessageFlow<MR, L> {
 				return None;
 			},
 		};
-
 		let (invoice, forward_invoice_request_path) = match self.create_static_invoice_for_server(
 			&offer,
 			offer_nonce,
@@ -1583,7 +1585,6 @@ impl<MR: MessageRouter, L: Logger> OffersMessageFlow<MR, L> {
 				return None;
 			},
 		};
-
 		if let Err(()) = self.async_receive_offer_cache.lock().unwrap().cache_pending_offer(
 			offer,
 			message.paths_absolute_expiry,
@@ -1595,7 +1596,6 @@ impl<MR: MessageRouter, L: Logger> OffersMessageFlow<MR, L> {
 			log_error!(self.logger, "Failed to cache pending offer");
 			return None;
 		}
-
 		let reply_path_context = {
 			MessageContext::AsyncPayments(AsyncPaymentsContext::StaticInvoicePersisted {
 				offer_id,
@@ -1711,7 +1711,17 @@ impl<MR: MessageRouter, L: Logger> OffersMessageFlow<MR, L> {
 	/// [`StaticInvoicePersisted`]: crate::onion_message::async_payments::StaticInvoicePersisted
 	pub fn handle_static_invoice_persisted(&self, context: AsyncPaymentsContext) -> bool {
 		let mut cache = self.async_receive_offer_cache.lock().unwrap();
-		cache.static_invoice_persisted(context)
+		let updated = cache.static_invoice_persisted(context);
+		#[cfg(feature = "std")]
+		if updated {
+			self.async_receive_offer_ready_notifier.notify();
+		}
+		updated
+	}
+
+	#[cfg(feature = "std")]
+	pub(crate) fn wait_for_async_receive_offer_ready(&self, max_wait: Duration) -> bool {
+		self.async_receive_offer_ready_notifier.get_future().wait_timeout(max_wait)
 	}
 
 	/// Get the encoded [`AsyncReceiveOfferCache`] for persistence.