Merge pull request lightningdevkit#3510 from tnull/2025-01-start-referring-to-liquidity-blips

Introduce bLIP numbers in `lightning-liquidity` documentation

Author: TheBlueMatt

lightning-liquidity/README.md

@@ -1,15 +1,15 @@
 # lightning-liquidity
 
-The goal of this crate is to provide types and primitives to integrate a spec-compliant LSP with an LDK-based node. To this end, this crate provides client-side as well as service-side logic to implement the [LSP specifications].
+The goal of this crate is to provide types and primitives to integrate a spec-compliant LSP with an LDK-based node. To this end, this crate provides client-side as well as service-side logic to implement the LSPS specifications.
 
 **Note**: Service-side support is currently considered "beta", i.e., not fully
 ready for production use.
 
 Currently the following specifications are supported:
-- [LSPS0] defines the transport protocol with the LSP over which the other protocols communicate.
-- [LSPS1] allows to order Lightning channels from an LSP. This is useful when the client needs
+- [bLIP-50 / LSPS0] defines the transport protocol with the LSP over which the other protocols communicate.
+- [bLIP-51 / LSPS1] allows to order Lightning channels from an LSP. This is useful when the client needs
 inbound Lightning liquidity for which they are willing and able to pay in bitcoin.
-- [LSPS2] allows to generate a special invoice for which, when paid, an LSP
+- [bLIP-52 / LSPS2] allows to generate a special invoice for which, when paid, an LSP
   will open a "just-in-time" channel. This is useful for the initial
   on-boarding of clients as the channel opening fees are deducted from the
   incoming payment, i.e., no funds are required client-side to initiate this
@@ -19,7 +19,6 @@ To get started, you'll want to setup a `LiquidityManager` and configure it to be
 
 `LiquidityManager` uses an eventing system to notify the user about important updates to the protocol flow. To this end, you will need to handle events emitted via one of the event handling methods provided by `LiquidityManager`, e.g., `LiquidityManager::next_event`.
 
