Send static invoice in response to offer paths

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

As part of this process, the static invoice server sends us blinded message
paths to include in our offer so they'll receive invoice requests from senders
trying to pay us while we're offline. On receipt of these paths, create an
offer and static invoice and send the invoice back to the server so they can
provide the invoice to payers.

Author: valentinewallace

lightning/src/blinded_path/message.rs

@@ -23,6 +23,8 @@ use crate::ln::channelmanager::PaymentId;
 use crate::ln::msgs::DecodeError;
 use crate::ln::onion_utils;
 use crate::offers::nonce::Nonce;
+use crate::offers::offer::Offer;
+use crate::onion_message::messenger::Responder;
 use crate::onion_message::packet::ControlTlvs;
 use crate::routing::gossip::{NodeId, ReadOnlyNetworkGraph};
 use crate::sign::{EntropySource, NodeSigner, Recipient};
@@ -424,6 +426,58 @@ pub enum AsyncPaymentsContext {
 		/// is no longer configured to accept paths from them.
 		path_absolute_expiry: core::time::Duration,
 	},
+	/// Context used by a reply path to a [`ServeStaticInvoice`] message, provided back to us in
+	/// corresponding [`StaticInvoicePersisted`] messages.
+	///
+	/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+	/// [`StaticInvoicePersisted`]: crate::onion_message::async_payments::StaticInvoicePersisted
+	StaticInvoicePersisted {
+		/// The offer corresponding to the [`StaticInvoice`] that has been persisted. This invoice is
+		/// now ready to be provided by the static invoice server in response to [`InvoiceRequest`]s.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		offer: Offer,
+		/// A [`Nonce`] useful for updating the [`StaticInvoice`] that corresponds to the
+		/// [`AsyncPaymentsContext::StaticInvoicePersisted::offer`], since the offer may be much longer
+		/// lived than the invoice.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		offer_nonce: Nonce,
+		/// Useful to determine how far an offer is into its lifespan, to decide whether the offer is
+		/// expiring soon and we should start building a new one.
+		offer_created_at: core::time::Duration,
+		/// A [`Responder`] useful for updating the [`StaticInvoice`] that corresponds to the
+		/// [`AsyncPaymentsContext::StaticInvoicePersisted::offer`], since the offer may be much longer
+		/// lived than the invoice.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		update_static_invoice_path: Responder,
+		/// The time as duration since the Unix epoch at which the [`StaticInvoice`] expires, used to track
+		/// when we need to generate and persist a new invoice with the static invoice server.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		static_invoice_absolute_expiry: core::time::Duration,
+		/// A nonce used for authenticating that a [`StaticInvoicePersisted`] message is valid for a
+		/// preceding [`ServeStaticInvoice`] message.
+		///
+		/// [`StaticInvoicePersisted`]: crate::onion_message::async_payments::StaticInvoicePersisted
+		/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+		nonce: Nonce,
+		/// Authentication code for the [`StaticInvoicePersisted`] message.
+		///
+		/// Prevents nodes from creating their own blinded path to us and causing us to cache an
+		/// unintended async receive offer.
+		///
+		/// [`StaticInvoicePersisted`]: crate::onion_message::async_payments::StaticInvoicePersisted
+		hmac: Hmac<Sha256>,
+		/// The time as duration since the Unix epoch at which this path expires and messages sent over
+		/// it should be ignored.
+		///
+		/// Prevents a static invoice server from causing an async recipient to cache an old offer if
+		/// the recipient is no longer configured to use that server.
+		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.
@@ -511,6 +565,16 @@ impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
 		(2, hmac, required),
 		(4, path_absolute_expiry, required),
 	},
+	(3, StaticInvoicePersisted) => {
+		(0, offer, required),
+		(2, offer_nonce, required),
+		(4, offer_created_at, required),
+		(6, update_static_invoice_path, required),
+		(8, static_invoice_absolute_expiry, required),
+		(10, nonce, required),
+		(12, hmac, required),
+		(14, path_absolute_expiry, required),
+	},
 );
 
 /// Contains a simple nonce for use in a blinded path's context.

