Add LSPS5 (bLIP-55) webhook notification support

Implement the bLIP-55 / LSPS5 webhook registration protocol on top of the
multi-LSP liquidity module (src/liquidity/{client,service}).

Client side, exposed via Node::liquidity().lsps5():
- set_webhook / list_webhooks / remove_webhook to manage webhook
  registrations with a given LSP. Each takes the LSP's node ID explicitly:
  bLIP-55 has the notification service verify the x-lsps5-signature header
  against the signing LSP's node ID, so a registration is meaningful only
  for one LSP at a time.

Service side, enabled by passing an LSPS5ServiceConfig to
Builder::enable_liquidity_provider():
- Deliver outgoing webhook notifications over HTTPS in response to
  LSPS5ServiceEvent::SendWebhookNotification.
- Send lsps5.payment_incoming when an inbound HTLC forward to a client
  fails because the client is offline (wired from LdkEvent::
  HTLCHandlingFailed with LocalHTLCFailureReason::PeerOffline).
- Send lsps5.onion_message_incoming when an intercepted onion message
  targets a client that is currently offline.
- Send lsps5.expiry_soon from a periodic task that scans channels for outbound
  HTLCs approaching their cltv_expiry, so a client that went offline holding an
  HTLC has a chance to come online and settle before it expires.

Adds integration tests covering webhook registration and the
payment_incoming trigger, and wires the feature through the UniFFI
bindings.

Author: Camillarhi

bindings/ldk_node.udl

@@ -206,6 +206,14 @@ enum NodeError {
 	"InvalidLnurl",
 	"ChainSourceNotSupported",
 	"InvalidPayerProof",
+	"LiquiditySetWebhookFailed",
+	"LiquidityRemoveWebhookFailed",
+	"LiquidityListWebhooksFailed",
+	"LiquidityNotifyWebhookFailed",
+	"LiquidityWebhookLimitExceeded",
+	"LiquidityWebhookNoPriorActivity",
+	"LiquidityWebhookAppNameNotFound",
+	"LiquidityWebhookInvalid"
 };
 
 typedef dictionary NodeStatus;

src/builder.rs

@@ -100,8 +100,8 @@ use crate::runtime::{Runtime, RuntimeSpawner};
 use crate::tx_broadcaster::TransactionBroadcaster;
 use crate::types::{
 	AsyncPersister, ChainMonitor, ChannelManager, DynStore, DynStoreRef, DynStoreWrapper,
-	GossipSync, Graph, KeysManager, MessageRouter, OnionMessenger, PaymentStore, PeerManager,
-	PendingPaymentStore,
+	GossipSync, Graph, KeysManager, LSPS5ServiceConfig, MessageRouter, OnionMessenger,
+	PaymentStore, PeerManager, PendingPaymentStore,
 };
 use crate::wallet::persist::{read_address_pool, KVStoreWalletPersister};
 use crate::wallet::Wallet;