-[LSP specifications]: https://github.com/BitcoinAndLightningLayerSpecs/lsp
-[LSPS0]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0
-[LSPS1]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS1
-[LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS2
+[bLIP-50 / LSPS0]: https://github.com/lightning/blips/blob/master/blip-0050.md
+[bLIP-51 / LSPS1]: https://github.com/lightning/blips/blob/master/blip-0051.md
+[bLIP-52 / LSPS2]: https://github.com/lightning/blips/blob/master/blip-0052.md

lightning-liquidity/src/lib.rs

@@ -8,19 +8,21 @@
 // licenses.
 #![crate_name = "lightning_liquidity"]
 
-//! The goal of this crate is to provide types and primitives to integrate a spec-compliant LSP with an LDK-based node. To this end, this crate provides client-side as well as service-side logic to implement the [LSP specifications].
+//! The goal of this crate is to provide types and primitives to integrate a spec-compliant LSP
+//! with an LDK-based node. To this end, this crate provides client-side as well as service-side
+//! logic to implement the LSPS specifications.
 //!
 //! **Note**: Service-side support is currently considered "beta", i.e., not fully ready for
 //! production use.
 //!
 //! Currently the following specifications are supported:
-//! - [LSPS0] defines the transport protocol with the LSP over which the other protocols communicate.
-//! - [LSPS1] allows to order Lightning channels from an LSP. This is useful when the client needs
+//! - [bLIP-50 / LSPS0] defines the transport protocol with the LSP over which the other protocols communicate.
+//! - [bLIP-51 / LSPS1] defines a protocol for ordering Lightning channels from an LSP. This is useful when the client needs
 //! inbound Lightning liquidity for which they are willing and able to pay in bitcoin.
-//! - [LSPS2] allows to generate a special invoice for which, when paid, an LSP will open a
-//! "just-in-time" channel. This is useful for the initial on-boarding of clients as the channel
-//! opening fees are deducted from the incoming payment, i.e., no funds are required client-side to
-//! initiate this flow.
+//! - [bLIP-52 / LSPS2] defines a protocol for generating a special invoice for which, when paid,
+//! an LSP will open a "just-in-time" channel. This is useful for the initial on-boarding of
+//! clients as the channel opening fees are deducted from the incoming payment, i.e., no funds are
+//! required client-side to initiate this flow.
 //!
 //! To get started, you'll want to setup a [`LiquidityManager`] and configure it to be the
 //! [`CustomMessageHandler`] of your LDK node. You can then for example call
@@ -32,10 +34,9 @@
 //! protocol flow. To this end, you will need to handle events emitted via one of the event
 //! handling methods provided by [`LiquidityManager`], e.g., [`LiquidityManager::next_event`].
 //!
-//! [LSP specifications]: https://github.com/BitcoinAndLightningLayerSpecs/lsp
-//! [LSPS0]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0
-//! [LSPS1]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS1
-//! [LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS2
+//! [bLIP-50 / LSPS0]: https://github.com/lightning/blips/blob/master/blip-0050.md
+//! [bLIP-51 / LSPS1]: https://github.com/lightning/blips/blob/master/blip-0051.md
+//! [bLIP-52 / LSPS2]: https://github.com/lightning/blips/blob/master/blip-0052.md
 //! [`CustomMessageHandler`]: lightning::ln::peer_handler::CustomMessageHandler
 //! [`LiquidityManager::next_event`]: crate::LiquidityManager::next_event
 #![deny(missing_docs)]

lightning-liquidity/src/lsps0/client.rs

@@ -1,7 +1,7 @@
-//! Contains the main LSPS0 client-side object, [`LSPS0ClientHandler`].
+//! Contains the main bLIP-50 / LSPS0 client-side object, [`LSPS0ClientHandler`].
 //!
-//! Please refer to the [LSPS0
-//! specifcation](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0) for more
+//! Please refer to the [bLIP-50 / LSPS0
+//! specifcation](https://github.com/lightning/blips/blob/master/blip-0050.md) for more
 //! information.
 
 use crate::events::{Event, EventQueue};
@@ -22,7 +22,7 @@ use bitcoin::secp256k1::PublicKey;
 
 use core::ops::Deref;
 
-/// A message handler capable of sending and handling LSPS0 messages.
+/// A message handler capable of sending and handling bLIP-50 / LSPS0 messages.
 pub struct LSPS0ClientHandler<ES: Deref>
 where
 	ES::Target: EntropySource,
@@ -43,10 +43,10 @@ where
 		Self { entropy_source, pending_messages, pending_events }
 	}
 
-	/// Calls LSPS0's `list_protocols`.
+	/// Calls bLIP-50 / LSPS0's `list_protocols`.
 	///
-	/// Please refer to the [LSPS0
-	/// specifcation](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0#lsps-specification-support-query)
+	/// Please refer to the [bLIP-50 / LSPS0
+	/// specifcation](https://github.com/lightning/blips/blob/master/blip-0050.md#lsps-specification-support-query)
 	/// for more information.
 	pub fn list_protocols(&self, counterparty_node_id: &PublicKey) {
 		let msg = LSPS0Message::Request(

lightning-liquidity/src/lsps0/event.rs

@@ -7,12 +7,12 @@
 // You may not use this file except in accordance with one or both of these
 // licenses.
 
-//! Contains LSPS0 event types
+//! Contains bLIP-50 / LSPS0 event types.
 
 use crate::prelude::Vec;
 use bitcoin::secp256k1::PublicKey;
 
-/// An event which an LSPS0 client may want to take some action in response to.
+/// An event which an bLIP-50 / LSPS0 client may want to take some action in response to.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum LSPS0ClientEvent {
 	/// Information from the LSP about the protocols they support.

lightning-liquidity/src/lsps0/mod.rs

@@ -7,7 +7,7 @@
 // You may not use this file except in accordance with one or both of these
 // licenses.
 
-//! Types and primitives that implement the LSPS0: Transport Layer specification.
+//! Types and primitives that implement the bLIP-50 / LSPS0: Transport Layer specification.
 
 pub mod client;
 pub mod event;

lightning-liquidity/src/lsps0/msgs.rs

@@ -11,24 +11,27 @@ pub(crate) const LSPS0_LISTPROTOCOLS_METHOD_NAME: &str = "lsps0.list_protocols";
 
 /// A `list_protocols` request.
 ///
-/// Please refer to the [LSPS0 specification](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0#lsps-specification-support-query)
+/// Please refer to the [bLIP-50 / LSPS0
+/// specification](https://github.com/lightning/blips/blob/master/blip-0050.md#lsps-specification-support-query)
 /// for more information.
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize, Default)]
 pub struct ListProtocolsRequest {}
 
 /// A response to a `list_protocols` request.
 ///
