breez_sdk_liquid/
lib.rs

1#![allow(rustdoc::private_intra_doc_links)]
2//! # Breez SDK - Liquid
3//!
4//! This SDK provides developers with an end-to-end solution for integrating self-custodial Lightning
5//! payments into their apps and services. It eliminates the need for third-parties, simplifies the
6//! complexities of Bitcoin and Lightning, and enables seamless onboarding for billions of users to
7//! the future of peer-to-peer payments.
8//!
9//! The Liquid implementation is a nodeless Lightning integration. It offers a self-custodial,
10//! end-to-end solution for integrating Lightning payments, utilizing the Liquid Network with
11//! on-chain interoperability and third-party fiat on-ramps.
12//!
13//! * Sending payments (via protocols such as: bolt11, lnurl-pay, lightning address, btc address)
14//! * Receiving payments (via protocols such as: bolt11, lnurl-withdraw, btc address)
15//! * Interacting with a wallet (e.g. balance, max allow to pay, max allow to receive, on-chain balance)
16//!
17//! ## Getting Started
18//!
19//! The following code initialize the SDK and make it ready to be used:
20//!
21//! ```ignore
22//! let mnemonic = Mnemonic::generate_in(Language::English, 12)?;
23//!
24//! // Create the default config
25//! let mut config = sdk::LiquidSdk::default_config(LiquidNetwork::Mainnet);
26//!
27//! // Customize the config object according to your needs
28//! config.working_dir = "path to an existing directory".into();
29//!
30//! let connect_request = ConnectRequest {
31//!     mnemonic: mnemonic.to_string(),
32//!     config,
33//! };
34//! let sdk = sdk::LiquidSdk::connect(connect_request).await?;
35//!
36//! ```
37//!
38//! We can now receive payments
39//!
40//! ```ignore
41//! // Fetch the Receive limits
42//! let current_limits = sdk.fetch_lightning_limits().await?;
43//! info!("Minimum amount: {} sats", current_limits.receive.min_sat);
44//! info!("Maximum amount: {} sats", current_limits.receive.max_sat);
45//!
46//! // Set the amount you wish the payer to send, which should be within the above limits
47//! let prepare_receive_response = sdk
48//!     .prepare_receive_payment(&PrepareReceiveRequest {
49//!         payment_method: PaymentMethod::Lightning,
50//!         payer_amount_sat: Some(5_000),
51//!     })
52//!     .await?;
53//!
54//! // If the fees are acceptable, continue to create the Receive Payment
55//! let receive_fees_sat = prepare_receive_response.fees_sat;
56//!
57//! let receive_payment_response = sdk.receive_payment(&ReceivePaymentRequest {
58//!     description: Some("my description".to_string()),
59//!     prepare_response: receive_payment_response,
60//! }).await?;
61//!
62//! let destination = receive_payment_response.destination;
63//! ```
64//!
65//! or make payments
66//! ```ignore
67//! // Set the BOLT11 invoice or Liquid BIP21/address you wish to pay
68//! let prepare_send_response = sdk
69//!     .prepare_send_payment(&PrepareSendRequest {
70//!         destination: "invoice or Liquid BIP21/address".to_string(),
71//!         amount_sat: Some(3_000),
72//!     })
73//!     .await?;
74//!
75//! // If the fees are acceptable, continue to create the Send Payment
76//! let send_fees_sat = prepare_send_response.fees_sat;
77//!
78//! let send_response = sdk.send_payment(&SendPayentRequest {
79//!     prepare_response: prepare_send_response,
80//! }).await?;
81//! let payment = send_response.payment;
82//! ```
83//!
84//! At any point we can fetch the wallet state
85//! ```ignore
86//! let wallet_info = sdk.get_info().await?;
87//! let balance_sat = wallet_info.balance_sat;
88//! let pending_send_sat = wallet_info.pending_send_sat;
89//! let pending_receive_sat = wallet_info.pending_receive_sat;
90//! ```
91//!
92//! or fetch other useful infos, like the current mempool [model::RecommendedFees]
93//! ```ignore
94//! let fees = sdk.recommended_fees().await?;
95//! ```
96//!
97//! These different types of operations are described below in more detail.
98//!
99//! ### Initializing the SDK
100//!
101//! There are two simple steps necessary to initialize the SDK:
102//!
103//! 1. [sdk::LiquidSdk::default_config] to construct the SDK [model::Config]
104//! 2. [sdk::LiquidSdk::connect] to initialize the [sdk::LiquidSdk] instance
105//!
106//! Although you can create your own config from scratch it is recommended to use the
107//! [sdk::LiquidSdk::default_config] method and customize it according to your needs.
108//! Once the [model::Config] is created it is passed to the [sdk::LiquidSdk::connect] method
109//! along with the mnemonic.
110//!
111//! Now your SDK is ready to be used.
112//!
113//! ### Sending a Lightning payment
114//!
115//! * [sdk::LiquidSdk::prepare_send_payment] to check fees
116//! * [sdk::LiquidSdk::send_payment] to pay an invoice
117//!
118//! ### Receiving a Lightning/onchain payment
119//!
120//! * [sdk::LiquidSdk::prepare_receive_payment] to check fees
121//! * [sdk::LiquidSdk::receive_payment] to generate an invoice/Liquid BIP21/Liquid address
122//!
123//! ### Sending an onchain payment
124//!
125//! * [sdk::LiquidSdk::prepare_pay_onchain] to check fees
126//! * [sdk::LiquidSdk::pay_onchain] to pay to a Bitcoin address
127//!
128//! ### Refunding a payment
129//!
130//! * [sdk::LiquidSdk::list_refundables] to get a list of refundable swaps
131//! * [sdk::LiquidSdk::prepare_refund] to check the refund fees
132//! * [sdk::LiquidSdk::refund] to broadcast a refund transaction
133//!
134//! ### Using LNURL
135//!
136//! * [parse] the LNURL endpoint URL to get the workflow parameters
137//! * [sdk::LiquidSdk::lnurl_pay] to pay to the parsed LNURL
138//! * [sdk::LiquidSdk::lnurl_withdraw] to withdraw from the parsed LNURL
139//!
140//! ### Supporting fiat currencies
141//!
142//! * [sdk::LiquidSdk::list_fiat_currencies] to get the supported fiat currencies
143//! * [sdk::LiquidSdk::fetch_fiat_rates] to get the current exchange rates
144
145//! ### Utilities
146//!
147//! * [sdk::LiquidSdk::recommended_fees] for the recommended mempool fees
148//! * [parse] to parse a string into an [InputType]
149//! * [parse_invoice] to parse a string into an [LNInvoice]
150//!
151//!
152//! ## Bindings
153//!
154//! * Dart
155//! * Flutter
156//! * Kotlin
157//! * Python
158//! * React-Native
159//! * Swift
160//!
161//! ## Support
162//!
163//! Join this [telegram group](https://t.me/breezsdk).
164
165#[cfg(feature = "frb")]
166#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
167pub(crate) mod bindings;
168pub(crate) mod buy;
169pub(crate) mod chain;
170pub(crate) mod chain_swap;
171pub mod error;
172pub(crate) mod event;
173#[cfg(feature = "frb")]
174#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
175pub(crate) mod frb_generated;
176pub(crate) mod lnurl;
177#[cfg(not(all(target_family = "wasm", target_os = "unknown")))]
178pub mod logger;
179pub mod model;
180pub(crate) mod payjoin;
181pub mod persist;
182pub mod receive_swap;
183pub(crate) mod recover;
184pub mod sdk;
185pub(crate) mod send_swap;
186pub mod signer;
187pub(crate) mod swapper;
188pub(crate) mod sync;
189#[cfg(feature = "test-utils")]
190pub mod test_utils;
191#[cfg(test)]
192#[cfg(not(feature = "test-utils"))]
193pub(crate) mod test_utils;
194#[allow(hidden_glob_reexports)]
195pub(crate) mod utils;
196pub mod wallet;
197
198pub use lwk_wollet::bitcoin;
199pub use lwk_wollet::elements;
200pub use sdk_common::prelude::*;
201
202#[allow(ambiguous_glob_reexports)]
203#[rustfmt::skip]
204pub mod prelude {
205    pub use crate::*;
206    pub use crate::model::*;
207    pub use crate::sdk::*;
208    pub use crate::signer::SdkSigner;
209    pub use sdk_common::utils::Arc;
210}
breez_sdk_liquid/lib.rs

breez_sdk_liquid/
lib.rs
