Cleanup API names in LSPS2 client flow

In order to make the API flow a bit more intuitive, we rename the
corresponding methods and events:

- `create_invoice` -> `request_opening_params`
- `opening_fee_params_selected` -> `select_opening_params`
- `LSPS2ClientEvent::GetInfoResponse` -> `OpeningParametersReady`
- `LSPS2ClientEvent::InvoiceGenerationReady` -> `InvoiceParametersReady`

We also cleanup the docs a bit.

Author: tnull

src/lsps2/client.rs

@@ -203,20 +203,26 @@ 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.
+	/// Request the channel opening parameters from the LSP.
 	///
-	/// `counterparty_node_id` is the node_id of the LSP you would like to use.
+	/// This initiates the JIT-channel flow that, at the end of it, will have the LSP
+	/// open a channel with sufficient inbound liquidity to be able to receive the payment.
+	///
+	/// The user will receive the LSP's response via an [`OpeningParametersReady`] event.
+	///
+	/// `counterparty_node_id` is the `node_id` of the LSP you would like to use.
 	///
 	/// If `payment_size_msat` is [`Option::Some`] then the invoice will be for a fixed amount
 	/// and MPP can be used to pay it.
 	///
 	/// If `payment_size_msat` is [`Option::None`] then the invoice can be for an arbitrary amount
 	/// but MPP can no longer be used to pay it.
 	///
-	/// `token` is an optional String that will be provided to the LSP.
+	/// `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 create_invoice(
+	///
+	/// [`OpeningParametersReady`]: crate::lsps2::event::LSPS2ClientEvent::OpeningParametersReady
+	pub fn request_opening_params(
 		&self, counterparty_node_id: PublicKey, payment_size_msat: Option<u64>,
 		token: Option<String>, user_channel_id: u128,
 	) {
@@ -239,14 +245,19 @@ where
 		);
 	}
 
-	/// Used by client to confirm which channel parameters to use for the JIT Channel buy request.
+	/// Confirms a set of chosen channel opening parameters to use for the JIT channel and
+	/// requests the necessary invoice generation parameters from the LSP.
+	///
+	/// Should be called in response to receiving a [`OpeningParametersReady`] event.
+	///
+	/// The user will receive the LSP's response via an [`InvoiceParametersReady`] event.
+	///
 	/// The client agrees to paying an opening fee equal to
 	/// `max(min_fee_msat, proportional*(payment_size_msat/1_000_000))`.
 	///
