Add hodl invoice support

Adds three new API endpoints for hodl invoices, which allow the receiver
to inspect incoming payments before deciding whether to claim or reject
them. Also add a `PaymentClaimable` event that is published when a hodl
invoice payment arrives and is waiting to be manually claimed or failed.

This is was needed when getting ldk-server to work with loop.

Author: benthecarman

e2e-tests/tests/e2e.rs

@@ -14,6 +14,8 @@ use e2e_tests::{
 	find_available_port, mine_and_sync, run_cli, run_cli_raw, setup_funded_channel,
 	wait_for_onchain_balance, LdkServerHandle, RabbitMqEventConsumer, TestBitcoind,
 };
+use hex_conservative::DisplayHex;
+use ldk_node::bitcoin::hashes::{sha256, Hash};
 use ldk_node::lightning::ln::msgs::SocketAddress;
 use ldk_server_client::ldk_server_protos::api::{
 	Bolt11ReceiveRequest, Bolt12ReceiveRequest, OnchainReceiveRequest,
@@ -634,3 +636,145 @@ async fn test_forwarded_payment_event() {
 
 	node_c.stop().unwrap();
 }
+
+#[tokio::test]
+async fn test_hodl_invoice_claim() {
+	let bitcoind = TestBitcoind::new();
+	let server_a = LdkServerHandle::start(&bitcoind).await;
+	let server_b = LdkServerHandle::start(&bitcoind).await;
+
+	let mut consumer_a = RabbitMqEventConsumer::new(&server_a.exchange_name).await;
+	let mut consumer_b = RabbitMqEventConsumer::new(&server_b.exchange_name).await;
+
+	setup_funded_channel(&bitcoind, &server_a, &server_b, 100_000).await;
+
+	// Test three claim variants: (preimage, amount, hash)
+	let test_cases: Vec<([u8; 32], Option<&str>, bool)> = vec![
+		([42u8; 32], Some("10000000msat"), true),  // all args
+		([44u8; 32], Some("10000000msat"), false), // preimage + amount
+		([45u8; 32], None, false),                 // preimage only
+		([46u8; 32], None, true),                  // hash only
+	];
+
+	for (preimage_bytes, amount, include_hash) in &test_cases {
+		let preimage_hex = preimage_bytes.to_lower_hex_string();
+		let payment_hash_hex =
+			sha256::Hash::hash(preimage_bytes).to_byte_array().to_lower_hex_string();
+
+		// Create hodl invoice on B
+		let invoice_resp = run_cli(
+			&server_b,
+			&[
+				"bolt11-receive-for-hash",
+				&payment_hash_hex,
+				"10000000msat",
+				"-d",
+				"hodl test",
+				"-e",
+				"3600",
+			],
+		);
+		let invoice = invoice_resp["invoice"].as_str().unwrap();
+
+		// Pay the hodl invoice from A
+		run_cli(&server_a, &["bolt11-send", invoice]);
+
+		// Verify PaymentClaimable event on B
+		let events_b = consumer_b.consume_events(1, Duration::from_secs(10)).await;
+		assert!(
+			events_b.iter().any(|e| matches!(&e.event, Some(Event::PaymentClaimable(_)))),
+			"Expected PaymentClaimable on receiver, got events: {:?}",
+			events_b.iter().map(|e| &e.event).collect::<Vec<_>>()
+		);
+
+		// Claim the payment on B
+		let mut args: Vec<&str> = vec!["bolt11-claim-for-hash", &preimage_hex];
+		if let Some(amt) = amount {
+			args.extend(["-c", amt]);
+		}
+		if *include_hash {
+			args.extend(["-p", &payment_hash_hex]);
+		}
+		run_cli(&server_b, &args);
+
+		// Verify PaymentReceived event on B
+		let events_b = consumer_b.consume_events(1, Duration::from_secs(10)).await;
+		assert!(
+			events_b.iter().any(|e| matches!(&e.event, Some(Event::PaymentReceived(_)))),
+			"Expected PaymentReceived on receiver after claim, got events: {:?}",
+			events_b.iter().map(|e| &e.event).collect::<Vec<_>>()
+		);
+
+		// Verify PaymentSuccessful on A
+		let events_a = consumer_a.consume_events(1, Duration::from_secs(10)).await;
+		assert!(
+			events_a.iter().any(|e| matches!(&e.event, Some(Event::PaymentSuccessful(_)))),
+			"Expected PaymentSuccessful on sender, got events: {:?}",
+			events_a.iter().map(|e| &e.event).collect::<Vec<_>>()
+		);
+	}
+}
+
+#[tokio::test]
+async fn test_hodl_invoice_fail() {
+	use hex_conservative::DisplayHex;
+	use ldk_node::bitcoin::hashes::{sha256, Hash};
+
+	let bitcoind = TestBitcoind::new();
+	let server_a = LdkServerHandle::start(&bitcoind).await;
+	let server_b = LdkServerHandle::start(&bitcoind).await;
+
+	// Set up event consumers before any payments
+	let mut consumer_a = RabbitMqEventConsumer::new(&server_a.exchange_name).await;
+	let mut consumer_b = RabbitMqEventConsumer::new(&server_b.exchange_name).await;
+
+	setup_funded_channel(&bitcoind, &server_a, &server_b, 100_000).await;
+
+	// Generate a known preimage and compute its payment hash
+	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 hodl invoice on B
+	let invoice_resp = run_cli(
+		&server_b,
+		&[
+			"bolt11-receive-for-hash",
+			&payment_hash_hex,
+			"10000000msat",
+			"-d",
+			"hodl fail test",
+			"-e",
+			"3600",
+		],
+	);
+	let invoice = invoice_resp["invoice"].as_str().unwrap();
+
+	// Pay the hodl invoice from A
+	run_cli(&server_a, &["bolt11-send", invoice]);
+
+	// Wait for payment to arrive at B
+	tokio::time::sleep(Duration::from_secs(5)).await;
+
+	// Verify PaymentClaimable event on B
+	let events_b = consumer_b.consume_events(5, Duration::from_secs(10)).await;
+	assert!(
+		events_b.iter().any(|e| matches!(&e.event, Some(Event::PaymentClaimable(_)))),
+		"Expected PaymentClaimable on receiver, got events: {:?}",
+		events_b.iter().map(|e| &e.event).collect::<Vec<_>>()
+	);
+
+	// Fail the payment on B using CLI
+	run_cli(&server_b, &["bolt11-fail-for-hash", &payment_hash_hex]);
+
+	// Wait for failure to propagate
+	tokio::time::sleep(Duration::from_secs(5)).await;
+
+	// Verify PaymentFailed on A
+	let events_a = consumer_a.consume_events(10, Duration::from_secs(10)).await;
+	assert!(
+		events_a.iter().any(|e| matches!(&e.event, Some(Event::PaymentFailed(_)))),
+		"Expected PaymentFailed on sender after hodl rejection, got events: {:?}",
+		events_a.iter().map(|e| &e.event).collect::<Vec<_>>()
+	);
+}

ldk-server-cli/src/main.rs

@@ -22,6 +22,8 @@ use ldk_server_client::error::LdkServerErrorCode::{
 	AuthError, InternalError, InternalServerError, InvalidRequestError, LightningError,
 };
 use ldk_server_client::ldk_server_protos::api::{
+	Bolt11ClaimForHashRequest, Bolt11ClaimForHashResponse, Bolt11FailForHashRequest,
+	Bolt11FailForHashResponse, Bolt11ReceiveForHashRequest, Bolt11ReceiveForHashResponse,
 	Bolt11ReceiveRequest, Bolt11ReceiveResponse, Bolt11SendRequest, Bolt11SendResponse,
 	Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRequest, Bolt12SendResponse,
 	CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest, ConnectPeerResponse,
@@ -134,6 +136,48 @@ enum Commands {
 		#[arg(short, long, help = "Invoice expiry time in seconds (default: 86400)")]
 		expiry_secs: Option<u32>,
 	},
+	#[command(
+		about = "Create a BOLT11 hodl invoice for a given payment hash (manual claim required)"
+	)]
+	Bolt11ReceiveForHash {
+		#[arg(help = "The hex-encoded 32-byte payment hash")]
+		payment_hash: String,
+		#[arg(
+			help = "Amount to request, e.g. 50sat or 50000msat. If unset, a variable-amount invoice is returned"
+		)]
+		amount: Option<Amount>,
+		#[arg(short, long, help = "Description to attach along with the invoice")]
+		description: Option<String>,
+		#[arg(
+			long,
+			help = "SHA-256 hash of the description (hex). Use instead of description for longer text"
+		)]
+		description_hash: Option<String>,
+		#[arg(short, long, help = "Invoice expiry time in seconds (default: 86400)")]
+		expiry_secs: Option<u32>,
+	},
+	#[command(about = "Claim a held payment by providing the preimage")]
+	Bolt11ClaimForHash {
+		#[arg(help = "The hex-encoded 32-byte payment preimage")]
+		preimage: String,
+		#[arg(
+			short,
+			long,
+			help = "The claimable amount, e.g. 50sat or 50000msat, only used for verifying we are claiming the expected amount"
+		)]
+		claimable_amount: Option<Amount>,
+		#[arg(
+			short,
+			long,
+			help = "The hex-encoded 32-byte payment hash, used to verify the preimage matches"
+		)]
+		payment_hash: Option<String>,
+	},
+	#[command(about = "Fail/reject a held payment")]
+	Bolt11FailForHash {
+		#[arg(help = "The hex-encoded 32-byte payment hash")]
+		payment_hash: String,
+	},
 	#[command(about = "Pay a BOLT11 invoice")]
 	Bolt11Send {
 		#[arg(help = "A BOLT11 invoice for a payment within the Lightning Network")]
@@ -551,6 +595,58 @@ async fn main() {
 				client.bolt11_receive(request).await,
 			);
 		},
