Track cached async receive offers in offers::Flow

In future commits, as part of being an async recipient, we will interactively
build offers and static invoices with an always-online node that will serve
static invoices on our behalf.

Once an offer is built and the static invoice is confirmed as persisted by the
server, we will use the new offer cache added here to save the invoice metadata
and the offer in ChannelManager, though the OffersMessageFlow is responsible
for keeping the cache updated.

We want to cache and persist these offers so we always have them at the ready,
we don't want to begin the process of interactively building an offer the
moment it is needed. The offers are likely to be long-lived so caching them
avoids having to keep interactively rebuilding them after every restart.

Author: valentinewallace

lightning/src/ln/channelmanager.rs

@@ -85,6 +85,7 @@ use crate::ln::outbound_payment::{
 	SendAlongPathArgs, StaleExpiration,
 };
 use crate::ln::types::ChannelId;
+use crate::offers::async_receive_offer_cache::AsyncReceiveOfferCache;
 use crate::offers::flow::OffersMessageFlow;
 use crate::offers::invoice::{
 	Bolt12Invoice, DerivedSigningPubkey, InvoiceBuilder, DEFAULT_RELATIVE_EXPIRY,
@@ -13683,6 +13684,7 @@ where
 			(15, self.inbound_payment_id_secret, required),
 			(17, in_flight_monitor_updates, option),
 			(19, peer_storage_dir, optional_vec),
+			(21, self.flow.writeable_async_receive_offer_cache(), required),
 		});
 
 		Ok(())
@@ -14247,6 +14249,7 @@ where
 		let mut decode_update_add_htlcs: Option<HashMap<u64, Vec<msgs::UpdateAddHTLC>>> = None;
 		let mut inbound_payment_id_secret = None;
 		let mut peer_storage_dir: Option<Vec<(PublicKey, Vec<u8>)>> = None;
+		let mut async_receive_offer_cache: AsyncReceiveOfferCache = AsyncReceiveOfferCache::new();
 		read_tlv_fields!(reader, {
 			(1, pending_outbound_payments_no_retry, option),
 			(2, pending_intercepted_htlcs, option),
@@ -14264,6 +14267,7 @@ where
 			(15, inbound_payment_id_secret, option),
 			(17, in_flight_monitor_updates, option),
 			(19, peer_storage_dir, optional_vec),
+			(21, async_receive_offer_cache, (default_value, async_receive_offer_cache)),
 		});
 		let mut decode_update_add_htlcs = decode_update_add_htlcs.unwrap_or_else(|| new_hash_map());
 		let peer_storage_dir: Vec<(PublicKey, Vec<u8>)> = peer_storage_dir.unwrap_or_else(Vec::new);
@@ -14950,6 +14954,8 @@ where
 			chain_hash, best_block, our_network_pubkey,
 			highest_seen_timestamp, expanded_inbound_key,
 			secp_ctx.clone(), args.message_router
