Improve documentation for LSPS1 (#77)

Srg213 · web-flow · commit 832b0b3ad069 · 2024-01-10T09:22:44.000+01:00
* Added doc for lsps1/events

* Added docs for pub fn in lsps1

* LSPS1 doc fixes
diff --git a/src/lsps1/client.rs b/src/lsps1/client.rs
@@ -221,6 +221,7 @@ where
 	C::Target: Filter,
 	ES::Target: EntropySource,
 {
+	/// Constructs an `LSPS1ClientHandler`.
 	pub(crate) fn new(
 		entropy_source: ES, pending_messages: Arc<MessageQueue>, pending_events: Arc<EventQueue>,
 		channel_manager: CM, chain_source: Option<C>, config: LSPS1ClientConfig,
@@ -236,7 +237,12 @@ where
 		}
 	}
 
-	fn request_for_info(&self, counterparty_node_id: PublicKey, channel_id: u128) {
+	/// Retrieve information from the LSP regarding the options supported.
+	///
+	/// `counterparty_node_id` is the node_id of the LSP you would like to use.
+	///
+	/// 'channel_id' is the id used to uniquely identify the channel with counterparty node.
+	pub fn request_for_info(&self, counterparty_node_id: PublicKey, channel_id: u128) {
 		let channel = InboundCRChannel::new(channel_id);
 
 		let mut outer_state_lock = self.per_peer_state.write().unwrap();
@@ -313,7 +319,13 @@ where
 		Ok(())
 	}
 
-	fn place_order(
+	/// Places an order with the connected LSP given its `counterparty_node_id`.
+	/// The client agrees to paying channel fees according to the provided parameters.
+	///
+	/// Should be called in response to receiving a [`LSPS1ClientEvent::GetInfoResponse`] event.
+	///
+	/// [`LSPS1ClientEvent::GetInfoResponse`]: crate::lsps1::event::LSPS1ClientEvent::GetInfoResponse
+	pub fn place_order(
 		&self, channel_id: u128, counterparty_node_id: &PublicKey, order: OrderParams,
 	) -> Result<(), APIError> {
 		let outer_state_lock = self.per_peer_state.write().unwrap();
@@ -466,7 +478,12 @@ where
 		}
 	}
 
-	fn check_order_status(
+	/// Queries the status of a pending payment, i.e., whether a payment has been received by the LSP.
+	///
+	/// Should be called in response to receiving a [`LSPS1ClientEvent::DisplayOrder`] event.
+	///
+	/// [`LSPS1ClientEvent::DisplayOrder`]: crate::lsps1::event::LSPS1ClientEvent::DisplayOrder
+	pub fn check_order_status(
 		&self, counterparty_node_id: &PublicKey, order_id: OrderId, channel_id: u128,
 	) -> Result<(), APIError> {
 		let outer_state_lock = self.per_peer_state.write().unwrap();
diff --git a/src/lsps1/event.rs b/src/lsps1/event.rs
@@ -1,3 +1,12 @@
+// 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.
+
 //! Contains LSPS1 event types
 
 use super::msgs::{ChannelInfo, OptionsSupported, OrderId, OrderParams, OrderPayment};
@@ -10,62 +19,103 @@ use bitcoin::secp256k1::PublicKey;
 /// An event which an LSPS1 client should take some action in response to.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum LSPS1ClientEvent {
-	/// TODO
+	/// Information from the LSP about their supported protocol options.
+	///
+	/// You must check whether LSP supports the parameters the client wants and then call
+	/// [`LSPS1ClientHandler::place_order`] to place an order.
+	///
+	/// [`LSPS1ClientHandler::place_order`]: crate::lsps1::client::LSPS1ClientHandler::place_order
 	GetInfoResponse {
-		/// TODO
+		/// This is a randomly generated identifier used to track the channel state.
+		///
+		/// It is not related in anyway to the eventual lightning channel id.
+		/// It needs to be passed to [`LSPS1ClientHandler::place_order`].
+		///
+		/// [`LSPS1ClientHandler::place_order`]: crate::lsps1::client::LSPS1ClientHandler::place_order
 		id: u128,
-		/// TODO
+		/// An identifier to track messages received.
 		request_id: RequestId,
-		/// TODO
+		/// The node id of the LSP that provided this response.
 		counterparty_node_id: PublicKey,
-		/// TODO
+		/// The website of the LSP.
 		website: String,
-		/// TODO
+		/// All options supported by the LSP.
 		options_supported: OptionsSupported,
 	},
-	/// TODO
+	/// Confirmation from the LSP about the order created by the client.
+	///
+	/// When the payment is confirmed, the LSP will open a channel to you
+	/// with the below agreed upon parameters.
+	///
+	/// You must pay the invoice if you want to continue and then
+	/// call [`LSPS1ClientHandler::check_order_status`] with the order id
+	/// to get information from LSP about progress of the order.
+	///
+	/// [`LSPS1ClientHandler::check_order_status`]: crate::lsps1::client::LSPS1ClientHandler::check_order_status
 	DisplayOrder {
-		/// TODO
+		/// This is a randomly generated identifier used to track the channel state.
+		/// It is not related in anyway to the eventual lightning channel id.
+		/// It needs to be passed to [`LSPS1ClientHandler::check_order_status`].
+		///
+		/// [`LSPS1ClientHandler::check_order_status`]: crate::lsps1::client::LSPS1ClientHandler::check_order_status
 		id: u128,
-		/// TODO
+		/// The node id of the LSP.
 		counterparty_node_id: PublicKey,
-		/// TODO
+		/// The order created by client and approved by LSP.
 		order: OrderParams,
-		/// TODO
+		/// The details regarding payment of the order
 		payment: OrderPayment,
-		/// TODO
+		/// The details regarding state of the channel ordered.
 		channel: Option<ChannelInfo>,
 	},
 }
 
 /// An event which an LSPS1 server should take some action in response to.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum LSPS1ServiceEvent {
-	/// TODO
+	/// A client has selected the parameters to use from the supported options of the LSP
+	/// and would like to open a channel with the given payment parameters.
+	///
+	/// You must call [`LSPS1ServiceHandler::send_invoice_for_order`] to
+	/// generate a complete invoice including the details regarding the
+	/// payment and order id for this order for the client.
+	///
+	/// [`LSPS1ServiceHandler::send_invoice_for_order`]: crate::lsps1::service::LSPS1ServiceHandler::send_invoice_for_order
 	CreateInvoice {
-		/// TODO
+		/// An identifier that must be passed to [`LSPS1ServiceHandler::send_invoice_for_order`].
+		///
+		/// [`LSPS1ServiceHandler::send_invoice_for_order`]: crate::lsps1::service::LSPS1ServiceHandler::send_invoice_for_order
 		request_id: RequestId,
-		/// TODO
+		/// The node id of the client making the information request.
 		counterparty_node_id: PublicKey,
-		/// TODO
+		/// The order requested by the client.
 		order: OrderParams,
 	},
-	/// TODO
+	/// A request from client to check the status of the payment.
+	///
+	/// An event to poll for checking payment status either onchain or lightning.
+	///
+	/// You must call [`LSPS1ServiceHandler::update_order_status`] to update the client
+	/// regarding the status of the payment and order.
+	///
+	/// [`LSPS1ServiceHandler::update_order_status`]: crate::lsps1::service::LSPS1ServiceHandler::update_order_status
 	CheckPaymentConfirmation {
-		/// TODO
+		/// An identifier that must be passed to [`LSPS1ServiceHandler::update_order_status`].
+		///
+		/// [`LSPS1ServiceHandler::update_order_status`]: crate::lsps1::service::LSPS1ServiceHandler::update_order_status
 		request_id: RequestId,
-		/// TODO
+		/// The node id of the client making the information request.
 		counterparty_node_id: PublicKey,
-		/// TODO
+		/// The order id of order with pending payment.
 		order_id: OrderId,
 	},
-	/// TODO
+	/// If error is encountered, refund the amount if paid by the client.
 	Refund {
-		/// TODO
+		/// An identifier.
 		request_id: RequestId,
-		/// TODO
+		/// The node id of the client making the information request.
 		counterparty_node_id: PublicKey,
-		/// TODO
+		/// The order id of the refunded order.
 		order_id: OrderId,
 	},
 }
diff --git a/src/lsps1/service.rs b/src/lsps1/service.rs
@@ -152,6 +152,7 @@ where
 	C::Target: Filter,
 	ES::Target: EntropySource,
 {
+	/// Constructs a `LSPS1ServiceHandler`.
 	pub(crate) fn new(
 		entropy_source: ES, pending_messages: Arc<MessageQueue>, pending_events: Arc<EventQueue>,
 		channel_manager: CM, chain_source: Option<C>, config: LSPS1ServiceConfig,
@@ -232,7 +233,12 @@ where
 		Ok(())
 	}
 
-	fn send_invoice_for_order(
+	/// Used by LSP to send invoice containing details regarding the channel fees and payment information.
+	///
+	/// Should be called in response to receiving a [`LSPS1ServiceEvent::CreateInvoice`] event.
+	///
+	/// [`LSPS1ServiceEvent::CreateInvoice`]: crate::lsps1::event::LSPS1ServiceEvent::CreateInvoice
+	pub fn send_invoice_for_order(
 		&self, request_id: RequestId, counterparty_node_id: &PublicKey, payment: OrderPayment,
 		created_at: chrono::DateTime<Utc>, expires_at: chrono::DateTime<Utc>,
 	) -> Result<(), APIError> {
@@ -342,7 +348,15 @@ where
 		Ok(())
 	}
 
-	fn update_order_status(
+	/// Used by LSP to give details to client regarding the status of channel opening.
+	/// Called to respond to client's GetOrder request.
+	/// The LSP continously polls for checking payment confirmation on-chain or lighting
+	/// and then responds to client request.
+	///
+	/// Should be called in response to receiving a [`LSPS1ServiceEvent::CheckPaymentConfirmation`] event.
+	///
+	/// [`LSPS1ServiceEvent::CheckPaymentConfirmation`]: crate::lsps1::event::LSPS1ServiceEvent::CheckPaymentConfirmation
+	pub fn update_order_status(
 		&self, request_id: RequestId, counterparty_node_id: PublicKey, order_id: OrderId,
 		order_state: OrderState, channel: Option<ChannelInfo>,
 	) -> Result<(), APIError> {
