add webhook message support in serializer, events, and liquidity manager

- Update events.rs to include LSPS5 client and service event variants and From conversions.
- Enhance lib.rs documentation to reference bLIP-55 / LSPS5 protocol support.
- Modify manager.rs to initialize and route LSPS5 client and service handlers in LiquidityService.
- Extend lsps0/ser.rs to support LSPS5 methods in LSPSMethod and LSPSMessage (de)serialization for SetWebhook, ListWebhooks, and RemoveWebhook.
- Extend the match in TryFrom<LSPSMessage> to handle LSPSMessage::LSPS5 and explicitly return an error.

Author: martinsaposnic

lightning-liquidity/src/events.rs

@@ -18,6 +18,7 @@
 use crate::lsps0;
 use crate::lsps1;
 use crate::lsps2;
+use crate::lsps5;
 use crate::prelude::{Vec, VecDeque};
 use crate::sync::{Arc, Mutex};
 
@@ -116,6 +117,10 @@ pub enum LiquidityEvent {
 	LSPS2Client(lsps2::event::LSPS2ClientEvent),
 	/// An LSPS2 (JIT Channel) server event.
 	LSPS2Service(lsps2::event::LSPS2ServiceEvent),
+	/// An LSPS5 (Webhook) client event.
+	LSPS5Client(lsps5::event::LSPS5ClientEvent),
+	/// An LSPS5 (Webhook) server event.
+	LSPS5Service(lsps5::event::LSPS5ServiceEvent),
 }
 
 impl From<lsps0::event::LSPS0ClientEvent> for LiquidityEvent {
@@ -149,6 +154,18 @@ impl From<lsps2::event::LSPS2ServiceEvent> for LiquidityEvent {
 	}
 }
 
+impl From<lsps5::event::LSPS5ClientEvent> for LiquidityEvent {
+	fn from(event: lsps5::event::LSPS5ClientEvent) -> Self {
+		Self::LSPS5Client(event)
+	}
+}
+
+impl From<lsps5::event::LSPS5ServiceEvent> for LiquidityEvent {
+	fn from(event: lsps5::event::LSPS5ServiceEvent) -> Self {
+		Self::LSPS5Service(event)
+	}
+}
+
 struct EventFuture {
 	event_queue: Arc<Mutex<VecDeque<LiquidityEvent>>>,
 	waker: Arc<Mutex<Option<Waker>>>,

lightning-liquidity/src/lib.rs

@@ -23,6 +23,8 @@
 //! an LSP will open a "just-in-time" channel. This is useful for the initial on-boarding of
 //! clients as the channel opening fees are deducted from the incoming payment, i.e., no funds are
 //! required client-side to initiate this flow.
+//! - [bLIP-55 / LSPS5] defines a protocol for sending webhook notifications to clients. This is
+//! useful for notifying clients about incoming payments, channel expiries, etc.
 //!
 //! To get started, you'll want to setup a [`LiquidityManager`] and configure it to be the
 //! [`CustomMessageHandler`] of your LDK node. You can then for example call
@@ -37,6 +39,7 @@
 //! [bLIP-50 / LSPS0]: https://github.com/lightning/blips/blob/master/blip-0050.md
 //! [bLIP-51 / LSPS1]: https://github.com/lightning/blips/blob/master/blip-0051.md
 //! [bLIP-52 / LSPS2]: https://github.com/lightning/blips/blob/master/blip-0052.md
+//! [bLIP-55 / LSPS5]: https://github.com/lightning/blips/pull/55/files
 //! [`CustomMessageHandler`]: lightning::ln::peer_handler::CustomMessageHandler
 //! [`LiquidityManager::next_event`]: crate::LiquidityManager::next_event
 #![deny(missing_docs)]
@@ -65,6 +68,7 @@ pub mod events;
 pub mod lsps0;
 pub mod lsps1;
 pub mod lsps2;
+pub mod lsps5;
 mod manager;
 pub mod message_queue;
 #[allow(dead_code)]

lightning-liquidity/src/lsps0/msgs.rs

@@ -83,6 +83,7 @@ impl TryFrom<LSPSMessage> for LSPS0Message {
 			LSPSMessage::LSPS0(message) => Ok(message),
 			LSPSMessage::LSPS1(_) => Err(()),
 			LSPSMessage::LSPS2(_) => Err(()),
+			LSPSMessage::LSPS5(_) => Err(()),
 		}
 	}
 }

