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.

Author: valentinewallace

lightning/src/ln/channelmanager.rs

@@ -66,6 +66,7 @@ use crate::ln::msgs::{BaseMessageHandler, ChannelMessageHandler, CommitmentUpdat
 #[cfg(test)]
 use crate::ln::outbound_payment;
 use crate::ln::outbound_payment::{Bolt11PaymentError, OutboundPayments, PendingOutboundPayment, RetryableInvoiceRequest, SendAlongPathArgs, StaleExpiration};
+use crate::offers::async_receive_offer_cache::AsyncReceiveOfferCache;
 use crate::offers::invoice::{Bolt12Invoice, DerivedSigningPubkey, InvoiceBuilder, DEFAULT_RELATIVE_EXPIRY};
 use crate::offers::invoice_error::InvoiceError;
 use crate::offers::invoice_request::InvoiceRequest;
@@ -13759,6 +13760,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),
@@ -13776,6 +13778,7 @@ where
 			(15, inbound_payment_id_secret, option),
 			(17, in_flight_monitor_updates, required),
 			(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);
@@ -14430,7 +14433,12 @@ where
 		}
 
 		let best_block = BestBlock::new(best_block_hash, best_block_height);
-		let flow = OffersMessageFlow::new(chain_hash, best_block, our_network_pubkey, highest_seen_timestamp, expanded_inbound_key, secp_ctx.clone(), args.message_router);
+		let flow = OffersMessageFlow::new(
+			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 {
 			chain_hash,

lightning/src/offers/async_receive_offer_cache.rs

@@ -0,0 +1,103 @@
+// 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.
+	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,
@@ -98,6 +99,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 +138,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`]`
 	pub fn get_our_node_id(&self) -> PublicKey {
 		self.our_network_pubkey
@@ -724,14 +745,14 @@ where
 
 	/// Creates an [`InvoiceBuilder`] using the provided [`Refund`].
 	///
-	/// This method is used when a node wishes to construct an [`InvoiceBuilder`]  
+	/// This method is used when a node wishes to construct an [`InvoiceBuilder`]
 	/// in response to a [`Refund`] request as part of a BOLT 12 flow.
 	///
 	/// Returns an `InvoiceBuilder` configured with:
 	/// - Blinded paths derived from the provided `payment_secret`, which the counterparty will use to pay the invoice.
 	/// - The given `payment_hash` and `payment_secret` to enable secure claim verification.
 	///
-	/// Returns an error if the refund targets a different chain or if no valid  
+	/// Returns an error if the refund targets a different chain or if no valid
 	/// blinded path can be constructed.
 	pub fn create_invoice_builder_from_refund<'a, ES: Deref, R: Deref>(
 		&'a self, router: &R, entropy_source: ES, refund: &'a Refund, payment_hash: PaymentHash,

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;