Expose full per-payment sending parameters for BOLT11 and BOLT12

Replace per-payment `Option<RouteParametersConfig>` with dedicated
`Bolt11SendingParameters` and `Bolt12SendingParameters` structs that
expose the full LDK optional payment params (retry strategy, route
parameters, custom TLVs, MPP override) on a per-payment basis.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: benthecarman

src/config.rs

@@ -12,8 +12,9 @@ use std::time::Duration;
 
 use bitcoin::secp256k1::PublicKey;
 use bitcoin::Network;
+use lightning::ln::channelmanager::{OptionalBolt11PaymentParams, OptionalOfferPaymentParams};
 use lightning::ln::msgs::SocketAddress;
-use lightning::ln::outbound_payment::Retry;
+use lightning::ln::outbound_payment::{RecipientCustomTlvs, Retry};
 use lightning::routing::gossip::NodeAlias;
 use lightning::routing::router::RouteParametersConfig;
 use lightning::util::config::{
@@ -684,6 +685,136 @@ impl From<PaymentRetryStrategy> for Retry {
 	}
 }
 
+/// Represents options which allow to override the default sending parameters for BOLT11 payments
+/// on a per-payment basis.
+///
+/// These can be used to override the parameters set in [`Config::route_parameters`] and
+/// [`Config::payment_retry_strategy`].
+///
+/// See [`OptionalBolt11PaymentParams`] for the underlying LDK type.
+#[derive(Clone, Debug, Default)]
+#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
+pub struct Bolt11SendingParameters {
+	/// Configuration options for payment routing and pathfinding.
+	///
+	/// Setting the [`RouteParametersConfig`] provides flexibility to customize how payments are
+	/// routed, including setting limits on routing fees, CLTV expiry, and channel utilization.
+	///
+	/// If set, these will override the node-wide parameters configured via
+	/// [`Config::route_parameters`] for this payment.
+	pub route_parameters: Option<RouteParametersConfig>,
+	/// The strategy used when retrying failed payments.
+	///
+	/// If set, this will override the node-wide retry strategy configured via
+	/// [`Config::payment_retry_strategy`] for this payment.
+	pub retry_strategy: Option<PaymentRetryStrategy>,
+	/// A set of custom TLVs to include in the onion message to the recipient.
+	///
+	/// Each TLV is a `(type, value)` pair where the type number must be >= 2^16 (i.e., in the
+	/// custom range) and unique. Invalid TLV types will be ignored.
+	pub custom_tlvs: Option<Vec<CustomTlv>>,
+	/// If the payment being made from this node is part of a larger MPP payment from multiple
+	/// nodes (i.e., because a single payment is being made from multiple wallets), you can specify
+	/// the total amount being paid here.
+	///
+	/// If set, it must be at least the amount of the invoice. Further, if set, the amount sent
+	/// from this node may be lower than the invoice amount (as the payment from this node may be
+	/// a small part of the total).
+	pub declared_total_mpp_value_msat_override: Option<u64>,
+}
+
+/// Represents options which allow to override the default sending parameters for BOLT12 payments
+/// on a per-payment basis.
+///
+/// These can be used to override the parameters set in [`Config::route_parameters`] and
+/// [`Config::payment_retry_strategy`].
+///
+/// See [`OptionalOfferPaymentParams`] for the underlying LDK type.
+#[derive(Clone, Debug, Default)]
+#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
+pub struct Bolt12SendingParameters {
+	/// Configuration options for payment routing and pathfinding.
+	///
+	/// Setting the [`RouteParametersConfig`] provides flexibility to customize how payments are
+	/// routed, including setting limits on routing fees, CLTV expiry, and channel utilization.
+	///
+	/// If set, these will override the node-wide parameters configured via
+	/// [`Config::route_parameters`] for this payment.
+	pub route_parameters: Option<RouteParametersConfig>,
+	/// The strategy used when retrying failed payments.
+	///
+	/// If set, this will override the node-wide retry strategy configured via
+	/// [`Config::payment_retry_strategy`] for this payment.
+	pub retry_strategy: Option<PaymentRetryStrategy>,
+}
+
+/// A custom TLV entry that can be included in the onion message to the recipient.
+///
+/// TLV type numbers must be unique and >= 2^16 (in the custom range).
+#[derive(Clone, Debug, PartialEq, Eq)]
+#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
+pub struct CustomTlv {
+	/// The type number for this TLV. Must be >= 2^16.
+	pub tlv_type: u64,
+	/// The serialized value for this TLV.
+	pub value: Vec<u8>,
+}
+
+impl Bolt11SendingParameters {
+	pub(crate) fn into_ldk_params(
+		params: Option<Self>, config: &Config,
+	) -> OptionalBolt11PaymentParams {
+		if let Some(params) = params {
+			let route_params_config =
+				params.route_parameters.or(config.route_parameters).unwrap_or_default();
+			let retry_strategy = params
+				.retry_strategy
+				.map(Into::into)
+				.unwrap_or_else(|| config.payment_retry_strategy.into());
+			let custom_tlvs = params
+				.custom_tlvs
+				.map(|tlvs| tlvs.into_iter().map(|t| (t.tlv_type, t.value)).collect())
+				.and_then(|tlvs| RecipientCustomTlvs::new(tlvs).ok())
+				.unwrap_or_else(|| RecipientCustomTlvs::new(vec![]).unwrap());
+			OptionalBolt11PaymentParams {
+				route_params_config,
+				retry_strategy,
+				custom_tlvs,
+				declared_total_mpp_value_msat_override: params
+					.declared_total_mpp_value_msat_override,
+			}
+		} else {
+			OptionalBolt11PaymentParams {
+				route_params_config: config.route_parameters.unwrap_or_default(),
+				retry_strategy: config.payment_retry_strategy.into(),
+				..Default::default()
+			}
+		}
+	}
+}
+
+impl Bolt12SendingParameters {
+	pub(crate) fn into_ldk_params(
+		params: Option<Self>, payer_note: Option<String>, config: &Config,
+	) -> OptionalOfferPaymentParams {
+		if let Some(params) = params {
+			let route_params_config =
+				params.route_parameters.or(config.route_parameters).unwrap_or_default();
+			let retry_strategy = params
+				.retry_strategy
+				.map(Into::into)
+				.unwrap_or_else(|| config.payment_retry_strategy.into());
+			OptionalOfferPaymentParams { payer_note, route_params_config, retry_strategy }
+		} else {
+			OptionalOfferPaymentParams {
+				payer_note,
+				route_params_config: config.route_parameters.unwrap_or_default(),
+				retry_strategy: config.payment_retry_strategy.into(),
+			}
+		}
+	}
+}
+
 #[cfg(test)]
 mod tests {
 	use std::str::FromStr;

src/payment/bolt11.rs

@@ -13,17 +13,15 @@ use std::sync::{Arc, RwLock};
 
 use bitcoin::hashes::sha256::Hash as Sha256;
 use bitcoin::hashes::Hash;
-use lightning::ln::channelmanager::{
-	Bolt11InvoiceParameters, OptionalBolt11PaymentParams, PaymentId,
-};
+use lightning::ln::channelmanager::{Bolt11InvoiceParameters, PaymentId};
 use lightning::ln::outbound_payment::{Bolt11PaymentError, RetryableSendFailure};
 use lightning::routing::router::{PaymentParameters, RouteParameters, RouteParametersConfig};
 use lightning_invoice::{
 	Bolt11Invoice as LdkBolt11Invoice, Bolt11InvoiceDescription as LdkBolt11InvoiceDescription,
 };
 use lightning_types::payment::{PaymentHash, PaymentPreimage};
 
-use crate::config::Config;
+use crate::config::{Bolt11SendingParameters, Config};
 use crate::connection::ConnectionManager;
 use crate::data_store::DataStoreUpdateResult;
 use crate::error::Error;
@@ -236,10 +234,11 @@ impl Bolt11Payment {
 impl Bolt11Payment {
 	/// Send a payment given an invoice.
 	///
-	/// If `route_parameters` are provided they will override the default as well as the
-	/// node-wide parameters configured via [`Config::route_parameters`] on a per-field basis.
+	/// If [`Bolt11SendingParameters`] are provided they will override the default as well as the
+	/// node-wide parameters configured via [`Config::route_parameters`] and
+	/// [`Config::payment_retry_strategy`].
 	pub fn send(
-		&self, invoice: &Bolt11Invoice, route_parameters: Option<RouteParametersConfig>,
+		&self, invoice: &Bolt11Invoice, sending_parameters: Option<Bolt11SendingParameters>,
 	) -> Result<PaymentId, Error> {
 		if !*self.is_running.read().unwrap() {
 			return Err(Error::NotRunning);
@@ -257,16 +256,9 @@ impl Bolt11Payment {
 			}
 		}
 
-		let route_params_config =
-			route_parameters.or(self.config.route_parameters).unwrap_or_default();
-		let retry_strategy = self.config.payment_retry_strategy.into();
 		let payment_secret = Some(*invoice.payment_secret());
-
-		let optional_params = OptionalBolt11PaymentParams {
-			retry_strategy,
-			route_params_config,
-			..Default::default()
-		};
+		let optional_params =
+			Bolt11SendingParameters::into_ldk_params(sending_parameters, &self.config);
 		match self.channel_manager.pay_for_bolt11_invoice(
 			invoice,
 			payment_id,
@@ -336,23 +328,30 @@ impl Bolt11Payment {
 	/// This can be used to pay a so-called "zero-amount" invoice, i.e., an invoice that leaves the
 	/// amount paid to be determined by the user.
 	///
-	/// If `route_parameters` are provided they will override the default as well as the
-	/// node-wide parameters configured via [`Config::route_parameters`] on a per-field basis.
+	/// If [`Bolt11SendingParameters`] are provided they will override the default as well as the
+	/// node-wide parameters configured via [`Config::route_parameters`] and
+	/// [`Config::payment_retry_strategy`].
 	pub fn send_using_amount(
 		&self, invoice: &Bolt11Invoice, amount_msat: u64,
-		route_parameters: Option<RouteParametersConfig>,
+		sending_parameters: Option<Bolt11SendingParameters>,
 	) -> Result<PaymentId, Error> {
 		if !*self.is_running.read().unwrap() {
 			return Err(Error::NotRunning);
 		}
 
 		let invoice = maybe_deref(invoice);
-		if let Some(invoice_amount_msat) = invoice.amount_milli_satoshis() {
-			if amount_msat < invoice_amount_msat {
-				log_error!(
-					self.logger,
-					"Failed to pay as the given amount needs to be at least the invoice amount: required {}msat, gave {}msat.", invoice_amount_msat, amount_msat);
-				return Err(Error::InvalidAmount);
+		let is_mpp_override = sending_parameters
+			.as_ref()
+			.and_then(|sp| sp.declared_total_mpp_value_msat_override)
+			.is_some();
+		if !is_mpp_override {
+			if let Some(invoice_amount_msat) = invoice.amount_milli_satoshis() {
+				if amount_msat < invoice_amount_msat {
+					log_error!(
+						self.logger,
+						"Failed to pay as the given amount needs to be at least the invoice amount: required {}msat, gave {}msat.", invoice_amount_msat, amount_msat);
+					return Err(Error::InvalidAmount);
+				}
 			}
 		}
 
@@ -367,16 +366,9 @@ impl Bolt11Payment {
 			}
 		}
 
-		let route_params_config =
-			route_parameters.or(self.config.route_parameters).unwrap_or_default();
-		let retry_strategy = self.config.payment_retry_strategy.into();
 		let payment_secret = Some(*invoice.payment_secret());
-
-		let optional_params = OptionalBolt11PaymentParams {
-			retry_strategy,
-			route_params_config,
-			..Default::default()
-		};
+		let optional_params =
+			Bolt11SendingParameters::into_ldk_params(sending_parameters, &self.config);
 		match self.channel_manager.pay_for_bolt11_invoice(
 			invoice,
 			payment_id,