lightning/src/ln/channelmanager.rs

@@ -12356,7 +12356,25 @@ where
 	fn handle_offer_paths(
 		&self, _message: OfferPaths, _context: AsyncPaymentsContext, _responder: Option<Responder>,
 	) -> Option<(ServeStaticInvoice, ResponseInstruction)> {
-		None
+		#[cfg(async_payments)] {
+			let responder = match _responder {
+				Some(responder) => responder,
+				None => return None
+			};
+			let (serve_static_invoice, reply_context) =
+				match self.flow.handle_offer_paths(
+					_message, _context, responder.clone(), self.get_peers_for_blinded_path(),
+					self.list_usable_channels()
+				) {
+					Some((msg, ctx)) => (msg, ctx),
+					None => return None,
+				};
+			let response_instructions = responder.respond_with_reply_path(reply_context);
+			return Some((serve_static_invoice, response_instructions))
+		}
+
+		#[cfg(not(async_payments))]
+		return None
 	}
 
 	fn handle_serve_static_invoice(

lightning/src/offers/async_receive_offer_cache.rs

@@ -16,6 +16,8 @@ use crate::io::Read;
 use crate::ln::msgs::DecodeError;
 use crate::offers::nonce::Nonce;
 use crate::offers::offer::Offer;
+#[cfg(async_payments)]
+use crate::onion_message::async_payments::OfferPaths;
 use crate::onion_message::messenger::Responder;
 use crate::util::ser::{Readable, Writeable, Writer};
 use core::time::Duration;
@@ -94,6 +96,29 @@ impl AsyncReceiveOfferCache {
 			&& self.offer_paths_request_attempts < Self::MAX_UPDATE_ATTEMPTS
 	}
 
+	/// Returns whether the new paths we've just received from the static invoice server should be used
+	/// to build a new offer.
+	pub(super) fn should_build_offer_with_paths(
+		&mut self, message: &OfferPaths, duration_since_epoch: Duration,
+	) -> bool {
+		let needs_new_offers = self.check_expire_offers(duration_since_epoch);
+		if !needs_new_offers {
+			return false;
+		}
+
+		// Require the offer that would be built using these paths to last at least a few hours.
+		let min_offer_paths_absolute_expiry =
+			duration_since_epoch.as_secs().saturating_add(3 * 60 * 60);
+		let offer_paths_absolute_expiry =
+			message.paths_absolute_expiry.map(|exp| exp.as_secs()).unwrap_or(u64::MAX);
+		if offer_paths_absolute_expiry < min_offer_paths_absolute_expiry {
+			return false;
+		}
+
+		// Check that we don't have any current offers that already contain these paths
+		self.offers.iter().all(|offer| offer.offer.paths() != message.paths)
+	}
+
 	/// Removes expired offers from our cache, returning whether new offers are needed.
 	fn check_expire_offers(&mut self, duration_since_epoch: Duration) -> bool {
 		// Remove expired offers from the cache.

lightning/src/offers/flow.rs

@@ -70,7 +70,10 @@ use {
 		StaticInvoice, StaticInvoiceBuilder,
 		DEFAULT_RELATIVE_EXPIRY as STATIC_INVOICE_DEFAULT_RELATIVE_EXPIRY,
 	},
-	crate::onion_message::async_payments::{HeldHtlcAvailable, OfferPathsRequest},
+	crate::onion_message::async_payments::{
+		HeldHtlcAvailable, OfferPaths, OfferPathsRequest, ServeStaticInvoice,
+	},
+	crate::onion_message::messenger::Responder,
 };
 
 #[cfg(feature = "dnssec")]
@@ -477,29 +480,61 @@ where
 		&self, absolute_expiry: Option<Duration>, nonce: Option<Nonce>,
 		peers: Vec<MessageForwardNode>,
 	) -> Result<OfferBuilder<DerivedMetadata, secp256k1::All>, Bolt12SemanticError> {
+		self.create_offer_builder_internal(absolute_expiry, nonce, peers, None)
+			.map(|(offer, _nonce)| offer)
+	}
+
+	/// NB: the offer utils diff in this commit will go away when the offers message flow PR is updated
+	pub fn create_async_receive_offer_builder(
+		&self, absolute_expiry: Option<Duration>, peers: Vec<MessageForwardNode>,
+		message_paths_to_always_online_node: Vec<BlindedMessagePath>,
+	) -> Result<(OfferBuilder<DerivedMetadata, secp256k1::All>, Nonce), Bolt12SemanticError> {
+		self.create_offer_builder_internal(
+			absolute_expiry,
+			None,
+			peers,
+			Some(message_paths_to_always_online_node),
+		)
+	}
+
+	fn create_offer_builder_internal(
+		&self, absolute_expiry: Option<Duration>, nonce: Option<Nonce>,
+		peers: Vec<MessageForwardNode>,
+		message_paths_to_always_online_node: Option<Vec<BlindedMessagePath>>,
+	) -> Result<(OfferBuilder<DerivedMetadata, secp256k1::All>, Nonce), Bolt12SemanticError> {
 		let node_id = self.get_our_node_id();
 		let expanded_key = &self.inbound_payment_key;
 		let entropy = &*self.entropy_source;
 		let secp_ctx = &self.secp_ctx;
 
-		let nonce = nonce.unwrap_or(Nonce::from_entropy_source(entropy));
-		let context = OffersContext::InvoiceRequest { nonce };
+		let offer_nonce = nonce.unwrap_or(Nonce::from_entropy_source(entropy));
+		let context = OffersContext::InvoiceRequest { nonce: offer_nonce };
 
-		let path = self
-			.create_blinded_paths_using_absolute_expiry(context, absolute_expiry, peers)
-			.and_then(|paths| paths.into_iter().next().ok_or(()))
-			.map_err(|_| Bolt12SemanticError::MissingPaths)?;
+		let mut builder =
+			OfferBuilder::deriving_signing_pubkey(node_id, expanded_key, offer_nonce, secp_ctx)
+				.chain_hash(self.chain_hash);
 
-		let builder = OfferBuilder::deriving_signing_pubkey(node_id, expanded_key, nonce, secp_ctx)
-			.chain_hash(self.chain_hash)
-			.path(path);
+		match message_paths_to_always_online_node {
+			Some(paths) => {
+				for path in paths {
+					builder = builder.path(path);
+				}
+			},
+			None => {
+				let path = self
+					.create_blinded_paths_using_absolute_expiry(context, absolute_expiry, peers)
+					.and_then(|paths| paths.into_iter().next().ok_or(()))
+					.map_err(|_| Bolt12SemanticError::MissingPaths)?;
+				builder = builder.path(path);
+			},
+		}
 
 		let builder = match absolute_expiry {
 			None => builder,
 			Some(absolute_expiry) => builder.absolute_expiry(absolute_expiry),
 		};
 
-		Ok(builder)
+		Ok((builder, offer_nonce))
 	}
 
 	/// Creates a [`RefundBuilder`] such that the [`Refund`] it builds is recognized by the
