lightning_liquidity/lsps1/
event.rs

1// This file is Copyright its original authors, visible in version control
2// history.
3//
4// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
5// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
7// You may not use this file except in accordance with one or both of these
8// licenses.
9
10//! Contains bLIP-51 / LSPS1 event types
11
12use super::msgs::LSPS1OrderId;
13use super::msgs::{LSPS1ChannelInfo, LSPS1Options, LSPS1OrderParams, LSPS1PaymentInfo};
14
15use crate::lsps0::ser::{LSPSRequestId, LSPSResponseError};
16
17use bitcoin::secp256k1::PublicKey;
18
19/// An event which an bLIP-51 / LSPS1 client should take some action in response to.
20#[derive(Clone, Debug, PartialEq, Eq)]
21pub enum LSPS1ClientEvent {
22	/// A request previously issued via [`LSPS1ClientHandler::request_supported_options`]
23	/// succeeded as the LSP returned the options it supports.
24	///
25	/// You must check whether LSP supports the parameters the client wants and then call
26	/// [`LSPS1ClientHandler::create_order`] to place an order.
27	///
28	/// **Note: ** This event will *not* be persisted across restarts.
29	///
30	/// [`LSPS1ClientHandler::request_supported_options`]: crate::lsps1::client::LSPS1ClientHandler::request_supported_options
31	/// [`LSPS1ClientHandler::create_order`]: crate::lsps1::client::LSPS1ClientHandler::create_order
32	SupportedOptionsReady {
33		/// The identifier of the issued bLIP-51 / LSPS1 `get_info` request, as returned by
34		/// [`LSPS1ClientHandler::request_supported_options`]
35		///
36		/// This can be used to track which request this event corresponds to.
37		///
38		/// [`LSPS1ClientHandler::request_supported_options`]: crate::lsps1::client::LSPS1ClientHandler::request_supported_options
39		request_id: LSPSRequestId,
40		/// The node id of the LSP that provided this response.
41		counterparty_node_id: PublicKey,
42		/// All options supported by the LSP.
43		supported_options: LSPS1Options,
44	},
45	/// A request previously issued via [`LSPS1ClientHandler::request_supported_options`]
46	/// failed as the LSP returned an error response.
47	///
48	/// **Note: ** This event will *not* be persisted across restarts.
49	///
50	/// [`LSPS1ClientHandler::request_supported_options`]: crate::lsps1::client::LSPS1ClientHandler::request_supported_options
51	SupportedOptionsRequestFailed {
52		/// The identifier of the issued bLIP-51 / LSPS1 `get_info` request, as returned by
53		/// [`LSPS1ClientHandler::request_supported_options`]
54		///
55		/// This can be used to track which request this event corresponds to.
56		///
57		/// [`LSPS1ClientHandler::request_supported_options`]: crate::lsps1::client::LSPS1ClientHandler::request_supported_options
58		request_id: LSPSRequestId,
59		/// The node id of the LSP that provided this response.
60		counterparty_node_id: PublicKey,
61		/// The error that was returned.
62		error: LSPSResponseError,
63	},
64	/// Confirmation from the LSP about the order created by the client.
65	///
66	/// When the payment is confirmed, the LSP will open a channel to you
67	/// with the below agreed upon parameters.
68	///
69	/// You must pay the invoice or onchain address if you want to continue and then
70	/// call [`LSPS1ClientHandler::check_order_status`] with the order id
71	/// to get information from LSP about progress of the order.
72	///
73	/// **Note: ** This event will *not* be persisted across restarts.
74	///
75	/// [`LSPS1ClientHandler::check_order_status`]: crate::lsps1::client::LSPS1ClientHandler::check_order_status
76	OrderCreated {
77		/// The identifier of the issued bLIP-51 / LSPS1 `create_order` request, as returned by
78		/// [`LSPS1ClientHandler::create_order`]
79		///
80		/// This can be used to track which request this event corresponds to.
81		///
82		/// [`LSPS1ClientHandler::create_order`]: crate::lsps1::client::LSPS1ClientHandler::create_order
83		request_id: LSPSRequestId,
84		/// The node id of the LSP.
85		counterparty_node_id: PublicKey,
86		/// The id of the channel order.
87		order_id: LSPS1OrderId,
88		/// The order created by client and approved by LSP.
89		order: LSPS1OrderParams,
90		/// The details regarding payment of the order
91		payment: LSPS1PaymentInfo,
92		/// The details regarding state of the channel ordered.
93		channel: Option<LSPS1ChannelInfo>,
94	},
95	/// Information from the LSP about the status of a previously created order.
96	///
97	/// Will be emitted in response to calling [`LSPS1ClientHandler::check_order_status`].
98	///
99	/// **Note: ** This event will *not* be persisted across restarts.
100	///
101	/// [`LSPS1ClientHandler::check_order_status`]: crate::lsps1::client::LSPS1ClientHandler::check_order_status
102	OrderStatus {
103		/// The identifier of the issued bLIP-51 / LSPS1 `get_order` request, as returned by
104		/// [`LSPS1ClientHandler::check_order_status`]
105		///
106		/// This can be used to track which request this event corresponds to.
107		///
108		/// [`LSPS1ClientHandler::check_order_status`]: crate::lsps1::client::LSPS1ClientHandler::check_order_status
109		request_id: LSPSRequestId,
110		/// The node id of the LSP.
111		counterparty_node_id: PublicKey,
112		/// The id of the channel order.
113		order_id: LSPS1OrderId,
114		/// The order created by client and approved by LSP.
115		order: LSPS1OrderParams,
116		/// The details regarding payment of the order
117		payment: LSPS1PaymentInfo,
118		/// The details regarding state of the channel ordered.
119		channel: Option<LSPS1ChannelInfo>,
120	},
121	/// A request previously issued via [`LSPS1ClientHandler::create_order`] or [`LSPS1ClientHandler::check_order_status`].
122	/// failed as the LSP returned an error response.
123	///
124	/// **Note: ** This event will *not* be persisted across restarts.
125	///
126	/// [`LSPS1ClientHandler::create_order`]: crate::lsps1::client::LSPS1ClientHandler::create_order
127	/// [`LSPS1ClientHandler::check_order_status`]: crate::lsps1::client::LSPS1ClientHandler::check_order_status
128	OrderRequestFailed {
129		/// The identifier of the issued LSPS1 `create_order` or `get_order` request, as returned by
130		/// [`LSPS1ClientHandler::create_order`] or [`LSPS1ClientHandler::check_order_status`].
131		///
132		/// This can be used to track which request this event corresponds to.
133		///
134		/// [`LSPS1ClientHandler::create_order`]: crate::lsps1::client::LSPS1ClientHandler::create_order
135		/// [`LSPS1ClientHandler::check_order_status`]: crate::lsps1::client::LSPS1ClientHandler::check_order_status
136		request_id: LSPSRequestId,
137		/// The node id of the LSP.
138		counterparty_node_id: PublicKey,
139		/// The error that was returned.
140		error: LSPSResponseError,
141	},
142}
143
144/// An event which an LSPS1 server should take some action in response to.
145#[cfg(lsps1_service)]
146#[derive(Clone, Debug, PartialEq, Eq)]
147pub enum LSPS1ServiceEvent {
148	/// A client has selected the parameters to use from the supported options of the LSP
149	/// and would like to open a channel with the given payment parameters.
150	///
151	/// You must call [`LSPS1ServiceHandler::send_payment_details`] to
152	/// send order parameters including the details regarding the
153	/// payment and order id for this order for the client.
154	///
155	/// **Note: ** This event will *not* be persisted across restarts.
156	///
157	/// [`LSPS1ServiceHandler::send_payment_details`]: crate::lsps1::service::LSPS1ServiceHandler::send_payment_details
158	RequestForPaymentDetails {
159		/// An identifier that must be passed to [`LSPS1ServiceHandler::send_payment_details`].
160		///
161		/// [`LSPS1ServiceHandler::send_payment_details`]: crate::lsps1::service::LSPS1ServiceHandler::send_payment_details
162		request_id: LSPSRequestId,
163		/// The node id of the client making the information request.
164		counterparty_node_id: PublicKey,
165		/// The order requested by the client.
166		order: LSPS1OrderParams,
167	},
168	/// A request from client to check the status of the payment.
169	///
170	/// An event to poll for checking payment status either onchain or lightning.
171	///
172	/// You must call [`LSPS1ServiceHandler::update_order_status`] to update the client
173	/// regarding the status of the payment and order.
174	///
175	/// **Note: ** This event will *not* be persisted across restarts.
176	///
177	/// [`LSPS1ServiceHandler::update_order_status`]: crate::lsps1::service::LSPS1ServiceHandler::update_order_status
178	CheckPaymentConfirmation {
179		/// An identifier that must be passed to [`LSPS1ServiceHandler::update_order_status`].
180		///
181		/// [`LSPS1ServiceHandler::update_order_status`]: crate::lsps1::service::LSPS1ServiceHandler::update_order_status
182		request_id: LSPSRequestId,
183		/// The node id of the client making the information request.
184		counterparty_node_id: PublicKey,
185		/// The order id of order with pending payment.
186		order_id: LSPS1OrderId,
187	},
188	/// If error is encountered, refund the amount if paid by the client.
189	///
190	/// **Note: ** This event will *not* be persisted across restarts.
191	Refund {
192		/// An identifier.
193		request_id: LSPSRequestId,
194		/// The node id of the client making the information request.
195		counterparty_node_id: PublicKey,
196		/// The order id of the refunded order.
197		order_id: LSPS1OrderId,
198	},
199}
lightning_liquidity/lsps1/event.rs

lightning_liquidity/lsps1/
event.rs
