Merge pull request lightningdevkit#702 from tnull/2025-11-allow-to-set-routeparameters-in-bolt12

Allow to set optional `RouteParametersConfig` in BOLT12 API

Author: tnull

bindings/ldk_node.udl

@@ -201,17 +201,17 @@ interface Bolt11Payment {
 
 interface Bolt12Payment {
 	[Throws=NodeError]
-	PaymentId send([ByRef]Offer offer, u64? quantity, string? payer_note);
+	PaymentId send([ByRef]Offer offer, u64? quantity, string? payer_note, RouteParametersConfig? route_parameters);
 	[Throws=NodeError]
-	PaymentId send_using_amount([ByRef]Offer offer, u64 amount_msat, u64? quantity, string? payer_note);
+	PaymentId send_using_amount([ByRef]Offer offer, u64 amount_msat, u64? quantity, string? payer_note, RouteParametersConfig? route_parameters);
 	[Throws=NodeError]
 	Offer receive(u64 amount_msat, [ByRef]string description, u32? expiry_secs, u64? quantity);
 	[Throws=NodeError]
 	Offer receive_variable_amount([ByRef]string description, u32? expiry_secs);
 	[Throws=NodeError]
 	Bolt12Invoice request_refund_payment([ByRef]Refund refund);
 	[Throws=NodeError]
-	Refund initiate_refund(u64 amount_msat, u32 expiry_secs, u64? quantity, string? payer_note);
+	Refund initiate_refund(u64 amount_msat, u32 expiry_secs, u64? quantity, string? payer_note, RouteParametersConfig? route_parameters);
 	[Throws=NodeError]
 	Offer receive_async();
 	[Throws=NodeError]
@@ -256,7 +256,7 @@ interface UnifiedQrPayment {
 	[Throws=NodeError]
 	string receive(u64 amount_sats, [ByRef]string message, u32 expiry_sec);
 	[Throws=NodeError]
-	QrPaymentResult send([ByRef]string uri_str);
+	QrPaymentResult send([ByRef]string uri_str, RouteParametersConfig? route_parameters);
 };
 
 interface LSPS1Liquidity {

src/lib.rs

@@ -857,6 +857,7 @@ impl Node {
 		Bolt12Payment::new(
 			Arc::clone(&self.channel_manager),
 			Arc::clone(&self.payment_store),
+			Arc::clone(&self.config),
 			Arc::clone(&self.is_running),
 			Arc::clone(&self.logger),
 			self.async_payments_role,
@@ -871,6 +872,7 @@ impl Node {
 		Arc::new(Bolt12Payment::new(
 			Arc::clone(&self.channel_manager),
 			Arc::clone(&self.payment_store),
+			Arc::clone(&self.config),
 			Arc::clone(&self.is_running),
 			Arc::clone(&self.logger),
 			self.async_payments_role,

src/payment/bolt12.rs

@@ -23,7 +23,7 @@ use lightning::util::ser::{Readable, Writeable};
 use lightning_types::string::UntrustedString;
 use rand::RngCore;
 
-use crate::config::{AsyncPaymentsRole, LDK_PAYMENT_RETRY_TIMEOUT};
+use crate::config::{AsyncPaymentsRole, Config, LDK_PAYMENT_RETRY_TIMEOUT};
 use crate::error::Error;
 use crate::ffi::{maybe_deref, maybe_wrap};
 use crate::logger::{log_error, log_info, LdkLogger, Logger};
@@ -54,6 +54,7 @@ type Refund = Arc<crate::ffi::Refund>;
 pub struct Bolt12Payment {
 	channel_manager: Arc<ChannelManager>,
 	payment_store: Arc<PaymentStore>,
+	config: Arc<Config>,
 	is_running: Arc<RwLock<bool>>,
 	logger: Arc<Logger>,
 	async_payments_role: Option<AsyncPaymentsRole>,
@@ -62,10 +63,10 @@ pub struct Bolt12Payment {
 impl Bolt12Payment {
 	pub(crate) fn new(
 		channel_manager: Arc<ChannelManager>, payment_store: Arc<PaymentStore>,
-		is_running: Arc<RwLock<bool>>, logger: Arc<Logger>,
+		config: Arc<Config>, is_running: Arc<RwLock<bool>>, logger: Arc<Logger>,
 		async_payments_role: Option<AsyncPaymentsRole>,
 	) -> Self {
-		Self { channel_manager, payment_store, is_running, logger, async_payments_role }
+		Self { channel_manager, payment_store, config, is_running, logger, async_payments_role }
 	}
 
 	/// Send a payment given an offer.
@@ -74,8 +75,12 @@ impl Bolt12Payment {
 	/// response.
 	///
 	/// If `quantity` is `Some` it represents the number of items requested.
+	///
+	/// 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.
 	pub fn send(
 		&self, offer: &Offer, quantity: Option<u64>, payer_note: Option<String>,
+		route_parameters: Option<RouteParametersConfig>,
 	) -> Result<PaymentId, Error> {
 		if !*self.is_running.read().unwrap() {
 			return Err(Error::NotRunning);
@@ -87,7 +92,8 @@ impl Bolt12Payment {
 		rand::rng().fill_bytes(&mut random_bytes);
 		let payment_id = PaymentId(random_bytes);
 		let retry_strategy = Retry::Timeout(LDK_PAYMENT_RETRY_TIMEOUT);
-		let route_params_config = RouteParametersConfig::default();
+		let route_parameters =
+			route_parameters.or(self.config.route_parameters).unwrap_or_default();
 
 		let offer_amount_msat = match offer.amount() {
 			Some(Amount::Bitcoin { amount_msats }) => amount_msats,
@@ -104,7 +110,7 @@ impl Bolt12Payment {
 		let params = OptionalOfferPaymentParams {
 			payer_note: payer_note.clone(),
 			retry_strategy,
-			route_params_config,
+			route_params_config: route_parameters,
 		};
 		let res = if let Some(quantity) = quantity {
 			self.channel_manager
@@ -181,8 +187,12 @@ impl Bolt12Payment {
 	///
 	/// If `payer_note` is `Some` it will be seen by the recipient and reflected back in the invoice
 	/// response.
+	///
+	/// 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.
 	pub fn send_using_amount(
 		&self, offer: &Offer, amount_msat: u64, quantity: Option<u64>, payer_note: Option<String>,
+		route_parameters: Option<RouteParametersConfig>,
 	) -> Result<PaymentId, Error> {
 		if !*self.is_running.read().unwrap() {
 			return Err(Error::NotRunning);
@@ -194,7 +204,8 @@ impl Bolt12Payment {
 		rand::rng().fill_bytes(&mut random_bytes);
 		let payment_id = PaymentId(random_bytes);
 		let retry_strategy = Retry::Timeout(LDK_PAYMENT_RETRY_TIMEOUT);
-		let route_params_config = RouteParametersConfig::default();
+		let route_parameters =
+			route_parameters.or(self.config.route_parameters).unwrap_or_default();
 
 		let offer_amount_msat = match offer.amount() {
 			Some(Amount::Bitcoin { amount_msats }) => amount_msats,
@@ -215,7 +226,7 @@ impl Bolt12Payment {
 		let params = OptionalOfferPaymentParams {
 			payer_note: payer_note.clone(),
 			retry_strategy,
-			route_params_config,
+			route_params_config: route_parameters,
 		};
 		let res = if let Some(quantity) = quantity {
 			self.channel_manager.pay_for_offer_with_quantity(
@@ -402,10 +413,13 @@ impl Bolt12Payment {
 
 	/// Returns a [`Refund`] object that can be used to offer a refund payment of the amount given.
 	///
+	/// 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.
+	///
 	/// [`Refund`]: lightning::offers::refund::Refund
 	pub fn initiate_refund(
 		&self, amount_msat: u64, expiry_secs: u32, quantity: Option<u64>,
-		payer_note: Option<String>,
+		payer_note: Option<String>, route_parameters: Option<RouteParametersConfig>,
 	) -> Result<Refund, Error> {
 		let mut random_bytes = [0u8; 32];
 		rand::rng().fill_bytes(&mut random_bytes);
@@ -415,7 +429,8 @@ impl Bolt12Payment {
 			.duration_since(UNIX_EPOCH)
 			.unwrap();
 		let retry_strategy = Retry::Timeout(LDK_PAYMENT_RETRY_TIMEOUT);
-		let route_params_config = RouteParametersConfig::default();
+		let route_parameters =
+			route_parameters.or(self.config.route_parameters).unwrap_or_default();
 
 		let mut refund_builder = self
 			.channel_manager
@@ -424,7 +439,7 @@ impl Bolt12Payment {
 				absolute_expiry,
 				payment_id,
 				retry_strategy,
-				route_params_config,
+				route_parameters,
 			)
 			.map_err(|e| {
 				log_error!(self.logger, "Failed to create refund builder: {:?}", e);

src/payment/unified_qr.rs

@@ -20,6 +20,7 @@ use bitcoin::address::{NetworkChecked, NetworkUnchecked};
 use bitcoin::{Amount, Txid};
 use lightning::ln::channelmanager::PaymentId;
 use lightning::offers::offer::Offer;
+use lightning::routing::router::RouteParametersConfig;
 use lightning_invoice::{Bolt11Invoice, Bolt11InvoiceDescription, Description};
 
 use crate::error::Error;
@@ -137,8 +138,13 @@ impl UnifiedQrPayment {
 	/// Returns a `QrPaymentResult` indicating the outcome of the payment. If an error
 	/// occurs, an `Error` is returned detailing the issue encountered.
 	///
+	/// 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.
+	///
 	/// [BIP 21]: https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki
-	pub fn send(&self, uri_str: &str) -> Result<QrPaymentResult, Error> {
+	pub fn send(
+		&self, uri_str: &str, route_parameters: Option<RouteParametersConfig>,
+	) -> Result<QrPaymentResult, Error> {
 		let uri: bip21::Uri<NetworkUnchecked, Extras> =
 			uri_str.parse().map_err(|_| Error::InvalidUri)?;
 
@@ -147,15 +153,15 @@ impl UnifiedQrPayment {
 
 		if let Some(offer) = uri_network_checked.extras.bolt12_offer {
 			let offer = maybe_wrap(offer);
-			match self.bolt12_payment.send(&offer, None, None) {
+			match self.bolt12_payment.send(&offer, None, None, route_parameters) {
 				Ok(payment_id) => return Ok(QrPaymentResult::Bolt12 { payment_id }),
 				Err(e) => log_error!(self.logger, "Failed to send BOLT12 offer: {:?}. This is part of a unified QR code payment. Falling back to the BOLT11 invoice.", e),
 			}
 		}
 
 		if let Some(invoice) = uri_network_checked.extras.bolt11_invoice {
 			let invoice = maybe_wrap(invoice);
-			match self.bolt11_invoice.send(&invoice, None) {
+			match self.bolt11_invoice.send(&invoice, route_parameters) {
 				Ok(payment_id) => return Ok(QrPaymentResult::Bolt11 { payment_id }),
 				Err(e) => log_error!(self.logger, "Failed to send BOLT11 invoice: {:?}. This is part of a unified QR code payment. Falling back to the on-chain transaction.", e),
 			}

tests/integration_tests_rust.rs

@@ -967,7 +967,7 @@ async fn simple_bolt12_send_receive() {
 	let expected_payer_note = Some("Test".to_string());
 	let payment_id = node_a
 		.bolt12_payment()
-		.send(&offer, expected_quantity, expected_payer_note.clone())
+		.send(&offer, expected_quantity, expected_payer_note.clone(), None)
 		.unwrap();
 
 	expect_payment_successful_event!(node_a, Some(payment_id), None);
@@ -1023,7 +1023,7 @@ async fn simple_bolt12_send_receive() {
 	let expected_payer_note = Some("Test".to_string());
 	assert!(node_a
 		.bolt12_payment()
-		.send_using_amount(&offer, less_than_offer_amount, None, None)
+		.send_using_amount(&offer, less_than_offer_amount, None, None, None)
 		.is_err());
 	let payment_id = node_a
 		.bolt12_payment()
@@ -1032,6 +1032,7 @@ async fn simple_bolt12_send_receive() {
 			expected_amount_msat,
 			expected_quantity,
 			expected_payer_note.clone(),
+			None,
 		)
 		.unwrap();
 
@@ -1089,7 +1090,13 @@ async fn simple_bolt12_send_receive() {
 	let expected_payer_note = Some("Test".to_string());
 	let refund = node_b
 		.bolt12_payment()
-		.initiate_refund(overpaid_amount, 3600, expected_quantity, expected_payer_note.clone())
+		.initiate_refund(
+			overpaid_amount,
+			3600,
+			expected_quantity,
+			expected_payer_note.clone(),
+			None,
+		)
 		.unwrap();
 	let invoice = node_a.bolt12_payment().request_refund_payment(&refund).unwrap();
 	expect_payment_received_event!(node_a, overpaid_amount);
@@ -1275,7 +1282,7 @@ async fn async_payment() {
 	node_receiver.stop().unwrap();
 
 	let payment_id =
-		node_sender.bolt12_payment().send_using_amount(&offer, 5_000, None, None).unwrap();
+		node_sender.bolt12_payment().send_using_amount(&offer, 5_000, None, None, None).unwrap();
 
 	// Sleep to allow the payment reach a state where the htlc is held and waiting for the receiver to come online.
 	tokio::time::sleep(std::time::Duration::from_millis(3000)).await;
@@ -1473,7 +1480,7 @@ async fn unified_qr_send_receive() {
 
 	let uqr_payment = node_b.unified_qr_payment().receive(expected_amount_sats, "asdf", expiry_sec);
 	let uri_str = uqr_payment.clone().unwrap();
-	let offer_payment_id: PaymentId = match node_a.unified_qr_payment().send(&uri_str) {
+	let offer_payment_id: PaymentId = match node_a.unified_qr_payment().send(&uri_str, None) {
 		Ok(QrPaymentResult::Bolt12 { payment_id }) => {
 			println!("\nBolt12 payment sent successfully with PaymentID: {:?}", payment_id);
 			payment_id
@@ -1494,7 +1501,7 @@ async fn unified_qr_send_receive() {
 	// Cut off the BOLT12 part to fallback to BOLT11.
 	let uri_str_without_offer = uri_str.split("&lno=").next().unwrap();
 	let invoice_payment_id: PaymentId =
-		match node_a.unified_qr_payment().send(uri_str_without_offer) {
+		match node_a.unified_qr_payment().send(uri_str_without_offer, None) {
 			Ok(QrPaymentResult::Bolt12 { payment_id: _ }) => {
 				panic!("Expected Bolt11 payment but got Bolt12");
 			},
@@ -1517,7 +1524,7 @@ async fn unified_qr_send_receive() {
 
 	// Cut off any lightning part to fallback to on-chain only.
 	let uri_str_without_lightning = onchain_uqr_payment.split("&lightning=").next().unwrap();
-	let txid = match node_a.unified_qr_payment().send(&uri_str_without_lightning) {
+	let txid = match node_a.unified_qr_payment().send(&uri_str_without_lightning, None) {
 		Ok(QrPaymentResult::Bolt12 { payment_id: _ }) => {
 			panic!("Expected on-chain payment but got Bolt12")
 		},