lightning-liquidity/src/lsps0/ser.rs

@@ -16,6 +16,10 @@ use crate::lsps1::msgs::{
 use crate::lsps2::msgs::{
 	LSPS2Message, LSPS2Request, LSPS2Response, LSPS2_BUY_METHOD_NAME, LSPS2_GET_INFO_METHOD_NAME,
 };
+use crate::lsps5::msgs::{
+	LSPS5Message, LSPS5Request, LSPS5Response, LSPS5_LIST_WEBHOOKS_METHOD_NAME,
+	LSPS5_REMOVE_WEBHOOK_METHOD_NAME, LSPS5_SET_WEBHOOK_METHOD_NAME,
+};
 use crate::prelude::{HashMap, String};
 
 use lightning::ln::msgs::LightningError;
@@ -55,6 +59,9 @@ pub(crate) enum LSPSMethod {
 	LSPS1CreateOrder,
 	LSPS2GetInfo,
 	LSPS2Buy,
+	LSPS5SetWebhook,
+	LSPS5ListWebhooks,
+	LSPS5RemoveWebhook,
 }
 
 impl LSPSMethod {
@@ -66,6 +73,9 @@ impl LSPSMethod {
 			Self::LSPS1GetOrder => LSPS1_GET_ORDER_METHOD_NAME,
 			Self::LSPS2GetInfo => LSPS2_GET_INFO_METHOD_NAME,
 			Self::LSPS2Buy => LSPS2_BUY_METHOD_NAME,
+			Self::LSPS5SetWebhook => LSPS5_SET_WEBHOOK_METHOD_NAME,
+			Self::LSPS5ListWebhooks => LSPS5_LIST_WEBHOOKS_METHOD_NAME,
+			Self::LSPS5RemoveWebhook => LSPS5_REMOVE_WEBHOOK_METHOD_NAME,
 		}
 	}
 }
@@ -80,6 +90,10 @@ impl FromStr for LSPSMethod {
 			LSPS1_GET_ORDER_METHOD_NAME => Ok(Self::LSPS1GetOrder),
 			LSPS2_GET_INFO_METHOD_NAME => Ok(Self::LSPS2GetInfo),
 			LSPS2_BUY_METHOD_NAME => Ok(Self::LSPS2Buy),
+			// Add LSPS5 methods
+			LSPS5_SET_WEBHOOK_METHOD_NAME => Ok(Self::LSPS5SetWebhook),
+			LSPS5_LIST_WEBHOOKS_METHOD_NAME => Ok(Self::LSPS5ListWebhooks),
+			LSPS5_REMOVE_WEBHOOK_METHOD_NAME => Ok(Self::LSPS5RemoveWebhook),
 			_ => Err(&"Unknown method name"),
 		}
 	}
@@ -112,6 +126,17 @@ impl From<&LSPS2Request> for LSPSMethod {
 	}
 }
 