+		).with_async_payments_offers_cache(
+			async_receive_offer_cache, &args.default_config.paths_to_static_invoice_server[..]
 		);
 
 		let channel_manager = ChannelManager {

lightning/src/offers/async_receive_offer_cache.rs

@@ -0,0 +1,106 @@
+// This file is Copyright its original authors, visible in version control
+// history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
+// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
+// You may not use this file except in accordance with one or both of these
+// licenses.
+
+//! Data structures and methods for caching offers that we interactively build with a static invoice
+//! server as an async recipient. The static invoice server will serve the resulting invoices to
+//! payers on our behalf when we're offline.
+
+use crate::io;
+use crate::io::Read;
+use crate::ln::msgs::DecodeError;
+use crate::offers::nonce::Nonce;
+use crate::offers::offer::Offer;
+use crate::onion_message::messenger::Responder;
+use crate::prelude::*;
+use crate::util::ser::{Readable, Writeable, Writer};
+use core::time::Duration;
+
+struct AsyncReceiveOffer {
+	offer: Offer,
+	/// We determine whether an offer is expiring "soon" based on how far the offer is into its total
+	/// lifespan, using this field.
+	offer_created_at: Duration,
+
+	/// The below fields are used to generate and persist a new static invoice with the invoice
+	/// server, if the invoice is expiring prior to the corresponding offer. We support automatically
+	/// rotating the invoice for long-lived offers so users don't have to update the offer they've
+	/// posted on e.g. their website if fees change or the invoices' payment paths become otherwise
+	/// outdated.
+	offer_nonce: Nonce,
+	update_static_invoice_path: Responder,
+	static_invoice_absolute_expiry: Duration,
+	invoice_update_attempts: u8,
+}
+
+impl_writeable_tlv_based!(AsyncReceiveOffer, {
+	(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, invoice_update_attempts, (static_value, 0)),
+});
+
+/// If we are an often-offline recipient, we'll want to interactively build offers and static
+/// invoices with an always-online node that will serve those static invoices to payers on our
+/// behalf when we are offline.
+///
+/// This struct is used to cache those interactively built offers, and should be passed into
+/// [`OffersMessageFlow`] on startup as well as persisted whenever an offer or invoice is updated
+/// with the static invoice server.
+///
+/// [`OffersMessageFlow`]: crate::offers::flow::OffersMessageFlow
+pub struct AsyncReceiveOfferCache {
+	offers: Vec<AsyncReceiveOffer>,
+	/// Used to limit the number of times we request paths for our offer from the static invoice
+	/// server.
+	#[allow(unused)] // TODO: remove when we get rid of async payments cfg flag
+	offer_paths_request_attempts: u8,
+	/// Used to determine whether enough time has passed since our last request for offer paths that
+	/// more requests should be allowed to go out.
+	#[allow(unused)] // TODO: remove when we get rid of async payments cfg flag
+	last_offer_paths_request_timestamp: Duration,
+}
+
+impl AsyncReceiveOfferCache {
+	/// Creates an empty [`AsyncReceiveOfferCache`] to be passed into [`OffersMessageFlow`].
+	///
+	/// [`OffersMessageFlow`]: crate::offers::flow::OffersMessageFlow
+	pub fn new() -> Self {
+		Self {
+			offers: Vec::new(),
+			offer_paths_request_attempts: 0,
+			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, {
+			(0, self.offers, required_vec),
+			// offer paths request retry info always resets on restart
+		});
+		Ok(())
+	}
+}
+
+impl Readable for AsyncReceiveOfferCache {
+	fn read<R: Read>(r: &mut R) -> Result<Self, DecodeError> {
+		_init_and_read_len_prefixed_tlv_fields!(r, {
+			(0, offers, required_vec),
+		});
+		let offers: Vec<AsyncReceiveOffer> = offers;
+		Ok(Self {
+			offers,
+			offer_paths_request_attempts: 0,
+			last_offer_paths_request_timestamp: Duration::from_secs(0),
+		})
+	}
+}

lightning/src/offers/flow.rs

@@ -36,6 +36,7 @@ use crate::ln::channelmanager::{
 	Verification, {PaymentId, CLTV_FAR_FAR_AWAY, MAX_SHORT_LIVED_RELATIVE_EXPIRY},
 };
 use crate::ln::inbound_payment;
+use crate::offers::async_receive_offer_cache::AsyncReceiveOfferCache;
 use crate::offers::invoice::{
 	Bolt12Invoice, DerivedSigningPubkey, ExplicitSigningPubkey, InvoiceBuilder,
 	UnsignedBolt12Invoice, DEFAULT_RELATIVE_EXPIRY,
@@ -56,6 +57,7 @@ use crate::routing::router::Router;
 use crate::sign::{EntropySource, NodeSigner};
 use crate::sync::{Mutex, RwLock};
 use crate::types::payment::{PaymentHash, PaymentSecret};
+use crate::util::ser::Writeable;
 
 #[cfg(async_payments)]
 use {
@@ -98,6 +100,10 @@ where
 	pub(crate) pending_offers_messages: Mutex<Vec<(OffersMessage, MessageSendInstructions)>>,
 
 	pending_async_payments_messages: Mutex<Vec<(AsyncPaymentsMessage, MessageSendInstructions)>>,
+	async_receive_offer_cache: Mutex<AsyncReceiveOfferCache>,
+	/// Blinded paths used to request offer paths from the static invoice server, if we are an async
+	/// recipient.
+	paths_to_static_invoice_server: Vec<BlindedMessagePath>,
 
 	#[cfg(feature = "dnssec")]
 	pub(crate) hrn_resolver: OMNameResolver,
@@ -133,9 +139,25 @@ where
 			hrn_resolver: OMNameResolver::new(current_timestamp, best_block.height),
 			#[cfg(feature = "dnssec")]
 			pending_dns_onion_messages: Mutex::new(Vec::new()),
+
+			async_receive_offer_cache: Mutex::new(AsyncReceiveOfferCache::new()),
+			paths_to_static_invoice_server: Vec::new(),
 		}
 	}
 
+	/// If we are an async recipient, on startup we'll interactively build offers and static invoices
+	/// with an always-online node that will serve static invoices on our behalf. Once the offer is
+	/// built and the static invoice is confirmed as persisted by the server, the underlying
+	/// [`AsyncReceiveOfferCache`] should be persisted so we remember the offers we've built.
+	pub(crate) fn with_async_payments_offers_cache(
+		mut self, async_receive_offer_cache: AsyncReceiveOfferCache,
+		paths_to_static_invoice_server: &[BlindedMessagePath],
+	) -> Self {
+		self.async_receive_offer_cache = Mutex::new(async_receive_offer_cache);
+		self.paths_to_static_invoice_server = paths_to_static_invoice_server.to_vec();
+		self
+	}
+
 	/// Gets the node_id held by this [`OffersMessageFlow`]`
 	fn get_our_node_id(&self) -> PublicKey {
 		self.our_network_pubkey
@@ -1082,4 +1104,9 @@ where
 	) -> Vec<(DNSResolverMessage, MessageSendInstructions)> {
 		core::mem::take(&mut self.pending_dns_onion_messages.lock().unwrap())
 	}
+
+	/// Get the `AsyncReceiveOfferCache` for persistence.
+	pub(crate) fn writeable_async_receive_offer_cache(&self) -> impl Writeable + '_ {
+		&self.async_receive_offer_cache
+	}
 }

lightning/src/offers/mod.rs

@@ -16,6 +16,7 @@
 pub mod offer;
 pub mod flow;
 
+pub(crate) mod async_receive_offer_cache;
 pub mod invoice;
 pub mod invoice_error;
 mod invoice_macros;