Introduce FlowEvents for manual handling of offers messages

Until now, offers messages were processed internally without exposing
intermediate steps. This made it harder for callers to intercept or
analyse offer messages before deciding how to respond to them.

`FlowEvents` provide an optional mechanism to surface these events back
to the user. With events enabled, the caller can manually inspect an
incoming message, choose to construct and sign an invoice, or send back
an InvoiceError. This shifts control to the user where needed, while
keeping the default automatic flow unchanged.

Author: shaavan

lightning/src/ln/channelmanager.rs

@@ -3985,7 +3985,8 @@ where
 		let flow = OffersMessageFlow::new(
 			ChainHash::using_genesis_block(params.network), params.best_block,
 			our_network_pubkey, current_timestamp, expanded_inbound_key,
-			node_signer.get_receive_auth_key(), secp_ctx.clone(), message_router, logger.clone(),
+			node_signer.get_receive_auth_key(), secp_ctx.clone(), message_router, false,
+			logger.clone(),
 		);
 
 		ChannelManager {
@@ -15271,7 +15272,7 @@ where
 					None => return None,
 				};
 
-				let invoice_request = match self.flow.verify_invoice_request(invoice_request, context) {
+				let invoice_request = match self.flow.verify_invoice_request(invoice_request, context, responder.clone()) {
 					Ok(InvreqResponseInstructions::SendInvoice(invoice_request)) => invoice_request,
 					Ok(InvreqResponseInstructions::SendStaticInvoice { recipient_id, invoice_slot, invoice_request }) => {
 						self.pending_events.lock().unwrap().push_back((Event::StaticInvoiceRequested {
@@ -15280,6 +15281,7 @@ where
 
 						return None
 					},
+					Ok(InvreqResponseInstructions::AsynchronouslyHandleResponse) => return None,
 					Err(_) => return None,
 				};
 
@@ -18081,6 +18083,7 @@ where
 			args.node_signer.get_receive_auth_key(),
 			secp_ctx.clone(),
 			args.message_router,
+			false,
 			args.logger.clone(),
 		)
 		.with_async_payments_offers_cache(async_receive_offer_cache);

lightning/src/offers/flow.rs

@@ -71,6 +71,32 @@ use {
 	crate::onion_message::dns_resolution::{DNSResolverMessage, DNSSECQuery, OMNameResolver},
 };
 
+/// Defines the events that can be optionally triggered when processing offers messages.
+///
+/// Once generated, these events are stored in the [`OffersMessageFlow`], where they can be
+/// manually inspected and responded to.
+pub enum OfferMessageFlowEvent {
+	/// Notifies that an [`InvoiceRequest`] has been received.
+	///
+	/// To respond to this message:
+	/// - Based on the variant of [`InvoiceRequestVerifiedFromOffer`], create the appropriate invoice builder:
+	///   - [`InvoiceRequestVerifiedFromOffer::DerivedKeys`] → use
+	///     [`OffersMessageFlow::create_invoice_builder_from_invoice_request_with_keys`]
+	///   - [`InvoiceRequestVerifiedFromOffer::ExplicitKeys`] → use
+	///     [`OffersMessageFlow::create_invoice_builder_from_invoice_request_without_keys`]
+	/// - After building the invoice, sign it and send it back using the provided reply path via
+	///   [`OffersMessageFlow::enqueue_invoice_using_reply_paths`].
+	///
+	/// If the invoice request is invalid, respond with an [`InvoiceError`] using
+	/// [`OffersMessageFlow::enqueue_invoice_error`].
+	InvoiceRequestReceived {
+		/// The received, verified invoice request.
+		invoice_request: InvoiceRequestVerifiedFromOffer,
+		/// The reply path to use when responding to the invoice request.
+		reply_path: BlindedMessagePath,
+	},
+}
+
 /// A BOLT12 offers code and flow utility provider, which facilitates
 /// BOLT12 builder generation and onion message handling.
 ///
@@ -93,6 +119,8 @@ where
 	secp_ctx: Secp256k1<secp256k1::All>,
 	message_router: MR,
 
+	pub(crate) enable_events: bool,
+
 	#[cfg(not(any(test, feature = "_test_utils")))]
 	pending_offers_messages: Mutex<Vec<(OffersMessage, MessageSendInstructions)>>,
 	#[cfg(any(test, feature = "_test_utils"))]
@@ -106,6 +134,8 @@ where
 	#[cfg(feature = "dnssec")]
 	pending_dns_onion_messages: Mutex<Vec<(DNSResolverMessage, MessageSendInstructions)>>,
 
+	pending_flow_events: Mutex<Vec<OfferMessageFlowEvent>>,
+
 	logger: L,
 }
 
@@ -119,7 +149,7 @@ where
 		chain_hash: ChainHash, best_block: BestBlock, our_network_pubkey: PublicKey,
 		current_timestamp: u32, inbound_payment_key: inbound_payment::ExpandedKey,
 		receive_auth_key: ReceiveAuthKey, secp_ctx: Secp256k1<secp256k1::All>, message_router: MR,
-		logger: L,
+		enable_events: bool, logger: L,
 	) -> Self {
 		Self {
 			chain_hash,
@@ -134,6 +164,8 @@ where
 			secp_ctx,
 			message_router,
 
+			enable_events,
+
 			pending_offers_messages: Mutex::new(Vec::new()),
 			pending_async_payments_messages: Mutex::new(Vec::new()),
 
@@ -144,6 +176,8 @@ where
 
 			async_receive_offer_cache: Mutex::new(AsyncReceiveOfferCache::new()),
 
+			pending_flow_events: Mutex::new(Vec::new()),
+
 			logger,
 		}
 	}
@@ -160,6 +194,18 @@ where
 		self
 	}
 
