Add receive_via_jit_channel_for_hash() method

Author: andrei-21

src/event.rs

@@ -683,7 +683,8 @@ where
 					// 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::Bolt11 { preimage, .. }
+						| PaymentKind::Bolt11Jit { preimage, .. } => {
 							if purpose.preimage().is_none() {
 								debug_assert!(
 									preimage.is_none(),

src/liquidity.rs

@@ -987,7 +987,7 @@ where
 
 	pub(crate) async fn lsps2_receive_to_jit_channel(
 		&self, amount_msat: u64, description: &Bolt11InvoiceDescription, expiry_secs: u32,
-		max_total_lsp_fee_limit_msat: Option<u64>,
+		max_total_lsp_fee_limit_msat: Option<u64>, payment_hash: Option<PaymentHash>,
 	) -> Result<(Bolt11Invoice, u64), Error> {
 		let fee_response = self.lsps2_request_opening_fee_params().await?;
 
@@ -1039,6 +1039,7 @@ where
 			Some(amount_msat),
 			description,
 			expiry_secs,
+			payment_hash,
 		)?;
 
 		log_info!(self.logger, "JIT-channel invoice created: {}", invoice);
@@ -1047,7 +1048,7 @@ where
 
 	pub(crate) async fn lsps2_receive_variable_amount_to_jit_channel(
 		&self, description: &Bolt11InvoiceDescription, expiry_secs: u32,
-		max_proportional_lsp_fee_limit_ppm_msat: Option<u64>,
+		max_proportional_lsp_fee_limit_ppm_msat: Option<u64>, payment_hash: Option<PaymentHash>,
 	) -> Result<(Bolt11Invoice, u64), Error> {
 		let fee_response = self.lsps2_request_opening_fee_params().await?;
 
@@ -1081,8 +1082,13 @@ where
 		);
 
 		let buy_response = self.lsps2_send_buy_request(None, min_opening_params).await?;
-		let invoice =
-			self.lsps2_create_jit_invoice(buy_response, None, description, expiry_secs)?;
+		let invoice = self.lsps2_create_jit_invoice(
+			buy_response,
+			None,
+			description,
+			expiry_secs,
+			payment_hash,
+		)?;
 
 		log_info!(self.logger, "JIT-channel invoice created: {}", invoice);
 		Ok((invoice, min_prop_fee_ppm_msat))
@@ -1165,18 +1171,36 @@ where
 	fn lsps2_create_jit_invoice(
 		&self, buy_response: LSPS2BuyResponse, amount_msat: Option<u64>,
 		description: &Bolt11InvoiceDescription, expiry_secs: u32,
+		payment_hash: Option<PaymentHash>,
 	) -> Result<Bolt11Invoice, Error> {
 		let lsps2_client = self.lsps2_client.as_ref().ok_or(Error::LiquiditySourceUnavailable)?;
 
 		// LSPS2 requires min_final_cltv_expiry_delta to be at least 2 more than usual.
 		let min_final_cltv_expiry_delta = MIN_FINAL_CLTV_EXPIRY_DELTA + 2;
-		let (payment_hash, payment_secret) = self
-			.channel_manager
-			.create_inbound_payment(None, expiry_secs, Some(min_final_cltv_expiry_delta))
-			.map_err(|e| {
-				log_error!(self.logger, "Failed to register inbound payment: {:?}", e);
-				Error::InvoiceCreationFailed
-			})?;
+		let (payment_hash, payment_secret) = match payment_hash {
+			Some(payment_hash) => {
+				let payment_secret = self
+					.channel_manager
+					.create_inbound_payment_for_hash(
+						payment_hash,
+						None,
+						expiry_secs,
+						Some(min_final_cltv_expiry_delta),
+					)
+					.map_err(|e| {
+						log_error!(self.logger, "Failed to register inbound payment: {:?}", e);
+						Error::InvoiceCreationFailed
+					})?;
+				(payment_hash, payment_secret)
+			},
+			None => self
+				.channel_manager
+				.create_inbound_payment(None, expiry_secs, Some(min_final_cltv_expiry_delta))
+				.map_err(|e| {
+					log_error!(self.logger, "Failed to register inbound payment: {:?}", e);
+					Error::InvoiceCreationFailed
+				})?,
+		};
 
 		let route_hint = RouteHint(vec![RouteHintHop {
 			src_node_id: lsps2_client.lsp_node_id,

src/payment/bolt11.rs

@@ -578,6 +578,44 @@ impl Bolt11Payment {
 			expiry_secs,
 			max_total_lsp_fee_limit_msat,
 			None,
+			None,
+		)?;
+		Ok(maybe_wrap(invoice))
+	}
+
+	/// Returns a payable invoice that can be used to request a payment of the amount given and
+	/// receive it via a newly created just-in-time (JIT) channel.
+	///
+	/// When the returned invoice is paid, the configured [LSPS2]-compliant LSP will open a channel
+	/// to us, supplying just-in-time inbound liquidity.
+	///
+	/// If set, `max_total_lsp_fee_limit_msat` will limit how much fee we allow the LSP to take for opening the
+	/// channel to us. We'll use its cheapest offer otherwise.
+	///
+	/// We will register the given payment hash and emit a [`PaymentClaimable`] event once
+	/// the inbound payment arrives.
+	///
+	/// **Note:** users *MUST* handle this event and claim the payment manually via
+	/// [`claim_for_hash`] as soon as they have obtained access to the preimage of the given
+	/// payment hash. If they're unable to obtain the preimage, they *MUST* immediately fail the payment via
+	/// [`fail_for_hash`].
+	///
+	/// [LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/blob/main/LSPS2/README.md
+	/// [`PaymentClaimable`]: crate::Event::PaymentClaimable
+	/// [`claim_for_hash`]: Self::claim_for_hash
+	/// [`fail_for_hash`]: Self::fail_for_hash
+	pub fn receive_via_jit_channel_for_hash(
+		&self, amount_msat: u64, description: &Bolt11InvoiceDescription, expiry_secs: u32,
+		max_total_lsp_fee_limit_msat: Option<u64>, payment_hash: PaymentHash,
+	) -> Result<Bolt11Invoice, Error> {
+		let description = maybe_try_convert_enum(description)?;
+		let invoice = self.receive_via_jit_channel_inner(
+			Some(amount_msat),
+			&description,
+			expiry_secs,
+			max_total_lsp_fee_limit_msat,
+			None,
+			Some(payment_hash),
 		)?;
 		Ok(maybe_wrap(invoice))
 	}
@@ -604,14 +642,15 @@ impl Bolt11Payment {
 			expiry_secs,
 			None,
 			max_proportional_lsp_fee_limit_ppm_msat,
+			None,
 		)?;
 		Ok(maybe_wrap(invoice))
 	}
 
 	fn receive_via_jit_channel_inner(
 		&self, amount_msat: Option<u64>, description: &LdkBolt11InvoiceDescription,
 		expiry_secs: u32, max_total_lsp_fee_limit_msat: Option<u64>,
-		max_proportional_lsp_fee_limit_ppm_msat: Option<u64>,
+		max_proportional_lsp_fee_limit_ppm_msat: Option<u64>, payment_hash: Option<PaymentHash>,
 	) -> Result<LdkBolt11Invoice, Error> {
 		let liquidity_source =
 			self.liquidity_source.as_ref().ok_or(Error::LiquiditySourceUnavailable)?;
@@ -649,6 +688,7 @@ impl Bolt11Payment {
 								description,
 								expiry_secs,
 								max_total_lsp_fee_limit_msat,
+								payment_hash,
 							)
 							.await
 							.map(|(invoice, total_fee)| (invoice, Some(total_fee), None))
@@ -658,6 +698,7 @@ impl Bolt11Payment {
 								description,
 								expiry_secs,
 								max_proportional_lsp_fee_limit_ppm_msat,
+								payment_hash,
 							)
 							.await
 							.map(|(invoice, prop_fee)| (invoice, None, Some(prop_fee)))