+// Add implementation for LSPS5Request
+impl From<&LSPS5Request> for LSPSMethod {
+	fn from(value: &LSPS5Request) -> Self {
+		match value {
+			LSPS5Request::SetWebhook(_) => Self::LSPS5SetWebhook,
+			LSPS5Request::ListWebhooks(_) => Self::LSPS5ListWebhooks,
+			LSPS5Request::RemoveWebhook(_) => Self::LSPS5RemoveWebhook,
+		}
+	}
+}
+
 impl<'de> Deserialize<'de> for LSPSMethod {
 	fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
 	where
@@ -269,6 +294,8 @@ pub enum LSPSMessage {
 	LSPS1(LSPS1Message),
 	/// An LSPS2 message.
 	LSPS2(LSPS2Message),
+	/// An LSPS5 message.
+	LSPS5(LSPS5Message),
 }
 
 impl LSPSMessage {
@@ -296,6 +323,10 @@ impl LSPSMessage {
 			LSPSMessage::LSPS2(LSPS2Message::Request(request_id, request)) => {
 				Some((LSPSRequestId(request_id.0.clone()), request.into()))
 			},
+			// Add LSPS5
+			LSPSMessage::LSPS5(LSPS5Message::Request(request_id, request)) => {
+				Some((LSPSRequestId(request_id.0.clone()), request.into()))
+			},
 			_ => None,
 		}
 	}
@@ -412,6 +443,47 @@ impl Serialize for LSPSMessage {
 				jsonrpc_object.serialize_field(JSONRPC_ID_FIELD_KEY, &serde_json::Value::Null)?;
 				jsonrpc_object.serialize_field(JSONRPC_ERROR_FIELD_KEY, &error)?;
 			},
+			LSPSMessage::LSPS5(LSPS5Message::Request(request_id, request)) => {
+				jsonrpc_object.serialize_field(JSONRPC_ID_FIELD_KEY, &request_id.0)?;
+				jsonrpc_object
+					.serialize_field(JSONRPC_METHOD_FIELD_KEY, &LSPSMethod::from(request))?;
+
+				match request {
+					LSPS5Request::SetWebhook(params) => {
+						jsonrpc_object.serialize_field(JSONRPC_PARAMS_FIELD_KEY, params)?
+					},
+					LSPS5Request::ListWebhooks(params) => {
+						jsonrpc_object.serialize_field(JSONRPC_PARAMS_FIELD_KEY, params)?
+					},
+					LSPS5Request::RemoveWebhook(params) => {
+						jsonrpc_object.serialize_field(JSONRPC_PARAMS_FIELD_KEY, params)?
+					},
+				}
+			},
+			LSPSMessage::LSPS5(LSPS5Message::Response(request_id, response)) => {
+				jsonrpc_object.serialize_field(JSONRPC_ID_FIELD_KEY, &request_id.0)?;
+
+				match response {
+					LSPS5Response::SetWebhook(result) => {
+						jsonrpc_object.serialize_field(JSONRPC_RESULT_FIELD_KEY, result)?
+					},
+					LSPS5Response::SetWebhookError(error) => {
+						jsonrpc_object.serialize_field(JSONRPC_ERROR_FIELD_KEY, error)?
+					},
+					LSPS5Response::ListWebhooks(result) => {
+						jsonrpc_object.serialize_field(JSONRPC_RESULT_FIELD_KEY, result)?
+					},
+					LSPS5Response::ListWebhooksError(error) => {
+						jsonrpc_object.serialize_field(JSONRPC_ERROR_FIELD_KEY, error)?
+					},
+					LSPS5Response::RemoveWebhook(result) => {
+						jsonrpc_object.serialize_field(JSONRPC_RESULT_FIELD_KEY, result)?
+					},
+					LSPS5Response::RemoveWebhookError(error) => {
+						jsonrpc_object.serialize_field(JSONRPC_ERROR_FIELD_KEY, error)?
+					},
+				}
+			},
 		}
 
 		jsonrpc_object.end()
@@ -525,6 +597,31 @@ impl<'de, 'a> Visitor<'de> for LSPSMessageVisitor<'a> {
 						.map_err(de::Error::custom)?;
 					Ok(LSPSMessage::LSPS2(LSPS2Message::Request(id, LSPS2Request::Buy(request))))
 				},
