Check and refresh async receive offers

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.

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 as an async
+	/// recipient in corresponding [`OfferPaths`] messages from the static invoice server.
+	///
+	/// [`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`] that we sent as an async recipient.
+		///
+		/// [`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 that terminates at our async recipient
+		/// node 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.
+		///
+		/// As an async recipient we use this field to time out a static invoice server from sending us
+		/// offer paths if we are 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

@@ -5139,6 +5139,20 @@ 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(()) => {},
+		}
+	}
+
 	#[cfg(async_payments)]
 	fn initiate_async_payment(
 		&self, invoice: &StaticInvoice, payment_id: PaymentId,
@@ -7133,6 +7147,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.
@@ -11654,6 +11671,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

@@ -81,6 +81,103 @@ 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_RESET_INTERVAL: 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.
+#[cfg(async_payments)]
+const OFFER_EXPIRES_SOON_THRESHOLD_PERCENT: u64 = 90;
+
+#[cfg(async_payments)]
+impl AsyncReceiveOfferCache {
+	/// Remove expired offers from the cache, returning whether new offers are needed.
+	pub(super) fn prune_expired_offers(&mut self, duration_since_epoch: Duration) -> bool {
+		// 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();
+		} else {
+			// 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);
+		}
+
+		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_RESET_INTERVAL)
+				< 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();
+
+		// Update the cache to remove expired offers, and check to see whether we need new offers to be
+		// interactively built with the static invoice server.
+		let needs_new_offers = self
+			.async_receive_offer_cache
+			.lock()
+			.unwrap()
+			.prune_expired_offers(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)
+}