WIP

Author: martinsaposnic

lightning-liquidity/src/lsps5/client.rs

@@ -137,12 +137,15 @@ impl PeerState {
 ///
 /// # Core Capabilities
 ///
-///  - `set_webhook(peer, app_name, url)` -> register or update a webhook (`lsps5.set_webhook`)
-///  - `list_webhooks(peer)` -> retrieve all registered webhooks (`lsps5.list_webhooks`)
-///  - `remove_webhook(peer, name)` -> delete a webhook (`lsps5.remove_webhook`)
+///  - `set_webhook(peer, app_name, url)` -> register or update a webhook [`lsps5.set_webhook`]
+///  - `list_webhooks(peer)` -> retrieve all registered webhooks [`lsps5.list_webhooks`]
+///  - `remove_webhook(peer, name)` -> delete a webhook [`lsps5.remove_webhook`]
 ///  - `parse_webhook_notification(...)` -> verify signature, timestamp, replay, and emit event
 ///
 /// [`bLIP-55 / LSPS5 specification`]: https://github.com/lightning/blips/pull/55/files
+/// [`lsps5.set_webhook`]: super::msgs::LSPS5Request::SetWebhook
+/// [`lsps5.list_webhooks`]: super::msgs::LSPS5Request::ListWebhooks
+/// [`lsps5.remove_webhook`]: super::msgs::LSPS5Request::RemoveWebhook
 pub struct LSPS5ClientHandler<ES: Deref>
 where
 	ES::Target: EntropySource,
@@ -205,11 +208,11 @@ where
 	/// A unique `LSPSRequestId` for correlating the asynchronous response.
 	///
 	/// Response from the LSP peer will be provided asynchronously through a
-	/// [`LSPS5Response::SetWebhook`] or [`LSPS5Response::SetWebhookError`] message, and the this client
+	/// [`LSPS5Response::SetWebhook`] or [`LSPS5Response::SetWebhookError`] message, and this client
 	/// will then enqueue either a [`WebhookRegistered`] or [`WebhookRegistrationFailed`] event.
 	///
 	/// **Note**: Ensure the app name is valid and its length does not exceed [`MAX_APP_NAME_LENGTH`].
-	/// **Note**: Ensure the URL is valid and its length does not exceed [`MAX_WEBHOOK_URL_LENGTH`]
+	/// Also ensure the URL is valid, has HTTPS protocol, its length does not exceed [`MAX_WEBHOOK_URL_LENGTH`]
 	/// and that the URL points to a public host.
 	///
 	/// [`MAX_WEBHOOK_URL_LENGTH`]: super::msgs::MAX_WEBHOOK_URL_LENGTH
@@ -259,9 +262,14 @@ where
 	/// # Returns
 	/// A unique `LSPSRequestId` for correlating the asynchronous response.
 	///
+	/// Response from the LSP peer will be provided asynchronously through a
+	/// [`LSPS5Response::ListWebhooks`] or [`LSPS5Response::ListWebhooksError`] message, and this client
+	/// will then enqueue either a [`WebhooksListed`] or [`WebhooksListFailed`] event.
 	///
-	/// Response will be provided asynchronously through the event queue as a
-	/// WebhooksListed or WebhooksListFailed event.
+	/// [`WebhooksListed`]: super::event::LSPS5ClientEvent::WebhooksListed
+	/// [`WebhooksListFailed`]: super::event::LSPS5ClientEvent::WebhooksListFailed
+	/// [`LSPS5Response::ListWebhooks`]: super::msgs::LSPS5Response::ListWebhooks
+	/// [`LSPS5Response::ListWebhooksError`]: super::msgs::LSPS5Response::ListWebhooksError
 	pub fn list_webhooks(
 		&self, counterparty_node_id: PublicKey,
 	) -> Result<LSPSRequestId, LSPS5Error> {
@@ -291,8 +299,14 @@ where
 	/// # Returns
 	/// A unique `LSPSRequestId` for correlating the asynchronous response.
 	///
-	/// Response will be provided asynchronously through the event queue as a
-	/// WebhookRemoved or WebhookRemovalFailed event.
+	/// Response from the LSP peer will be provided asynchronously through a
+	/// [`LSPS5Response::RemoveWebhook`] or [`LSPS5Response::RemoveWebhookError`] message, and this client
+	/// will then enqueue either a [`WebhookRemoved`] or [`WebhookRemovalFailed`] event.
+	///
+	/// [`WebhookRemoved`]: super::event::LSPS5ClientEvent::WebhookRemoved
+	/// [`WebhookRemovalFailed`]: super::event::LSPS5ClientEvent::WebhookRemovalFailed
+	/// [`LSPS5Response::RemoveWebhook`]: super::msgs::LSPS5Response::RemoveWebhook
+	/// [`LSPS5Response::RemoveWebhookError`]: super::msgs::LSPS5Response::RemoveWebhookError
 	pub fn remove_webhook(
 		&self, counterparty_node_id: PublicKey, app_name: String,
 	) -> Result<LSPSRequestId, LSPS5Error> {
@@ -512,18 +526,22 @@ where
 	/// - `signature`: the zbase32-encoded LN signature over timestamp+body.
 	/// - `notification_json`: the JSON string of the JSON-RPC notification object.
 	///
-	/// On success, emits `LSPS5ClientEvent::WebhookNotificationReceived`
-	/// and returns the parsed `WebhookNotification`.
+	/// On success, emits [`LSPS5ClientEvent::WebhookNotificationReceived`]
+	/// and returns the parsed [`WebhookNotification`].
 	///
 	/// Failure reasons include:
 	/// - Timestamp too old (drift > 10 minutes)
 	/// - Replay attack detected (signature reused)
 	/// - Invalid signature (crypto check fails)
 	/// - JSON parse errors for malformed `notification_json`
 	///
-	/// Clients should call this method upon receiving a SendWebhookNotifications
+	/// Clients should call this method upon receiving a [`LSPS5ServiceEvent::SendWebhookNotification`]
 	/// event, before taking action on the notification. This guarantees that only authentic,
 	/// non-replayed notifications reach your application.
+	///
+	/// [`LSPS5ClientEvent::WebhookNotificationReceived`]: super::event::LSPS5ClientEvent::WebhookNotificationReceived
+	/// [`LSPS5ServiceEvent::SendWebhookNotification`]: super::event::LSPS5ServiceEvent::SendWebhookNotification
+	/// [`WebhookNotification`]: super::msgs::WebhookNotification
 	pub fn parse_webhook_notification(
 		&self, counterparty_node_id: PublicKey, timestamp: &LSPSDateTime, signature: &str,
 		notification_json: &str,

lightning-liquidity/src/lsps5/event.rs

@@ -62,12 +62,20 @@ pub enum LSPS5ServiceEvent {
 		/// Client node ID that requested their webhooks.
 		counterparty_node_id: PublicKey,
 		/// App names with registered webhooks for this client.
+		///
+		/// Each [`app_name`] in this list corresponds to a registered webhook.
+		///
+		/// [`app_name`]: super::msgs::LSPS5AppName
 		app_names: Vec<LSPS5AppName>,
 		/// The identifier of the issued bLIP-55 / LSPS5 webhook listing request.
 		///
 		/// This can be used to track which request this event corresponds to.
 		request_id: LSPSRequestId,
 		/// Maximum number of webhooks allowed by LSP per client.
+		///
+		/// This is the value defined in [`max_webhooks_per_client`] within the service configuration.
+		///
+		/// [`max_webhooks_per_client`]: super::service::LSPS5ServiceConfig::max_webhooks_per_client
 		max_webhooks: u32,
 	},
 
@@ -78,6 +86,12 @@ pub enum LSPS5ServiceEvent {
 		/// Client node ID that removed the webhook.
 		counterparty_node_id: PublicKey,
 		/// App name that was removed.
+		///
+		/// This identifies the webhook that was removed.
+		///
+		/// **Note**: The [`app_name`] must have been previously registered via `lsps5.set_webhook`.
+		///
+		/// [`app_name`]: super::msgs::LSPS5AppName
 		app_name: LSPS5AppName,
 		/// The identifier of the issued bLIP-55 / LSPS5 webhook removal request.
 		///
@@ -96,18 +110,37 @@ pub enum LSPS5ServiceEvent {
 	/// When the client receives this notification, they will process it and generate a
 	/// `WebhookNotificationReceived` event on their side. The client will validate the
 	/// signature using the LSP's node ID to ensure the notification is authentic.
-	SendWebhookNotifications {
+	SendWebhookNotification {
 		/// Client node ID to be notified.
 		counterparty_node_id: PublicKey,
 		/// App name to be notified.
+		///
+		/// This identifies which webhook registration should be notified.
+		///
+		/// **Note**: The [`app_name`] must have been previously registered via `lsps5.set_webhook`.
+		///
+		/// [`app_name`]: super::msgs::LSPS5AppName
 		app_name: LSPS5AppName,
 		/// URL that to be contacted.
+		///
+		/// This is the webhook URL (HTTPS) provided by the client during registration.
+		///
+		/// **Note**: The URL must be a valid HTTPS URL that points to a public host.
+		///
+		/// [`url`]: super::msgs::LSPS5WebhookUrl
 		url: LSPS5WebhookUrl,
 		/// Notification method with its parameters.
+		///
+		/// This contains the type of notification and any associated data to be sent to the client.
 		notification: WebhookNotification,
 		///  Timestamp of the notification.
+		///
+		/// This timestamp is used for signing the notification and must be within 10 minutes
+		/// of the client's local time for the signature to be accepted.
 		timestamp: LSPSDateTime,
 		/// Signature of the notification using the LSP's node ID.
+		///
+		/// This signature helps the client verify that the notification was sent by the LSP.
 		signature: String,
 		/// Headers to be included in the HTTP POST request.
 		///
@@ -124,7 +157,14 @@ pub enum LSPS5ClientEvent {
 	/// A webhook was successfully registered with the LSP.
 	///
 	/// This event is triggered when the LSP confirms successful registration
-	/// of a webhook via `lsps5.set_webhook`.
+	/// of a webhook via `lsps5.set_webhook`. The [`app_name`] and [`url`]
+	/// both must respect maximum lengths of [`MAX_APP_NAME_LENGTH`] and
+	/// [`MAX_WEBHOOK_URL_LENGTH`] respectively, and the [`url`] must use HTTPS.
+	///
+	/// [`app_name`]: super::msgs::LSPS5AppName
+	/// [`url`]: super::msgs::LSPS5WebhookUrl
+	/// [`MAX_APP_NAME_LENGTH`]: super::msgs::MAX_APP_NAME_LENGTH
+	/// [`MAX_WEBHOOK_URL_LENGTH`]: super::msgs::MAX_WEBHOOK_URL_LENGTH
 	WebhookRegistered {
 		/// The node id of the LSP that confirmed the registration.
 		counterparty_node_id: PublicKey,
@@ -145,11 +185,22 @@ pub enum LSPS5ClientEvent {
 		request_id: LSPSRequestId,
 	},
 
-	/// A webhook registration attempt failed
+	/// A webhook registration attempt failed.
 	///
 	/// This event is triggered when the LSP rejects a webhook registration
-	/// via `lsps5.set_webhook`. This can happen if the app_name or URL is too long,
-	/// the URL uses an unsupported protocol, or the maximum number of webhooks is reached.
+	/// via `lsps5.set_webhook`. This can happen if the [`app_name`]
+	/// exceeds [`MAX_APP_NAME_LENGTH`], the [`url`] exceeds
+	/// [`MAX_WEBHOOK_URL_LENGTH`], the [`url`] uses an unsupported protocol
+	/// (HTTPS is required), or the maximum number of webhooks
+	/// (`max_webhooks_per_client`) has been reached.
+	///
+	/// See also [`LSPS5Error::AppNameTooLong`], [`LSPS5Error::WebhookUrlTooLong`],
+	/// [`LSPS5Error::UnsupportedProtocol`], [`LSPS5Error::TooManyWebhooks`].
+	///
+	/// [`app_name`]: super::msgs::LSPS5AppName
+	/// [`url`]: super::msgs::LSPS5WebhookUrl
+	/// [`MAX_APP_NAME_LENGTH`]: super::msgs::MAX_APP_NAME_LENGTH
+	/// [`MAX_WEBHOOK_URL_LENGTH`]: super::msgs::MAX_WEBHOOK_URL_LENGTH
 	WebhookRegistrationFailed {
 		/// The node id of the LSP that rejected the registration.
 		counterparty_node_id: PublicKey,
@@ -167,7 +218,8 @@ pub enum LSPS5ClientEvent {
 
 	/// The list of registered webhooks was successfully retrieved.
 	///
-	/// This event is triggered when the LSP responds to a `lsps5.list_webhooks` request.
+	/// This event is triggered when the LSP responds to a
+	/// `lsps5.list_webhooks` request.
 	WebhooksListed {
 		/// The node id of the LSP that provided the list.
 		counterparty_node_id: PublicKey,
@@ -183,7 +235,8 @@ pub enum LSPS5ClientEvent {
 
 	/// The attempt to list webhooks failed.
 	///
-	/// This event is triggered when the LSP rejects a `lsps5.list_webhooks` request.
+	/// This event is triggered when the LSP rejects a
+	/// `lsps5.list_webhooks` request.
 	WebhooksListFailed {
 		/// The node id of the LSP that rejected the request.
 		counterparty_node_id: PublicKey,
@@ -213,7 +266,13 @@ pub enum LSPS5ClientEvent {
 	/// A webhook removal attempt failed.
 	///
 	/// This event is triggered when the LSP rejects a webhook removal
-	/// via `lsps5.remove_webhook`. The most common error is app_name_not_found (1010).
+	/// via `lsps5.remove_webhook`. The most common error is
+	/// [`LSPS5Error::AppNameNotFound`] (error code [`LSPS5_APP_NAME_NOT_FOUND_ERROR_CODE`]),
+	/// which indicates the given [`app_name`] was not found.
+	///
+	/// [`LSPS5Error::AppNameNotFound`]: super::msgs::LSPS5Error::AppNameNotFound
+	/// [`LSPS5_APP_NAME_NOT_FOUND_ERROR_CODE`]: super::msgs::LSPS5_APP_NAME_NOT_FOUND_ERROR_CODE
+	/// [`app_name`]: super::msgs::LSPS5AppName
 	WebhookRemovalFailed {
 		/// The node id of the LSP that rejected the removal.
 		counterparty_node_id: PublicKey,
@@ -230,8 +289,7 @@ pub enum LSPS5ClientEvent {
 	/// A webhook notification was received from the LSP.
 	///
 	/// This event is triggered when the client receives a webhook notification
-	/// from the LSP. This can happen for various reasons such as incoming payment,
-	/// expiring HTLCs, liquidity management requests, or incoming onion messages.
+	/// from the LSP. The signature and timestamp must be verified before use.
 	WebhookNotificationReceived {
 		/// LSP node ID that sent the notification.
 		counterparty_node_id: PublicKey,

lightning-liquidity/src/lsps5/msgs.rs

@@ -34,11 +34,16 @@ pub const MAX_APP_NAME_LENGTH: usize = 64;
 /// Maximum allowed length for a webhook URL (in characters).
 pub const MAX_WEBHOOK_URL_LENGTH: usize = 1024;
 
-pub(crate) const LSPS5_TOO_LONG_ERROR_CODE: i32 = 500;
-pub(crate) const LSPS5_URL_PARSE_ERROR_CODE: i32 = 501;
-pub(crate) const LSPS5_UNSUPPORTED_PROTOCOL_ERROR_CODE: i32 = 502;
-pub(crate) const LSPS5_TOO_MANY_WEBHOOKS_ERROR_CODE: i32 = 503;
-pub(crate) const LSPS5_APP_NAME_NOT_FOUND_ERROR_CODE: i32 = 1010;
+/// Either the app name or the webhook URL is too long.
+pub const LSPS5_TOO_LONG_ERROR_CODE: i32 = 500;
+/// The provided URL could not be parsed.
+pub const LSPS5_URL_PARSE_ERROR_CODE: i32 = 501;
+/// The provided URL is not HTTPS.
+pub const LSPS5_UNSUPPORTED_PROTOCOL_ERROR_CODE: i32 = 502;
+/// The client has too many webhooks registered.
+pub const LSPS5_TOO_MANY_WEBHOOKS_ERROR_CODE: i32 = 503;
+/// The app name was not found.
+pub const LSPS5_APP_NAME_NOT_FOUND_ERROR_CODE: i32 = 1010;
 
 pub(crate) const LSPS5_SET_WEBHOOK_METHOD_NAME: &str = "lsps5.set_webhook";
 pub(crate) const LSPS5_LIST_WEBHOOKS_METHOD_NAME: &str = "lsps5.list_webhooks";