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

@@ -1582,6 +1582,47 @@ 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 the recipient was configured with
+	/// them via [`ChannelManager::set_paths_to_static_invoice_server`].
+	///
+	/// [`ChannelManager::blinded_paths_for_async_recipient`]: crate::ln::channelmanager::ChannelManager::blinded_paths_for_async_recipient
+	/// [`ChannelManager::set_paths_to_static_invoice_server`]: crate::ln::channelmanager::ChannelManager::set_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,
+		/// Useful for the recipient to replace a specific invoice stored by us as the static invoice
+		/// server.
+		///
+		/// When this invoice and its metadata are persisted, this slot number should be included so if
+		/// we receive another [`Event::PersistStaticInvoice`] containing the same slot number we can
+		/// swap the existing invoice out for the new one.
+		invoice_slot: u16,
+		/// An identifier for the recipient, originally provided to
+		/// [`ChannelManager::blinded_paths_for_async_recipient`].
+		///
+		/// When an `Event::StaticInvoiceRequested` comes in for the invoice, this id will be surfaced
+		/// and can be used alongside the `invoice_id` to retrieve the invoice from the database.
+		recipient_id: Vec<u8>,
+		/// A random identifier for the invoice. When an `Event::StaticInvoiceRequested` comes in for
+		/// the invoice, this id will be surfaced and can be used alongside the `recipient_id` to
+		/// retrieve the invoice from the database.
+		///
+		/// Note that this id will remain the same for all invoice updates corresponding to a particular
+		/// offer that the recipient has cached.
+		invoice_id: u128,
+		/// Once the [`StaticInvoice`], `invoice_slot` and `invoice_id` are 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 {
@@ -2012,6 +2053,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`.
@@ -2583,6 +2630,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

@@ -5272,6 +5272,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.static_invoice_persisted(invoice_persisted_path);
+	}
+
 	#[cfg(async_payments)]
 	fn initiate_async_payment(
 		&self, invoice: &StaticInvoice, payment_id: PaymentId,
@@ -13535,6 +13542,31 @@ where
 		&self, _message: ServeStaticInvoice, _context: AsyncPaymentsContext,
 		_responder: Option<Responder>,
 	) {
+		#[cfg(async_payments)]
+		{
+			let responder = match _responder {
+				Some(resp) => resp,
+				None => return,
+			};
+
+			let (recipient_id, invoice_id) =
+				match self.flow.verify_serve_static_invoice_message(&_message, _context) {
+					Ok((recipient_id, inv_id)) => (recipient_id, inv_id),
+					Err(()) => return,
+				};
+
+			let mut pending_events = self.pending_events.lock().unwrap();
+			pending_events.push_back((
+				Event::PersistStaticInvoice {
+					invoice: _message.invoice,
+					invoice_slot: _message.invoice_slot,
+					recipient_id,
+					invoice_id,
+					invoice_persisted_path: responder,
+				},
+				None,
+			));
+		}
 	}
 
 	fn handle_static_invoice_persisted(

lightning/src/offers/flow.rs

@@ -68,6 +68,7 @@ use {
 	crate::offers::static_invoice::{StaticInvoice, StaticInvoiceBuilder},
 	crate::onion_message::async_payments::{
 		HeldHtlcAvailable, OfferPaths, OfferPathsRequest, ServeStaticInvoice,
+		StaticInvoicePersisted,
 	},
 	crate::onion_message::messenger::Responder,
 };
@@ -1526,6 +1527,49 @@ where
 		Ok((invoice, forward_invoice_request_path))
 	}
 
+	/// 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.
+	///
+	/// On success, returns `(recipient_id, invoice_id)` for use in persisting and later retrieving
+	/// the static invoice from the database.
+	///
+	/// [`ServeStaticInvoice::invoice`]: crate::onion_message::async_payments::ServeStaticInvoice::invoice
+	#[cfg(async_payments)]
+	pub fn verify_serve_static_invoice_message(
+		&self, message: &ServeStaticInvoice, context: AsyncPaymentsContext,
+	) -> Result<(Vec<u8>, u128), ()> {
+		if message.invoice.is_expired_no_std(self.duration_since_epoch()) {
+			return Err(());
+		}
+		match context {
+			AsyncPaymentsContext::ServeStaticInvoice {
+				recipient_id,
+				invoice_id,
+				path_absolute_expiry,
+			} => {
+				if self.duration_since_epoch() > path_absolute_expiry {
+					return Err(());
+				}
+
+				return Ok((recipient_id, invoice_id));
+			},
+			_ => 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 fn static_invoice_persisted(&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.
 	///