Introduce active_recurrence_sessions (PoC state tracker)

This commit adds a minimal state tracker in `ChannelManager` for handling
inbound recurring BOLT12 payments. Each entry records the payer’s
recurrence progress (offset, next expected counter, and basetime), giving
the payee enough information to validate successive `invoice_request`s
and produce consistent invoices.

LDK inbound payments have historically been fully stateless. Introducing
a stateful mechanism here is a deliberate PoC choice to make recurrence
behavior correct and testable end-to-end. For production, we may instead
push this state to the user layer, or provide hooks so nodes can manage
their own recurrence state externally.

For now, this internal tracker gives us a clear foundation to build and
evaluate the recurrence flow.

Author: shaavan

lightning/src/ln/channelmanager.rs

@@ -95,7 +95,7 @@ use crate::offers::invoice::{Bolt12Invoice, UnsignedBolt12Invoice};
 use crate::offers::invoice_error::InvoiceError;
 use crate::offers::invoice_request::{InvoiceRequest, InvoiceRequestVerifiedFromOffer};
 use crate::offers::nonce::Nonce;
-use crate::offers::offer::{Offer, OfferFromHrn, RecurrenceFields};
+use crate::offers::offer::{Offer, OfferFromHrn, RecurrenceData, RecurrenceFields};
 use crate::offers::parse::Bolt12SemanticError;
 use crate::offers::refund::Refund;
 use crate::offers::static_invoice::StaticInvoice;
@@ -2671,6 +2671,20 @@ pub struct ChannelManager<
 	#[cfg(not(test))]
 	flow: OffersMessageFlow<MR, L>,
 
+	/// Tracks all active recurrence sessions for this node.
+	///
+	/// Each entry is keyed by the payer’s `payer_signing_pubkey` from the
+	/// initial `invoice_request`. The associated `RecurrenceData` stores
+	/// everything the payee needs to validate incoming `invoice_request`s
+	/// and generate invoices for the appropriate recurrence period.
+	///
+	/// This is used by the payee to:
+	/// - verify the correctness of each incoming `invoice_request`
+	///   (period offset, counter, basetime, etc.)
+	/// - ensure continuity across periods
+	/// - maintain recurrence state until cancellation or completion.
+	active_recurrence_sessions: Mutex<HashMap<PublicKey, RecurrenceData>>,
+
 	/// See `ChannelManager` struct-level documentation for lock order requirements.
 	#[cfg(any(test, feature = "_test_utils"))]
 	pub(super) best_block: RwLock<BestBlock>,
@@ -3960,6 +3974,8 @@ where
 			router,
 			flow,
 
+			active_recurrence_sessions: Mutex::new(new_hash_map()),
+
 			best_block: RwLock::new(params.best_block),
 
 			outbound_scid_aliases: Mutex::new(new_hash_set()),
@@ -17285,6 +17301,7 @@ where
 		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();
+		let mut active_recurrence_sessions = Some(new_hash_map());
 		read_tlv_fields!(reader, {
 			(1, pending_outbound_payments_no_retry, option),
 			(2, pending_intercepted_htlcs, option),
@@ -17303,6 +17320,7 @@ where
 			(17, in_flight_monitor_updates, option),
 			(19, peer_storage_dir, optional_vec),
 			(21, async_receive_offer_cache, (default_value, async_receive_offer_cache)),
+			(23, active_recurrence_sessions, option),
 		});
 		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);
@@ -18197,6 +18215,8 @@ where
 			router: args.router,
 			flow,
 
+			active_recurrence_sessions: Mutex::new(active_recurrence_sessions.unwrap()),
+
 			best_block: RwLock::new(best_block),
 
 			inbound_payment_key: expanded_inbound_key,

lightning/src/offers/offer.rs

@@ -859,6 +859,52 @@ impl Readable for RecurrenceLimit {
 	}
 }
 
+/// State required for a node to act as a BOLT12 recurrence payee.
+///
+/// This tracks the information needed to validate incoming
+/// `invoice_request`s for a given recurrence session and
+/// to produce consistent invoices across all periods.
+pub struct RecurrenceData {
+	/// The period offset established by the payer in the first
+	/// recurrence-enabled `invoice_request`.
+	///
+	/// This is `Some(offset)` only when the original Offer defined an explicit
+	/// `recurrence_base`. In that case, every subsequent invoice must use the
+	/// **same** offset to remain aligned with the Offer’s schedule.
+	///
+	/// If the Offer did not define a basetime, this will be `None` and period
+	/// alignment is determined solely by the `recurrence_basetime`.
+	pub invoice_request_start: Option<u32>,
+
+	/// The next expected recurrence period counter.
+	///
+	/// Instead of storing the last seen `recurrence_counter`, we store the
+	/// *next expected counter*. This simplifies validation:
+	/// `incoming_counter == next_payable_counter`
+	/// means the payer is correctly advancing through periods.
+	///
+	/// This also avoids off-by-one confusion and gives the payee a single,
+	/// stable point of truth for the expected next invoice.
+	pub next_payable_counter: u32,
+
+	/// The recurrence anchor time for this session.
+	///
+	/// This is:
+	/// - the Offer’s `recurrence_base` if one was provided, or
+	/// - the `created_at` timestamp of the **first** invoice otherwise.
+	///
+	/// This value must remain identical across *all* invoices in the session,
+	/// and is a requirement of the BOLT12 spec. The payee uses it to populate
+	/// `invoice_recurrence_basetime` consistently for every period.
+	pub recurrence_basetime: u64,
+}
+
+impl_writeable_tlv_based!(RecurrenceData, {
+	(0, invoice_request_start, option),
+	(2, next_payable_counter, required),
+	(4, recurrence_basetime, required),
+});
+
 /// Represents the recurrence-related fields in an Offer.
 ///
 /// Design note: