9
9
10
10
//! Events generated by the LSPS5 service and client
11
11
12
+ use crate :: lsps0:: ser:: LSPSDateTime ;
12
13
use crate :: lsps0:: ser:: LSPSRequestId ;
13
14
use alloc:: string:: String ;
14
15
use alloc:: vec:: Vec ;
15
16
use bitcoin:: secp256k1:: PublicKey ;
16
17
17
18
use super :: msgs:: LSPS5AppName ;
19
+ use super :: msgs:: LSPS5Error ;
18
20
use super :: msgs:: LSPS5WebhookUrl ;
19
21
use super :: msgs:: WebhookNotification ;
20
-
21
22
/// An event which an bLIP-55 / LSPS5 server should take some action in response to.
22
23
#[ derive( Debug , Clone , PartialEq , Eq ) ]
23
24
pub enum LSPS5ServiceEvent {
@@ -26,101 +27,119 @@ pub enum LSPS5ServiceEvent {
26
27
/// This event occurs when a client successfully registers a webhook via `lsps5.set_webhook`.
27
28
/// You should store this information to be able to contact the client when they are offline.
28
29
WebhookRegistered {
29
- /// Client node ID that registered the webhook
30
+ /// Client node ID that registered the webhook.
30
31
counterparty_node_id : PublicKey ,
31
- /// App name provided by the client (up to 64 bytes in UTF-8 format)
32
+ /// App name provided by the client.
33
+ ///
34
+ /// This app name is used to identify the webhook registration.
35
+ ///
36
+ /// **Note**: Ensure the app name is valid and its length does not exceed [`MAX_APP_NAME_LENGTH`].
37
+ ///
38
+ /// [`MAX_APP_NAME_LENGTH`]: super::msgs::MAX_APP_NAME_LENGTH
32
39
app_name : LSPS5AppName ,
33
- /// Webhook URL (HTTPS) that should be contacted to notify the client (up to 1024 ASCII characters)
40
+ /// Webhook URL (HTTPS) to be contacted for notifying the client.
41
+ ///
42
+ /// This URL is used by the LSP to send notifications.
43
+ ///
44
+ /// **Note**: Ensure the URL is valid and its length does not exceed [`MAX_WEBHOOK_URL_LENGTH`].
45
+ /// Also ensure that the URL points to a public host.
46
+ ///
47
+ /// [`MAX_WEBHOOK_URL_LENGTH`]: super::msgs::MAX_WEBHOOK_URL_LENGTH
34
48
url : LSPS5WebhookUrl ,
35
- /// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
49
+ /// The identifier of the issued bLIP-55 / LSPS5 webhook registration request.
36
50
///
37
51
/// This can be used to track which request this event corresponds to.
38
52
request_id : LSPSRequestId ,
39
- /// Whether this was a new registration or an update to existing one with no changes
40
- /// If false, a notification should be sent to the registered webhook
53
+ /// Whether this was a new registration or an update to existing one with no changes.
54
+ /// If false, a notification should be sent to the registered webhook.
41
55
no_change : bool ,
42
56
} ,
43
57
44
- /// Webhooks were listed for a client
58
+ /// Webhooks were listed for a client.
45
59
///
46
60
/// This event occurs when a client requests their registered webhooks via `lsps5.list_webhooks`.
47
61
WebhooksListed {
48
- /// Client node ID that requested their webhooks
62
+ /// Client node ID that requested their webhooks.
49
63
counterparty_node_id : PublicKey ,
50
- /// App names with registered webhooks for this client
64
+ /// App names with registered webhooks for this client.
51
65
app_names : Vec < LSPS5AppName > ,
52
- /// The identifier of the issued bLIP-55 / LSPS5 webhook listing request
66
+ /// The identifier of the issued bLIP-55 / LSPS5 webhook listing request.
53
67
///
54
68
/// This can be used to track which request this event corresponds to.
55
69
request_id : LSPSRequestId ,
56
- /// Maximum number of webhooks allowed by LSP per client
70
+ /// Maximum number of webhooks allowed by LSP per client.
57
71
max_webhooks : u32 ,
58
72
} ,
59
73
60
- /// A webhook was removed by a client
74
+ /// A webhook was removed by a client.
61
75
///
62
76
/// This event occurs when a client successfully removes a webhook via `lsps5.remove_webhook`.
63
77
WebhookRemoved {
64
- /// Client node ID that removed the webhook
78
+ /// Client node ID that removed the webhook.
65
79
counterparty_node_id : PublicKey ,
66
- /// App name that was removed
80
+ /// App name that was removed.
67
81
app_name : LSPS5AppName ,
68
- /// The identifier of the issued bLIP-55 / LSPS5 webhook removal request
82
+ /// The identifier of the issued bLIP-55 / LSPS5 webhook removal request.
69
83
///
70
84
/// This can be used to track which request this event corresponds to.
71
85
request_id : LSPSRequestId ,
72
86
} ,
73
87
74
- /// A notification needs to be sent to a client's webhook
88
+ /// A notification needs to be sent to a client's webhook.
75
89
///
76
90
/// This event occurs when the LSP needs to send a notification to a client's webhook.
77
91
/// When this event is received, the LSP should:
78
- /// 1. Serialize the notification to JSON
79
- /// 2. Make an HTTP POST request to the provided URL with the given headers and the serialized notification
92
+ /// 1. Serialize the notification to JSON.
93
+ /// 2. Make an HTTP POST request to the provided
94
+ /// URL with the given headers and the serialized notification.
80
95
///
81
96
/// When the client receives this notification, they will process it and generate a
82
97
/// `WebhookNotificationReceived` event on their side. The client will validate the
83
98
/// signature using the LSP's node ID to ensure the notification is authentic.
84
99
SendWebhookNotifications {
85
- /// Client node ID to be notified
100
+ /// Client node ID to be notified.
86
101
counterparty_node_id : PublicKey ,
87
- /// App name to be notified
102
+ /// App name to be notified.
88
103
app_name : LSPS5AppName ,
89
- /// URL that to be contacted
104
+ /// URL that to be contacted.
90
105
url : LSPS5WebhookUrl ,
91
- /// Notification method with its parameters
106
+ /// Notification method with its parameters.
92
107
notification : WebhookNotification ,
93
- /// ISO8601 timestamp of the notification (YYYY-MM-DDThh:mm:ss.uuuZ format)
94
- timestamp : String ,
95
- /// Signature of the notification using the LSP's node ID
108
+ /// Timestamp of the notification.
109
+ timestamp : LSPSDateTime ,
110
+ /// Signature of the notification using the LSP's node ID.
96
111
signature : String ,
97
- /// Headers to be included in the HTTP POST request
112
+ /// Headers to be included in the HTTP POST request.
113
+ ///
114
+ /// Content-Type (application/json).
115
+ /// x-lsps5-timestamp (timestamp in RFC3339 (YYYY-MM-DDThh:mm:ss.uuuZ) format).
116
+ /// x-lsps5-signature (signature of the notification using the LSP's node ID).
98
117
headers : Vec < ( String , String ) > ,
99
118
} ,
100
119
}
101
120
102
121
/// An event which an LSPS5 client should take some action in response to.
103
122
#[ derive( Debug , Clone , PartialEq , Eq ) ]
104
123
pub enum LSPS5ClientEvent {
105
- /// A webhook was successfully registered with the LSP
124
+ /// A webhook was successfully registered with the LSP.
106
125
///
107
126
/// This event is triggered when the LSP confirms successful registration
108
127
/// of a webhook via `lsps5.set_webhook`.
109
128
WebhookRegistered {
110
- /// The node id of the LSP that confirmed the registration
129
+ /// The node id of the LSP that confirmed the registration.
111
130
counterparty_node_id : PublicKey ,
112
- /// Current number of webhooks registered for this client
131
+ /// Current number of webhooks registered for this client.
113
132
num_webhooks : u32 ,
114
- /// Maximum number of webhooks allowed by LSP
133
+ /// Maximum number of webhooks allowed by LSP.
115
134
max_webhooks : u32 ,
116
- /// Whether this was an unchanged registration (same app_name and URL)
117
- /// If true, the LSP didn't send a webhook notification for this registration
135
+ /// Whether this was an unchanged registration (same app_name and URL).
136
+ /// If true, the LSP didn't send a webhook notification for this registration.
118
137
no_change : bool ,
119
- /// The app name that was registered (up to 64 bytes in UTF-8 format)
138
+ /// The app name that was registered.
120
139
app_name : LSPS5AppName ,
121
- /// The webhook URL that was registered (HTTPS protocol)
140
+ /// The webhook URL that was registered.
122
141
url : LSPS5WebhookUrl ,
123
- /// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
142
+ /// The identifier of the issued bLIP-55 / LSPS5 webhook registration request.
124
143
///
125
144
/// This can be used to track which request this event corresponds to.
126
145
request_id : LSPSRequestId ,
@@ -132,102 +151,95 @@ pub enum LSPS5ClientEvent {
132
151
/// via `lsps5.set_webhook`. This can happen if the app_name or URL is too long,
133
152
/// the URL uses an unsupported protocol, or the maximum number of webhooks is reached.
134
153
WebhookRegistrationFailed {
135
- /// The node id of the LSP that rejected the registration
154
+ /// The node id of the LSP that rejected the registration.
136
155
counterparty_node_id : PublicKey ,
137
- /// Error code from the LSP (500: too_long, 501: url_parse_error,
138
- /// 502: unsupported_protocol, 503: too_many_webhooks)
139
- error_code : i32 ,
140
- /// Error message from the LSP
141
- error_message : String ,
142
- /// The app name that was attempted
156
+ /// Error from the LSP.
157
+ error : LSPS5Error ,
158
+ /// The app name that was attempted.
143
159
app_name : LSPS5AppName ,
144
- /// The webhook URL that was attempted
160
+ /// The webhook URL that was attempted.
145
161
url : LSPS5WebhookUrl ,
146
- /// The identifier of the issued bLIP-55 / LSPS5 webhook registration request
162
+ /// The identifier of the issued bLIP-55 / LSPS5 webhook registration request.
147
163
///
148
164
/// This can be used to track which request this event corresponds to.
149
165
request_id : LSPSRequestId ,
150
166
} ,
151
167
152
- /// The list of registered webhooks was successfully retrieved
168
+ /// The list of registered webhooks was successfully retrieved.
153
169
///
154
170
/// This event is triggered when the LSP responds to a `lsps5.list_webhooks` request.
155
171
WebhooksListed {
156
- /// The node id of the LSP that provided the list
172
+ /// The node id of the LSP that provided the list.
157
173
counterparty_node_id : PublicKey ,
158
- /// List of app names with registered webhooks
174
+ /// List of app names with registered webhooks.
159
175
app_names : Vec < LSPS5AppName > ,
160
- /// Maximum number of webhooks allowed by LSP
176
+ /// Maximum number of webhooks allowed by LSP.
161
177
max_webhooks : u32 ,
162
- /// The identifier of the issued bLIP-55 / LSPS5 list webhooks request
178
+ /// The identifier of the issued bLIP-55 / LSPS5 list webhooks request.
163
179
///
164
180
/// This can be used to track which request this event corresponds to.
165
181
request_id : LSPSRequestId ,
166
182
} ,
167
183
168
- /// The attempt to list webhooks failed
184
+ /// The attempt to list webhooks failed.
169
185
///
170
186
/// This event is triggered when the LSP rejects a `lsps5.list_webhooks` request.
171
187
WebhooksListFailed {
172
- /// The node id of the LSP that rejected the request
188
+ /// The node id of the LSP that rejected the request.
173
189
counterparty_node_id : PublicKey ,
174
- /// Error code from the LSP
175
- error_code : i32 ,
176
- /// Error message from the LSP
177
- error_message : String ,
178
- /// The identifier of the issued bLIP-55 / LSPS5 list webhooks request
190
+ /// Error from the LSP.
191
+ error : LSPS5Error ,
192
+ /// The identifier of the issued bLIP-55 / LSPS5 list webhooks request.
179
193
///
180
194
/// This can be used to track which request this event corresponds to.
181
195
request_id : LSPSRequestId ,
182
196
} ,
183
197
184
- /// A webhook was successfully removed
198
+ /// A webhook was successfully removed.
185
199
///
186
200
/// This event is triggered when the LSP confirms successful removal
187
201
/// of a webhook via `lsps5.remove_webhook`.
188
202
WebhookRemoved {
189
- /// The node id of the LSP that confirmed the removal
203
+ /// The node id of the LSP that confirmed the removal.
190
204
counterparty_node_id : PublicKey ,
191
- /// The app name that was removed
205
+ /// The app name that was removed.
192
206
app_name : LSPS5AppName ,
193
- /// The identifier of the issued bLIP-55 / LSPS5 remove webhook request
207
+ /// The identifier of the issued bLIP-55 / LSPS5 remove webhook request.
194
208
///
195
209
/// This can be used to track which request this event corresponds to.
196
210
request_id : LSPSRequestId ,
197
211
} ,
198
212
199
- /// A webhook removal attempt failed
213
+ /// A webhook removal attempt failed.
200
214
///
201
215
/// This event is triggered when the LSP rejects a webhook removal
202
216
/// via `lsps5.remove_webhook`. The most common error is app_name_not_found (1010).
203
217
WebhookRemovalFailed {
204
- /// The node id of the LSP that rejected the removal
218
+ /// The node id of the LSP that rejected the removal.
205
219
counterparty_node_id : PublicKey ,
206
- /// Error code from the LSP (1010: app_name_not_found)
207
- error_code : i32 ,
208
- /// Error message from the LSP
209
- error_message : String ,
210
- /// The app name that was attempted to be removed
220
+ /// Error from the LSP.
221
+ error : LSPS5Error ,
222
+ /// The app name that was attempted to be removed.
211
223
app_name : LSPS5AppName ,
212
- /// The identifier of the issued bLIP-55 / LSPS5 remove webhook request
224
+ /// The identifier of the issued bLIP-55 / LSPS5 remove webhook request.
213
225
///
214
226
/// This can be used to track which request this event corresponds to.
215
227
request_id : LSPSRequestId ,
216
228
} ,
217
229
218
- /// A webhook notification was received from the LSP
230
+ /// A webhook notification was received from the LSP.
219
231
///
220
232
/// This event is triggered when the client receives a webhook notification
221
233
/// from the LSP. This can happen for various reasons such as incoming payment,
222
234
/// expiring HTLCs, liquidity management requests, or incoming onion messages.
223
235
WebhookNotificationReceived {
224
- /// LSP node ID that sent the notification
236
+ /// LSP node ID that sent the notification.
225
237
counterparty_node_id : PublicKey ,
226
- /// The notification with its method and parameters
238
+ /// The notification with its method and parameters.
227
239
notification : WebhookNotification ,
228
- /// Timestamp of the notification in ISO8601 format (YYYY-MM-DDThh:mm:ss.uuuZ)
229
- timestamp : String ,
230
- /// Whether the LSP's signature was successfully verified
240
+ /// Timestamp of the notification.
241
+ timestamp : LSPSDateTime ,
242
+ /// Whether the LSP's signature was successfully verified.
231
243
signature_valid : bool ,
232
244
} ,
233
245
}
0 commit comments