Check and refresh async receive offer

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

At the start of this process, we send a requests for paths to include in our
offers to the always-online node on startup and refresh the cached offers when
they expire.

We previously weren't dropping the cache lock if no new offers were needed, then
attempted to acquire it again in a later method

We're gonna expose these for testing later so move them

Author: valentinewallace

lightning/src/blinded_path/message.rs

@@ -404,6 +404,32 @@ pub enum OffersContext {
 /// [`AsyncPaymentsMessage`]: crate::onion_message::async_payments::AsyncPaymentsMessage
 #[derive(Clone, Debug)]
 pub enum AsyncPaymentsContext {
+	/// Context used by a reply path to an [`OfferPathsRequest`], provided back to us in corresponding
+	/// [`OfferPaths`] messages.
+	///
+	/// [`OfferPathsRequest`]: crate::onion_message::async_payments::OfferPathsRequest
+	/// [`OfferPaths`]: crate::onion_message::async_payments::OfferPaths
+	OfferPaths {
+		/// A nonce used for authenticating that an [`OfferPaths`] message is valid for a preceding
+		/// [`OfferPathsRequest`].
+		///
+		/// [`OfferPathsRequest`]: crate::onion_message::async_payments::OfferPathsRequest
+		/// [`OfferPaths`]: crate::onion_message::async_payments::OfferPaths
+		nonce: Nonce,
+		/// Authentication code for the [`OfferPaths`] message.
+		///
+		/// Prevents nodes from creating their own blinded path to us and causing us to cache an
+		/// unintended async receive offer.
+		///
+		/// [`OfferPaths`]: crate::onion_message::async_payments::OfferPaths
+		hmac: Hmac<Sha256>,
+		/// The time as duration since the Unix epoch at which this path expires and messages sent over
+		/// it should be ignored.
+		///
+		/// Used to time out a static invoice server from providing offer paths if the async recipient
+		/// is no longer configured to accept paths from them.
+		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.
@@ -486,6 +512,11 @@ impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
 		(2, hmac, required),
 		(4, path_absolute_expiry, required),
 	},
+	(2, OfferPaths) => {
+		(0, nonce, required),
+		(2, hmac, required),
+		(4, path_absolute_expiry, required),
+	},
 );
 
 /// Contains a simple nonce for use in a blinded path's context.

lightning/src/ln/channelmanager.rs

@@ -5105,7 +5105,21 @@ where
 	}
 
 	#[cfg(async_payments)]
+	fn check_refresh_async_receive_offers(&self) {
+		let peers = self.get_peers_for_blinded_path();
+		match self.flow.check_refresh_async_receive_offers(peers, &*self.entropy_source) {
+			Err(()) => {
+				log_error!(
+					self.logger,
+					"Failed to create blinded paths when requesting async receive offer paths"
+				);
+			},
+			Ok(()) => {},
+		}
+	}
+
 	#[rustfmt::skip]
+	#[cfg(async_payments)]
 	fn initiate_async_payment(
 		&self, invoice: &StaticInvoice, payment_id: PaymentId
 	) -> Result<(), Bolt12PaymentError> {
@@ -7049,6 +7063,9 @@ where
 				duration_since_epoch, &self.pending_events
 			);
 
+			#[cfg(async_payments)]
+			self.check_refresh_async_receive_offers();
+
 			// Technically we don't need to do this here, but if we have holding cell entries in a
 			// channel that need freeing, it's better to do that here and block a background task
 			// than block the message queueing pipeline.
@@ -11484,6 +11501,13 @@ where
 			return NotifyOption::SkipPersistHandleEvents;
 			//TODO: Also re-broadcast announcement_signatures
 		});
+
+		// While we usually refresh the AsyncReceiveOfferCache on a timer, we also want to start
+		// interactively building offers as soon as we can after startup. We can't start building offers
+		// until we have some peer connection(s) to send onion messages over, so as a minor optimization
+		// refresh the cache when a peer connects.
+		#[cfg(async_payments)]
+		self.check_refresh_async_receive_offers();
 		res
 	}
 

lightning/src/offers/async_receive_offer_cache.rs

@@ -78,6 +78,105 @@ impl AsyncReceiveOfferCache {
 	}
 }
 