-	/// Should be called in response to receiving a [`LSPS2ClientEvent::GetInfoResponse`] event.
-	///
-	/// [`LSPS2ClientEvent::GetInfoResponse`]: crate::lsps2::event::LSPS2ClientEvent::GetInfoResponse
-	pub fn opening_fee_params_selected(
+	/// [`OpeningParametersReady`]: crate::lsps2::event::LSPS2ClientEvent::OpeningParametersReady
+	/// [`InvoiceParametersReady`]: crate::lsps2::event::LSPS2ClientEvent::InvoiceParametersReady
+	pub fn select_opening_params(
 		&self, counterparty_node_id: PublicKey, jit_channel_id: u128,
 		opening_fee_params: OpeningFeeParams,
 	) -> Result<(), APIError> {
@@ -334,7 +345,7 @@ where
 				}
 
 				self.pending_events.enqueue(Event::LSPS2Client(
-					LSPS2ClientEvent::GetInfoResponse {
+					LSPS2ClientEvent::OpeningParametersReady {
 						counterparty_node_id: *counterparty_node_id,
 						opening_fee_params_menu: result.opening_fee_params_menu,
 						min_payment_size_msat: result.min_payment_size_msat,
@@ -442,7 +453,7 @@ where
 
 				if let Ok(intercept_scid) = result.intercept_scid.to_scid() {
 					self.pending_events.enqueue(Event::LSPS2Client(
-						LSPS2ClientEvent::InvoiceGenerationReady {
+						LSPS2ClientEvent::InvoiceParametersReady {
 							counterparty_node_id: *counterparty_node_id,
 							intercept_scid,
 							cltv_expiry_delta: result.lsp_cltv_expiry_delta,

src/lsps2/event.rs

@@ -20,16 +20,24 @@ use bitcoin::secp256k1::PublicKey;
 pub enum LSPS2ClientEvent {
 	/// Information from the LSP about their current fee rates and channel parameters.
 	///
-	/// You must call [`LSPS2ClientHandler::opening_fee_params_selected`] with the fee parameter
+	/// You must call [`LSPS2ClientHandler::select_opening_params`] with the fee parameter
 	/// you want to use if you wish to proceed opening a channel.
 	///
-	/// [`LSPS2ClientHandler::opening_fee_params_selected`]: crate::lsps2::client::LSPS2ClientHandler::opening_fee_params_selected
-	GetInfoResponse {
+	/// [`LSPS2ClientHandler::select_opening_params`]: crate::lsps2::client::LSPS2ClientHandler::select_opening_params
+	OpeningParametersReady {
+		/// A user-specified identifier used to track the channel open.
+		///
+		/// This is the same value as previously passed to
+		/// [`LSPS2ClientHandler::request_opening_params`].
+		///
+		/// [`LSPS2ClientHandler::request_opening_params`]: crate::lsps2::client::LSPS2ClientHandler::request_opening_params
+		user_channel_id: u128,
 		/// This is a randomly generated identifier used to track the JIT channel state.
-		/// It is not related in anyway to the eventual lightning channel id.
-		/// It needs to be passed to [`LSPS2ClientHandler::opening_fee_params_selected`].
 		///
-		/// [`LSPS2ClientHandler::opening_fee_params_selected`]: crate::lsps2::client::LSPS2ClientHandler::opening_fee_params_selected
+		/// It is not related in anyway to the eventual lightning channel id, but needs to be
+		/// given to [`LSPS2ClientHandler::select_opening_params`].
+		///
+		/// [`LSPS2ClientHandler::select_opening_params`]: crate::lsps2::client::LSPS2ClientHandler::select_opening_params
 		jit_channel_id: u128,
 		/// The node id of the LSP that provided this response.
 		counterparty_node_id: PublicKey,
@@ -40,16 +48,20 @@ pub enum LSPS2ClientEvent {
 		min_payment_size_msat: u64,
 		/// The max payment size allowed when opening the channel.
 		max_payment_size_msat: u64,
-		/// The user_channel_id value passed in to [`LSPS2ClientHandler::create_invoice`].
-		///
-		/// [`LSPS2ClientHandler::create_invoice`]: crate::lsps2::client::LSPS2ClientHandler::create_invoice
-		user_channel_id: u128,
 	},
-	/// Use the provided fields to generate an invoice and give to payer.
+	/// Provides the necessary information to generate a payable invoice that then may be given to
+	/// the payer.
 	///
-	/// When the invoice is paid the LSP will open a channel to you
-	/// with the previously agreed upon parameters.
-	InvoiceGenerationReady {
+	/// When the invoice is paid, the LSP will open a channel with the previously agreed upon
+	/// parameters to you.
+	InvoiceParametersReady {
+		/// A user-specified identifier used to track the channel open.
+		///
+		/// This is the same value as previously passed to
+		/// [`LSPS2ClientHandler::select_opening_params`].
+		///
+		/// [`LSPS2ClientHandler::select_opening_params`]: crate::lsps2::client::LSPS2ClientHandler::select_opening_params
+		user_channel_id: u128,
 		/// The node id of the LSP.
 		counterparty_node_id: PublicKey,
 		/// The intercept short channel id to use in the route hint.
@@ -58,10 +70,6 @@ pub enum LSPS2ClientEvent {
 		cltv_expiry_delta: u32,
 		/// The initial payment size you specified.
 		payment_size_msat: Option<u64>,
-		/// The `user_channel_id` value passed in to [`LSPS2ClientHandler::create_invoice`].
-		///
-		/// [`LSPS2ClientHandler::create_invoice`]: crate::lsps2::client::LSPS2ClientHandler::create_invoice
-		user_channel_id: u128,
 	},
 }