@@ -1100,4 +1135,126 @@ where
 
 		Ok(())
 	}
+
+	/// Handles an incoming [`OfferPaths`] onion message from the static invoice server, sending out
+	/// [`ServeStaticInvoice`] onion messages in response if we want to use the paths we've received
+	/// to build and cache an async receive offer.
+	#[cfg(async_payments)]
+	pub(crate) fn handle_offer_paths(
+		&self, message: OfferPaths, context: AsyncPaymentsContext, responder: Responder,
+		peers: Vec<MessageForwardNode>, usable_channels: Vec<ChannelDetails>,
+	) -> Option<(ServeStaticInvoice, MessageContext)> {
+		let expanded_key = &self.inbound_payment_key;
+		let duration_since_epoch = self.duration_since_epoch();
+
+		match context {
+			AsyncPaymentsContext::OfferPaths { nonce, hmac, path_absolute_expiry } => {
+				if let Err(()) = signer::verify_offer_paths_context(nonce, hmac, expanded_key) {
+					return None;
+				}
+				if duration_since_epoch > path_absolute_expiry {
+					return None;
+				}
+			},
+			_ => return None,
+		}
+
+		{
+			// Only respond with ServeStaticInvoice if we actually need a new offer built.
+			let mut cache = self.async_receive_offer_cache.lock().unwrap();
+			if !cache.should_build_offer_with_paths(&message, duration_since_epoch) {
+				return None;
+			}
+		}
+
+		let (offer_builder, offer_nonce) = match self.create_async_receive_offer_builder(
+			message.paths_absolute_expiry,
+			peers.clone(),
+			message.paths,
+		) {
+			Ok((builder, nonce)) => (builder, nonce),
+			Err(_e) => return None, // TODO log error
+		};
+		let offer = match offer_builder.build() {
+			Ok(offer) => offer,
+			Err(_e) => return None, // TODO log error
+		};
+
+		let (serve_invoice_message, reply_path_context) = match self
+			.create_serve_static_invoice_message(
+				offer,
+				offer_nonce,
+				duration_since_epoch,
+				peers,
+				usable_channels,
+				responder,
+			) {
+			Ok((msg, context)) => (msg, context),
+			Err(()) => return None,
+		};
+
+		let context = MessageContext::AsyncPayments(reply_path_context);
+		Some((serve_invoice_message, context))
+	}
+
+	/// Creates a [`ServeStaticInvoice`] onion message, including reply path context for the static
+	/// invoice server to respond with [`StaticInvoicePersisted`].
+	///
+	/// [`StaticInvoicePersisted`]: crate::onion_message::async_payments::StaticInvoicePersisted
+	#[cfg(async_payments)]
+	fn create_serve_static_invoice_message(
+		&self, offer: Offer, offer_nonce: Nonce, offer_created_at: Duration,
+		peers: Vec<MessageForwardNode>, usable_channels: Vec<ChannelDetails>,
+		update_static_invoice_path: Responder,
+	) -> Result<(ServeStaticInvoice, AsyncPaymentsContext), ()> {
+		let expanded_key = &self.inbound_payment_key;
+		let entropy = &*self.entropy_source;
+		let duration_since_epoch = self.duration_since_epoch();
+		let secp_ctx = &self.secp_ctx;
+		const REPLY_PATH_RELATIVE_EXPIRY: Duration = Duration::from_secs(7200);
+
+		let offer_relative_expiry = offer
+			.absolute_expiry()
+			.unwrap_or_else(|| Duration::from_secs(u64::MAX))
+			.saturating_sub(duration_since_epoch);
+
+		// We limit the static invoice lifetime to STATIC_INVOICE_DEFAULT_RELATIVE_EXPIRY, meaning we'll
+		// need to refresh the static invoice using the reply path to the `OfferPaths` message if the
+		// offer expires later than that.
+		let static_invoice_relative_expiry = Duration::from_secs(core::cmp::min(
+			offer_relative_expiry.as_secs(),
+			STATIC_INVOICE_DEFAULT_RELATIVE_EXPIRY.as_secs(),
+		));
+
+		let static_invoice = self
+			.create_static_invoice_builder(
+				&offer,
+				offer_nonce,
+				Some(static_invoice_relative_expiry),
+				usable_channels,
+				peers,
+			)
+			.and_then(|builder| builder.build_and_sign(secp_ctx))
+			.map_err(|_e| ())?; // TODO: log error
+
+		let reply_path_context = {
+			let nonce = Nonce::from_entropy_source(entropy);
+			let hmac = signer::hmac_for_static_invoice_persisted_context(nonce, expanded_key);
+			AsyncPaymentsContext::StaticInvoicePersisted {
+				offer,
+				offer_nonce,
+				offer_created_at,
+				update_static_invoice_path,
+				static_invoice_absolute_expiry: static_invoice
+					.created_at()
+					.saturating_add(static_invoice.relative_expiry()),
+				nonce,
+				hmac,
+				path_absolute_expiry: duration_since_epoch
+					.saturating_add(REPLY_PATH_RELATIVE_EXPIRY),
+			}
+		};
+
+		Ok((ServeStaticInvoice { invoice: static_invoice }, reply_path_context))
+	}
 }