Add API to retrieve a cached async receive offer

Over the past multiple commits we've implemented interactively building async
receive offers with a static invoice server that will service invoice requests
on our behalf as an async recipient.

Here we add an API to retrieve a resulting offer so we can receive payments
when we're offline.

Author: valentinewallace

lightning/src/ln/channelmanager.rs

@@ -10749,9 +10749,23 @@ where
 	#[cfg(c_bindings)]
 	create_refund_builder!(self, RefundMaybeWithDerivedMetadataBuilder);
 
+	/// Retrieve an [`Offer`] for receiving async payments as an often-offline recipient. Will only
+	/// return an offer if [`Self::set_paths_to_static_invoice_server`] was called and we succeeded in
+	/// interactively building a [`StaticInvoice`] with the static invoice server.
+	///
+	/// Useful for posting offers to receive payments later, such as posting an offer on a website.
+	#[cfg(async_payments)]
+	pub fn get_async_receive_offer(&self) -> Result<Offer, ()> {
+		self.flow.get_async_receive_offer()
+	}
+
 	/// Create an offer for receiving async payments as an often-offline recipient.
 	///
-	/// Because we may be offline when the payer attempts to request an invoice, you MUST:
+	/// Instead of using this method, it is preferable to call
+	/// [`Self::set_paths_to_static_invoice_server`] and retrieve the automatically built offer via
+	/// [`Self::get_async_receive_offer`].
+	///
+	/// If you want to build the [`StaticInvoice`] manually using this method instead, you MUST:
 	/// 1. Provide at least 1 [`BlindedMessagePath`] terminating at an always-online node that will
 	///    serve the [`StaticInvoice`] created from this offer on our behalf.
 	/// 2. Use [`Self::create_static_invoice_builder`] to create a [`StaticInvoice`] from this
@@ -10768,6 +10782,10 @@ where
 	/// Creates a [`StaticInvoiceBuilder`] from the corresponding [`Offer`] and [`Nonce`] that were
 	/// created via [`Self::create_async_receive_offer_builder`]. If `relative_expiry` is unset, the
 	/// invoice's expiry will default to [`STATIC_INVOICE_DEFAULT_RELATIVE_EXPIRY`].
+	///
+	/// Instead of using this method to manually build the invoice, it is preferable to set
+	/// [`Self::set_paths_to_static_invoice_server`] and retrieve the automatically built offer via
+	/// [`Self::get_async_receive_offer`].
 	#[cfg(async_payments)]
 	pub fn create_static_invoice_builder<'a>(
 		&self, offer: &'a Offer, offer_nonce: Nonce, relative_expiry: Option<Duration>,

lightning/src/offers/async_receive_offer_cache.rs

@@ -155,6 +155,39 @@ const MIN_OFFER_PATHS_RELATIVE_EXPIRY_SECS: u64 = 3 * 30 * 24 * 60 * 60;
 
 #[cfg(async_payments)]
 impl AsyncReceiveOfferCache {
+	/// Retrieve a cached [`Offer`] for receiving async payments as an often-offline recipient.
+	pub fn get_async_receive_offer(&mut self, duration_since_epoch: Duration) -> Result<Offer, ()> {
+		self.prune_expired_offers(duration_since_epoch, false);
+
+		// Find the freshest unused offer based on when the invoice was confirmed persisted by the
+		// server
+		let newest_ready_offer_opt = {
+			self.offers_with_idx()
+				.filter_map(|(idx, offer)| match offer.status {
+					OfferStatus::Ready { invoice_confirmed_persisted_at } => {
+						Some((idx, offer, invoice_confirmed_persisted_at))
+					},
+					_ => None,
+				})
+				.max_by(|a, b| a.2.cmp(&b.2))
+				.map(|(idx, offer, _)| (idx, offer.offer.clone()))
+		};
+		if let Some((idx, newest_ready_offer)) = newest_ready_offer_opt {
+			self.offers[idx].as_mut().map(|offer| offer.status = OfferStatus::Used);
+			return Ok(newest_ready_offer);
+		}
+
+		self.offers_with_idx()
+			.filter(|(_, offer)| matches!(offer.status, OfferStatus::Used))
+			.max_by(|a, b| {
+				let abs_expiry_a = a.1.offer.absolute_expiry().unwrap_or(Duration::MAX);
+				let abs_expiry_b = b.1.offer.absolute_expiry().unwrap_or(Duration::MAX);
+				abs_expiry_a.cmp(&abs_expiry_b)
+			})
+			.map(|(_, cache_offer)| cache_offer.offer.clone())
+			.ok_or(())
+	}
+
 	/// Remove expired offers from the cache, returning whether new offers are needed.
 	pub(super) fn prune_expired_offers(
 		&mut self, duration_since_epoch: Duration, timer_tick_occurred: bool,

lightning/src/offers/flow.rs

@@ -1127,6 +1127,17 @@ where
 		core::mem::take(&mut self.pending_dns_onion_messages.lock().unwrap())
 	}
 
+	/// Retrieve an [`Offer`] for receiving async payments as an often-offline recipient. Will only
+	/// return an offer if [`Self::set_paths_to_static_invoice_server`] was called and we succeeded in
+	/// interactively building a [`StaticInvoice`] with the static invoice server.
+	#[cfg(async_payments)]
+	pub(crate) fn get_async_receive_offer(&self) -> Result<Offer, ()> {
+		self.async_receive_offer_cache
+			.lock()
+			.unwrap()
+			.get_async_receive_offer(self.duration_since_epoch())
+	}
+
 	/// Sends out [`OfferPathsRequest`] and [`ServeStaticInvoice`] onion messages if we are an
 	/// often-offline recipient and are configured to interactively build offers and static invoices
 	/// with a static invoice server.