Add LSPS5 event enums for webhook operations

- Introduce LSPS5ServiceEvent for LSPS-side webhook events including registration, listing, removal, and notification.
- Define LSPS5ClientEvent for handling webhook outcomes on the client (Lightning node) side.
- Outline WebhookNotificationParams enum to support notification-specific parameters.
- Improve LSPS5 event documentation and field naming
- Rename client/lsp fields to counterparty_node_id for consistent terminology
- Replace generic String types with more specific Lsps5AppName and Lsps5WebhookUrl
- Add comprehensive documentation for all events and fields
- Include format specifications (UTF-8, ISO8601) and size constraints
- Add request_id field to all relevant events for consistent request tracking
- Provide detailed descriptions of error codes and their meanings
- Use complete sentences in documentation comments

Author: martinsaposnic

lightning-liquidity/src/lsps5/event.rs

@@ -0,0 +1,226 @@
+// This file is Copyright its original authors, visible in version control
+// history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
+// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
+// You may not use this file except in accordance with one or both of these
+// licenses.
+
+//! Events generated by the LSPS5 service and client
+
+use crate::lsps0::ser::LSPSRequestId;
+use crate::prelude::String;
+use crate::prelude::Vec;
+use bitcoin::secp256k1::PublicKey;
+
+use super::msgs::LSPS5AppName;
+use super::msgs::LSPS5WebhookUrl;
+use super::msgs::WebhookNotification;
+
+/// An event which an bLIP-55 / LSPS5 server should take some action in response to.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum LSPS5ServiceEvent {
+	/// A webhook was registered by a client
+	///
+	/// This event occurs when a client successfully registers a webhook via `lsps5.set_webhook`.
+	/// You should store this information to be able to contact the client when they are offline.
+	WebhookRegistered {
+		/// Client node ID that registered the webhook
+		counterparty_node_id: PublicKey,
+		/// App name provided by the client (up to 64 bytes in UTF-8 format)
+		app_name: LSPS5AppName,
+		/// Webhook URL (HTTPS) that should be contacted to notify the client (up to 1024 ASCII characters)
+		url: LSPS5WebhookUrl,
+		/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
+		///
+		/// This can be used to track which request this event corresponds to.
+		request_id: LSPSRequestId,
+		/// Whether this was a new registration or an update to existing one with no changes
+		/// If false, a notification should be sent to the registered webhook
+		no_change: bool,
+	},
+
+	/// Webhooks were listed for a client
+	///
+	/// This event occurs when a client requests their registered webhooks via `lsps5.list_webhooks`.
+	WebhooksListed {
+		/// Client node ID that requested their webhooks
+		counterparty_node_id: PublicKey,
+		/// App names with registered webhooks for this client
+		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
+		max_webhooks: u32,
+	},
+
+	/// A webhook was removed by a client
+	///
+	/// This event occurs when a client successfully removes a webhook via `lsps5.remove_webhook`.
+	WebhookRemoved {
+		/// Client node ID that removed the webhook
+		counterparty_node_id: PublicKey,
+		/// App name that was removed
+		app_name: LSPS5AppName,
+		/// The identifier of the issued bLIP-55 / LSPS5 webhook removal request
+		///
+		/// This can be used to track which request this event corresponds to.
+		request_id: LSPSRequestId,
+	},
+
+	/// A notification needs to be sent to a client's webhook
+	///
+	/// This event occurs when the LSP needs to send a notification to a client's webhook.
+	SendWebhookNotifications {
+		/// Client node ID to be notified
+		counterparty_node_id: PublicKey,
+		/// App name to be notified
+		app_name: LSPS5AppName,
+		/// URL that to be contacted
+		url: LSPS5WebhookUrl,
+		/// Notification method with its parameters
+		notification: WebhookNotification,
+		/// ISO8601 timestamp of the notification (YYYY-MM-DDThh:mm:ss.uuuZ format)
+		timestamp: String,
+		/// Signature of the notification using the LSP's node ID
+		signature: String,
+		/// Headers to be included in the HTTP POST request
+		headers: Vec<(String, String)>,
+	},
+}
+
+/// An event which an LSPS5 client should take some action in response to.
+#[derive(Debug, Clone, PartialEq, Eq)]
+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`.
+	WebhookRegistered {
+		/// The node id of the LSP that confirmed the registration
+		counterparty_node_id: PublicKey,
+		/// Current number of webhooks registered for this client
+		num_webhooks: u32,
+		/// Maximum number of webhooks allowed by LSP
+		max_webhooks: u32,
+		/// Whether this was an unchanged registration (same app_name and URL)
+		/// If true, the LSP didn't send a webhook notification for this registration
+		no_change: bool,
+		/// The app name that was registered (up to 64 bytes in UTF-8 format)
+		app_name: LSPS5AppName,
+		/// The webhook URL that was registered (HTTPS protocol)
+		url: LSPS5WebhookUrl,
+		/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
+		///
+		/// This can be used to track which request this event corresponds to.
+		request_id: LSPSRequestId,
+	},
+
+	/// 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.
+	WebhookRegistrationFailed {
+		/// The node id of the LSP that rejected the registration
+		counterparty_node_id: PublicKey,
+		/// Error code from the LSP (500: too_long, 501: url_parse_error,
+		/// 502: unsupported_protocol, 503: too_many_webhooks)
+		error_code: i32,
+		/// Error message from the LSP
+		error_message: String,
+		/// The app name that was attempted
+		app_name: LSPS5AppName,
+		/// The webhook URL that was attempted
+		url: LSPS5WebhookUrl,
+		/// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
+		///
+		/// This can be used to track which request this event corresponds to.
+		request_id: LSPSRequestId,
+	},
+
+	/// The list of registered webhooks was successfully retrieved
+	///
+	/// 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,
+		/// List of app names with registered webhooks
+		app_names: Vec<LSPS5AppName>,
+		/// Maximum number of webhooks allowed by LSP
+		max_webhooks: u32,
+		/// The identifier of the issued bLIP-55 / LSPS5 list webhooks request
+		///
+		/// This can be used to track which request this event corresponds to.
+		request_id: LSPSRequestId,
+	},
+
+	/// The attempt to list webhooks failed
+	///
+	/// 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,
+		/// Error code from the LSP
+		error_code: i32,
+		/// Error message from the LSP
+		error_message: String,
+		/// The identifier of the issued bLIP-55 / LSPS5 list webhooks request
+		///
+		/// This can be used to track which request this event corresponds to.
+		request_id: LSPSRequestId,
+	},
+
+	/// A webhook was successfully removed
+	///
+	/// This event is triggered when the LSP confirms successful removal
+	/// of a webhook via `lsps5.remove_webhook`.
+	WebhookRemoved {
+		/// The node id of the LSP that confirmed the removal
+		counterparty_node_id: PublicKey,
+		/// The app name that was removed
+		app_name: LSPS5AppName,
+		/// The identifier of the issued bLIP-55 / LSPS5 remove webhook request
+		///
+		/// This can be used to track which request this event corresponds to.
+		request_id: LSPSRequestId,
+	},
+
+	/// 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).
+	WebhookRemovalFailed {
+		/// The node id of the LSP that rejected the removal
+		counterparty_node_id: PublicKey,
+		/// Error code from the LSP (1010: app_name_not_found)
+		error_code: i32,
+		/// Error message from the LSP
+		error_message: String,
+		/// The app name that was attempted to be removed
+		app_name: LSPS5AppName,
+		/// The identifier of the issued bLIP-55 / LSPS5 remove webhook request
+		///
+		/// This can be used to track which request this event corresponds to.
+		request_id: LSPSRequestId,
+	},
+
+	/// 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.
+	WebhookNotificationReceived {
+		/// LSP node ID that sent the notification
+		counterparty_node_id: PublicKey,
+		/// The notification with its method and parameters
+		notification: WebhookNotification,
+		/// Timestamp of the notification in ISO8601 format (YYYY-MM-DDThh:mm:ss.uuuZ)
+		timestamp: String,
+		/// Whether the LSP's signature was successfully verified
+		signature_valid: bool,
+	},
+}