Introduce specific InvoiceBuilders in OffersMessageFlow

This change improves type safety and architectural clarity
by introducing dedicated `InvoiceBuilder` methods tied to
each variant of `VerifiedInvoiceRequestEnum`.

With this change, users are now required to match on the
enum variant before calling the corresponding builder method.
This pushes the responsibility of selecting the correct
builder to the user and ensures that invalid builder
usage is caught at compile time, rather than relying
on runtime checks.

The signing logic has also been moved from the builder
to the `ChannelManager`. This shift simplifies the
builder's role and aligns it with the rest of the API,
where builder methods return a configurable object that
can be extended before signing. The result is a more
consistent and predictable interface that separates
concerns cleanly and makes future maintenance easier.

Author: shaavan

lightning/src/ln/channelmanager.rs

@@ -92,10 +92,11 @@ use crate::ln::types::ChannelId;
 use crate::offers::async_receive_offer_cache::AsyncReceiveOfferCache;
 use crate::offers::flow::{InvreqResponseInstructions, OffersMessageFlow};
 use crate::offers::invoice::{
-	Bolt12Invoice, DerivedSigningPubkey, InvoiceBuilder, DEFAULT_RELATIVE_EXPIRY,
+	Bolt12Invoice, DerivedSigningPubkey, InvoiceBuilder, UnsignedBolt12Invoice,
+	DEFAULT_RELATIVE_EXPIRY,
 };
 use crate::offers::invoice_error::InvoiceError;
-use crate::offers::invoice_request::InvoiceRequest;
+use crate::offers::invoice_request::{InvoiceRequest, VerifiedInvoiceRequestEnum};
 use crate::offers::nonce::Nonce;
 use crate::offers::offer::Offer;
 use crate::offers::parse::Bolt12SemanticError;
@@ -14112,16 +14113,79 @@ where
 					},
 				};
 
