Introduce recurrence fields in Invoice (BOLT12 PoC)

This commit adds the recurrence-related TLVs to the `Invoice` encoding,
allowing the payee to include `invoice_recurrence_basetime`. This field
anchors the start time (UNIX timestamp) of the recurrence schedule and is
required for validating period boundaries across successive invoices.

Additional initialization logic, validation notes, and design considerations
are documented inline within the commit.

Spec reference:
https://github.com/rustyrussell/bolts/blob/guilt/offers-recurrence/12-offer-encoding.md#invoices

Author: shaavan

lightning/src/offers/invoice.rs

@@ -255,6 +255,7 @@ macro_rules! invoice_explicit_signing_pubkey_builder_methods {
 					amount_msats,
 					signing_pubkey,
 				),
+				invoice_recurrence_basetime: None,
 			};
 
 			Self::new(&invoice_request.bytes, contents, ExplicitSigningPubkey {})
@@ -328,6 +329,7 @@ macro_rules! invoice_derived_signing_pubkey_builder_methods {
 					amount_msats,
 					signing_pubkey,
 				),
+				invoice_recurrence_basetime: None,
 			};
 
 			Self::new(&invoice_request.bytes, contents, DerivedSigningPubkey(keys))
@@ -438,6 +440,28 @@ macro_rules! invoice_builder_methods {
 
 			Ok(Self { invreq_bytes, invoice: contents, signing_pubkey_strategy })
 		}
+
+		/// Sets the `invoice_recurrence_basetime` inside the invoice contents.
+		///
+		/// This anchors the recurrence schedule for invoices produced in a
+		/// recurring-offer flow. Must be identical across all invoices in the
+		/// same recurrence session.
+		pub(crate) fn set_invoice_recurrence_basetime(
+			&mut $self,
+			basetime: u64
+		) {
+			match &mut $self.invoice {
+				InvoiceContents::ForOffer { invoice_recurrence_basetime, .. } => {
+					*invoice_recurrence_basetime = Some(basetime);
+				},
+				InvoiceContents::ForRefund { .. } => {
+					debug_assert!(
+						false,
+						"set_invoice_recurrence_basetime called on refund invoice"
+					);
+				}
+			}
+		}
 	};
 }
 