-/// Please refer to the [LSPS0 specification](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0#lsps-specification-support-query)
+/// Please refer to the [bLIP-50 / LSPS0
+/// specification](https://github.com/lightning/blips/blob/master/blip-0050.md#lsps-specification-support-query)
 /// for more information.
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
 pub struct ListProtocolsResponse {
 	/// A list of supported protocols.
 	pub protocols: Vec<u16>,
 }
 
-/// An LSPS0 protocol request.
+/// An bLIP-50 / LSPS0 protocol request.
 ///
-/// Please refer to the [LSPS0 specification](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0)
+/// Please refer to the [bLIP-50 / LSPS0
+/// specification](https://github.com/lightning/blips/blob/master/blip-0050.md#lsps-specification-support-query)
 /// for more information.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum LSPS0Request {
@@ -45,9 +48,10 @@ impl LSPS0Request {
 	}
 }
 
-/// An LSPS0 protocol request.
+/// An bLIP-50 / LSPS0 protocol request.
 ///
-/// Please refer to the [LSPS0 specification](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0)
+/// Please refer to the [bLIP-50 / LSPS0
+/// specification](https://github.com/lightning/blips/blob/master/blip-0050.md#lsps-specification-support-query)
 /// for more information.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum LSPS0Response {
@@ -57,9 +61,10 @@ pub enum LSPS0Response {
 	ListProtocolsError(ResponseError),
 }
 
-/// An LSPS0 protocol message.
+/// An bLIP-50 / LSPS0 protocol message.
 ///
-/// Please refer to the [LSPS0 specification](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0)
+/// Please refer to the [bLIP-50 / LSPS0
+/// specification](https://github.com/lightning/blips/blob/master/blip-0050.md#lsps-specification-support-query)
 /// for more information.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum LSPS0Message {

lightning-liquidity/src/lsps0/ser.rs

@@ -1,6 +1,8 @@
 //! Contains basic data types that allow for the (de-)seralization of LSPS messages in the JSON-RPC 2.0 format.
 //!
