Static invoice server: persist invoices once built

As part of serving static invoices to payers on behalf of often-offline
recipients, the recipient will send us the final static invoice once it's done
being interactively built. We will then persist this invoice and confirm to
them that the corresponding offer is ready to be used for async payments.

Surface an event once the invoice is received and expose an API to tell the
recipient that it's ready for payments.

Author: valentinewallace

lightning/src/events/mod.rs

@@ -52,6 +52,9 @@ use bitcoin::{OutPoint, Transaction};
 use core::ops::Deref;
 use core::time::Duration;
 
+#[cfg(async_payments)]
+use crate::offers::nonce::Nonce;
+
 #[allow(unused_imports)]
 use crate::prelude::*;
 
@@ -1572,6 +1575,32 @@ pub enum Event {
 		/// onion messages.
 		peer_node_id: PublicKey,
 	},
+	/// As a static invoice server, we received a [`StaticInvoice`] from an async recipient that wants
+	/// us to serve the invoice to payers on their behalf when they are offline. This event will only
+	/// be generated if we previously created paths using
+	/// [`ChannelManager::blinded_paths_for_async_recipient`] and configured the recipient with them
+	/// via [`UserConfig::paths_to_static_invoice_server`].
+	///
+	/// [`ChannelManager::blinded_paths_for_async_recipient`]: crate::ln::channelmanager::ChannelManager::blinded_paths_for_async_recipient
+	/// [`UserConfig::paths_to_static_invoice_server`]: crate::util::config::UserConfig::paths_to_static_invoice_server
+	#[cfg(async_payments)]
+	PersistStaticInvoice {
+		/// The invoice that should be persisted and later provided to payers when handling a future
+		/// `Event::StaticInvoiceRequested`.
+		invoice: StaticInvoice,
+		/// An identifier for the recipient, originally surfaced in
+		/// [`ChannelManager::blinded_paths_for_async_recipient`]. When an
+		/// `Event::StaticInvoiceRequested` comes in for this invoice, this id will be surfaced so the
+		/// persisted invoice can be retrieved from the database.
+		recipient_id_nonce: Nonce,
+		/// Once the [`StaticInvoice`] is persisted, [`ChannelManager::static_invoice_persisted`] should
+		/// be called with this responder to confirm to the recipient that their [`Offer`] is ready to
+		/// be used for async payments.
+		///
+		/// [`ChannelManager::static_invoice_persisted`]: crate::ln::channelmanager::ChannelManager::static_invoice_persisted
+		/// [`Offer`]: crate::offers::offer::Offer
+		invoice_persisted_path: Responder,
+	},
 }
 
 impl Writeable for Event {
@@ -1996,6 +2025,12 @@ impl Writeable for Event {
 					(8, former_temporary_channel_id, required),
 				});
 			},
+			#[cfg(async_payments)]
+			&Event::PersistStaticInvoice { .. } => {
+				45u8.write(writer)?;
+				// No need to write these events because we can just restart the static invoice negotiation
+				// on startup.
+			},
 			// Note that, going forward, all new events must only write data inside of
 			// `write_tlv_fields`. Versions 0.0.101+ will ignore odd-numbered events that write
 			// data via `write_tlv_fields`.
@@ -2560,6 +2595,9 @@ impl MaybeReadable for Event {
 					former_temporary_channel_id: former_temporary_channel_id.0.unwrap(),
 				}))
 			},
+			// Note that we do not write a length-prefixed TLV for PersistStaticInvoice events.
+			#[cfg(async_payments)]
+			45u8 => Ok(None),
 			// Versions prior to 0.0.100 did not ignore odd types, instead returning InvalidValue.
 			// Version 0.0.100 failed to properly ignore odd types, possibly resulting in corrupt
 			// reads.

lightning/src/ln/channelmanager.rs

@@ -5121,6 +5121,13 @@ where
 		}
 	}
 
