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

@@ -11028,9 +11028,29 @@ 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, ()> {
+		let (offer, needs_persist) = self.flow.get_async_receive_offer()?;
+		if needs_persist {
+			// We need to re-persist the cache if a fresh offer was just marked as used to ensure we
+			// continue to keep this offer's invoice updated and don't replace it with the server.
+			let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
+		}
+		Ok(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
@@ -11047,6 +11067,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

@@ -196,6 +196,41 @@ 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, as
+	/// well as returning a bool indicating whether the cache needs to be re-persisted.
+	///
+	// We need to re-persist the cache if a fresh offer was just marked as used to ensure we continue
+	// to keep this offer's invoice updated and don't replace it with the server.
+	pub fn get_async_receive_offer(
+		&mut self, duration_since_epoch: Duration,
+	) -> Result<(Offer, bool), ()> {
+		self.prune_expired_offers(duration_since_epoch, false);
+
+		// Find the freshest unused offer, where "freshness" is based on when the invoice was confirmed
+		// persisted by the server. See `OfferStatus::Ready`.
+		let newest_unused_offer_opt = self
+			.unused_offers()
+			.max_by(|(_, _, persisted_at_a), (_, _, persisted_at_b)| {
+				persisted_at_a.cmp(&persisted_at_b)
+			})
+			.map(|(idx, offer, _)| (idx, offer.offer.clone()));
+		if let Some((idx, newest_ready_offer)) = newest_unused_offer_opt {
+			self.offers[idx].as_mut().map(|offer| offer.status = OfferStatus::Used);
+			return Ok((newest_ready_offer, true));
+		}
+
+		// If no unused offers are available, return the used offer with the latest absolute expiry
+		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(), false))
+			.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, force_reset_request_attempts: bool,

lightning/src/offers/flow.rs

@@ -1134,6 +1134,15 @@ 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, bool), ()> {
+		let mut cache = self.async_receive_offer_cache.lock().unwrap();
+		cache.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.