Introduce bLIP numbers in lightning-liquidity documentation

Recently, LSPS0, 1, and 2 were upstreamed as bLIP-50, 51, and 52,
respectively. Here, we

1. start linking to the bLIPs instead of the LSP spec repository, which
   is likely going to be deprecated.
2. start consistently citing the specs as `bLIP-5X / LSPSX` to avoid any
   confusions and to potentially initiate a process in which the LSP
   specs will be referred to by their bLIP number rather than their LSPS
   number (especially given that any upcoming specs by the LSP
   spec group will directly be drafted as bLIPs going forward).

Author: tnull

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.

lightning-liquidity/src/lsps1/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 LSPS1: Channel Request specification.
+//! Types and primitives that implement the bLIP-51 / LSPS1: Channel Request specification.
 
 pub mod client;
 pub mod event;

lightning-liquidity/src/lsps1/msgs.rs

@@ -1,4 +1,4 @@
-//! Message, request, and other primitive types used to implement LSPS1.
+//! Message, request, and other primitive types used to implement bLIP-51 / LSPS1.
 
 use crate::lsps0::ser::{
 	string_amount, u32_fee_rate, unchecked_address, unchecked_address_option, LSPSMessage,
@@ -31,8 +31,9 @@ pub struct OrderId(pub String);
 
 /// A request made to an LSP to retrieve the supported options.
 ///
-/// Please refer to the [LSPS1 specification](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS1#1-lsps1info)
-/// for more information.
+/// Please refer to the [bLIP-51 / LSPS1
+/// specification](https://github.com/lightning/blips/blob/master/blip-0051.md#1-lsps1get_info) for
+/// more information.
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize, Default)]
 #[serde(default)]
 pub struct GetInfoRequest {}
@@ -78,7 +79,8 @@ pub struct GetInfoResponse {
 
 /// A request made to an LSP to create an order.
 ///
-/// Please refer to the [LSPS1 specification](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS1#2-lsps1create_order)
+/// Please refer to the [bLIP-51 / LSPS1
+/// specification](https://github.com/lightning/blips/blob/master/blip-0051.md#2-lsps1create_order)
 /// for more information.
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
 pub struct CreateOrderRequest {
@@ -92,7 +94,7 @@ pub struct CreateOrderRequest {
 	pub refund_onchain_address: Option<Address>,
 }
 
-/// An object representing an LSPS1 channel order.
+/// An object representing an bLIP-51 / LSPS1 channel order.
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
 pub struct OrderParameters {
 	/// Indicates how many satoshi the LSP will provide on their side.
@@ -244,15 +246,16 @@ pub struct ChannelInfo {
 
 /// A request made to an LSP to retrieve information about an previously made order.
 ///
-/// Please refer to the [LSPS1 specification](https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS1#21-lsps1get_order)
+/// Please refer to the [bLIP-51 / LSPS1
+/// specification](https://github.com/lightning/blips/blob/master/blip-0051.md#21-lsps1get_order)
 /// for more information.
 #[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
 pub struct GetOrderRequest {
 	/// The id of the order.
 	pub order_id: OrderId,
 }
 
-/// An enum that captures all the valid JSON-RPC requests in the LSPS1 protocol.
+/// An enum that captures all the valid JSON-RPC requests in the bLIP-51 / LSPS1 protocol.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum LSPS1Request {
 	/// A request to learn about the options supported by the LSP.
@@ -263,7 +266,7 @@ pub enum LSPS1Request {
 	GetOrder(GetOrderRequest),
 }
 
-/// An enum that captures all the valid JSON-RPC responses in the LSPS1 protocol.
+/// An enum that captures all the valid JSON-RPC responses in the bLIP-51 / LSPS1 protocol.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum LSPS1Response {
 	/// A successful response to a [`GetInfoRequest`].
@@ -280,7 +283,7 @@ pub enum LSPS1Response {
 	GetOrderError(ResponseError),
 }
 
-/// An enum that captures all valid JSON-RPC messages in the LSPS1 protocol.
+/// An enum that captures all valid JSON-RPC messages in the bLIP-51 / LSPS1 protocol.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum LSPS1Message {
 	/// An LSPS1 JSON-RPC request.