Move JIT parameters to encrypted payment metadata

Author: tnull

CHANGELOG.md

@@ -1,3 +1,9 @@
+# Pending
+
+## Compatibility Notes
+- Pending JIT-channel payments created before upgrading may fail after upgrade because the
+  prior LSPS2 fee-limit state stored in `PaymentKind::Bolt11Jit` is not migrated.
+
 # 0.7.0 - Dec. 3, 2025
 This seventh minor release introduces numerous new features, bug fixes, and API improvements. In particular, it adds support for channel Splicing, Async Payments, as well as sourcing chain data from a Bitcoin Core REST backend.
 
@@ -419,4 +425,3 @@ integrated LDK and BDK-based wallets.
 
 **Note:** This release is still considered experimental, should not be run in
 production, and no compatibility guarantees are given until the release of 0.1.
-

src/builder.rs

@@ -75,6 +75,7 @@ use crate::lnurl_auth::LnurlAuth;
 use crate::logger::{log_error, LdkLogger, LogLevel, LogWriter, Logger};
 use crate::message_handler::NodeCustomMessageHandler;
 use crate::payment::asynchronous::om_mailbox::OnionMessageMailbox;
+use crate::payment::PaymentMetadataKeys;
 use crate::peer_store::PeerStore;
 use crate::runtime::{Runtime, RuntimeSpawner};
 use crate::tx_broadcaster::TransactionBroadcaster;
@@ -88,6 +89,7 @@ use crate::wallet::Wallet;
 use crate::{Node, NodeMetrics};
 
 const LSPS_HARDENED_CHILD_INDEX: u32 = 577;
+const PAYMENT_METADATA_HARDENED_CHILD_INDEX: u32 = 578;
 const PERSISTER_MAX_PENDING_UPDATES: u64 = 100;
 
 #[derive(Debug, Clone)]
@@ -2004,6 +2006,15 @@ fn build_with_store_internal(
 	};
 
 	let lnurl_auth = Arc::new(LnurlAuth::new(xprv, Arc::clone(&logger)));
+	let payment_metadata_keys = {
+		let payment_metadata_xpriv = derive_xprv(
+			Arc::clone(&config),
+			&seed_bytes,
+			PAYMENT_METADATA_HARDENED_CHILD_INDEX,
+			Arc::clone(&logger),
+		)?;
+		PaymentMetadataKeys::new(payment_metadata_xpriv.private_key.secret_bytes())
+	};
 
 	let (stop_sender, _) = tokio::sync::watch::channel(());
 	let (background_processor_stop_sender, _) = tokio::sync::watch::channel(());