@@ -144,10 +144,12 @@ struct PathfindingScoresSyncConfig {
 
 #[derive(Debug, Clone, Default)]
 struct LiquiditySourceConfig {
-	// Acts for both LSPS1 and LSPS2 clients connecting to the given service.
+	// Acts for LSPS1, LSPS2 and LSPS5 clients connecting to the given service.
 	lsp_nodes: Vec<LspConfig>,
 	// Act as an LSPS2 service.
 	lsps2_service: Option<LSPS2ServiceConfig>,
+	// Act as an LSPS5 service.
+	lsps5_service: Option<LSPS5ServiceConfig>,
 }
 
 #[derive(Clone)]
@@ -532,18 +534,26 @@ impl NodeBuilder {
 		self
 	}
 
-	/// Configures the [`Node`] instance to provide an [LSPS2] service, issuing just-in-time
-	/// channels to clients.
+	/// Configures the [`Node`] instance to provide [bLIP-52 / LSPS2] and/or [bLIP-55 / LSPS5]
+	/// services to clients.
+	///
+	/// [bLIP-52 / LSPS2] issues just-in-time channels to clients, [bLIP-55 / LSPS5] allows clients
+	/// to register webhooks for push notifications.
+	///
+	/// Passing `None` leaves the respective service disabled.
 	///
 	/// **Caution**: LSP service support is in **alpha** and is considered an experimental feature.
 	///
-	/// [LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/blob/main/LSPS2/README.md
+	/// [bLIP-52 / LSPS2]: https://github.com/lightning/blips/blob/master/blip-0052.md
+	/// [bLIP-55 / LSPS5]: https://github.com/lightning/blips/blob/master/blip-0055.md
 	pub fn enable_liquidity_provider(
-		&mut self, lsps2_service_config: LSPS2ServiceConfig,
+		&mut self, lsps2_service_config: Option<LSPS2ServiceConfig>,
+		lsps5_service_config: Option<LSPS5ServiceConfig>,
 	) -> &mut Self {
 		let liquidity_source_config =
 			self.liquidity_source_config.get_or_insert(LiquiditySourceConfig::default());
-		liquidity_source_config.lsps2_service = Some(lsps2_service_config);
+		liquidity_source_config.lsps2_service = lsps2_service_config;
+		liquidity_source_config.lsps5_service = lsps5_service_config;
 		self
 	}
 
@@ -1171,14 +1181,26 @@ impl Builder {
 
 #[cfg(feature = "uniffi")]
 impl ArcedNodeBuilder {
-	/// Configures the [`Node`] instance to provide an [LSPS2] service, issuing just-in-time
-	/// channels to clients.
+	/// Configures the [`Node`] instance to provide [bLIP-52 / LSPS2] and/or [bLIP-55 / LSPS5]
+	/// services to clients.
+	///
+	/// [bLIP-52 / LSPS2] issues just-in-time channels to clients, [bLIP-55 / LSPS5] allows clients
+	/// to register webhooks for push notifications.
+	///
+	/// Passing `None` leaves the respective service disabled.
 	///
 	/// **Caution**: LSP service support is in **alpha** and is considered an experimental feature.
 	///
-	/// [LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/blob/main/LSPS2/README.md
-	pub fn enable_liquidity_provider(&self, lsps2_service_config: LSPS2ServiceConfig) {
-		self.inner.write().expect("lock").enable_liquidity_provider(lsps2_service_config);
+	/// [bLIP-52 / LSPS2]: https://github.com/lightning/blips/blob/master/blip-0052.md
+	/// [bLIP-55 / LSPS5]: https://github.com/lightning/blips/blob/master/blip-0055.md
+	pub fn enable_liquidity_provider(
+		&self, lsps2_service_config: Option<LSPS2ServiceConfig>,
+		lsps5_service_config: Option<LSPS5ServiceConfig>,
+	) {
+		self.inner
+			.write()
+			.expect("lock")
+			.enable_liquidity_provider(lsps2_service_config, lsps5_service_config);
 	}
 }
 
@@ -2256,6 +2278,7 @@ fn build_with_store_internal(
 			Arc::clone(&tx_broadcaster),
 			Arc::clone(&kv_store),
 			Arc::clone(&config),
+			Arc::clone(&runtime),
 			Arc::clone(&logger),
 		);
 
@@ -2274,6 +2297,10 @@ fn build_with_store_internal(
 			lsc.lsps2_service.as_ref().map(|config| {
 				liquidity_source_builder.lsps2_service(promise_secret, config.clone())
 			});
+
+			lsc.lsps5_service
+				.as_ref()
+				.map(|config| liquidity_source_builder.lsps5_service(config.clone()));
 		}
 
 		let liquidity_source = runtime
@@ -2334,6 +2361,8 @@ fn build_with_store_internal(
 
 	liquidity_source.lsps2_service().set_peer_manager(Arc::downgrade(&peer_manager));
 
+	liquidity_source.lsps5_service().set_peer_manager(Arc::downgrade(&peer_manager));
+
 	let connection_manager = Arc::new(ConnectionManager::new(
 		Arc::clone(&peer_manager),
 		config.tor_config.clone(),

src/config.rs

@@ -14,6 +14,7 @@ use std::time::Duration;
 
 use bitcoin::secp256k1::PublicKey;
 use bitcoin::Network;
+use lightning::chain::channelmonitor::HTLC_FAIL_BACK_BUFFER;
 use lightning::ln::msgs::SocketAddress;
 use lightning::routing::gossip::NodeAlias;
 use lightning::routing::router::RouteParametersConfig;
@@ -169,6 +170,28 @@ pub(crate) const LIQUIDITY_DISCOVERY_RETRY_INITIAL_DELAY: Duration = Duration::f
 // thereafter until every configured LSP has been discovered.
 pub(crate) const LIQUIDITY_DISCOVERY_RETRY_MAX_DELAY: Duration = Duration::from_secs(60 * 60);
 
+// The timeout after which we abort a LSPS5 webhook notification operation.
+pub(crate) const LSPS5_WEBHOOK_TIMEOUT_SECS: u64 = 30;
+
+// The maximum size of a response body we'll accept when delivering an LSPS5 webhook notification.
+pub(crate) const LSPS5_WEBHOOK_MAX_RESPONSE_SIZE: usize = 64 * 1024;
+
+// The time in-between checks for HTLCs approaching expiry on LSPS5 clients' channels.
+pub(crate) const LSPS5_EXPIRY_CHECK_INTERVAL: Duration = Duration::from_secs(60);
+
+// The number of blocks we wait before notifying a client about the same expiring HTLCs again.
+pub(crate) const LSPS5_EXPIRY_RENOTIFY_INTERVAL_BLOCKS: u32 = 6;
+
+// The number of blocks before an outbound HTLC's expiry at which we start notifying offline
+// LSPS5 clients.
+//
+// A client that doesn't come online and settle before `cltv_expiry` loses the payment, and LDK
+// force-closes the channel shortly after (`cltv_expiry + LATENCY_GRACE_PERIOD_BLOCKS`). We anchor
+// the lead time on `HTLC_FAIL_BACK_BUFFER`, the margin LDK itself treats as too close to expiry to
+// safely handle an HTLC, and double it to leave the client room to receive the notification and
+// act on it.
+pub(crate) const LSPS5_EXPIRY_NOTIFICATION_THRESHOLD_BLOCKS: u32 = HTLC_FAIL_BACK_BUFFER * 2;
+
 #[derive(Debug, Clone)]
 #[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
 /// Represents the configuration of an [`Node`] instance.

src/error.rs

@@ -147,6 +147,29 @@ pub enum Error {
 	ChainSourceNotSupported,
 	/// The provided payer proof is invalid.
 	InvalidPayerProof,
+	/// Failed to set a webhook with the LSP.
+	LiquiditySetWebhookFailed,
+	/// Failed to remove a webhook with the LSP.
+	LiquidityRemoveWebhookFailed,
+	/// Failed to list webhooks with the LSP.
+	LiquidityListWebhooksFailed,
+	/// Failed to send a webhook notification to a client.
+	LiquidityNotifyWebhookFailed,
+	/// The LSP rejected a webhook registration because the client has reached the maximum number
+	/// of webhooks the LSP allows.
+	LiquidityWebhookLimitExceeded,
+	/// The LSP rejected a webhook registration because we have no prior activity with it.
+	///
+	/// LSPs typically require an open channel, or an in-flight LSPS1 or LSPS2 flow, before
+	/// accepting webhook registrations.
+	LiquidityWebhookNoPriorActivity,
+	/// No webhook is registered under the given `app_name` with the LSP.
+	LiquidityWebhookAppNameNotFound,
+	/// The `app_name` or webhook URL is invalid.
+	///
+	/// The `app_name` may exceed 64 bytes, or the URL may exceed 1024 bytes, fail to parse, or
+	/// not use the `https` scheme.
+	LiquidityWebhookInvalid,
 }
 
 impl fmt::Display for Error {
@@ -239,6 +262,33 @@ impl fmt::Display for Error {
 				write!(f, "The configured chain source is not supported.")
 			},
 			Self::InvalidPayerProof => write!(f, "The provided payer proof is invalid."),
+			Self::LiquiditySetWebhookFailed => {
+				write!(f, "Failed to set a webhook with the LSP.")
+			},
+			Self::LiquidityRemoveWebhookFailed => {
+				write!(f, "Failed to remove a webhook with the LSP.")
+			},
+			Self::LiquidityListWebhooksFailed => {
+				write!(f, "Failed to list webhooks with the LSP.")
+			},
+			Self::LiquidityNotifyWebhookFailed => {
+				write!(f, "Failed to send a webhook notification to a client.")
+			},
+			Self::LiquidityWebhookLimitExceeded => {
+				write!(
+					f,
+					"The LSP's maximum number of webhooks for this client is already reached."
+				)
+			},
+			Self::LiquidityWebhookNoPriorActivity => {
+				write!(f, "The LSP rejected the webhook registration due to no prior activity.")
+			},
+			Self::LiquidityWebhookAppNameNotFound => {
+				write!(f, "No webhook is registered under the given app name with this LSP.")
+			},
+			Self::LiquidityWebhookInvalid => {
+				write!(f, "The given app name or webhook URL is invalid.")
+			},
 		}
 	}
 }

src/event.rs

@@ -19,10 +19,12 @@ use lightning::events::bump_transaction::BumpTransactionEvent;
 #[cfg(not(feature = "uniffi"))]
 use lightning::events::PaidBolt12Invoice;
 use lightning::events::{
-	ClosureReason, Event as LdkEvent, FundingInfo, HTLCLocator as LdkHtlcLocator,
-	PaymentFailureReason, PaymentPurpose, ReplayEvent,
+	ClosureReason, Event as LdkEvent, FundingInfo, HTLCHandlingFailureReason,
+	HTLCHandlingFailureType, HTLCLocator as LdkHtlcLocator, PaymentFailureReason, PaymentPurpose,
+	ReplayEvent,
 };
 use lightning::ln::channelmanager::{PaymentId, TrustedChannelFeatures};
+use lightning::ln::onion_utils::LocalHTLCFailureReason;
 use lightning::ln::types::ChannelId;
 use lightning::routing::gossip::NodeId;
 use lightning::sign::EntropySource;
@@ -1499,11 +1501,29 @@ where
 					prober.handle_background_probe_failed(&path, payment_id);
 				}
 			},
-			LdkEvent::HTLCHandlingFailed { failure_type, .. } => {
+			LdkEvent::HTLCHandlingFailed { failure_type, failure_reason, .. } => {
+				// Capture the client's node id before `failure_type` is consumed below. A forward
+				// that failed only because the next-hop peer was offline is our cue to wake an
+				// LSPS5 client. The HTLC is failed back as `temporary_channel_failure`, which is
+				// not permanent, so the sender can retry once the client is online.
+				let offline_node_id = match (&failure_type, &failure_reason) {
+					(
+						HTLCHandlingFailureType::Forward { node_id: Some(node_id), .. },
+						Some(HTLCHandlingFailureReason::Local {
+							reason: LocalHTLCFailureReason::PeerOffline,
+						}),
+					) => Some(*node_id),
+					_ => None,
+				};
+
 				self.liquidity_source
 					.lsps2_service()
 					.handle_htlc_handling_failed(failure_type)
 					.await;
+
+				if let Some(node_id) = offline_node_id {
+					self.liquidity_source.lsps5_service().notify_payment_incoming(node_id);
+				}
 			},
 			LdkEvent::SpendableOutputs { outputs, channel_id, counterparty_node_id } => {
 				match self
@@ -1987,6 +2007,8 @@ where
 				debug_assert!(false, "We currently don't handle BOLT12 invoices manually, so this event should never be emitted.");
 			},
 			LdkEvent::ConnectionNeeded { node_id, addresses } => {
+				self.liquidity_source.lsps5_service().notify_onion_message_incoming(node_id);
+
 				let spawn_logger = self.logger.clone();
 				let spawn_cm = Arc::clone(&self.connection_manager);
 				let future = async move {
@@ -2045,6 +2067,9 @@ where
 							"Onion message intercepted, but no onion message mailbox available"
 						);
 					}
+					self.liquidity_source
+						.lsps5_service()
+						.notify_onion_message_incoming(peer_node_id);
 				} else {
 					log_error!(self.logger, "Onion message intercepted for unknown SCID");
 				}

src/lib.rs

@@ -197,7 +197,10 @@ pub use types::{
 #[cfg(feature = "storage-vss")]
 pub use vss_client;
 
-use crate::config::{LIQUIDITY_DISCOVERY_RETRY_INITIAL_DELAY, LIQUIDITY_DISCOVERY_RETRY_MAX_DELAY};
+use crate::config::{
+	LIQUIDITY_DISCOVERY_RETRY_INITIAL_DELAY, LIQUIDITY_DISCOVERY_RETRY_MAX_DELAY,
+	LSPS5_EXPIRY_CHECK_INTERVAL,
+};
 use crate::ffi::{maybe_deref, maybe_wrap};
 use crate::liquidity::Liquidity;
 use crate::scoring::setup_background_pathfinding_scores_sync;
@@ -836,6 +839,28 @@ impl Node {
 			}
 		});
 
+		// Regularly notify offline LSPS5 clients about HTLCs approaching their expiry.
+		if self.liquidity_source.liquidity_manager().lsps5_service_handler().is_some() {
+			let expiry_liquidity_source = Arc::clone(&self.liquidity_source);
+			let expiry_liquidy_logger = Arc::clone(&self.logger);
+			let mut stop_expiry = self.stop_sender.subscribe();
+			self.runtime.spawn_cancellable_background_task(async move {
+				let mut interval = tokio::time::interval(LSPS5_EXPIRY_CHECK_INTERVAL);
+				interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
+				loop {
+					tokio::select! {
+							_ = stop_expiry.changed() => {
+									log_debug!(expiry_liquidy_logger, "Stopping LSPS5 HTLC expiry checks.");
+									return;
+							}
+							_ = interval.tick() => {
+									expiry_liquidity_source.lsps5_service().check_expiring_htlcs();
+							}
+					}
+				}
+			});
+		}
+
 		log_info!(self.logger, "Startup complete.");
 		*is_running_lock = true;
 		Ok(())