From f55dafe2f904342d16d85bb6e3a97663863223c9 Mon Sep 17 00:00:00 2001 From: Srg213 Date: Tue, 26 Dec 2023 13:09:39 +0530 Subject: [PATCH 1/3] Added doc for lsps1/events --- src/lsps1/event.rs | 97 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 73 insertions(+), 24 deletions(-) diff --git a/src/lsps1/event.rs b/src/lsps1/event.rs index 753a5c6..a87305a 100644 --- 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 or the MIT license +// , 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,30 +19,52 @@ 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 params 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 invoice is paid, 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, }, } @@ -41,31 +72,49 @@ pub enum LSPS1ClientEvent { /// 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 LSP + /// and would like to open a channel with the given invoice. + /// + /// 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::send_invoice_for_order`]: crate::lsps1::service::LSPS1ServiceHandler::send_invoice_for_order 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, }, } From aac3418122142ff3c1fae2e470d905cdc7e03050 Mon Sep 17 00:00:00 2001 From: Srg213 Date: Tue, 26 Dec 2023 18:46:01 +0530 Subject: [PATCH 2/3] Added docs for pub fn in lsps1 --- src/lsps1/client.rs | 24 ++++++++++++++++++++++-- src/lsps1/service.rs | 18 ++++++++++++++++-- 2 files changed, 38 insertions(+), 4 deletions(-) diff --git a/src/lsps1/client.rs b/src/lsps1/client.rs index 75e71b4..4c3da4e 100644 --- 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, pending_events: Arc, channel_manager: CM, chain_source: Option, config: LSPS1ClientConfig, @@ -236,7 +237,14 @@ where } } - fn request_for_info(&self, counterparty_node_id: PublicKey, channel_id: u128) { + /// Initiate the creation of an invoice that when paid will open a channel + /// with enough inbound liquidity to be able to receive the payment. + /// + /// `counterparty_node_id` is the node_id of the LSP you would like to use. + /// + /// `token` is an optional String that will be provided to the LSP. + /// It can be used by the LSP as an API key, coupon code, or some other way to identify a user. + 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 +321,14 @@ where Ok(()) } - fn place_order( + /// Used by client to place an order to LSP with the provided parameters. + /// The client agrees to paying an channel fees as per requested by + /// the LSP. + /// + /// 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,6 +481,11 @@ where } } + /// Used by client to check whether payment is received by LSP and status of order. + /// + /// Should be called in response to receiving a [`LSPS1ClientEvent::DisplayOrder`] event. + /// + /// [`LSPS1ClientEvent::DisplayOrder`]: crate::lsps1::event::LSPS1ClientEvent::DisplayOrder fn check_order_status( &self, counterparty_node_id: &PublicKey, order_id: OrderId, channel_id: u128, ) -> Result<(), APIError> { diff --git a/src/lsps1/service.rs b/src/lsps1/service.rs index c7cf665..8eeef56 100644 --- 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, pending_events: Arc, channel_manager: CM, chain_source: Option, 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, expires_at: chrono::DateTime, ) -> 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, ) -> Result<(), APIError> { From 08ffddca6809fd25a2f51d6d5b8dd5737cbe62d4 Mon Sep 17 00:00:00 2001 From: Srg213 Date: Mon, 8 Jan 2024 16:16:12 +0530 Subject: [PATCH 3/3] LSPS1 doc fixes --- src/lsps1/client.rs | 15 ++++++--------- src/lsps1/event.rs | 13 +++++++------ 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/src/lsps1/client.rs b/src/lsps1/client.rs index 4c3da4e..94f55e3 100644 --- a/src/lsps1/client.rs +++ b/src/lsps1/client.rs @@ -237,13 +237,11 @@ where } } - /// Initiate the creation of an invoice that when paid will open a channel - /// with enough inbound liquidity to be able to receive the payment. + /// Retrieve information from the LSP regarding the options supported. /// /// `counterparty_node_id` is the node_id of the LSP you would like to use. /// - /// `token` is an optional String that will be provided to the LSP. - /// It can be used by the LSP as an API key, coupon code, or some other way to identify a user. + /// '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); @@ -321,9 +319,8 @@ where Ok(()) } - /// Used by client to place an order to LSP with the provided parameters. - /// The client agrees to paying an channel fees as per requested by - /// the LSP. + /// 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. /// @@ -481,12 +478,12 @@ where } } - /// Used by client to check whether payment is received by LSP and status of order. + /// 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 - fn check_order_status( + 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 index a87305a..c506692 100644 --- a/src/lsps1/event.rs +++ b/src/lsps1/event.rs @@ -21,12 +21,13 @@ use bitcoin::secp256k1::PublicKey; pub enum LSPS1ClientEvent { /// Information from the LSP about their supported protocol options. /// - /// You must check whether LSP supports the params the client wants and then call + /// 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 + /// [`LSPS1ClientHandler::place_order`]: crate::lsps1::client::LSPS1ClientHandler::place_order GetInfoResponse { /// 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`]. /// @@ -43,7 +44,7 @@ pub enum LSPS1ClientEvent { }, /// Confirmation from the LSP about the order created by the client. /// - /// When the invoice is paid, the LSP will open a channel to you + /// 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 @@ -72,8 +73,8 @@ pub enum LSPS1ClientEvent { /// An event which an LSPS1 server should take some action in response to. #[derive(Clone, Debug, PartialEq, Eq)] pub enum LSPS1ServiceEvent { - /// A client has selected the parameters to use from the supported options of LSP - /// and would like to open a channel with the given invoice. + /// 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 @@ -97,7 +98,7 @@ pub enum LSPS1ServiceEvent { /// You must call [`LSPS1ServiceHandler::update_order_status`] to update the client /// regarding the status of the payment and order. /// - /// [`LSPS1ServiceHandler::send_invoice_for_order`]: crate::lsps1::service::LSPS1ServiceHandler::send_invoice_for_order + /// [`LSPS1ServiceHandler::update_order_status`]: crate::lsps1::service::LSPS1ServiceHandler::update_order_status CheckPaymentConfirmation { /// An identifier that must be passed to [`LSPS1ServiceHandler::update_order_status`]. ///