+	/// Should be called after handling an [`Event::PersistStaticInvoice`], where the `Responder`
+	/// comes from [`Event::PersistStaticInvoice::invoice_persisted_path`].
+	#[cfg(async_payments)]
+	pub fn static_invoice_persisted(&self, invoice_persisted_path: Responder) {
+		self.flow.serving_static_invoice(invoice_persisted_path);
+	}
+
 	#[rustfmt::skip]
 	#[cfg(async_payments)]
 	fn initiate_async_payment(
@@ -12938,6 +12945,29 @@ where
 		&self, _message: ServeStaticInvoice, _context: AsyncPaymentsContext,
 		_responder: Option<Responder>,
 	) {
+		#[cfg(async_payments)]
+		{
+			let responder = match _responder {
+				Some(resp) => resp,
+				None => return,
+			};
+
+			let recipient_id_nonce =
+				match self.flow.verify_serve_static_invoice_message(&_message, _context) {
+					Ok(nonce) => nonce,
+					Err(()) => return,
+				};
+
+			let mut pending_events = self.pending_events.lock().unwrap();
+			pending_events.push_back((
+				Event::PersistStaticInvoice {
+					invoice: _message.invoice,
+					recipient_id_nonce,
+					invoice_persisted_path: responder,
+				},
+				None,
+			));
+		}
 	}
 
 	fn handle_static_invoice_persisted(

lightning/src/offers/flow.rs

@@ -71,6 +71,7 @@ use {
 	},
 	crate::onion_message::async_payments::{
 		HeldHtlcAvailable, OfferPaths, OfferPathsRequest, ServeStaticInvoice,
+		StaticInvoicePersisted,
 	},
 	crate::onion_message::messenger::Responder,
 };
@@ -1551,6 +1552,59 @@ where
 		Ok((ServeStaticInvoice { invoice, forward_invoice_request_path }, reply_path_context))
 	}
 
+	/// Verifies an incoming [`ServeStaticInvoice`] onion message from an often-offline recipient who
+	/// wants us as a static invoice server to serve the [`ServeStaticInvoice::invoice`] to payers on
+	/// their behalf.
+	///
+	/// If verification succeeds, the provided [`ServeStaticInvoice::invoice`] should be persisted
+	/// keyed by [`ServeStaticInvoice::recipient_id_nonce`]. The invoice should then be served in
+	/// response to incoming [`InvoiceRequest`]s that have a context of
+	/// [`OffersContext::StaticInvoiceRequested`], where the
+	/// [`OffersContext::StaticInvoiceRequested::recipient_id_nonce`] matches the `recipient_id_nonce`
+	/// from the original [`ServeStaticInvoice`] message.
+	///
+	/// Once the invoice is persisted, [`Self::static_invoice_persisted`] must be called to confirm to
+	/// the recipient that their offer is ready to receive async payments.
+	///
+	/// [`ServeStaticInvoice::invoice`]: crate::onion_message::async_payments::ServeStaticInvoice::invoice
+	#[cfg(async_payments)]
+	pub(crate) fn verify_serve_static_invoice_message(
+		&self, message: &ServeStaticInvoice, context: AsyncPaymentsContext,
+	) -> Result<Nonce, ()> {
+		if message.invoice.is_expired_no_std(self.duration_since_epoch()) {
+			return Err(());
+		}
+		let expanded_key = &self.inbound_payment_key;
+		match context {
+			AsyncPaymentsContext::ServeStaticInvoice {
+				recipient_id_nonce,
+				nonce,
+				hmac,
+				path_absolute_expiry,
+			} => {
+				signer::verify_serve_static_invoice_context(nonce, hmac, expanded_key)?;
+				if self.duration_since_epoch() > path_absolute_expiry {
+					return Err(());
+				}
+
+				return Ok(recipient_id_nonce);
+			},
+			_ => return Err(()),
+		};
+	}
+
+	/// Indicates that a [`ServeStaticInvoice::invoice`] has been persisted and is ready to be served
+	/// to payers on behalf of an often-offline recipient. This method must be called after persisting
+	/// a [`StaticInvoice`] to confirm to the recipient that their corresponding [`Offer`] is ready to
+	/// receive async payments.
+	#[cfg(async_payments)]
+	pub(crate) fn serving_static_invoice(&self, responder: Responder) {
+		let mut pending_async_payments_messages =
+			self.pending_async_payments_messages.lock().unwrap();
+		let message = AsyncPaymentsMessage::StaticInvoicePersisted(StaticInvoicePersisted {});
+		pending_async_payments_messages.push((message, responder.respond().into_instructions()));
+	}
+
 	/// Handles an incoming [`StaticInvoicePersisted`] onion message from the static invoice server.
 	/// Returns a bool indicating whether the async receive offer cache needs to be re-persisted.
 	///

lightning/src/offers/signer.rs

@@ -657,6 +657,17 @@ pub(crate) fn hmac_for_serve_static_invoice_context(
 	Hmac::from_engine(hmac)
 }
 
+#[cfg(async_payments)]
+pub(crate) fn verify_serve_static_invoice_context(
+	nonce: Nonce, hmac: Hmac<Sha256>, expanded_key: &ExpandedKey,
+) -> Result<(), ()> {
+	if hmac_for_serve_static_invoice_context(nonce, expanded_key) == hmac {
+		Ok(())
+	} else {
+		Err(())
+	}
+}
+
 #[cfg(async_payments)]
 pub(crate) fn hmac_for_static_invoice_persisted_context(
 	nonce: Nonce, expanded_key: &ExpandedKey,