lightning_liquidity/
lib.rs

1// This file is Copyright its original authors, visible in version control
2// history.
3//
4// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
5// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
7// You may not use this file except in accordance with one or both of these
8// licenses.
9#![crate_name = "lightning_liquidity"]
10
11//! 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].
12//!
13//! **Note**: Service-side support is currently considered "beta", i.e., not fully ready for
14//! production use.
15//!
16//! Currently the following specifications are supported:
17//! - [LSPS0] defines the transport protocol with the LSP over which the other protocols communicate.
18//! - [LSPS1] allows to order Lightning channels from an LSP. This is useful when the client needs
19//! inbound Lightning liquidity for which they are willing and able to pay in bitcoin.
20//! - [LSPS2] allows to generate a special invoice for which, when paid, an LSP will open a
21//! "just-in-time" channel. This is useful for the initial on-boarding of clients as the channel
22//! opening fees are deducted from the incoming payment, i.e., no funds are required client-side to
23//! initiate this flow.
24//!
25//! To get started, you'll want to setup a [`LiquidityManager`] and configure it to be the
26//! [`CustomMessageHandler`] of your LDK node. You can then for example call
27//! [`LiquidityManager::lsps1_client_handler`] / [`LiquidityManager::lsps2_client_handler`], or
28//! [`LiquidityManager::lsps2_service_handler`], to access the respective client-side or
29//! service-side handlers.
30//!
31//! [`LiquidityManager`] uses an eventing system to notify the user about important updates to the
32//! protocol flow. To this end, you will need to handle events emitted via one of the event
33//! handling methods provided by [`LiquidityManager`], e.g., [`LiquidityManager::next_event`].
34//!
35//! [LSP specifications]: https://github.com/BitcoinAndLightningLayerSpecs/lsp
36//! [LSPS0]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS0
37//! [LSPS1]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS1
38//! [LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS2
39//! [`CustomMessageHandler`]: lightning::ln::peer_handler::CustomMessageHandler
40//! [`LiquidityManager::next_event`]: crate::LiquidityManager::next_event
41#![deny(missing_docs)]
42#![deny(rustdoc::broken_intra_doc_links)]
43#![deny(rustdoc::private_intra_doc_links)]
44#![allow(bare_trait_objects)]
45#![allow(ellipsis_inclusive_range_patterns)]
46#![allow(clippy::drop_non_drop)]
47#![cfg_attr(docsrs, feature(doc_auto_cfg))]
48#![cfg_attr(not(feature = "std"), no_std)]
49
50#[macro_use]
51extern crate alloc;
52
53mod prelude {
54	#![allow(unused_imports)]
55	pub use alloc::{boxed::Box, collections::VecDeque, string::String, vec, vec::Vec};
56
57	pub use alloc::borrow::ToOwned;
58	pub use alloc::string::ToString;
59
60	pub(crate) use lightning::util::hash_tables::*;
61}
62
63pub mod events;
64pub mod lsps0;
65pub mod lsps1;
66pub mod lsps2;
67mod manager;
68pub mod message_queue;
69#[allow(dead_code)]
70#[allow(unused_imports)]
71mod sync;
72#[cfg(test)]
73mod tests;
74mod utils;
75
76pub use manager::{LiquidityClientConfig, LiquidityManager, LiquidityServiceConfig};
lightning_liquidity/lib.rs

lightning_liquidity/
lib.rs
