Add static invoice server messages and boilerplate

Because async recipients are not online to respond to invoice requests,
the plan is for another node on the network that is always-online to serve
static invoices on their behalf.

The protocol is as follows:
- Recipient is configured with blinded message paths to reach the static invoice
  server
- On startup, recipient requests blinded message paths for inclusion in their
  offer from the static invoice server over the configured paths
- Server replies with offer paths for the recipient
- Recipient builds their offer using these paths and the corresponding static
  invoice and replies with the invoice
- Server persists the invoice and confirms that they've persisted it, causing
  the recipient to cache the interactively built offer for use

At pay-time, the payer sends an invoice request to the static invoice server,
who replies with the static invoice after forwarding the invreq to the
recipient (to give them a chance to provide a fresh invoice in case they're
online).

Here we add the requisite trait methods and onion messages to support this
protocol.

An alterate design could be for the async recipient to publish static invoices
directly without a preceding offer, e.g. on their website. Some drawbacks of
this design include:
1) No fallback to regular BOLT 12 in the case that the recipient happens to be online
at pay-time. Falling back to regular BOLT 12 allows the recipient to provide a fresh
invoice and regain the proof-of-payment property
2) Static invoices don't fit in a QR code
3) No automatic rotation of the static invoice, which is useful in the case that payment
paths become outdated due to changing fees, etc

Author: valentinewallace

fuzz/src/onion_message.rs