+		Commands::Bolt11ReceiveForHash {
+			payment_hash,
+			amount,
+			description,
+			description_hash,
+			expiry_secs,
+		} => {
+			let amount_msat = amount.map(|a| a.to_msat());
+			let invoice_description = match (description, description_hash) {
+				(Some(desc), None) => Some(Bolt11InvoiceDescription {
+					kind: Some(bolt11_invoice_description::Kind::Direct(desc)),
+				}),
+				(None, Some(hash)) => Some(Bolt11InvoiceDescription {
+					kind: Some(bolt11_invoice_description::Kind::Hash(hash)),
+				}),
+				(Some(_), Some(_)) => {
+					handle_error(LdkServerError::new(
+						InternalError,
+						"Only one of description or description_hash can be set.".to_string(),
+					));
+				},
+				(None, None) => None,
+			};
+
+			let expiry_secs = expiry_secs.unwrap_or(DEFAULT_EXPIRY_SECS);
+			let request = Bolt11ReceiveForHashRequest {
+				description: invoice_description,
+				expiry_secs,
+				amount_msat,
+				payment_hash,
+			};
+
+			handle_response_result::<_, Bolt11ReceiveForHashResponse>(
+				client.bolt11_receive_for_hash(request).await,
+			);
+		},
+		Commands::Bolt11ClaimForHash { preimage, claimable_amount, payment_hash } => {
+			handle_response_result::<_, Bolt11ClaimForHashResponse>(
+				client
+					.bolt11_claim_for_hash(Bolt11ClaimForHashRequest {
+						payment_hash,
+						claimable_amount_msat: claimable_amount.map(|a| a.to_msat()),
+						preimage,
+					})
+					.await,
+			);
+		},
+		Commands::Bolt11FailForHash { payment_hash } => {
+			handle_response_result::<_, Bolt11FailForHashResponse>(
+				client.bolt11_fail_for_hash(Bolt11FailForHashRequest { payment_hash }).await,
+			);
+		},
 		Commands::Bolt11Send {
 			invoice,
 			amount,

ldk-server-client/src/client.rs

@@ -12,6 +12,8 @@ use std::time::{SystemTime, UNIX_EPOCH};
 use bitcoin_hashes::hmac::{Hmac, HmacEngine};
 use bitcoin_hashes::{sha256, Hash, HashEngine};
 use ldk_server_protos::api::{
+	Bolt11ClaimForHashRequest, Bolt11ClaimForHashResponse, Bolt11FailForHashRequest,
+	Bolt11FailForHashResponse, Bolt11ReceiveForHashRequest, Bolt11ReceiveForHashResponse,
 	Bolt11ReceiveRequest, Bolt11ReceiveResponse, Bolt11SendRequest, Bolt11SendResponse,
 	Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRequest, Bolt12SendResponse,
 	CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest, ConnectPeerResponse,
@@ -30,6 +32,7 @@ use ldk_server_protos::api::{
 	VerifySignatureRequest, VerifySignatureResponse,
 };
 use ldk_server_protos::endpoints::{
+	BOLT11_CLAIM_FOR_HASH_PATH, BOLT11_FAIL_FOR_HASH_PATH, BOLT11_RECEIVE_FOR_HASH_PATH,
 	BOLT11_RECEIVE_PATH, BOLT11_SEND_PATH, BOLT12_RECEIVE_PATH, BOLT12_SEND_PATH,
 	CLOSE_CHANNEL_PATH, CONNECT_PEER_PATH, DISCONNECT_PEER_PATH, EXPORT_PATHFINDING_SCORES_PATH,
 	FORCE_CLOSE_CHANNEL_PATH, GET_BALANCES_PATH, GET_NODE_INFO_PATH, GET_PAYMENT_DETAILS_PATH,
@@ -143,6 +146,34 @@ impl LdkServerClient {
 		self.post_request(&request, &url).await
 	}
 
+	/// Retrieve a new BOLT11 payable invoice for a given payment hash.
+	/// The inbound payment will NOT be automatically claimed upon arrival.
+	/// For API contract/usage, refer to docs for [`Bolt11ReceiveForHashRequest`] and [`Bolt11ReceiveForHashResponse`].
+	pub async fn bolt11_receive_for_hash(
+		&self, request: Bolt11ReceiveForHashRequest,
+	) -> Result<Bolt11ReceiveForHashResponse, LdkServerError> {
+		let url = format!("https://{}/{BOLT11_RECEIVE_FOR_HASH_PATH}", self.base_url);
+		self.post_request(&request, &url).await
+	}
+
+	/// Manually claim a payment for a given payment hash with the corresponding preimage.
+	/// For API contract/usage, refer to docs for [`Bolt11ClaimForHashRequest`] and [`Bolt11ClaimForHashResponse`].
+	pub async fn bolt11_claim_for_hash(
+		&self, request: Bolt11ClaimForHashRequest,
+	) -> Result<Bolt11ClaimForHashResponse, LdkServerError> {
+		let url = format!("https://{}/{BOLT11_CLAIM_FOR_HASH_PATH}", self.base_url);
+		self.post_request(&request, &url).await
+	}
+
+	/// Manually fail a payment for a given payment hash.
+	/// For API contract/usage, refer to docs for [`Bolt11FailForHashRequest`] and [`Bolt11FailForHashResponse`].
+	pub async fn bolt11_fail_for_hash(
+		&self, request: Bolt11FailForHashRequest,
+	) -> Result<Bolt11FailForHashResponse, LdkServerError> {
+		let url = format!("https://{}/{BOLT11_FAIL_FOR_HASH_PATH}", self.base_url);
+		self.post_request(&request, &url).await
+	}
+
 	/// Send a payment for a BOLT11 invoice.
 	/// For API contract/usage, refer to docs for [`Bolt11SendRequest`] and [`Bolt11SendResponse`].
 	pub async fn bolt11_send(