+// The target number of offers we want to have cached at any given time, to mitigate too much
+// reuse of the same offer.
+#[cfg(async_payments)]
+const NUM_CACHED_OFFERS_TARGET: usize = 3;
+
+// The max number of times we'll attempt to request offer paths or attempt to refresh a static
+// invoice before giving up.
+#[cfg(async_payments)]
+const MAX_UPDATE_ATTEMPTS: u8 = 3;
+
+// If we run out of attempts to request offer paths from the static invoice server, we'll stop
+// sending requests for some time. After this amount of time has passed, more requests are allowed
+// to be sent out.
+#[cfg(async_payments)]
+const PATHS_REQUESTS_BUFFER: Duration = Duration::from_secs(3 * 60 * 60);
+
+// If an offer is 90% of the way through its lifespan, it's expiring soon. This allows us to be
+// flexible for various offer lifespans, i.e. an offer that lasts 10 days expires soon after 9 days
+// and an offer that lasts 10 years expires soon after 9 years.
+const OFFER_EXPIRES_SOON_THRESHOLD_PERCENT: u64 = 90;
+
+#[cfg(async_payments)]
+impl AsyncReceiveOfferCache {
+	/// Remove expired offers from the cache.
+	pub(super) fn prune_expired_offers(&mut self, duration_since_epoch: Duration) {
+		// Remove expired offers from the cache.
+		let mut offer_was_removed = false;
+		self.offers.retain(|offer| {
+			if offer.offer.is_expired_no_std(duration_since_epoch) {
+				offer_was_removed = true;
+				return false;
+			}
+			true
+		});
+
+		// If we just removed a newly expired offer, force allowing more paths request attempts.
+		if offer_was_removed {
+			self.reset_offer_paths_request_attempts();
+		}
+
+		// If we haven't attempted to request new paths in a long time, allow more requests to go out
+		// if/when needed.
+		self.check_reset_offer_paths_request_attempts(duration_since_epoch);
+	}
+
+	/// Checks whether we should request new offer paths from the always-online static invoice server.
+	pub(super) fn should_request_offer_paths(&self, duration_since_epoch: Duration) -> bool {
+		self.needs_new_offers(duration_since_epoch)
+			&& self.offer_paths_request_attempts < MAX_UPDATE_ATTEMPTS
+	}
+
+	/// Returns a bool indicating whether new offers are needed in the cache.
+	fn needs_new_offers(&self, duration_since_epoch: Duration) -> bool {
+		// If we have fewer than NUM_CACHED_OFFERS_TARGET offers that aren't expiring soon, indicate
+		// that new offers should be interactively built.
+		let num_unexpiring_offers = self
+			.offers
+			.iter()
+			.filter(|offer| {
+				let offer_absolute_expiry = offer.offer.absolute_expiry().unwrap_or(Duration::MAX);
+				let offer_created_at = offer.offer_created_at;
+				let offer_lifespan =
+					offer_absolute_expiry.saturating_sub(offer_created_at).as_secs();
+				let elapsed = duration_since_epoch.saturating_sub(offer_created_at).as_secs();
+
+				// If an offer is in the last 10% of its lifespan, it's expiring soon.
+				elapsed.saturating_mul(100)
+					< offer_lifespan.saturating_mul(OFFER_EXPIRES_SOON_THRESHOLD_PERCENT)
+			})
+			.count();
+
+		num_unexpiring_offers < NUM_CACHED_OFFERS_TARGET
+	}
+
+	// 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, in case
+	// the server goes unresponsive.
+	pub(super) fn new_offers_requested(&mut self, duration_since_epoch: Duration) {
+		self.offer_paths_request_attempts += 1;
+		self.last_offer_paths_request_timestamp = duration_since_epoch;
+	}
+
+	/// If we haven't sent an offer paths request in a long time, reset the limit to allow more
+	/// requests to be sent out if/when needed.
+	fn check_reset_offer_paths_request_attempts(&mut self, duration_since_epoch: Duration) {
+		let should_reset =
+			self.last_offer_paths_request_timestamp.saturating_add(PATHS_REQUESTS_BUFFER)
+				< duration_since_epoch;
+		if should_reset {
+			self.reset_offer_paths_request_attempts();
+		}
+	}
+
+	fn reset_offer_paths_request_attempts(&mut self) {
+		self.offer_paths_request_attempts = 0;
+		self.last_offer_paths_request_timestamp = Duration::from_secs(0);
+	}
+}
+
 impl Writeable for AsyncReceiveOfferCache {
 	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
 		write_tlv_fields!(w, {

lightning/src/offers/flow.rs

@@ -66,7 +66,7 @@ use {
 	crate::offers::offer::Amount,
 	crate::offers::signer,
 	crate::offers::static_invoice::{StaticInvoice, StaticInvoiceBuilder},
-	crate::onion_message::async_payments::HeldHtlcAvailable,
+	crate::onion_message::async_payments::{HeldHtlcAvailable, OfferPathsRequest},
 };
 
 #[cfg(feature = "dnssec")]
@@ -217,6 +217,11 @@ where
 /// even if multiple invoices are received.
 const OFFERS_MESSAGE_REQUEST_LIMIT: usize = 10;
 
+/// The default relative expiry for reply paths where a quick response is expected and the reply
+/// path is single-use.
+#[cfg(async_payments)]
+const TEMP_REPLY_PATH_RELATIVE_EXPIRY: Duration = Duration::from_secs(7200);
+
 impl<MR: Deref> OffersMessageFlow<MR>
 where
 	MR::Target: MessageRouter,
@@ -1105,6 +1110,72 @@ where
 		core::mem::take(&mut self.pending_dns_onion_messages.lock().unwrap())
 	}
 
+	/// Sends out [`OfferPathsRequest`] onion messages if we are an often-offline recipient and are
+	/// configured to interactively build offers and static invoices with a static invoice server.
+	///
+	/// # Usage
+	///
+	/// This method should be called on peer connection and every few minutes or so, to keep the
+	/// offers cache updated.
+	///
+	/// Errors if we failed to create blinded reply paths when sending an [`OfferPathsRequest`] message.
+	#[cfg(async_payments)]
+	pub(crate) fn check_refresh_async_receive_offers<ES: Deref>(
+		&self, peers: Vec<MessageForwardNode>, entropy: ES,
+	) -> Result<(), ()>
+	where
+		ES::Target: EntropySource,
+	{
+		// Terminate early if this node does not intend to receive async payments.
+		if self.paths_to_static_invoice_server.is_empty() {
+			return Ok(());
+		}
+
+		let expanded_key = &self.inbound_payment_key;
+		let duration_since_epoch = self.duration_since_epoch();
+
+		// Check with the cache to see whether we need new offers to be interactively built with the
+		// static invoice server.
+		let needs_new_offers = {
+			let mut async_receive_offer_cache = self.async_receive_offer_cache.lock().unwrap();
+			async_receive_offer_cache.prune_expired_offers(duration_since_epoch);
+			async_receive_offer_cache.should_request_offer_paths(duration_since_epoch)
+		};
+
+		// If we need new offers, send out offer paths request messages to the static invoice server.
+		if needs_new_offers {
+			let nonce = Nonce::from_entropy_source(&*entropy);
+			let context = MessageContext::AsyncPayments(AsyncPaymentsContext::OfferPaths {
+				nonce,
+				hmac: signer::hmac_for_offer_paths_context(nonce, expanded_key),
+				path_absolute_expiry: duration_since_epoch
+					.saturating_add(TEMP_REPLY_PATH_RELATIVE_EXPIRY),
+			});
+			let reply_paths = match self.create_blinded_paths(peers, context) {
+				Ok(paths) => paths,
+				Err(()) => {
+					return Err(());
+				},
+			};
+
+			// We can't fail past this point, so indicate to the cache that we've requested new offers.
+			self.async_receive_offer_cache
+				.lock()
+				.unwrap()
+				.new_offers_requested(duration_since_epoch);
+
+			let message = AsyncPaymentsMessage::OfferPathsRequest(OfferPathsRequest {});
+			enqueue_onion_message_with_reply_paths(
+				message,
+				&self.paths_to_static_invoice_server[..],
+				reply_paths,
+				&mut self.pending_async_payments_messages.lock().unwrap(),
+			);
+		}
+
+		Ok(())
+	}
+
 	/// Get the `AsyncReceiveOfferCache` for persistence.
 	pub(crate) fn writeable_async_receive_offer_cache(&self) -> impl Writeable + '_ {
 		&self.async_receive_offer_cache

lightning/src/offers/signer.rs

@@ -55,6 +55,11 @@ const PAYMENT_TLVS_HMAC_INPUT: &[u8; 16] = &[8; 16];
 #[cfg(async_payments)]
 const ASYNC_PAYMENTS_HELD_HTLC_HMAC_INPUT: &[u8; 16] = &[9; 16];
 
+// HMAC input used in `AsyncPaymentsContext::OfferPaths` to authenticate inbound offer_paths onion
+// messages.
+#[cfg(async_payments)]
+const ASYNC_PAYMENTS_OFFER_PATHS_INPUT: &[u8; 16] = &[10; 16];
+
 /// Message metadata which possibly is derived from [`MetadataMaterial`] such that it can be
 /// verified.
 #[derive(Clone)]
@@ -570,3 +575,16 @@ pub(crate) fn verify_held_htlc_available_context(
 		Err(())
 	}
 }
+
+#[cfg(async_payments)]
+pub(crate) fn hmac_for_offer_paths_context(
+	nonce: Nonce, expanded_key: &ExpandedKey,
+) -> Hmac<Sha256> {
+	const IV_BYTES: &[u8; IV_LEN] = b"LDK Offer Paths~";
+	let mut hmac = expanded_key.hmac_for_offer();
+	hmac.input(IV_BYTES);
+	hmac.input(&nonce.0);
+	hmac.input(ASYNC_PAYMENTS_OFFER_PATHS_INPUT);
+
+	Hmac::from_engine(hmac)
+}