Add BOLT11 JIT hold-invoice RPCs.

Wrap ldk-node receive_via_jit_channel_for_hash and
receive_variable_amount_via_jit_channel_for_hash as two new RPCs.

Author: f3r10

docs/api-guide.md

@@ -125,6 +125,8 @@ a channel just-in-time when the invoice is paid.
 |--------------------------------------------|-----------------------------------------------------------|
 | `Bolt11ReceiveViaJitChannel`               | Create a fixed-amount invoice with JIT channel opening    |
 | `Bolt11ReceiveVariableAmountViaJitChannel` | Create a variable-amount invoice with JIT channel opening |
+| `Bolt11ReceiveViaJitChannelForHash`        | Create a fixed-amount invoice with JIT channel opening for a given payment hash (manual claim required) |
+| `Bolt11ReceiveVariableAmountViaJitChannelForHash` | Create a variable-amount invoice with JIT channel opening for a given payment hash (manual claim required) |
 
 ### BOLT12 Offers and Refunds
 
@@ -262,7 +264,7 @@ Hodl invoices allow you to inspect and conditionally accept incoming payments:
 
 1. **Subscribe:** Call `SubscribeEvents` before you create or share the invoice. Events are not
    replayed.
-2. **Create the invoice:** Generate a new payment hash. Call `Bolt11ReceiveForHash` with this hash.
+2. **Create the invoice:** Generate a new payment hash. Call `Bolt11ReceiveForHash`, `Bolt11ReceiveViaJitChannelForHash` or `Bolt11ReceiveVariableAmountViaJitChannelForHash` with this hash.
    Never reuse a payment hash. Reuse is unsafe and can cause loss of funds.
 3. **Handle each payment:** Save the payment ID from each `PaymentClaimable` event. A payer can pay
    the same invoice more than once. Each payment has a separate event and payment ID.

docs/configuration.md

@@ -157,8 +157,8 @@ to register several LSPs. Each LSP's supported protocols are discovered on start
 [bLIP-50 / LSPS0](https://github.com/lightning/blips/blob/master/blip-0050.md). LDK Server
 currently supports LSPS2 only, so an LSP that does not advertise it is registered but unused.
 
-When at least one LSPS2-capable LSP is configured, the `Bolt11ReceiveViaJitChannel` and
-`Bolt11ReceiveVariableAmountViaJitChannel` RPCs become available, and the cheapest fee offer
+When at least one LSPS2-capable LSP is configured, the `Bolt11ReceiveViaJitChannel`, 
+`Bolt11ReceiveVariableAmountViaJitChannel`, `Bolt11ReceiveViaJitChannelForHash` and `Bolt11ReceiveVariableAmountViaJitChannelForHash` RPCs become available, and the cheapest fee offer
 across all LSPS2-capable LSPs is selected per invoice.
 
 Requires each LSP's public key and address. Some LSPs also require an authentication token.

e2e-tests/src/lib.rs

@@ -139,8 +139,12 @@ pub enum ChainSource {
 		rpc_password: String,
 		rest_address: Option<String>,
 	},
-	Electrum { server_url: String },
-	Esplora { server_url: String },
+	Electrum {
+		server_url: String,
+	},
+	Esplora {
+		server_url: String,
+	},
 }
 
 impl ChainSource {
@@ -181,6 +185,7 @@ pub struct TestConfigBuilder {
 	metrics_auth: Option<(String, String)>,
 	log: Option<(Option<String>, String)>,
 	tls_hosts: Option<Vec<String>>,
+	lsps_clients: Vec<(String, String, bool)>,
 }
 
 impl TestConfigBuilder {
@@ -202,6 +207,7 @@ impl TestConfigBuilder {
 			metrics_auth: None,
 			log: None,
 			tls_hosts: None,
+			lsps_clients: Vec::new(),
 		}
 	}
 
@@ -247,6 +253,12 @@ impl TestConfigBuilder {
 		self
 	}
 
+	/// Add a `[[liquidity.lsps_client]]` section.
+	pub fn lsps_client(mut self, node_pubkey: &str, address: &str, trust_peer_0conf: bool) -> Self {
+		self.lsps_clients.push((node_pubkey.to_string(), address.to_string(), trust_peer_0conf));
+		self
+	}
+
 	/// Build the config into a TOML string.
 	pub fn build(&self) -> String {
 		fn toml_string_array(values: &[String]) -> String {
@@ -321,6 +333,15 @@ poll_metrics_interval = 1{metrics_auth}
 			config.push_str(&format!("\n[tls]\nhosts = {}\n", toml_string_array(hosts)));
 		}
 
+		for (node_pubkey, address, trust_peer_0conf) in &self.lsps_clients {
+			config.push_str(&format!(
+				"\n[[liquidity.lsps_client]]\n\
+				node_pubkey = \"{node_pubkey}\"\n\
+				address = \"{address}\"\n\
+				trust_peer_0conf = {trust_peer_0conf}\n"
+			));
+		}
+
 		config
 	}
 }