+				// Add LSPS5 methods
+				LSPSMethod::LSPS5SetWebhook => {
+					let request = serde_json::from_value(params.unwrap_or(json!({})))
+						.map_err(de::Error::custom)?;
+					Ok(LSPSMessage::LSPS5(LSPS5Message::Request(
+						id,
+						LSPS5Request::SetWebhook(request),
+					)))
+				},
+				LSPSMethod::LSPS5ListWebhooks => {
+					let request = serde_json::from_value(params.unwrap_or(json!({})))
+						.map_err(de::Error::custom)?;
+					Ok(LSPSMessage::LSPS5(LSPS5Message::Request(
+						id,
+						LSPS5Request::ListWebhooks(request),
+					)))
+				},
+				LSPSMethod::LSPS5RemoveWebhook => {
+					let request = serde_json::from_value(params.unwrap_or(json!({})))
+						.map_err(de::Error::custom)?;
+					Ok(LSPSMessage::LSPS5(LSPS5Message::Request(
+						id,
+						LSPS5Request::RemoveWebhook(request),
+					)))
+				},
 			},
 			None => match self.request_id_to_method_map.remove(&id) {
 				Some(method) => match method {
@@ -630,6 +727,58 @@ impl<'de, 'a> Visitor<'de> for LSPSMessageVisitor<'a> {
 							Err(de::Error::custom("Received invalid JSON-RPC object: one of method, result, or error required"))
 						}
 					},
+					// Add LSPS5 methods
+					LSPSMethod::LSPS5SetWebhook => {
+						if let Some(error) = error {
+							Ok(LSPSMessage::LSPS5(LSPS5Message::Response(
+								id,
+								LSPS5Response::SetWebhookError(error),
+							)))
+						} else if let Some(result) = result {
+							let response =
+								serde_json::from_value(result).map_err(de::Error::custom)?;
+							Ok(LSPSMessage::LSPS5(LSPS5Message::Response(
+								id,
+								LSPS5Response::SetWebhook(response),
+							)))
+						} else {
+							Err(de::Error::custom("Received invalid JSON-RPC object: one of method, result, or error required"))
+						}
+					},
+					LSPSMethod::LSPS5ListWebhooks => {
+						if let Some(error) = error {
+							Ok(LSPSMessage::LSPS5(LSPS5Message::Response(
+								id,
+								LSPS5Response::ListWebhooksError(error),
+							)))
+						} else if let Some(result) = result {
+							let response =
+								serde_json::from_value(result).map_err(de::Error::custom)?;
+							Ok(LSPSMessage::LSPS5(LSPS5Message::Response(
+								id,
+								LSPS5Response::ListWebhooks(response),
+							)))
+						} else {
+							Err(de::Error::custom("Received invalid JSON-RPC object: one of method, result, or error required"))
+						}
+					},
+					LSPSMethod::LSPS5RemoveWebhook => {
+						if let Some(error) = error {
+							Ok(LSPSMessage::LSPS5(LSPS5Message::Response(
+								id,
+								LSPS5Response::RemoveWebhookError(error),
+							)))
+						} else if let Some(result) = result {
+							let response =
+								serde_json::from_value(result).map_err(de::Error::custom)?;
+							Ok(LSPSMessage::LSPS5(LSPS5Message::Response(
+								id,
+								LSPS5Response::RemoveWebhook(response),
+							)))
+						} else {
+							Err(de::Error::custom("Received invalid JSON-RPC object: one of method, result, or error required"))
+						}
+					},
 				},
 				None => Err(de::Error::custom(format!(
 					"Received response for unknown request id: {}",

lightning-liquidity/src/manager.rs

@@ -7,6 +7,9 @@ use crate::lsps0::ser::{
 	LSPS_MESSAGE_TYPE_ID,
 };
 use crate::lsps0::service::LSPS0ServiceHandler;
+use crate::lsps5::client::{LSPS5ClientConfig, LSPS5ClientHandler};
+use crate::lsps5::msgs::LSPS5Message;
+use crate::lsps5::service::{LSPS5ServiceConfig, LSPS5ServiceHandler};
 use crate::message_queue::{MessageQueue, ProcessMessagesCallback};
 
 use crate::lsps1::client::{LSPS1ClientConfig, LSPS1ClientHandler};
@@ -48,6 +51,8 @@ pub struct LiquidityServiceConfig {
 	/// Optional server-side configuration for JIT channels
 	/// should you want to support them.
 	pub lsps2_service_config: Option<LSPS2ServiceConfig>,
+	/// Optional server-side configuration for LSPS5 webhook service.
+	pub lsps5_service_config: Option<LSPS5ServiceConfig>,
 	/// Controls whether the liquidity service should be advertised via setting the feature bit in
 	/// node announcment and the init message.
 	pub advertise_service: bool,
@@ -62,6 +67,8 @@ pub struct LiquidityClientConfig {
 	pub lsps1_client_config: Option<LSPS1ClientConfig>,
 	/// Optional client-side configuration for JIT channels.
 	pub lsps2_client_config: Option<LSPS2ClientConfig>,
+	/// Optional client-side configuration for LSPS5 webhook service.
+	pub lsps5_client_config: Option<LSPS5ClientConfig>,
 }
 
 /// The main interface into LSP functionality.
@@ -105,6 +112,8 @@ where
 	lsps1_client_handler: Option<LSPS1ClientHandler<ES>>,
 	lsps2_service_handler: Option<LSPS2ServiceHandler<CM>>,
 	lsps2_client_handler: Option<LSPS2ClientHandler<ES>>,
+	lsps5_service_handler: Option<LSPS5ServiceHandler>,
+	lsps5_client_handler: Option<LSPS5ClientHandler<ES>>,
 	service_config: Option<LiquidityServiceConfig>,
 	_client_config: Option<LiquidityClientConfig>,
 	best_block: RwLock<Option<BestBlock>>,
@@ -159,6 +168,32 @@ where {
 			})
 		});
 
+		let lsps5_client_handler = client_config.as_ref().and_then(|config| {
+			config.lsps5_client_config.as_ref().map(|config| {
+				LSPS5ClientHandler::new(
+					entropy_source.clone(),
+					Arc::clone(&pending_messages),
+					Arc::clone(&pending_events),
+					config.clone(),
+				)
+			})
+		});
+
+		let lsps5_service_handler = service_config.as_ref().and_then(|config| {
+			config.lsps5_service_config.as_ref().map(|config| {
+				if let Some(number) =
+					<LSPS5ServiceHandler as LSPSProtocolMessageHandler>::PROTOCOL_NUMBER
+				{
+					supported_protocols.push(number);
+				}
+				LSPS5ServiceHandler::new(
+					Arc::clone(&pending_events),
+					Arc::clone(&pending_messages),
+					config.clone(),
+				)
+			})
+		});
+
 		let lsps1_client_handler = client_config.as_ref().and_then(|config| {
 			config.lsps1_client_config.as_ref().map(|config| {
 				LSPS1ClientHandler::new(
@@ -213,6 +248,8 @@ where {
 			lsps1_service_handler,
 			lsps2_client_handler,
 			lsps2_service_handler,
+			lsps5_client_handler,
+			lsps5_service_handler,
 			service_config,
 			_client_config: client_config,
 			best_block: RwLock::new(chain_params.map(|chain_params| chain_params.best_block)),
@@ -260,6 +297,20 @@ where {
 		self.lsps2_service_handler.as_ref()
 	}
 
+	/// Returns a reference to the LSPS5 client-side handler.
+	///
+	/// The returned hendler allows to initiate the LSPS5 client-side flow. That is, it allows to
+	pub fn lsps5_client_handler(&self) -> Option<&LSPS5ClientHandler<ES>> {
+		self.lsps5_client_handler.as_ref()
+	}
+
+	/// Returns a reference to the LSPS5 server-side handler.
+	///
+	/// The returned hendler allows to initiate the LSPS5 service-side flow.
+	pub fn lsps5_service_handler(&self) -> Option<&LSPS5ServiceHandler> {
+		self.lsps5_service_handler.as_ref()
+	}
+
 	/// Allows to set a callback that will be called after new messages are pushed to the message
 	/// queue.
 	///
@@ -435,6 +486,26 @@ where {
 					},
 				}
 			},
+			LSPSMessage::LSPS5(msg @ LSPS5Message::Response(..)) => {
+				match &self.lsps5_client_handler {
+					Some(lsps5_client_handler) => {
+						lsps5_client_handler.handle_message(msg, sender_node_id)?;
+					},
+					None => {
+						return Err(LightningError { err: format!("Received LSPS5 response message without LSPS5 client handler configured. From node = {:?}", sender_node_id), action: ErrorAction::IgnoreAndLog(Level::Info)});
+					},
+				}
+			},
+			LSPSMessage::LSPS5(msg @ LSPS5Message::Request(..)) => {
+				match &self.lsps5_service_handler {
+					Some(lsps5_service_handler) => {
+						lsps5_service_handler.handle_message(msg, sender_node_id)?;
+					},
+					None => {
+						return Err(LightningError { err: format!("Received LSPS5 request message without LSPS5 service handler configured. From node = {:?}", sender_node_id), action: ErrorAction::IgnoreAndLog(Level::Info)});
+					},
+				}
+			},
 		}
 		Ok(())
 	}