-//! Please refer to the [LSPS0 specification](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0) for more information.
+//! Please refer to the [bLIP-50 / LSPS0
+//! specification](https://github.com/lightning/blips/blob/master/blip-0050.md) for more
+//! information.
 
 use crate::lsps0::msgs::{
 	LSPS0Message, LSPS0Request, LSPS0Response, ListProtocolsRequest,

lightning-liquidity/src/lsps0/service.rs

@@ -7,10 +7,10 @@
 // You may not use this file except in accordance with one or both of these
 // licenses.
 
-//! Contains the main LSPS0 server-side object, [`LSPS0ServiceHandler`].
+//! Contains the main bLIP-50 / LSPS0 server-side object, [`LSPS0ServiceHandler`].
 //!
-//! Please refer to the [LSPS0
-//! specifcation](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0) for more
+//! Please refer to the [bLIP-50 / LSPS0
+//! specifcation](https://github.com/lightning/blips/blob/master/blip-0050.md) for more
 //! information.
 
 use crate::lsps0::msgs::{LSPS0Message, LSPS0Request, LSPS0Response, ListProtocolsResponse};
@@ -24,7 +24,7 @@ use lightning::util::logger::Level;
 
 use bitcoin::secp256k1::PublicKey;
 
-/// The main server-side object allowing to send and receive LSPS0 messages.
+/// The main server-side object allowing to send and receive bLIP-50 / LSPS0 messages.
 pub struct LSPS0ServiceHandler {
 	pending_messages: Arc<MessageQueue>,
 	protocols: Vec<u16>,

lightning-liquidity/src/lsps1/client.rs

@@ -7,7 +7,7 @@
 // You may not use this file except in accordance with one or both of these
 // licenses.
 
-//! Contains the main LSPS1 client object, [`LSPS1ClientHandler`].
+//! Contains the main bLIP-51 / LSPS1 client object, [`LSPS1ClientHandler`].
 
 use super::event::LSPS1ClientEvent;
 use super::msgs::{
@@ -30,7 +30,7 @@ use bitcoin::Address;
 
 use core::ops::Deref;
 
-/// Client-side configuration options for LSPS1 channel requests.
+/// Client-side configuration options for bLIP-51 / LSPS1 channel requests.
 #[derive(Clone, Debug)]
 pub struct LSPS1ClientConfig {
 	/// The maximally allowed channel fees.
@@ -44,7 +44,7 @@ struct PeerState {
 	pending_get_order_requests: HashSet<RequestId>,
 }
 
-/// The main object allowing to send and receive LSPS1 messages.
+/// The main object allowing to send and receive bLIP-51 / LSPS1 messages.
 pub struct LSPS1ClientHandler<ES: Deref>
 where
 	ES::Target: EntropySource,

lightning-liquidity/src/lsps1/event.rs

@@ -7,7 +7,7 @@
 // You may not use this file except in accordance with one or both of these
 // licenses.
 
-//! Contains LSPS1 event types
+//! Contains bLIP-51 / LSPS1 event types
 
 use super::msgs::OrderId;
 use super::msgs::{ChannelInfo, LSPS1Options, OrderParameters, PaymentInfo};
@@ -16,7 +16,7 @@ use crate::lsps0::ser::{RequestId, ResponseError};
 
 use bitcoin::secp256k1::PublicKey;
 
-/// An event which an LSPS1 client should take some action in response to.
+/// An event which an bLIP-51 / LSPS1 client should take some action in response to.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum LSPS1ClientEvent {
 	/// A request previously issued via [`LSPS1ClientHandler::request_supported_options`]
@@ -28,7 +28,7 @@ pub enum LSPS1ClientEvent {
 	/// [`LSPS1ClientHandler::request_supported_options`]: crate::lsps1::client::LSPS1ClientHandler::request_supported_options
 	/// [`LSPS1ClientHandler::create_order`]: crate::lsps1::client::LSPS1ClientHandler::create_order
 	SupportedOptionsReady {
-		/// The identifier of the issued LSPS1 `get_info` request, as returned by
+		/// The identifier of the issued bLIP-51 / LSPS1 `get_info` request, as returned by
 		/// [`LSPS1ClientHandler::request_supported_options`]
 		///
 		/// This can be used to track which request this event corresponds to.
@@ -45,7 +45,7 @@ pub enum LSPS1ClientEvent {
 	///
 	/// [`LSPS1ClientHandler::request_supported_options`]: crate::lsps1::client::LSPS1ClientHandler::request_supported_options
 	SupportedOptionsRequestFailed {
-		/// The identifier of the issued LSPS1 `get_info` request, as returned by
+		/// The identifier of the issued bLIP-51 / LSPS1 `get_info` request, as returned by
 		/// [`LSPS1ClientHandler::request_supported_options`]
 		///
 		/// This can be used to track which request this event corresponds to.
@@ -68,7 +68,7 @@ pub enum LSPS1ClientEvent {
 	///
 	/// [`LSPS1ClientHandler::check_order_status`]: crate::lsps1::client::LSPS1ClientHandler::check_order_status
 	OrderCreated {
-		/// The identifier of the issued LSPS1 `create_order` request, as returned by
+		/// The identifier of the issued bLIP-51 / LSPS1 `create_order` request, as returned by
 		/// [`LSPS1ClientHandler::create_order`]
 		///
 		/// This can be used to track which request this event corresponds to.
@@ -92,7 +92,7 @@ pub enum LSPS1ClientEvent {
 	///
 	/// [`LSPS1ClientHandler::check_order_status`]: crate::lsps1::client::LSPS1ClientHandler::check_order_status
 	OrderStatus {
-		/// The identifier of the issued LSPS1 `get_order` request, as returned by
+		/// The identifier of the issued bLIP-51 / LSPS1 `get_order` request, as returned by
 		/// [`LSPS1ClientHandler::check_order_status`]
 		///
 		/// This can be used to track which request this event corresponds to.