@@ -783,9 +804,7 @@ pub async fn setup_funded_channel(
 		.open_channel(OpenChannelRequest {
 			node_pubkey: server_b.node_id().to_string(),
 			address: format!("127.0.0.1:{}", server_b.p2p_port),
-			amount: Some(open_channel_request::Amount::ChannelAmountSats(
-				channel_amount_sats,
-			)),
+			amount: Some(open_channel_request::Amount::ChannelAmountSats(channel_amount_sats)),
 			push_to_counterparty_msat: None,
 			channel_config: None,
 			announce_channel: true,

e2e-tests/tests/e2e.rs

@@ -14,7 +14,7 @@ use std::time::Duration;
 use e2e_tests::{
 	find_available_port, mine_and_sync, run_cli, run_cli_raw, run_cli_with_config,
 	setup_funded_channel, wait_for_event, wait_for_onchain_balance, wait_for_usable_channel,
-	LdkServerConfig, LdkServerHandle, TestBitcoind,
+	LdkServerConfig, LdkServerHandle, TestBitcoind, TestConfigBuilder,
 };
 use hex_conservative::{DisplayHex, FromHex};
 use ldk_node::bitcoin::hashes::{sha256, Hash};
@@ -439,13 +439,7 @@ async fn open_channel_via_cli(channel_amount: &str) {
 	let addr = format!("127.0.0.1:{}", server_b.p2p_port);
 	let output = run_cli(
 		&server_a,
-		&[
-			"open-channel",
-			server_b.node_id(),
-			&addr,
-			channel_amount,
-			"--announce-channel",
-		],
+		&["open-channel", server_b.node_id(), &addr, channel_amount, "--announce-channel"],
 	);
 	assert!(!output["user_channel_id"].as_str().unwrap().is_empty());
 }
@@ -482,9 +476,7 @@ async fn test_subscribe_events_channel_state_lifecycle_pending_ready_closed() {
 		.open_channel(OpenChannelRequest {
 			node_pubkey: server_b.node_id().to_string(),
 			address: format!("127.0.0.1:{}", server_b.p2p_port),
-			amount: Some(open_channel_request::Amount::ChannelAmountSats(
-				100_000,
-			)),
+			amount: Some(open_channel_request::Amount::ChannelAmountSats(100_000)),
 			push_to_counterparty_msat: None,
 			channel_config: None,
 			announce_channel: true,
@@ -512,7 +504,10 @@ async fn test_subscribe_events_channel_state_lifecycle_pending_ready_closed() {
 	assert!(pending_a.reason.is_none());
 	assert_eq!(pending_a.closure_initiator, ChannelClosureInitiator::Unspecified as i32);
 	assert!(pending_a.former_temporary_channel_id.as_deref().is_some_and(|id| !id.is_empty()));
-	assert_ne!(pending_a.former_temporary_channel_id.as_deref(), Some(pending_a.channel_id.as_str()));
+	assert_ne!(
+		pending_a.former_temporary_channel_id.as_deref(),
+		Some(pending_a.channel_id.as_str())
+	);
 
 	let pending_b = wait_for_event(&mut events_b, |e| {
 		matches!(
@@ -650,9 +645,7 @@ async fn test_subscribe_events_channel_state_lifecycle_pending_ready_force_close
 		.open_channel(OpenChannelRequest {
 			node_pubkey: server_b.node_id().to_string(),
 			address: format!("127.0.0.1:{}", server_b.p2p_port),
-			amount: Some(open_channel_request::Amount::ChannelAmountSats(
-				100_000,
-			)),
+			amount: Some(open_channel_request::Amount::ChannelAmountSats(100_000)),
 			push_to_counterparty_msat: None,
 			channel_config: None,
 			announce_channel: true,
@@ -680,7 +673,10 @@ async fn test_subscribe_events_channel_state_lifecycle_pending_ready_force_close
 	assert!(pending_a.reason.is_none());
 	assert_eq!(pending_a.closure_initiator, ChannelClosureInitiator::Unspecified as i32);
 	assert!(pending_a.former_temporary_channel_id.as_deref().is_some_and(|id| !id.is_empty()));
-	assert_ne!(pending_a.former_temporary_channel_id.as_deref(), Some(pending_a.channel_id.as_str()));
+	assert_ne!(
+		pending_a.former_temporary_channel_id.as_deref(),
+		Some(pending_a.channel_id.as_str())
+	);
 
 	let pending_b = wait_for_event(&mut events_b, |e| {
 		matches!(
@@ -1273,14 +1269,11 @@ async fn splice_in_via_cli(splice_amount: &str) {
 
 	let mut events_a = server_a.client().subscribe_events().await.unwrap();
 
-	let output = run_cli(
-		&server_a,
-		&["splice-in", &user_channel_id, server_b.node_id(), splice_amount],
-	);
+	let output =
+		run_cli(&server_a, &["splice-in", &user_channel_id, server_b.node_id(), splice_amount]);
 	assert!(output.is_object());
 
-	let event_a =
-		wait_for_event(&mut events_a, |e| matches!(e, Event::SpliceNegotiated(_))).await;
+	let event_a = wait_for_event(&mut events_a, |e| matches!(e, Event::SpliceNegotiated(_))).await;
 	match &event_a.event {
 		Some(Event::SpliceNegotiated(splice_negotiated)) => {
 			assert_eq!(splice_negotiated.user_channel_id, user_channel_id);
@@ -1663,10 +1656,183 @@ async fn test_hodl_invoice_fail() {
 		panic!("expected PaymentFailed");
 	};
 	assert!(!failed.payment.as_ref().unwrap().payment_id.is_empty());
-	assert_eq!(
-		failed.reason,
-		Some(PaymentFailureReason::RecipientRejected as i32)
+	assert_eq!(failed.reason, Some(PaymentFailureReason::RecipientRejected as i32));
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn test_jit_hodl_invoice_claim() {
+	let bitcoind = TestBitcoind::new();
+
+	// A: normal payer node
+	let server_a = LdkServerHandle::start(&bitcoind).await;
+
+	// Subscribe to events on A before any payments
+	let mut events_a = server_a.client().subscribe_events().await.unwrap();
+
+	// B: LSP node (all e2e servers include LSPS2 service config)
+	let server_b = LdkServerHandle::start(&bitcoind).await;
+
+	// Open channel A -> B (1M sats, larger for JIT forwarding)
+	setup_funded_channel(&bitcoind, &server_a, &server_b, 1_000_000).await;
+
+	// Fund B additionally so it can open JIT channel to C
+	let addr_b = server_b.client().onchain_receive(OnchainReceiveRequest {}).await.unwrap().address;
+	bitcoind.fund_address(&addr_b, 1.0);
+	mine_and_sync(&bitcoind, &[&server_a, &server_b], 6).await;
+
+	// C: JIT client
+	let lsp_pubkey = server_b.node_id().to_string();
+	let lsp_addr = format!("127.0.0.1:{}", server_b.p2p_port);
+	let server_c = LdkServerHandle::start_with_config(&bitcoind, |params| {
+		TestConfigBuilder::new(params).lsps_client(&lsp_pubkey, &lsp_addr, true).build()
+	})
+	.await;
+	let mut events_c = server_c.client().subscribe_events().await.unwrap();
+
+	let preimage_bytes_1 = [43u8; 32];
+	let preimage_hex_1 = preimage_bytes_1.to_lower_hex_string();
+	let payment_hash_1 = sha256::Hash::hash(&preimage_bytes_1);
+	let payment_hash_hex_1 = payment_hash_1.to_byte_array().to_lower_hex_string();
+
+	let preimage_bytes_2 = [44u8; 32];
+	let payment_hash_2 = sha256::Hash::hash(&preimage_bytes_2);
+	let payment_hash_hex_2 = payment_hash_2.to_byte_array().to_lower_hex_string();
+
+	// Create fixed amount hodl invoice on c
+	let invoice_resp_1 = run_cli(
+		&server_c,
+		&[
+			"bolt11-receive-via-jit-channel-for-hash",
+			&payment_hash_hex_1,
+			"100000000msat",
+			"-d",
+			"jit hodl test",
+			"-e",
+			"3600",
+		],
 	);
+	let invoice_1 = invoice_resp_1["invoice"].as_str().unwrap();
+	assert!(!invoice_1.is_empty());
+
+	// Create variable amount hodl invoice on c
+	let invoice_resp_2 = run_cli(
+		&server_c,
+		&[
+			"bolt11-receive-variable-amount-via-jit-channel-for-hash",
+			&payment_hash_hex_2,
+			"-d",
+			"jit variable hodl test",
+			"-e",
+			"3600",
+		],
+	);
+	let invoice_2 = invoice_resp_2["invoice"].as_str().unwrap();
+	assert!(!invoice_2.is_empty());
+
+	// Pay the hodl invoice from A
+	run_cli(&server_a, &["bolt11-send", invoice_1]);
+
+	// Wait for PaymentClaimable event on C (drain other events)
+	let claimable =
+		wait_for_event(&mut events_c, |e| matches!(e, Event::PaymentClaimable(_))).await;
+	let Some(Event::PaymentClaimable(claimable_event)) = &claimable.event else {
+		panic!("expected PaymentClaimable");
+	};
+	assert!(claimable_event.claim_deadline.is_some());
+	assert!(!claimable_event.payment_id.is_empty());
+
+	// Claim the payment on C
+	let claimable_amount = format!("{}msat", claimable_event.claimable_amount_msat);
+	let args: Vec<&str> = vec![
+		"bolt11-claim-for-id",
+		&claimable_event.payment_id,
+		&preimage_hex_1,
+		"-c",
+		&claimable_amount,
+	];
+
+	run_cli(&server_c, &args);
+
+	// Wait for PaymentSuccessful on A after claim (drain other events)
+	let successful =
+		wait_for_event(&mut events_a, |e| matches!(e, Event::PaymentSuccessful(_))).await;
+	let Some(Event::PaymentSuccessful(event)) = &successful.event else {
+		panic!("expected PaymentSuccessful");
+	};
+	assert!(!event.payment.as_ref().unwrap().payment_id.is_empty());
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn test_jit_hodl_invoice_fail() {
+	let bitcoind = TestBitcoind::new();
+
+	// A: normal payer node
+	let server_a = LdkServerHandle::start(&bitcoind).await;
+
+	// Subscribe to events on A before any payments
+	let mut events_a = server_a.client().subscribe_events().await.unwrap();
+
+	// B: LSP node (all e2e servers include LSPS2 service config)
+	let server_b = LdkServerHandle::start(&bitcoind).await;
+
+	// Open channel A -> B (1M sats, larger for JIT forwarding)
+	setup_funded_channel(&bitcoind, &server_a, &server_b, 1_000_000).await;
+
+	// Fund B additionally so it can open JIT channel to C
+	let addr_b = server_b.client().onchain_receive(OnchainReceiveRequest {}).await.unwrap().address;
+	bitcoind.fund_address(&addr_b, 1.0);
+	mine_and_sync(&bitcoind, &[&server_a, &server_b], 6).await;
+
+	// C: JIT client
+	let lsp_pubkey = server_b.node_id().to_string();
+	let lsp_addr = format!("127.0.0.1:{}", server_b.p2p_port);
+	let server_c = LdkServerHandle::start_with_config(&bitcoind, |params| {
+		TestConfigBuilder::new(params).lsps_client(&lsp_pubkey, &lsp_addr, true).build()
+	})
+	.await;
+	let mut events_c = server_c.client().subscribe_events().await.unwrap();
+
+	let preimage_bytes = [43u8; 32];
+	let payment_hash = sha256::Hash::hash(&preimage_bytes);
+	let payment_hash_hex = payment_hash.to_byte_array().to_lower_hex_string();
+
+	// Create fixed amount hodl invoice on c
+	let invoice_resp = run_cli(
+		&server_c,
+		&[
+			"bolt11-receive-via-jit-channel-for-hash",
+			&payment_hash_hex,
+			"100000000msat",
+			"-d",
+			"jit hodl test",
+			"-e",
+			"3600",
+		],
+	);
+	let invoice = invoice_resp["invoice"].as_str().unwrap();
+	assert!(!invoice.is_empty());
+
+	// Pay the hodl invoice from A
+	run_cli(&server_a, &["bolt11-send", invoice]);
+
+	// Wait for PaymentClaimable event on C (drain other events)
+	let claimable =
+		wait_for_event(&mut events_c, |e| matches!(e, Event::PaymentClaimable(_))).await;
+	let Some(Event::PaymentClaimable(claimable_event)) = &claimable.event else {
+		panic!("expected PaymentClaimable");
+	};
+	assert!(claimable_event.claim_deadline.is_some());
+	assert!(!claimable_event.payment_id.is_empty());
+
+	run_cli(&server_c, &["bolt11-fail-for-id", &claimable_event.payment_id]);
+
+	// Verify PaymentFailed on A and its failure reason.
+	let event_a = wait_for_event(&mut events_a, |e| matches!(e, Event::PaymentFailed(_))).await;
+	let Some(Event::PaymentFailed(failed)) = &event_a.event else {
+		panic!("expected PaymentFailed");
+	};
+	assert!(!failed.payment.as_ref().unwrap().payment_id.is_empty());
+	assert_eq!(failed.reason, Some(PaymentFailureReason::RecipientRejected as i32));
 }
 
 #[tokio::test]