diff --git a/src/lsps1/client.rs b/src/lsps1/client.rs index 75e71b4..94f55e3 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,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 index 753a5c6..c506692 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,53 @@ 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, }, } @@ -41,31 +73,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 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 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> {