Implement LSPS2 invoice creation flow

Author: tnull

bindings/ldk_node.udl

@@ -87,6 +87,8 @@ interface LDKNode {
 	Bolt11Invoice receive_payment(u64 amount_msat, [ByRef]string description, u32 expiry_secs);
 	[Throws=NodeError]
 	Bolt11Invoice receive_variable_amount_payment([ByRef]string description, u32 expiry_secs);
+	[Throws=NodeError]
+	Bolt11Invoice receive_payment_via_jit_channel(u64 amount_msat, [ByRef]string description, u32 expiry_secs, u64? max_lsp_fee_limit_msat);
 	PaymentDetails? payment([ByRef]PaymentHash payment_hash);
 	[Throws=NodeError]
 	void remove_payment([ByRef]PaymentHash payment_hash);
@@ -118,6 +120,7 @@ enum NodeError {
 	"MessageSigningFailed",
 	"TxSyncFailed",
 	"GossipUpdateFailed",
+	"LiquidityRequestFailed",
 	"InvalidAddress",
 	"InvalidSocketAddress",
 	"InvalidPublicKey",
@@ -132,6 +135,7 @@ enum NodeError {
 	"DuplicatePayment",
 	"InsufficientFunds",
 	"LiquiditySourceUnavailable",
+	"LiquidityFeeTooHigh",
 };
 
 [Error]
@@ -170,12 +174,8 @@ enum PaymentStatus {
 	"Failed",
 };
 
-[NonExhaustive]
-enum Network {
-	"Bitcoin",
-	"Testnet",
-	"Signet",
-	"Regtest",
+dictionary LSPFeeLimits {
+	u64? max_total_opening_fee_msat;
 };
 
 dictionary PaymentDetails {
@@ -185,6 +185,15 @@ dictionary PaymentDetails {
 	u64? amount_msat;
 	PaymentDirection direction;
 	PaymentStatus status;
+	LSPFeeLimits? lsp_fee_limits;
+};
+
+[NonExhaustive]
+enum Network {
+	"Bitcoin",
+	"Testnet",
+	"Signet",
+	"Regtest",
 };
 
 dictionary OutPoint {

src/builder.rs

@@ -694,6 +694,12 @@ fn build_with_store_internal<K: KVStore + Sync + Send + 'static>(
 		// generating the events otherwise.
 		user_config.manually_accept_inbound_channels = true;
 	}
+
+	if liquidity_source_config.is_some() {
+		// Generally allow claiming underpaying HTLCs as the LSP will skim off some fee. We'll
+		// check that they don't take too much before claiming.
+		user_config.channel_config.accept_underpaying_htlcs = true;
+	}
 	let channel_manager = {
 		if let Ok(res) = kv_store.read(
 			CHANNEL_MANAGER_PERSISTENCE_PRIMARY_NAMESPACE,

src/error.rs

@@ -37,6 +37,8 @@ pub enum Error {
 	TxSyncFailed,
 	/// A gossip updating operation failed.
 	GossipUpdateFailed,
+	/// A liquidity request operation failed.
+	LiquidityRequestFailed,
 	/// The given address is invalid.
 	InvalidAddress,
 	/// The given network address is invalid.
@@ -65,6 +67,8 @@ pub enum Error {
 	InsufficientFunds,
 	/// The given operation failed due to the required liquidity source being unavailable.
 	LiquiditySourceUnavailable,
+	/// The given operation failed due to the LSP's required opening fee being too high.
+	LiquidityFeeTooHigh,
 }
 
 impl fmt::Display for Error {
@@ -91,6 +95,7 @@ impl fmt::Display for Error {
 			Self::MessageSigningFailed => write!(f, "Failed to sign given message."),
 			Self::TxSyncFailed => write!(f, "Failed to sync transactions."),
 			Self::GossipUpdateFailed => write!(f, "Failed to update gossip data."),
+			Self::LiquidityRequestFailed => write!(f, "Failed to request inbound liquidity."),
 			Self::InvalidAddress => write!(f, "The given address is invalid."),
 			Self::InvalidSocketAddress => write!(f, "The given network address is invalid."),
 			Self::InvalidPublicKey => write!(f, "The given public key is invalid."),
@@ -111,6 +116,9 @@ impl fmt::Display for Error {
 			Self::LiquiditySourceUnavailable => {
 				write!(f, "The given operation failed due to the required liquidity source being unavailable.")
 			}
+			Self::LiquidityFeeTooHigh => {
+				write!(f, "The given operation failed due to the LSP's required opening fee being too high.")
+			}
 		}
 	}
 }

src/event.rs

@@ -395,7 +395,7 @@ where
 				via_user_channel_id: _,
 				claim_deadline: _,
 				onion_fields: _,
-				counterparty_skimmed_fee_msat: _,
+				counterparty_skimmed_fee_msat,
 			} => {
 				if let Some(info) = self.payment_store.get(&payment_hash) {
 					if info.status == PaymentStatus::Succeeded {
@@ -417,6 +417,29 @@ where
 						});
 						return;
 					}
+
+					let max_total_opening_fee_msat =
+						info.lsp_fee_limits.and_then(|l| l.max_total_opening_fee_msat).unwrap_or(0);
+					if counterparty_skimmed_fee_msat > max_total_opening_fee_msat {
+						log_info!(
+							self.logger,
+							"Refusing inbound payment with hash {} as the counterparty-withheld fee of {}msat exceeds our limit of {}msat",
+							hex_utils::to_string(&payment_hash.0),
+							counterparty_skimmed_fee_msat,
+							max_total_opening_fee_msat,
+						);
+						self.channel_manager.fail_htlc_backwards(&payment_hash);
+
+						let update = PaymentDetailsUpdate {
+							status: Some(PaymentStatus::Failed),
+							..PaymentDetailsUpdate::new(payment_hash)
+						};
+						self.payment_store.update(&update).unwrap_or_else(|e| {
+							log_error!(self.logger, "Failed to access payment store: {}", e);
+							panic!("Failed to access payment store");
+						});
+						return;
+					}
 				}
 
 				log_info!(
@@ -510,6 +533,7 @@ where
 							amount_msat: Some(amount_msat),
 							direction: PaymentDirection::Inbound,
 							status: PaymentStatus::Succeeded,
+							lsp_fee_limits: None,
 						};
 
 						match self.payment_store.insert(payment) {

src/lib.rs

@@ -120,7 +120,7 @@ use event::{EventHandler, EventQueue};
 use gossip::GossipSource;
 use liquidity::LiquiditySource;
 use payment_store::PaymentStore;
-pub use payment_store::{PaymentDetails, PaymentDirection, PaymentStatus};
+pub use payment_store::{LSPFeeLimits, PaymentDetails, PaymentDirection, PaymentStatus};
 use peer_store::{PeerInfo, PeerStore};
 use types::{
 	Broadcaster, ChainMonitor, ChannelManager, FeeEstimator, KeysManager, NetworkGraph,
@@ -1217,6 +1217,7 @@ impl<K: KVStore + Sync + Send + 'static> Node<K> {
 					amount_msat: invoice.amount_milli_satoshis(),
 					direction: PaymentDirection::Outbound,
 					status: PaymentStatus::Pending,
+					lsp_fee_limits: None,
 				};
 				self.payment_store.insert(payment)?;
 
@@ -1236,6 +1237,7 @@ impl<K: KVStore + Sync + Send + 'static> Node<K> {
 							amount_msat: invoice.amount_milli_satoshis(),
 							direction: PaymentDirection::Outbound,
 							status: PaymentStatus::Failed,
+							lsp_fee_limits: None,
 						};
 
 						self.payment_store.insert(payment)?;
@@ -1323,6 +1325,7 @@ impl<K: KVStore + Sync + Send + 'static> Node<K> {
 					amount_msat: Some(amount_msat),
 					direction: PaymentDirection::Outbound,
 					status: PaymentStatus::Pending,
+					lsp_fee_limits: None,
 				};
 				self.payment_store.insert(payment)?;
 
@@ -1343,6 +1346,7 @@ impl<K: KVStore + Sync + Send + 'static> Node<K> {
 							amount_msat: Some(amount_msat),
 							direction: PaymentDirection::Outbound,
 							status: PaymentStatus::Failed,
+							lsp_fee_limits: None,
 						};
 						self.payment_store.insert(payment)?;
 
@@ -1397,6 +1401,7 @@ impl<K: KVStore + Sync + Send + 'static> Node<K> {
 					status: PaymentStatus::Pending,
 					direction: PaymentDirection::Outbound,
 					amount_msat: Some(amount_msat),
+					lsp_fee_limits: None,
 				};
 				self.payment_store.insert(payment)?;
 
@@ -1417,6 +1422,7 @@ impl<K: KVStore + Sync + Send + 'static> Node<K> {
 							status: PaymentStatus::Failed,
 							direction: PaymentDirection::Outbound,
 							amount_msat: Some(amount_msat),
+							lsp_fee_limits: None,
 						};
 
 						self.payment_store.insert(payment)?;
@@ -1590,13 +1596,109 @@ impl<K: KVStore + Sync + Send + 'static> Node<K> {
 			amount_msat,
 			direction: PaymentDirection::Inbound,
 			status: PaymentStatus::Pending,
+			lsp_fee_limits: None,
 		};
 
 		self.payment_store.insert(payment)?;
 
 		Ok(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.
+	///
+	/// [LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/blob/main/LSPS2/README.md
+	pub fn receive_payment_via_jit_channel(
+		&self, amount_msat: u64, description: &str, expiry_secs: u32,
+		max_total_lsp_fee_limit_msat: Option<u64>,
+	) -> Result<Bolt11Invoice, Error> {
+		self.receive_payment_via_jit_channel_inner(
+			Some(amount_msat),
+			description,
+			expiry_secs,
+			max_total_lsp_fee_limit_msat,
+		)
+	}
+
+	fn receive_payment_via_jit_channel_inner(
+		&self, amount_msat: Option<u64>, description: &str, expiry_secs: u32,
+		max_total_lsp_fee_limit_msat: Option<u64>,
+	) -> Result<Bolt11Invoice, Error> {
+		let liquidity_source =
+			self.liquidity_source.as_ref().ok_or(Error::LiquiditySourceUnavailable)?;
+
+		let (node_id, address) = liquidity_source
+			.get_liquidity_source_details()
+			.ok_or(Error::LiquiditySourceUnavailable)?;
+
+		let rt_lock = self.runtime.read().unwrap();
+		let runtime = rt_lock.as_ref().unwrap();
+
+		let peer_info = PeerInfo { node_id, address };
+
+		let con_node_id = peer_info.node_id;
+		let con_addr = peer_info.address.clone();
+		let con_logger = Arc::clone(&self.logger);
+		let con_pm = Arc::clone(&self.peer_manager);
+
+		// We need to use our main runtime here as a local runtime might not be around to poll
+		// connection futures going forward.
+		tokio::task::block_in_place(move || {
+			runtime.block_on(async move {
+				connect_peer_if_necessary(con_node_id, con_addr, con_pm, con_logger).await
+			})
+		})?;
+
+		log_info!(self.logger, "Connected to LSP {}@{}. ", peer_info.node_id, peer_info.address);
+
+		let liquidity_source = Arc::clone(&liquidity_source);
+		let (invoice, lsp_total_opening_fee) = tokio::task::block_in_place(move || {
+			runtime.block_on(async move {
+				if let Some(amount_msat) = amount_msat {
+					liquidity_source
+						.lsps2_receive_to_jit_channel(
+							amount_msat,
+							description,
+							expiry_secs,
+							max_total_lsp_fee_limit_msat,
+						)
+						.await
+						.map(|(invoice, total_fee)| (invoice, Some(total_fee)))
+				} else {
+					// TODO: will be implemented in the next commit
+					Err(Error::LiquidityRequestFailed)
+				}
+			})
+		})?;
+
+		// Register payment in payment store.
+		let payment_hash = PaymentHash(invoice.payment_hash().to_byte_array());
+		let lsp_fee_limits =
+			Some(LSPFeeLimits { max_total_opening_fee_msat: lsp_total_opening_fee });
+		let payment = PaymentDetails {
+			hash: payment_hash,
+			preimage: None,
+			secret: Some(invoice.payment_secret().clone()),
+			amount_msat,
+			direction: PaymentDirection::Inbound,
+			status: PaymentStatus::Pending,
+			lsp_fee_limits,
+		};
+
+		self.payment_store.insert(payment)?;
+
+		// Persist LSP peer to make sure we reconnect on restart.
+		self.peer_store.add_peer(peer_info)?;
+
+		Ok(invoice)
+	}
+
 	/// Retrieve the details of a specific payment with the given hash.
 	///
 	/// Returns `Some` if the payment was known and `None` otherwise.