@@ -755,7 +779,40 @@ enum InvoiceContents {
 	/// Contents for an [`Bolt12Invoice`] corresponding to an [`Offer`].
 	///
 	/// [`Offer`]: crate::offers::offer::Offer
-	ForOffer { invoice_request: InvoiceRequestContents, fields: InvoiceFields },
+	ForOffer {
+		invoice_request: InvoiceRequestContents,
+		fields: InvoiceFields,
+		/// The recurrence anchor time (UNIX timestamp) for this invoice.
+		///
+		/// Semantics:
+		/// - If the offer specifies an explicit `recurrence_base`, this MUST equal it.
+		/// - If the offer does not specify a base, this MUST be the creation time
+		///   of the *first* invoice in the recurrence sequence.
+		///
+		/// Requirements:
+		/// - The payee must remember the basetime from the first invoice and reuse it
+		///   for all subsequent invoices in the recurrence.
+		/// - The payer must verify that the basetime in each invoice matches the
+		///   basetime of previously paid periods, ensuring a stable schedule.
+		///
+		/// Practical effect:
+		/// This timestamp anchors the recurrence period calculation for the entire
+		/// recurring-payment flow.
+		///
+		/// Spec Commentary:
+		/// The spec currently requires this field even when the offer already includes
+		/// its own `recurrence_base`. Since invoices are always prsent alongside their
+		/// offer, the basetime is already known. Duplicating it across offer → invoice
+		/// adds redundant equivalence checks without providing new information.
+		///
+		/// Possible simplification:
+		/// - Include `invoice_recurrence_basetime` **only when** the offer did *not* define one.
+		/// - Omit it otherwise and treat the offer as the single source of truth.
+		///
+		/// This avoids redundant duplication and simplifies validation while preserving
+		/// all necessary semantics.
+		invoice_recurrence_basetime: Option<u64>,
+	},
 	/// Contents for an [`Bolt12Invoice`] corresponding to a [`Refund`].
 	///
 	/// [`Refund`]: crate::offers::refund::Refund
@@ -1402,6 +1459,7 @@ impl InvoiceFields {
 				features,
 				node_id: Some(&self.signing_pubkey),
 				message_paths: None,
+				invoice_recurrence_basetime: None,
 			},
 			ExperimentalInvoiceTlvStreamRef {
 				#[cfg(test)]
@@ -1483,6 +1541,7 @@ tlv_stream!(InvoiceTlvStream, InvoiceTlvStreamRef<'a>, INVOICE_TYPES, {
 	(172, fallbacks: (Vec<FallbackAddress>, WithoutLength)),
 	(174, features: (Bolt12InvoiceFeatures, WithoutLength)),
 	(176, node_id: PublicKey),
+	(177, invoice_recurrence_basetime: (u64, HighZeroBytesDroppedBigSize)),
 	// Only present in `StaticInvoice`s.
 	(236, message_paths: (Vec<BlindedMessagePath>, WithoutLength)),
 });
@@ -1674,6 +1733,7 @@ impl TryFrom<PartialInvoiceTlvStream> for InvoiceContents {
 				features,
 				node_id,
 				message_paths,
+				invoice_recurrence_basetime,
 			},
 			experimental_offer_tlv_stream,
 			experimental_invoice_request_tlv_stream,
@@ -1720,6 +1780,11 @@ impl TryFrom<PartialInvoiceTlvStream> for InvoiceContents {
 		check_invoice_signing_pubkey(&fields.signing_pubkey, &offer_tlv_stream)?;
 
 		if offer_tlv_stream.issuer_id.is_none() && offer_tlv_stream.paths.is_none() {
+			// Recurrence should not be present in Refund.
+			if invoice_recurrence_basetime.is_some() {
+				return Err(Bolt12SemanticError::InvalidAmount);
+			}
+
 			let refund = RefundContents::try_from((
 				payer_tlv_stream,
 				offer_tlv_stream,
@@ -1742,13 +1807,72 @@ impl TryFrom<PartialInvoiceTlvStream> for InvoiceContents {
 				experimental_invoice_request_tlv_stream,
 			))?;
 
+			// Recurrence checks
+			if let Some(offer_recurrence) = invoice_request.inner.offer.recurrence_fields() {
+				// 1. MUST have basetime whenever offer has recurrence (optional or compulsory).
+				let invoice_basetime = match invoice_recurrence_basetime {
+					Some(ts) => ts,
+					None => {
+						return Err(Bolt12SemanticError::InvalidMetadata);
+					},
+				};
+
+				let offer_base = offer_recurrence.recurrence_base;
+				let counter = invoice_request.recurrence_counter();
+
+				// --------------------------------------------------------------------------
+				// Case A: Payer does NOT support recurrence (optional-mode fallback)
+				// No counter, no start, no cancel.
+				// We treat this invoice as a normal single-payment invoice.
+				// Basetime MUST still match presence rules, per the spec.
+				// --------------------------------------------------------------------------
+				if counter.is_none() {
+					// Nothing else to check here.
+					// The invoice is not part of a recurrence sequence.
+				}
+
+				// Safe to unwrap because we just excluded None
+				let counter = counter.unwrap();
+
+				// --------------------------------------------------------------------------
+				// Case B: First recurrence invoice (counter = 0)
+				// --------------------------------------------------------------------------
+				if counter == 0 {
+					match offer_base {
+						// Offer defined explicit basetime → MUST match exactly
+						Some(base) => {
+							if invoice_basetime != base.basetime {
+								return Err(Bolt12SemanticError::InvalidMetadata);
+							}
+						},
+
+						// Offer has no basetime → MUST match invoice.creation time
+						None => {
+							if invoice_basetime != fields.created_at.as_secs() {
+								return Err(Bolt12SemanticError::InvalidMetadata);
+							}
+						},
+					}
+				}
+				// --------------------------------------------------------------------------
+				// Case C: Successive recurrence invoices (counter > 0)
+				// --------------------------------------------------------------------------
+				else {
+					// Spec says SHOULD check equality with previous invoice basetime.
+					// But we cannot check that from here → MUST be done upstream.
+					// We leave a TODO so the reviewer sees this is intentional.
+					//
+					// TODO: Enforce SHOULD: invoice_basetime == previous_invoice_basetime
+				}
+			}
+
 			if let Some(requested_amount_msats) = invoice_request.amount_msats() {
 				if amount_msats != requested_amount_msats {
 					return Err(Bolt12SemanticError::InvalidAmount);
 				}
 			}
 
-			Ok(InvoiceContents::ForOffer { invoice_request, fields })
+			Ok(InvoiceContents::ForOffer { invoice_request, fields, invoice_recurrence_basetime })
 		}
 	}
 }
@@ -2019,6 +2143,7 @@ mod tests {
 					features: None,
 					node_id: Some(&recipient_pubkey()),
 					message_paths: None,
+					invoice_recurrence_basetime: None,
 				},
 				SignatureTlvStreamRef { signature: Some(&invoice.signature()) },
 				ExperimentalOfferTlvStreamRef { experimental_foo: None },
@@ -2130,6 +2255,7 @@ mod tests {
 					features: None,
 					node_id: Some(&recipient_pubkey()),
 					message_paths: None,
+					invoice_recurrence_basetime: None,
 				},
 				SignatureTlvStreamRef { signature: Some(&invoice.signature()) },
 				ExperimentalOfferTlvStreamRef { experimental_foo: None },

lightning/src/offers/static_invoice.rs

@@ -474,6 +474,7 @@ impl InvoiceContents {
 			node_id: Some(&self.signing_pubkey),
 			amount: None,
 			payment_hash: None,
+			invoice_recurrence_basetime: None,
 		};
 
 		let experimental_invoice = ExperimentalInvoiceTlvStreamRef {
@@ -673,6 +674,7 @@ impl TryFrom<PartialInvoiceTlvStream> for InvoiceContents {
 				message_paths,
 				payment_hash,
 				amount,
+				invoice_recurrence_basetime,
 			},
 			experimental_offer_tlv_stream,
 			ExperimentalInvoiceTlvStream {
@@ -710,6 +712,11 @@ impl TryFrom<PartialInvoiceTlvStream> for InvoiceContents {
 			return Err(Bolt12SemanticError::UnexpectedChain);
 		}
 
+		// Static invoices MUST NOT set recurrence.
+		if invoice_recurrence_basetime.is_some() {
+			return Err(Bolt12SemanticError::UnexpectedRecurrence);
+		}
+
 		Ok(InvoiceContents {
 			offer: OfferContents::try_from((offer_tlv_stream, experimental_offer_tlv_stream))?,
 			payment_paths,
@@ -927,6 +934,7 @@ mod tests {
 					features: None,
 					node_id: Some(&signing_pubkey),
 					message_paths: Some(&paths),
+					invoice_recurrence_basetime: None,
 				},
 				SignatureTlvStreamRef { signature: Some(&invoice.signature()) },
 				ExperimentalOfferTlvStreamRef { experimental_foo: None },