Add async offer refresh readiness APIs

Let async recipients refresh receive offers explicitly, wait for
readiness, and preserve payment metadata across static-invoice
refreshes.

Co-Authored-By: HAL 9000

Author: tnull

lightning/src/ln/channelmanager.rs

@@ -5884,30 +5884,95 @@ 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<(), ()> {
+		self.check_refresh_async_receive_offer_cache_with_payment_metadata(
+			timer_tick_occurred,
+			None,
+		)
+	}
+
+	fn check_refresh_async_receive_offer_cache_with_payment_metadata(
+		&self, timer_tick_occurred: bool, payment_metadata: Option<BTreeMap<u64, Vec<u8>>>,
+	) -> 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_with_payment_metadata(
 			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(()) => {},
-		}
+			payment_metadata,
+		)
 	}
 
 	#[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"
+			);
+		})
+	}
+
+	/// Requests fresh async receive offer paths from the configured static invoice server, if any,
+	/// and attaches `payment_metadata` to the resulting BOLT 12 payment contexts.
+	///
+	/// The metadata is persisted with the async receive offer cache so future static-invoice
+	/// refreshes for the same offer continue to include it.
+	pub fn refresh_async_receive_offers_with_payment_metadata(
+		&self, payment_metadata: BTreeMap<u64, Vec<u8>>,
+	) -> Result<(), ()> {
+		self.check_refresh_async_receive_offer_cache_with_payment_metadata(
+			false,
+			Some(payment_metadata),
+		)
+		.map_err(|()| {
+			log_error!(
+				self.logger,
+				"Failed to create blinded paths when requesting async receive offer paths"
+			);
+		})
+	}
+
+	/// Returns once an async receive offer is ready after the interactive static-invoice
+	/// protocol completes, or immediately if one is already available.
+	///
+	/// Callers that need a timeout can combine this future with their runtime's timeout
+	/// primitive.
+	#[cfg_attr(
+		feature = "std",
+		doc = "Synchronous callers should instead fetch the underlying [`Future`] via [`Self::get_async_receive_offer_ready_future`] and call [`Future::wait_timeout`] on it."
+	)]
+	///
+	/// [`Future`]: crate::util::wakers::Future
+	#[cfg_attr(
+		feature = "std",
+		doc = "[`Future::wait_timeout`]: crate::util::wakers::Future::wait_timeout"
+	)]
+	pub async fn await_async_receive_offer(&self) -> Result<Offer, ()> {
+		if let Ok(offer) = self.get_async_receive_offer() {
+			return Ok(offer);
+		}
+
+		self.flow.get_async_receive_offer_ready_future().await;
+		self.get_async_receive_offer()
+	}
+
+	/// Returns a [`Future`] that completes when an async receive offer is ready.
+	///
+	/// See [`OffersMessageFlow::get_async_receive_offer_ready_future`] for details.
+	///
+	/// [`Future`]: crate::util::wakers::Future
+	/// [`OffersMessageFlow::get_async_receive_offer_ready_future`]: crate::offers::flow::OffersMessageFlow::get_async_receive_offer_ready_future
+	pub fn get_async_receive_offer_ready_future(&self) -> crate::util::wakers::Future {
+		self.flow.get_async_receive_offer_ready_future()
 	}
 
 	/// Should be called after handling an [`Event::PersistStaticInvoice`], where the `Responder`
@@ -9129,7 +9194,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
@@ -16055,7 +16125,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/async_receive_offer_cache.rs

@@ -11,6 +11,8 @@
 //! server as an async recipient. The static invoice server will serve the resulting invoices to
 //! payers on our behalf when we're offline.
 
+use alloc::collections::BTreeMap;
+
 use crate::blinded_path::message::{AsyncPaymentsContext, BlindedMessagePath};
 use crate::io;
 use crate::io::Read;
@@ -19,7 +21,7 @@ use crate::offers::nonce::Nonce;
 use crate::offers::offer::Offer;
 use crate::onion_message::messenger::Responder;
 use crate::prelude::*;
-use crate::util::ser::{Readable, Writeable, Writer};
+use crate::util::ser::{BigSizeKeyedMap, Readable, Writeable, Writer};
 use core::time::Duration;
 
 /// The status of this offer in the cache.
@@ -62,6 +64,7 @@ struct AsyncReceiveOffer {
 	/// payment paths become otherwise outdated.
 	offer_nonce: Nonce,
 	update_static_invoice_path: Responder,
+	payment_metadata: Option<BTreeMap<u64, Vec<u8>>>,
 }
 
 impl AsyncReceiveOffer {
@@ -92,6 +95,7 @@ impl_ser_tlv_based!(AsyncReceiveOffer, {
 	(4, status, required),
 	(6, update_static_invoice_path, required),
 	(8, created_at, required),
+	(10, payment_metadata, (option, encoding: (BTreeMap<u64, Vec<u8>>, BigSizeKeyedMap))),
 });
 
 /// If we are an often-offline recipient, we'll want to interactively build offers and static
@@ -147,6 +151,8 @@ pub struct AsyncReceiveOfferCache {
 	/// Blinded paths used to request offer paths from the static invoice server.
 	#[allow(unused)] // TODO: remove when we get rid of async payments cfg flag
 	paths_to_static_invoice_server: Vec<BlindedMessagePath>,
+	/// Payment metadata associated with offer-path requests in flight.
+	pending_offer_payment_metadata: BTreeMap<u16, Option<BTreeMap<u64, Vec<u8>>>>,
 }
 
 impl AsyncReceiveOfferCache {
@@ -158,6 +164,7 @@ impl AsyncReceiveOfferCache {
 			offers: Vec::new(),
 			offer_paths_request_attempts: 0,
 			paths_to_static_invoice_server: Vec::new(),
+			pending_offer_payment_metadata: BTreeMap::new(),
 		}
 	}
 
@@ -320,6 +327,7 @@ impl AsyncReceiveOfferCache {
 	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, slot: u16,
+		payment_metadata: Option<BTreeMap<u64, Vec<u8>>>,
 	) -> Result<(), ()> {
 		self.prune_expired_offers(duration_since_epoch, false);
 
@@ -340,13 +348,15 @@ impl AsyncReceiveOfferCache {
 					offer_nonce,
 					status: OfferStatus::Pending,
 					update_static_invoice_path,
+					payment_metadata,
 				})
 			},
 			None => {
 				debug_assert!(false, "Slot in cache was invalid but should'be been checked above");
 				return Err(());
 			},
 		}
+		self.pending_offer_payment_metadata.remove(&slot);
 
 		Ok(())
 	}
@@ -433,8 +443,11 @@ impl AsyncReceiveOfferCache {
 
 	// Indicates that onion messages requesting new offer paths have been sent to the static invoice
 	// server. Calling this method allows the cache to self-limit how many requests are sent.
-	pub(super) fn new_offers_requested(&mut self) {
+	pub(super) fn new_offers_requested(
+		&mut self, slot: u16, payment_metadata: Option<BTreeMap<u64, Vec<u8>>>,
+	) {
 		self.offer_paths_request_attempts += 1;
+		self.pending_offer_payment_metadata.insert(slot, payment_metadata);
 	}
 
 	/// Called on timer tick (roughly once per minute) to allow another [`MAX_UPDATE_ATTEMPTS`] offer
@@ -447,7 +460,7 @@ impl AsyncReceiveOfferCache {
 	/// the static invoice server.
 	pub(super) fn offers_needing_invoice_refresh(
 		&self, duration_since_epoch: Duration,
-	) -> impl Iterator<Item = (&Offer, Nonce, &Responder)> {
+	) -> impl Iterator<Item = (&Offer, Nonce, &Responder, Option<BTreeMap<u64, Vec<u8>>>)> {
 		// For any offers which are either in use or pending confirmation by the server, we should send
 		// them a fresh invoice on each timer tick.
 		self.offers_with_idx().filter_map(move |(_, offer)| {
@@ -462,13 +475,44 @@ impl AsyncReceiveOfferCache {
 				OfferStatus::Ready { .. } => false,
 			};
 			if needs_invoice_update {
-				Some((&offer.offer, offer.offer_nonce, &offer.update_static_invoice_path))
+				Some((
+					&offer.offer,
+					offer.offer_nonce,
+					&offer.update_static_invoice_path,
+					offer.payment_metadata.clone(),
+				))
 			} else {
 				None
 			}
 		})
 	}
 
+	/// Returns the payment metadata that should be attached to a replacement offer in `slot`.
+	pub(super) fn payment_metadata_for_new_offer(
+		&self, slot: u16, payment_metadata: Option<BTreeMap<u64, Vec<u8>>>,
+	) -> Option<BTreeMap<u64, Vec<u8>>> {
+		payment_metadata
+			.or_else(|| self.pending_offer_payment_metadata.get(&slot).cloned().flatten())
+			.or_else(|| {
+				self.offers
+					.get(slot as usize)
+					.and_then(|offer| offer.as_ref())
+					.and_then(|offer| offer.payment_metadata.clone())
+			})
+	}
+
+	/// Returns the payment metadata associated with an incoming offer-path response for `slot`.
+	pub(super) fn payment_metadata_for_offer_slot(
+		&self, slot: u16,
+	) -> Option<BTreeMap<u64, Vec<u8>>> {
+		self.pending_offer_payment_metadata.get(&slot).cloned().flatten().or_else(|| {
+			self.offers
+				.get(slot as usize)
+				.and_then(|offer| offer.as_ref())
+				.and_then(|offer| offer.payment_metadata.clone())
+		})
+	}
+
 	/// Should be called when we receive a [`StaticInvoicePersisted`] message from the static invoice
 	/// server, which indicates that a new offer was persisted by the server and they are ready to
 	/// serve the corresponding static invoice to payers on our behalf.
@@ -536,6 +580,11 @@ impl Readable for AsyncReceiveOfferCache {
 			(2, paths_to_static_invoice_server, required_vec),
 		});
 		let offers: Vec<Option<AsyncReceiveOffer>> = offers;
-		Ok(Self { offers, offer_paths_request_attempts: 0, paths_to_static_invoice_server })
+		Ok(Self {
+			offers,
+			offer_paths_request_attempts: 0,
+			paths_to_static_invoice_server,
+			pending_offer_payment_metadata: BTreeMap::new(),
+		})
 	}
 }