+	/// Enables [`OfferMessageFlowEvent`] for this flow.
+	///
+	/// By default, events are not emitted when processing offers messages. Calling this method
+	/// sets the internal `enable_events` flag to `true`, allowing you to receive [`OfferMessageFlowEvent`]
+	/// such as [`OfferMessageFlowEvent::InvoiceRequestReceived`].
+	///
+	/// This is useful when you want to manually inspect, handle, or respond to incoming
+	/// offers messages rather than having them processed automatically.
+	pub fn enable_events(&mut self) {
+		self.enable_events = true;
+	}
+
 	/// Sets the [`BlindedMessagePath`]s that we will use as an async recipient to interactively build
 	/// [`Offer`]s with a static invoice server, so the server can serve [`StaticInvoice`]s to payers
 	/// on our behalf when we're offline.
@@ -421,6 +467,8 @@ pub enum InvreqResponseInstructions {
 		/// [`OffersMessageFlow::enqueue_invoice_request_to_forward`].
 		invoice_request: InvoiceRequest,
 	},
+	/// We are recipient of this payment, and should handle the response asynchronously.
+	AsynchronouslyHandleResponse,
 }
 
 /// Parameters for the reply path to a [`HeldHtlcAvailable`] onion message.
@@ -449,6 +497,7 @@ where
 	L::Target: Logger,
 {
 	/// Verifies an [`InvoiceRequest`] using the provided [`OffersContext`] or the [`InvoiceRequest::metadata`].
+	/// It also helps determine the response instructions, corresponding to the verified invoice request must be taken.
 	///
 	/// - If an [`OffersContext::InvoiceRequest`] with a `nonce` is provided, verification is performed using recipient context data.
 	/// - If no context is provided but the [`InvoiceRequest`] contains [`Offer`] metadata, verification is performed using that metadata.
@@ -461,6 +510,7 @@ where
 	/// - The verification process (via recipient context data or metadata) fails.
 	pub fn verify_invoice_request(
 		&self, invoice_request: InvoiceRequest, context: Option<OffersContext>,
+		responder: Responder,
 	) -> Result<InvreqResponseInstructions, ()> {
 		let secp_ctx = &self.secp_ctx;
 		let expanded_key = &self.inbound_payment_key;
@@ -494,7 +544,18 @@ where
 			None => invoice_request.verify_using_metadata(expanded_key, secp_ctx),
 		}?;
 
-		Ok(InvreqResponseInstructions::SendInvoice(invoice_request))
+		if self.enable_events {
+			self.pending_flow_events.lock().unwrap().push(
+				OfferMessageFlowEvent::InvoiceRequestReceived {
+					invoice_request,
+					reply_path: responder.into_blinded_path(),
+				},
+			);
+
+			Ok(InvreqResponseInstructions::AsynchronouslyHandleResponse)
+		} else {
+			Ok(InvreqResponseInstructions::SendInvoice(invoice_request))
+		}
 	}
 
 	/// Verifies a [`Bolt12Invoice`] using the provided [`OffersContext`] or the invoice's payer metadata,
@@ -1401,6 +1462,11 @@ where
 		Ok(())
 	}
 
+	/// Enqueues the generated [`OfferMessageFlowEvent`] to be processed.
+	pub fn enqueue_flow_event(&self, flow_event: OfferMessageFlowEvent) {
+		self.pending_flow_events.lock().unwrap().push(flow_event);
+	}
+
 	/// Gets the enqueued [`OffersMessage`] with their corresponding [`MessageSendInstructions`].
 	pub fn release_pending_offers_messages(&self) -> Vec<(OffersMessage, MessageSendInstructions)> {
 		core::mem::take(&mut self.pending_offers_messages.lock().unwrap())
@@ -1413,6 +1479,11 @@ where
 		core::mem::take(&mut self.pending_async_payments_messages.lock().unwrap())
 	}
 
+	/// Gets the enqueued [`OfferMessageFlowEvent`] to be processed.
+	pub fn release_pending_flow_events(&self) -> Vec<OfferMessageFlowEvent> {
+		core::mem::take(&mut self.pending_flow_events.lock().unwrap())
+	}
+
 	/// Gets the enqueued [`DNSResolverMessage`] with their corresponding [`MessageSendInstructions`].
 	#[cfg(feature = "dnssec")]
 	pub fn release_pending_dns_messages(