-				let entropy = &*self.entropy_source;
-				let (response, context) = self.flow.create_response_for_invoice_request(
-					&self.node_signer, &self.router, entropy, invoice_request, amount_msats,
-					payment_hash, payment_secret, self.list_usable_channels()
-				);
+				let (result, context) = match invoice_request {
+					VerifiedInvoiceRequestEnum::WithKeys(request) => {
+						let result = self.flow.create_invoice_builder_from_invoice_request_with_keys(
+							&self.router,
+							&*self.entropy_source,
+							&request,
+							amount_msats,
+							payment_hash,
+							payment_secret,
+							self.list_usable_channels(),
+						);
 
-				match context {
-					Some(context) => Some((response, responder.respond_with_reply_path(context))),
-					None => Some((response, responder.respond()))
-				}
+						match result {
+							Ok((builder, context)) => {
+								let res = builder
+									.build_and_sign(&self.secp_ctx)
+									.map_err(InvoiceError::from);
+
+								(res, context)
+							},
+							Err(error) => {
+								return Some((
+									OffersMessage::InvoiceError(InvoiceError::from(error)),
+									responder.respond(),
+								));
+							},
+						}
+					},
+					VerifiedInvoiceRequestEnum::WithoutKeys(request) => {
+						let result = self.flow.create_invoice_builder_from_invoice_request_without_keys(
+							&self.router,
+							&*self.entropy_source,
+							&request,
+							amount_msats,
+							payment_hash,
+							payment_secret,
+							self.list_usable_channels(),
+						);
+
+						match result {
+							Ok((builder, context)) => {
+								let res = builder.
+									build()
+									.map_err(InvoiceError::from)
+									.and_then(|invoice| {
+										#[cfg(c_bindings)]
+										let mut invoice = invoice;
+										invoice
+											.sign(|invoice: &UnsignedBolt12Invoice| self.node_signer.sign_bolt12_invoice(invoice))
+											.map_err(InvoiceError::from)
+									});
+								(res, context)
+							},
+							Err(error) => {
+								return Some((
+									OffersMessage::InvoiceError(InvoiceError::from(error)),
+									responder.respond(),
+								));
+							},
+						}
+					}
+				};
+
+				Some(match result {
+					Ok(invoice) => (
+						OffersMessage::Invoice(invoice),
+						responder.respond_with_reply_path(context),
+					),
+					Err(error) => (
+						OffersMessage::InvoiceError(error),
+						responder.respond(),
+					),
+				})
 			},
 			OffersMessage::Invoice(invoice) => {
 				let payment_id = match self.flow.verify_bolt12_invoice(&invoice, context.as_ref()) {

lightning/src/offers/flow.rs

@@ -37,11 +37,10 @@ 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,
+	DEFAULT_RELATIVE_EXPIRY,
 };
-use crate::offers::invoice_error::InvoiceError;
 use crate::offers::invoice_request::{
-	InvoiceRequest, InvoiceRequestBuilder, VerifiedInvoiceRequestEnum,
+	InvoiceRequest, InvoiceRequestBuilder, VerifiedInvoiceRequest, VerifiedInvoiceRequestEnum,
 };
 use crate::offers::nonce::Nonce;
 use crate::offers::offer::{DerivedMetadata, Offer, OfferBuilder};
@@ -52,7 +51,7 @@ use crate::onion_message::messenger::{Destination, MessageRouter, MessageSendIns
 use crate::onion_message::offers::OffersMessage;
 use crate::onion_message::packet::OnionMessageContents;
 use crate::routing::router::Router;
-use crate::sign::{EntropySource, NodeSigner, ReceiveAuthKey};
+use crate::sign::{EntropySource, ReceiveAuthKey};
 use crate::sync::{Mutex, RwLock};
 use crate::types::payment::{PaymentHash, PaymentSecret};
 use crate::util::ser::Writeable;
@@ -920,94 +919,126 @@ where
 		Ok(builder.into())
 	}
 
-	/// Creates a response for the provided [`VerifiedInvoiceRequestEnum`].
+	/// Creates an [`InvoiceBuilder`] with [`DerivedSigningPubkey`] for the
+	/// provided [`VerifiedInvoiceRequest<DerivedSigningPubkey>`].
 	///
-	/// A response can be either an [`OffersMessage::Invoice`] with additional [`MessageContext`],
-	/// or an [`OffersMessage::InvoiceError`], depending on the [`InvoiceRequest`].
+	/// Returns the invoice builder along with a [`MessageContext`] that can
+	/// later be used to respond to the counterparty.
 	///
-	/// An [`OffersMessage::InvoiceError`] will be generated if:
-	/// - We fail to generate valid payment paths to include in the [`Bolt12Invoice`].
-	/// - We fail to generate a valid signed [`Bolt12Invoice`] for the [`InvoiceRequest`].
-	pub fn create_response_for_invoice_request<ES: Deref, NS: Deref, R: Deref>(
-		&self, signer: &NS, router: &R, entropy_source: ES,
-		invoice_request: VerifiedInvoiceRequestEnum, amount_msats: u64, payment_hash: PaymentHash,
-		payment_secret: PaymentSecret, usable_channels: Vec<ChannelDetails>,
-	) -> (OffersMessage, Option<MessageContext>)
+	/// Use this method when you want to inspect or modify the [`InvoiceBuilder`]
+	/// before signing and generating the final [`Bolt12Invoice`].
+	///
+	/// # Errors
+	///
+	/// Returns a [`Bolt12SemanticError`] if:
+	/// - User call the function with [`VerifiedInvoiceRequest<ExplicitSigningPubkey>`].
+	/// - Valid blinded payment paths could not be generated for the [`Bolt12Invoice`].
+	/// - The [`InvoiceBuilder`] could not be created from the [`InvoiceRequest`].
+	pub fn create_invoice_builder_from_invoice_request_with_keys<'a, ES: Deref, R: Deref>(
+		&'a self, router: &R, entropy_source: ES,
+		invoice_request: &'a VerifiedInvoiceRequest<DerivedSigningPubkey>, amount_msats: u64,
+		payment_hash: PaymentHash, payment_secret: PaymentSecret,
+		usable_channels: Vec<ChannelDetails>,
+	) -> Result<(InvoiceBuilder<'a, DerivedSigningPubkey>, MessageContext), Bolt12SemanticError>
 	where
 		ES::Target: EntropySource,
-		NS::Target: NodeSigner,
+
 		R::Target: Router,
 	{
 		let entropy = &*entropy_source;
-		let secp_ctx = &self.secp_ctx;
+		let relative_expiry = DEFAULT_RELATIVE_EXPIRY.as_secs() as u32;
+
+		let context = PaymentContext::Bolt12Offer(Bolt12OfferContext {
+			offer_id: invoice_request.offer_id,
+			invoice_request: invoice_request.fields(),
+		});
+
+		let payment_paths = self
+			.create_blinded_payment_paths(
+				router,
+				entropy,
+				usable_channels,
+				Some(amount_msats),
+				payment_secret,
+				context,
+				relative_expiry,
+			)
+			.map_err(|_| Bolt12SemanticError::MissingPaths)?;
+
+		#[cfg(feature = "std")]
+		let builder = invoice_request.respond_using_derived_keys(payment_paths, payment_hash);
+		#[cfg(not(feature = "std"))]
+		let builder = invoice_request.respond_using_derived_keys_no_std(
+			payment_paths,
+			payment_hash,
+			Duration::from_secs(self.highest_seen_timestamp.load(Ordering::Acquire) as u64),
+		);
+		let builder = builder.map(|b| InvoiceBuilder::from(b).allow_mpp())?;
+
+		let context = MessageContext::Offers(OffersContext::InboundPayment { payment_hash });
+
+		Ok((builder, context))
+	}
 
+	/// Creates an [`InvoiceBuilder`] with [`ExplicitSigningPubkey`] for the
+	/// provided [`VerifiedInvoiceRequest<ExplicitSigningPubkey>`].
+	///
+	/// Returns the invoice builder along with a [`MessageContext`] that can
+	/// later be used to respond to the counterparty.
+	///
+	/// Use this method when you want to inspect or modify the [`InvoiceBuilder`]
+	/// before signing and generating the final [`Bolt12Invoice`].
+	///
+	/// # Errors
+	///
+	/// Returns a [`Bolt12SemanticError`] if:
+	/// - User call the function with [`VerifiedInvoiceRequest<DerivedSigningPubkey>`].
+	/// - Valid blinded payment paths could not be generated for the [`Bolt12Invoice`].
+	/// - The [`InvoiceBuilder`] could not be created from the [`InvoiceRequest`].
+	pub fn create_invoice_builder_from_invoice_request_without_keys<'a, ES: Deref, R: Deref>(
+		&'a self, router: &R, entropy_source: ES,
+		invoice_request: &'a VerifiedInvoiceRequest<ExplicitSigningPubkey>, amount_msats: u64,
+		payment_hash: PaymentHash, payment_secret: PaymentSecret,
+		usable_channels: Vec<ChannelDetails>,
+	) -> Result<(InvoiceBuilder<'a, ExplicitSigningPubkey>, MessageContext), Bolt12SemanticError>
+	where
+		ES::Target: EntropySource,
+		R::Target: Router,
+	{
+		let entropy = &*entropy_source;
 		let relative_expiry = DEFAULT_RELATIVE_EXPIRY.as_secs() as u32;
 
 		let context = PaymentContext::Bolt12Offer(Bolt12OfferContext {
-			offer_id: invoice_request.offer_id(),
+			offer_id: invoice_request.offer_id,
 			invoice_request: invoice_request.fields(),
 		});
 
-		let payment_paths = match self.create_blinded_payment_paths(
-			router,
-			entropy,
-			usable_channels,
-			Some(amount_msats),
-			payment_secret,
-			context,
-			relative_expiry,
-		) {
-			Ok(paths) => paths,
-			Err(_) => {
-				let error = InvoiceError::from(Bolt12SemanticError::MissingPaths);
-				return (OffersMessage::InvoiceError(error.into()), None);
-			},
-		};
+		let payment_paths = self
+			.create_blinded_payment_paths(
+				router,
+				entropy,
+				usable_channels,
+				Some(amount_msats),
+				payment_secret,
+				context,
+				relative_expiry,
+			)
+			.map_err(|_| Bolt12SemanticError::MissingPaths)?;
 
+		#[cfg(feature = "std")]
+		let builder = invoice_request.respond_with(payment_paths, payment_hash);
 		#[cfg(not(feature = "std"))]
-		let created_at = Duration::from_secs(self.highest_seen_timestamp.load(Ordering::Acquire) as u64);
+		let builder = invoice_request.respond_with_no_std(
+			payment_paths,
+			payment_hash,
+			Duration::from_secs(self.highest_seen_timestamp.load(Ordering::Acquire) as u64),
+		);
 
-		let response = match invoice_request {
-			VerifiedInvoiceRequestEnum::WithKeys(request) => {
-				#[cfg(feature = "std")]
-				let builder = request.respond_using_derived_keys(payment_paths, payment_hash);
-				#[cfg(not(feature = "std"))]
-				let builder = request.respond_using_derived_keys_no_std(payment_paths, payment_hash, created_at);
-				builder
-					.map(InvoiceBuilder::<DerivedSigningPubkey>::from)
-					.and_then(|builder| builder.allow_mpp().build_and_sign(secp_ctx))
-					.map_err(InvoiceError::from)
-			},
-			VerifiedInvoiceRequestEnum::WithoutKeys(request) => {
-				#[cfg(feature = "std")]
-				let builder = request.respond_with(payment_paths, payment_hash);
-				#[cfg(not(feature = "std"))]
-				let builder = request.respond_with_no_std(payment_paths, payment_hash, created_at);
-				builder
-					.map(InvoiceBuilder::<ExplicitSigningPubkey>::from)
-					.and_then(|builder| builder.allow_mpp().build())
-					.map_err(InvoiceError::from)
-					.and_then(|invoice| {
-						#[cfg(c_bindings)]
-						let mut invoice = invoice;
-						invoice
-							.sign(|invoice: &UnsignedBolt12Invoice| {
-								signer.sign_bolt12_invoice(invoice)
-							})
-							.map_err(InvoiceError::from)
-					})
-			},
-		};
+		let builder = builder.map(|b| InvoiceBuilder::from(b).allow_mpp())?;
 
-		match response {
-			Ok(invoice) => {
-				let context =
-					MessageContext::Offers(OffersContext::InboundPayment { payment_hash });
+		let context = MessageContext::Offers(OffersContext::InboundPayment { payment_hash });
 
-				(OffersMessage::Invoice(invoice), Some(context))
-			},
-			Err(error) => (OffersMessage::InvoiceError(error.into()), None),
-		}
+		Ok((builder, context))
 	}
 
 	/// Enqueues the created [`InvoiceRequest`] to be sent to the counterparty.
@@ -1034,6 +1065,7 @@ where
 	/// valid reply paths for the counterparty to send back the corresponding [`Bolt12Invoice`]
 	/// or [`InvoiceError`].
 	///
+	/// [`InvoiceError`]: crate::offers::invoice_error::InvoiceError
 	/// [`supports_onion_messages`]: crate::types::features::Features::supports_onion_messages
 	pub fn enqueue_invoice_request(
 		&self, invoice_request: InvoiceRequest, payment_id: PaymentId, nonce: Nonce,
@@ -1079,6 +1111,7 @@ where
 	/// reply paths for the counterparty to send back the corresponding [`InvoiceError`] if we fail
 	/// to create blinded reply paths
 	///
+	/// [`InvoiceError`]: crate::offers::invoice_error::InvoiceError
 	/// [`supports_onion_messages`]: crate::types::features::Features::supports_onion_messages
 	pub fn enqueue_invoice(
 		&self, invoice: Bolt12Invoice, refund: &Refund, peers: Vec<MessageForwardNode>,