@@ -15,7 +15,8 @@ use lightning::ln::peer_handler::IgnoringMessageHandler;
 use lightning::ln::script::ShutdownScript;
 use lightning::offers::invoice::UnsignedBolt12Invoice;
 use lightning::onion_message::async_payments::{
-	AsyncPaymentsMessageHandler, HeldHtlcAvailable, ReleaseHeldHtlc,
+	AsyncPaymentsMessageHandler, HeldHtlcAvailable, OfferPaths, OfferPathsRequest, ReleaseHeldHtlc,
+	ServeStaticInvoice, StaticInvoicePersisted,
 };
 use lightning::onion_message::messenger::{
 	CustomOnionMessageHandler, Destination, MessageRouter, MessageSendInstructions,
@@ -124,6 +125,30 @@ impl OffersMessageHandler for TestOffersMessageHandler {
 struct TestAsyncPaymentsMessageHandler {}
 
 impl AsyncPaymentsMessageHandler for TestAsyncPaymentsMessageHandler {
+	fn handle_offer_paths_request(
+		&self, _message: OfferPathsRequest, _context: AsyncPaymentsContext,
+		responder: Option<Responder>,
+	) -> Option<(OfferPaths, ResponseInstruction)> {
+		let responder = match responder {
+			Some(resp) => resp,
+			None => return None,
+		};
+		Some((OfferPaths { paths: Vec::new(), paths_absolute_expiry: None }, responder.respond()))
+	}
+	fn handle_offer_paths(
+		&self, _message: OfferPaths, _context: AsyncPaymentsContext, _responder: Option<Responder>,
+	) -> Option<(ServeStaticInvoice, ResponseInstruction)> {
+		None
+	}
+	fn handle_serve_static_invoice(
+		&self, _message: ServeStaticInvoice, _context: AsyncPaymentsContext,
+		_responder: Option<Responder>,
+	) {
+	}
+	fn handle_static_invoice_persisted(
+		&self, _message: StaticInvoicePersisted, _context: AsyncPaymentsContext,
+	) {
+	}
 	fn handle_held_htlc_available(
 		&self, _message: HeldHtlcAvailable, _context: AsyncPaymentsContext,
 		responder: Option<Responder>,

lightning/src/ln/channelmanager.rs

@@ -98,7 +98,8 @@ use crate::offers::parse::Bolt12SemanticError;
 use crate::offers::refund::Refund;
 use crate::offers::signer;
 use crate::onion_message::async_payments::{
-	AsyncPaymentsMessage, AsyncPaymentsMessageHandler, HeldHtlcAvailable, ReleaseHeldHtlc,
+	AsyncPaymentsMessage, AsyncPaymentsMessageHandler, HeldHtlcAvailable, OfferPaths,
+	OfferPathsRequest, ReleaseHeldHtlc, ServeStaticInvoice, StaticInvoicePersisted,
 };
 use crate::onion_message::dns_resolution::HumanReadableName;
 use crate::onion_message::messenger::{
@@ -12995,6 +12996,30 @@ where
 	MR::Target: MessageRouter,
 	L::Target: Logger,
 {
+	fn handle_offer_paths_request(
+		&self, _message: OfferPathsRequest, _context: AsyncPaymentsContext,
+		_responder: Option<Responder>,
+	) -> Option<(OfferPaths, ResponseInstruction)> {
+		None
+	}
+
+	fn handle_offer_paths(
+		&self, _message: OfferPaths, _context: AsyncPaymentsContext, _responder: Option<Responder>,
+	) -> Option<(ServeStaticInvoice, ResponseInstruction)> {
+		None
+	}
+
+	fn handle_serve_static_invoice(
+		&self, _message: ServeStaticInvoice, _context: AsyncPaymentsContext,
+		_responder: Option<Responder>,
+	) {
+	}
+
+	fn handle_static_invoice_persisted(
+		&self, _message: StaticInvoicePersisted, _context: AsyncPaymentsContext,
+	) {
+	}
+
 	fn handle_held_htlc_available(
 		&self, _message: HeldHtlcAvailable, _context: AsyncPaymentsContext,
 		_responder: Option<Responder>,

lightning/src/ln/peer_handler.rs

@@ -30,7 +30,7 @@ use crate::util::ser::{VecWriter, Writeable, Writer};
 use crate::ln::peer_channel_encryptor::{PeerChannelEncryptor, NextNoiseStep, MessageBuf, MSG_BUF_ALLOC_SIZE};
 use crate::ln::wire;
 use crate::ln::wire::{Encode, Type};
-use crate::onion_message::async_payments::{AsyncPaymentsMessageHandler, HeldHtlcAvailable, ReleaseHeldHtlc};
+use crate::onion_message::async_payments::{AsyncPaymentsMessageHandler, HeldHtlcAvailable, OfferPaths, OfferPathsRequest, ServeStaticInvoice, ReleaseHeldHtlc, StaticInvoicePersisted};
 use crate::onion_message::dns_resolution::{DNSResolverMessageHandler, DNSResolverMessage, DNSSECProof, DNSSECQuery};
 use crate::onion_message::messenger::{CustomOnionMessageHandler, Responder, ResponseInstruction, MessageSendInstructions};
 use crate::onion_message::offers::{OffersMessage, OffersMessageHandler};
@@ -148,6 +148,23 @@ impl OffersMessageHandler for IgnoringMessageHandler {
 	}
 }
 impl AsyncPaymentsMessageHandler for IgnoringMessageHandler {
+	fn handle_offer_paths_request(
+		&self, _message: OfferPathsRequest, _context: AsyncPaymentsContext, _responder: Option<Responder>,
+	) -> Option<(OfferPaths, ResponseInstruction)> {
+		None
+	}
+	fn handle_offer_paths(
+		&self, _message: OfferPaths, _context: AsyncPaymentsContext, _responder: Option<Responder>,
+	) -> Option<(ServeStaticInvoice, ResponseInstruction)> {
+		None
+	}
+	fn handle_serve_static_invoice(
+		&self, _message: ServeStaticInvoice, _context: AsyncPaymentsContext,
+		_responder: Option<Responder>,
+	) {}
+	fn handle_static_invoice_persisted(
+		&self, _message: StaticInvoicePersisted, _context: AsyncPaymentsContext,
+	) {}
 	fn handle_held_htlc_available(
 		&self, _message: HeldHtlcAvailable, _context: AsyncPaymentsContext,
 		_responder: Option<Responder>,

lightning/src/onion_message/async_payments.rs

@@ -9,22 +9,64 @@
 
 //! Message handling for async payments.
 
-use crate::blinded_path::message::AsyncPaymentsContext;
+use crate::blinded_path::message::{AsyncPaymentsContext, BlindedMessagePath};
 use crate::io;
 use crate::ln::msgs::DecodeError;
+use crate::offers::static_invoice::StaticInvoice;
 use crate::onion_message::messenger::{MessageSendInstructions, Responder, ResponseInstruction};
 use crate::onion_message::packet::OnionMessageContents;
 use crate::prelude::*;
 use crate::util::ser::{Readable, ReadableArgs, Writeable, Writer};
 
 // TLV record types for the `onionmsg_tlv` TLV stream as defined in BOLT 4.
+const OFFER_PATHS_REQ_TLV_TYPE: u64 = 65538;
+const OFFER_PATHS_TLV_TYPE: u64 = 65540;
+const SERVE_INVOICE_TLV_TYPE: u64 = 65542;
+const INVOICE_PERSISTED_TLV_TYPE: u64 = 65544;
 const HELD_HTLC_AVAILABLE_TLV_TYPE: u64 = 72;
 const RELEASE_HELD_HTLC_TLV_TYPE: u64 = 74;
 
 /// A handler for an [`OnionMessage`] containing an async payments message as its payload.
 ///
 /// [`OnionMessage`]: crate::ln::msgs::OnionMessage
 pub trait AsyncPaymentsMessageHandler {
+	/// Handle an [`OfferPathsRequest`] message. If we are a static invoice server and the message was
+	/// sent over paths that we previously provided to an async recipient via
+	/// [`UserConfig::paths_to_static_invoice_server`], an [`OfferPaths`] message should be returned.
+	///
+	/// [`UserConfig::paths_to_static_invoice_server`]: crate::util::config::UserConfig::paths_to_static_invoice_server
+	fn handle_offer_paths_request(
+		&self, message: OfferPathsRequest, context: AsyncPaymentsContext,
+		responder: Option<Responder>,
+	) -> Option<(OfferPaths, ResponseInstruction)>;
+
+	/// Handle an [`OfferPaths`] message. If this is in response to an [`OfferPathsRequest`] that
+	/// we previously sent as an async recipient, we should build an [`Offer`] containing the
+	/// included [`OfferPaths::paths`] and a corresponding [`StaticInvoice`], and reply with
+	/// [`ServeStaticInvoice`].
+	///
+	/// [`Offer`]: crate::offers::offer::Offer
+	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+	fn handle_offer_paths(
+		&self, message: OfferPaths, context: AsyncPaymentsContext, responder: Option<Responder>,
+	) -> Option<(ServeStaticInvoice, ResponseInstruction)>;
+
+	/// Handle a [`ServeStaticInvoice`] message. If this is in response to an [`OfferPaths`] message
+	/// we previously sent as a static invoice server, a [`StaticInvoicePersisted`] message should be
+	/// sent once the message is handled.
+	fn handle_serve_static_invoice(
+		&self, message: ServeStaticInvoice, context: AsyncPaymentsContext,
+		responder: Option<Responder>,
+	);
+
+	/// Handle a [`StaticInvoicePersisted`] message. If this is in response to a
+	/// [`ServeStaticInvoice`] message we previously sent as an async recipient, then the offer we
+	/// generated on receipt of a previous [`OfferPaths`] message is now ready to be used for async
+	/// payments.
+	fn handle_static_invoice_persisted(
+		&self, message: StaticInvoicePersisted, context: AsyncPaymentsContext,
+	);
+
 	/// Handle a [`HeldHtlcAvailable`] message. A [`ReleaseHeldHtlc`] should be returned to release
 	/// the held funds.
 	fn handle_held_htlc_available(
@@ -50,6 +92,29 @@ pub trait AsyncPaymentsMessageHandler {
 /// [`OnionMessage`]: crate::ln::msgs::OnionMessage
 #[derive(Clone, Debug)]
 pub enum AsyncPaymentsMessage {
+	/// A request from an async recipient for [`BlindedMessagePath`]s, sent to a static invoice
+	/// server.
+	OfferPathsRequest(OfferPathsRequest),
+
+	/// [`BlindedMessagePath`]s to be included in an async recipient's [`Offer::paths`], sent by a
+	/// static invoice server in response to an [`OfferPathsRequest`].
+	///
+	/// [`Offer::paths`]: crate::offers::offer::Offer::paths
+	OfferPaths(OfferPaths),
+
+	/// A request from an async recipient to a static invoice server that a [`StaticInvoice`] be
+	/// provided in response to [`InvoiceRequest`]s from payers.
+	///
+	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+	ServeStaticInvoice(ServeStaticInvoice),
+
+	/// Confirmation  from a static invoice server  that a [`StaticInvoice`] was persisted and the
+	/// corresponding [`Offer`] is ready to be used to receive async payments. Sent to an async
+	/// recipient in response to a [`ServeStaticInvoice`] message.
+	///
+	/// [`Offer`]: crate::offers::offer::Offer
+	StaticInvoicePersisted(StaticInvoicePersisted),
+
 	/// An HTLC is being held upstream for the often-offline recipient, to be released via
 	/// [`ReleaseHeldHtlc`].
 	HeldHtlcAvailable(HeldHtlcAvailable),
@@ -58,6 +123,62 @@ pub enum AsyncPaymentsMessage {
 	ReleaseHeldHtlc(ReleaseHeldHtlc),
 }
 
+/// A request from an async recipient for [`BlindedMessagePath`]s from a static invoice server.
+/// These paths will be used in the async recipient's [`Offer::paths`], so payers can request
+/// [`StaticInvoice`]s from the static invoice server.
+///
+/// [`Offer::paths`]: crate::offers::offer::Offer::paths
+#[derive(Clone, Debug)]
+pub struct OfferPathsRequest {}
+
+/// [`BlindedMessagePath`]s to be included in an async recipient's [`Offer::paths`], sent by a
+/// static invoice server in response to an [`OfferPathsRequest`].
+///
+/// [`Offer::paths`]: crate::offers::offer::Offer::paths
+#[derive(Clone, Debug)]
+pub struct OfferPaths {
+	/// The paths that should be included in the async recipient's [`Offer::paths`].
+	///
+	/// [`Offer::paths`]: crate::offers::offer::Offer::paths
+	pub paths: Vec<BlindedMessagePath>,
+	/// The time as seconds since the Unix epoch at which the [`Self::paths`] expire.
+	pub paths_absolute_expiry: Option<u64>,
+}
+
+/// A request from an async recipient to a static invoice server that a [`StaticInvoice`] be
+/// provided in response to [`InvoiceRequest`]s from payers.
+///
+/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+#[derive(Clone, Debug)]
+pub struct ServeStaticInvoice {
+	/// The invoice that should be served by the static invoice server. Once this invoice has been
+	/// persisted, the [`Responder`] accompanying this message should be used to send
+	/// [`StaticInvoicePersisted`] to the recipient to confirm that the offer corresponding to the
+	/// invoice is ready to receive async payments.
+	pub invoice: StaticInvoice,
+	/// If a static invoice server receives an [`InvoiceRequest`] for a [`StaticInvoice`], they should
+	/// also forward the [`InvoiceRequest`] to the async recipient so they can respond with a fresh
+	/// [`Bolt12Invoice`] if the recipient is online at the time. Use this path to forward the
+	/// [`InvoiceRequest`] to the async recipient.
+	///
+	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
+	pub forward_invoice_request_path: BlindedMessagePath,
+	/// The "slot" in the static invoice server's database that this invoice should go into. This
+	/// allows recipients to replace a specific invoice that is stored by the server, which is useful
+	/// for limiting the number of invoices stored by the server while also keeping all the invoices
+	/// persisted with the server fresh.
+	pub invoice_slot: u8,
+}
+
+/// Confirmation from a static invoice server  that a [`StaticInvoice`] was persisted and the
+/// corresponding [`Offer`] is ready to be used to receive async payments. Sent to an async
+/// recipient in response to a [`ServeStaticInvoice`] message.
+///
+/// [`Offer`]: crate::offers::offer::Offer
+#[derive(Clone, Debug)]
+pub struct StaticInvoicePersisted {}
+
 /// An HTLC destined for the recipient of this message is being held upstream. The reply path
 /// accompanying this onion message should be used to send a [`ReleaseHeldHtlc`] response, which
 /// will cause the upstream HTLC to be released.
@@ -68,6 +189,34 @@ pub struct HeldHtlcAvailable {}
 #[derive(Clone, Debug)]
 pub struct ReleaseHeldHtlc {}
 
+impl OnionMessageContents for OfferPaths {
+	fn tlv_type(&self) -> u64 {
+		OFFER_PATHS_TLV_TYPE
+	}
+	#[cfg(c_bindings)]
+	fn msg_type(&self) -> String {
+		"Offer Paths".to_string()
+	}
+	#[cfg(not(c_bindings))]
+	fn msg_type(&self) -> &'static str {
+		"Offer Paths"
+	}
+}
+
+impl OnionMessageContents for ServeStaticInvoice {
+	fn tlv_type(&self) -> u64 {
+		SERVE_INVOICE_TLV_TYPE
+	}
+	#[cfg(c_bindings)]
+	fn msg_type(&self) -> String {
+		"Serve Static Invoice".to_string()
+	}
+	#[cfg(not(c_bindings))]
+	fn msg_type(&self) -> &'static str {
+		"Serve Static Invoice"
+	}
+}
+
 impl OnionMessageContents for ReleaseHeldHtlc {
 	fn tlv_type(&self) -> u64 {
 		RELEASE_HELD_HTLC_TLV_TYPE
@@ -82,6 +231,21 @@ impl OnionMessageContents for ReleaseHeldHtlc {
 	}
 }
 
+impl_writeable_tlv_based!(OfferPathsRequest, {});
+
+impl_writeable_tlv_based!(OfferPaths, {
+	(0, paths, required_vec),
+	(2, paths_absolute_expiry, option),
+});
+
+impl_writeable_tlv_based!(ServeStaticInvoice, {
+	(0, invoice, required),
+	(2, forward_invoice_request_path, required),
+	(4, invoice_slot, required),
+});
+
+impl_writeable_tlv_based!(StaticInvoicePersisted, {});
+
 impl_writeable_tlv_based!(HeldHtlcAvailable, {});
 
 impl_writeable_tlv_based!(ReleaseHeldHtlc, {});
@@ -90,7 +254,12 @@ impl AsyncPaymentsMessage {
 	/// Returns whether `tlv_type` corresponds to a TLV record for async payment messages.
 	pub fn is_known_type(tlv_type: u64) -> bool {
 		match tlv_type {
-			HELD_HTLC_AVAILABLE_TLV_TYPE | RELEASE_HELD_HTLC_TLV_TYPE => true,
+			OFFER_PATHS_REQ_TLV_TYPE
+			| OFFER_PATHS_TLV_TYPE
+			| SERVE_INVOICE_TLV_TYPE
+			| INVOICE_PERSISTED_TLV_TYPE
+			| HELD_HTLC_AVAILABLE_TLV_TYPE
+			| RELEASE_HELD_HTLC_TLV_TYPE => true,
 			_ => false,
 		}
 	}
@@ -99,20 +268,32 @@ impl AsyncPaymentsMessage {
 impl OnionMessageContents for AsyncPaymentsMessage {
 	fn tlv_type(&self) -> u64 {
 		match self {
+			Self::OfferPathsRequest(_) => OFFER_PATHS_REQ_TLV_TYPE,
+			Self::OfferPaths(msg) => msg.tlv_type(),
+			Self::ServeStaticInvoice(msg) => msg.tlv_type(),
+			Self::StaticInvoicePersisted(_) => INVOICE_PERSISTED_TLV_TYPE,
 			Self::HeldHtlcAvailable(_) => HELD_HTLC_AVAILABLE_TLV_TYPE,
 			Self::ReleaseHeldHtlc(msg) => msg.tlv_type(),
 		}
 	}
 	#[cfg(c_bindings)]
 	fn msg_type(&self) -> String {
 		match &self {
+			Self::OfferPathsRequest(_) => "Offer Paths Request".to_string(),
+			Self::OfferPaths(msg) => msg.msg_type(),
+			Self::ServeStaticInvoice(msg) => msg.msg_type(),
+			Self::StaticInvoicePersisted(_) => "Static Invoice Persisted".to_string(),
 			Self::HeldHtlcAvailable(_) => "Held HTLC Available".to_string(),
 			Self::ReleaseHeldHtlc(msg) => msg.msg_type(),
 		}
 	}
 	#[cfg(not(c_bindings))]
 	fn msg_type(&self) -> &'static str {
 		match &self {
+			Self::OfferPathsRequest(_) => "Offer Paths Request",
+			Self::OfferPaths(msg) => msg.msg_type(),
+			Self::ServeStaticInvoice(msg) => msg.msg_type(),
+			Self::StaticInvoicePersisted(_) => "Static Invoice Persisted",
 			Self::HeldHtlcAvailable(_) => "Held HTLC Available",
 			Self::ReleaseHeldHtlc(msg) => msg.msg_type(),
 		}
@@ -122,6 +303,10 @@ impl OnionMessageContents for AsyncPaymentsMessage {
 impl Writeable for AsyncPaymentsMessage {
 	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
 		match self {
+			Self::OfferPathsRequest(message) => message.write(w),
+			Self::OfferPaths(message) => message.write(w),
+			Self::ServeStaticInvoice(message) => message.write(w),
+			Self::StaticInvoicePersisted(message) => message.write(w),
 			Self::HeldHtlcAvailable(message) => message.write(w),
 			Self::ReleaseHeldHtlc(message) => message.write(w),
 		}
@@ -131,6 +316,10 @@ impl Writeable for AsyncPaymentsMessage {
 impl ReadableArgs<u64> for AsyncPaymentsMessage {
 	fn read<R: io::Read>(r: &mut R, tlv_type: u64) -> Result<Self, DecodeError> {
 		match tlv_type {
+			OFFER_PATHS_REQ_TLV_TYPE => Ok(Self::OfferPathsRequest(Readable::read(r)?)),
+			OFFER_PATHS_TLV_TYPE => Ok(Self::OfferPaths(Readable::read(r)?)),
+			SERVE_INVOICE_TLV_TYPE => Ok(Self::ServeStaticInvoice(Readable::read(r)?)),
+			INVOICE_PERSISTED_TLV_TYPE => Ok(Self::StaticInvoicePersisted(Readable::read(r)?)),
 			HELD_HTLC_AVAILABLE_TLV_TYPE => Ok(Self::HeldHtlcAvailable(Readable::read(r)?)),
 			RELEASE_HELD_HTLC_TLV_TYPE => Ok(Self::ReleaseHeldHtlc(Readable::read(r)?)),
 			_ => Err(DecodeError::InvalidValue),