@@ -2050,6 +2061,7 @@ fn build_with_store_internal(
 		scorer,
 		peer_store,
 		payment_store,
+		payment_metadata_keys,
 		lnurl_auth,
 		is_running,
 		node_metrics,

src/event.rs

@@ -50,6 +50,7 @@ use crate::payment::asynchronous::static_invoice_store::StaticInvoiceStore;
 use crate::payment::store::{
 	PaymentDetails, PaymentDetailsUpdate, PaymentDirection, PaymentKind, PaymentStatus,
 };
+use crate::payment::{EncryptedPaymentMetadata, PaymentMetadata, PaymentMetadataKeys};
 use crate::runtime::Runtime;
 use crate::types::{
 	CustomTlvRecord, DynStore, KeysManager, OnionMessenger, PaymentStore, Sweeper, Wallet,
@@ -537,6 +538,7 @@ where
 	payment_store: Arc<PaymentStore>,
 	peer_store: Arc<PeerStore<L>>,
 	keys_manager: Arc<KeysManager>,
+	payment_metadata_keys: PaymentMetadataKeys,
 	runtime: Arc<Runtime>,
 	logger: L,
 	config: Arc<Config>,
@@ -556,9 +558,10 @@ where
 		output_sweeper: Arc<Sweeper>, network_graph: Arc<Graph>,
 		liquidity_source: Option<Arc<LiquiditySource<Arc<Logger>>>>,
 		payment_store: Arc<PaymentStore>, peer_store: Arc<PeerStore<L>>,
-		keys_manager: Arc<KeysManager>, static_invoice_store: Option<StaticInvoiceStore>,
-		onion_messenger: Arc<OnionMessenger>, om_mailbox: Option<Arc<OnionMessageMailbox>>,
-		runtime: Arc<Runtime>, logger: L, config: Arc<Config>,
+		keys_manager: Arc<KeysManager>, payment_metadata_keys: PaymentMetadataKeys,
+		static_invoice_store: Option<StaticInvoiceStore>, onion_messenger: Arc<OnionMessenger>,
+		om_mailbox: Option<Arc<OnionMessageMailbox>>, runtime: Arc<Runtime>, logger: L,
+		config: Arc<Config>,
 	) -> Self {
 		Self {
 			event_queue,
@@ -572,6 +575,7 @@ where
 			payment_store,
 			peer_store,
 			keys_manager,
+			payment_metadata_keys,
 			logger,
 			runtime,
 			config,
@@ -581,6 +585,36 @@ where
 		}
 	}
 
+	fn fail_claimable_payment(
+		&self, payment_id: PaymentId, payment_hash: &PaymentHash,
+	) -> Result<(), ReplayEvent> {
+		self.channel_manager.fail_htlc_backwards(payment_hash);
+
+		let update = PaymentDetailsUpdate {
+			status: Some(PaymentStatus::Failed),
+			..PaymentDetailsUpdate::new(payment_id)
+		};
+		match self.payment_store.update(update) {
+			Ok(_) => Ok(()),
+			Err(e) => {
+				log_error!(self.logger, "Failed to access payment store: {}", e);
+				Err(ReplayEvent())
+			},
+		}
+	}
+
+	fn lsps2_max_total_opening_fee_msat(
+		metadata: &PaymentMetadata, amount_msat: u64,
+	) -> Option<u64> {
+		let lsps2_parameters = metadata.lsps2_parameters?;
+		lsps2_parameters.max_total_opening_fee_msat.or_else(|| {
+			lsps2_parameters.max_proportional_opening_fee_ppm_msat.and_then(|max_prop_fee| {
+				// If it's a variable amount payment, compute the actual fee.
+				compute_opening_fee(amount_msat, 0, max_prop_fee)
+			})
+		})
+	}
+
 	pub async fn handle_event(&self, event: LdkEvent) -> Result<(), ReplayEvent> {
 		match event {
 			LdkEvent::FundingGenerationReady {
@@ -694,7 +728,8 @@ where
 				..
 			} => {
 				let payment_id = PaymentId(payment_hash.0);
-				if let Some(info) = self.payment_store.get(&payment_id) {
+				let payment_info = self.payment_store.get(&payment_id);
+				if let Some(info) = payment_info.as_ref() {
 					if info.direction == PaymentDirection::Outbound {
 						log_info!(
 							self.logger,
@@ -717,14 +752,13 @@ where
 					}
 
 					if info.status == PaymentStatus::Succeeded
-						|| matches!(info.kind, PaymentKind::Spontaneous { .. })
+						|| matches!(&info.kind, PaymentKind::Spontaneous { .. })
 					{
-						let stored_preimage = match info.kind {
+						let stored_preimage = match &info.kind {
 							PaymentKind::Bolt11 { preimage, .. }
-							| PaymentKind::Bolt11Jit { preimage, .. }
 							| PaymentKind::Bolt12Offer { preimage, .. }
 							| PaymentKind::Bolt12Refund { preimage, .. }
-							| PaymentKind::Spontaneous { preimage, .. } => preimage,
+							| PaymentKind::Spontaneous { preimage, .. } => *preimage,
 							_ => None,
 						};
 
@@ -759,22 +793,35 @@ where
 							},
 						};
 					}
+				}
 
-					let max_total_opening_fee_msat = match info.kind {
-						PaymentKind::Bolt11Jit { lsp_fee_limits, .. } => {
-							lsp_fee_limits
-								.max_total_opening_fee_msat
-								.or_else(|| {
-									lsp_fee_limits.max_proportional_opening_fee_ppm_msat.and_then(
-										|max_prop_fee| {
-											// If it's a variable amount payment, compute the actual fee.
-											compute_opening_fee(amount_msat, 0, max_prop_fee)
-										},
-									)
-								})
-								.unwrap_or(0)
-						},
-						_ => 0,
+				if counterparty_skimmed_fee_msat > 0 {
+					let max_total_opening_fee_msat = match &purpose {
+						PaymentPurpose::Bolt11InvoicePayment { payment_secret, .. } => onion_fields
+							.as_ref()
+							.and_then(|fields| fields.payment_metadata.as_ref())
+							.and_then(|metadata| {
+								EncryptedPaymentMetadata::from_raw(metadata.clone()).decrypt(
+									&self.payment_metadata_keys,
+									&payment_hash,
+									payment_secret,
+								)
+							})
+							.and_then(|metadata| {
+								Self::lsps2_max_total_opening_fee_msat(&metadata, amount_msat)
+							}),
+						_ => None,
+					};
+
+					let Some(max_total_opening_fee_msat) = max_total_opening_fee_msat else {
+						log_info!(
+							self.logger,
+							"Refusing inbound payment with hash {} as the counterparty withheld {}msat without valid BOLT11 LSPS2 payment metadata",
+							hex_utils::to_string(&payment_hash.0),
+							counterparty_skimmed_fee_msat,
+						);
+						self.fail_claimable_payment(payment_id, &payment_hash)?;
+						return Ok(());
 					};
 
 					if counterparty_skimmed_fee_msat > max_total_opening_fee_msat {
@@ -785,26 +832,13 @@ where
 							counterparty_skimmed_fee_msat,
 							max_total_opening_fee_msat,
 						);
-						self.channel_manager.fail_htlc_backwards(&payment_hash);
-
-						let update = PaymentDetailsUpdate {
-							hash: Some(Some(payment_hash)),
-							status: Some(PaymentStatus::Failed),
-							..PaymentDetailsUpdate::new(payment_id)
-						};
-						match self.payment_store.update(update) {
-							Ok(_) => return Ok(()),
-							Err(e) => {
-								log_error!(self.logger, "Failed to access payment store: {}", e);
-								return Err(ReplayEvent());
-							},
-						};
+						self.fail_claimable_payment(payment_id, &payment_hash)?;
+						return Ok(());
 					}
 
-					// If the LSP skimmed anything, update our stored payment.
-					if counterparty_skimmed_fee_msat > 0 {
-						match info.kind {
-							PaymentKind::Bolt11Jit { .. } => {
+					if let Some(info) = payment_info.as_ref() {
+						match &info.kind {
+							PaymentKind::Bolt11 { .. } => {
 								let update = PaymentDetailsUpdate {
 									counterparty_skimmed_fee_msat: Some(Some(counterparty_skimmed_fee_msat)),
 									..PaymentDetailsUpdate::new(payment_id)
@@ -817,16 +851,17 @@ where
 									},
 								};
 							}
-							_ => debug_assert!(false, "We only expect the counterparty to get away with withholding fees for JIT payments."),
+							_ => debug_assert!(false, "We only expect the counterparty to get away with withholding fees for BOLT11 payments."),
 						}
 					}
+				}
 
+				if let Some(info) = payment_info {
 					// If this is known by the store but ChannelManager doesn't know the preimage,
 					// the payment has been registered via `_for_hash` variants and needs to be manually claimed via
 					// user interaction.
 					match info.kind {
-						PaymentKind::Bolt11 { preimage, .. }
-						| PaymentKind::Bolt11Jit { preimage, .. } => {
+						PaymentKind::Bolt11 { preimage, .. } => {
 							if purpose.preimage().is_none() {
 								debug_assert!(
 									preimage.is_none(),
@@ -1897,8 +1932,50 @@ mod tests {
 
 	use super::*;
 	use crate::io::test_utils::InMemoryStore;
+	use crate::payment::store::LSPS2Parameters;
 	use crate::types::DynStoreWrapper;
 
+	#[test]
+	fn lsps2_payment_metadata_decodes_total_fee_limit() {
+		let metadata = PaymentMetadata {
+			lsps2_parameters: Some(LSPS2Parameters {
+				max_total_opening_fee_msat: Some(42_000),
+				max_proportional_opening_fee_ppm_msat: None,
+			}),
+		};
+
+		assert_eq!(
+			EventHandler::<Arc<TestLogger>>::lsps2_max_total_opening_fee_msat(&metadata, 100_000),
+			Some(42_000)
+		);
+	}
+
+	#[test]
+	fn lsps2_payment_metadata_missing_limit_is_rejected() {
+		let empty_metadata = PaymentMetadata { lsps2_parameters: None };
+		let metadata_without_fee_limit = PaymentMetadata {
+			lsps2_parameters: Some(LSPS2Parameters {
+				max_total_opening_fee_msat: None,
+				max_proportional_opening_fee_ppm_msat: None,
+			}),
+		};
+
+		assert_eq!(
+			EventHandler::<Arc<TestLogger>>::lsps2_max_total_opening_fee_msat(
+				&empty_metadata,
+				100_000
+			),
+			None
+		);
+		assert_eq!(
+			EventHandler::<Arc<TestLogger>>::lsps2_max_total_opening_fee_msat(
+				&metadata_without_fee_limit,
+				100_000
+			),
+			None
+		);
+	}
+
 	#[tokio::test]
 	async fn event_queue_persistence() {
 		let store: Arc<DynStore> = Arc::new(DynStoreWrapper(InMemoryStore::new()));

src/lib.rs

@@ -166,8 +166,8 @@ use logger::{log_debug, log_error, log_info, log_trace, LdkLogger, Logger};
 use payment::asynchronous::om_mailbox::OnionMessageMailbox;
 use payment::asynchronous::static_invoice_store::StaticInvoiceStore;
 use payment::{
-	Bolt11Payment, Bolt12Payment, OnchainPayment, PaymentDetails, SpontaneousPayment,
-	UnifiedPayment,
+	Bolt11Payment, Bolt12Payment, OnchainPayment, PaymentDetails, PaymentMetadataKeys,
+	SpontaneousPayment, UnifiedPayment,
 };
 use peer_store::{PeerInfo, PeerStore};
 use runtime::Runtime;
@@ -233,6 +233,7 @@ pub struct Node {
 	scorer: Arc<Mutex<Scorer>>,
 	peer_store: Arc<PeerStore<Arc<Logger>>>,
 	payment_store: Arc<PaymentStore>,
+	payment_metadata_keys: PaymentMetadataKeys,
 	lnurl_auth: Arc<LnurlAuth>,
 	is_running: Arc<RwLock<bool>>,
 	node_metrics: Arc<RwLock<NodeMetrics>>,
@@ -593,6 +594,7 @@ impl Node {
 			Arc::clone(&self.payment_store),
 			Arc::clone(&self.peer_store),
 			Arc::clone(&self.keys_manager),
+			self.payment_metadata_keys,
 			static_invoice_store,
 			Arc::clone(&self.onion_messenger),
 			self.om_mailbox.clone(),
@@ -885,6 +887,7 @@ impl Node {
 			self.liquidity_source.clone(),
 			Arc::clone(&self.payment_store),
 			Arc::clone(&self.peer_store),
+			self.payment_metadata_keys,
 			Arc::clone(&self.config),
 			Arc::clone(&self.is_running),
 			Arc::clone(&self.logger),
@@ -903,6 +906,7 @@ impl Node {
 			self.liquidity_source.clone(),
 			Arc::clone(&self.payment_store),
 			Arc::clone(&self.peer_store),
+			self.payment_metadata_keys,
 			Arc::clone(&self.config),
 			Arc::clone(&self.is_running),
 			Arc::clone(&self.logger),