Expand description
§Breez SDK - Liquid
This SDK provides developers with an end-to-end solution for integrating self-custodial Lightning payments into their apps and services. It eliminates the need for third-parties, simplifies the complexities of Bitcoin and Lightning, and enables seamless onboarding for billions of users to the future of peer-to-peer payments.
The Liquid implementation is a nodeless Lightning integration. It offers a self-custodial, end-to-end solution for integrating Lightning payments, utilizing the Liquid Network with on-chain interoperability and third-party fiat on-ramps.
- Sending payments (via protocols such as: bolt11, lnurl-pay, lightning address, btc address)
- Receiving payments (via protocols such as: bolt11, lnurl-withdraw, btc address)
- Interacting with a wallet (e.g. balance, max allow to pay, max allow to receive, on-chain balance)
§Getting Started
The following code initialize the SDK and make it ready to be used:
let mnemonic = Mnemonic::generate_in(Language::English, 12)?;
// Create the default config
let mut config = sdk::LiquidSdk::default_config(LiquidNetwork::Mainnet);
// Customize the config object according to your needs
config.working_dir = "path to an existing directory".into();
let connect_request = ConnectRequest {
mnemonic: mnemonic.to_string(),
config,
};
let sdk = sdk::LiquidSdk::connect(connect_request).await?;
We can now receive payments
// Fetch the Receive limits
let current_limits = sdk.fetch_lightning_limits().await?;
info!("Minimum amount: {} sats", current_limits.receive.min_sat);
info!("Maximum amount: {} sats", current_limits.receive.max_sat);
// Set the amount you wish the payer to send, which should be within the above limits
let prepare_receive_response = sdk
.prepare_receive_payment(&PrepareReceiveRequest {
payment_method: PaymentMethod::Lightning,
payer_amount_sat: Some(5_000),
})
.await?;
// If the fees are acceptable, continue to create the Receive Payment
let receive_fees_sat = prepare_receive_response.fees_sat;
let receive_payment_response = sdk.receive_payment(&ReceivePaymentRequest {
description: Some("my description".to_string()),
prepare_response: receive_payment_response,
}).await?;
let destination = receive_payment_response.destination;
or make payments
// Set the BOLT11 invoice or Liquid BIP21/address you wish to pay
let prepare_send_response = sdk
.prepare_send_payment(&PrepareSendRequest {
destination: "invoice or Liquid BIP21/address".to_string(),
amount_sat: Some(3_000),
})
.await?;
// If the fees are acceptable, continue to create the Send Payment
let send_fees_sat = prepare_send_response.fees_sat;
let send_response = sdk.send_payment(&SendPayentRequest {
prepare_response: prepare_send_response,
}).await?;
let payment = send_response.payment;
At any point we can fetch the wallet state
let wallet_info = sdk.get_info().await?;
let balance_sat = wallet_info.balance_sat;
let pending_send_sat = wallet_info.pending_send_sat;
let pending_receive_sat = wallet_info.pending_receive_sat;
or fetch other useful infos, like the current mempool model::RecommendedFees
let fees = sdk.recommended_fees().await?;
These different types of operations are described below in more detail.
§Initializing the SDK
There are two simple steps necessary to initialize the SDK:
- sdk::LiquidSdk::default_config to construct the SDK model::Config
- sdk::LiquidSdk::connect to initialize the sdk::LiquidSdk instance
Although you can create your own config from scratch it is recommended to use the sdk::LiquidSdk::default_config method and customize it according to your needs. Once the model::Config is created it is passed to the sdk::LiquidSdk::connect method along with the mnemonic.
Now your SDK is ready to be used.
§Sending a Lightning payment
- sdk::LiquidSdk::prepare_send_payment to check fees
- sdk::LiquidSdk::send_payment to pay an invoice
§Receiving a Lightning/onchain payment
- sdk::LiquidSdk::prepare_receive_payment to check fees
- sdk::LiquidSdk::receive_payment to generate an invoice/Liquid BIP21/Liquid address
§Sending an onchain payment
- sdk::LiquidSdk::prepare_pay_onchain to check fees
- sdk::LiquidSdk::pay_onchain to pay to a Bitcoin address
§Refunding a payment
- sdk::LiquidSdk::list_refundables to get a list of refundable swaps
- sdk::LiquidSdk::prepare_refund to check the refund fees
- sdk::LiquidSdk::refund to broadcast a refund transaction
§Using LNURL
- parse the LNURL endpoint URL to get the workflow parameters
- sdk::LiquidSdk::lnurl_pay to pay to the parsed LNURL
- sdk::LiquidSdk::lnurl_withdraw to withdraw from the parsed LNURL
§Supporting fiat currencies
- sdk::LiquidSdk::list_fiat_currencies to get the supported fiat currencies
- sdk::LiquidSdk::fetch_fiat_rates to get the current exchange rates
§Utilities
- sdk::LiquidSdk::recommended_fees for the recommended mempool fees
- parse to parse a string into an InputType
- parse_invoice to parse a string into an LNInvoice
§Bindings
- Dart
- Flutter
- Kotlin
- Python
- React-Native
- Swift
§Support
Join this telegram group.
Modules§
- Rust Bitcoin Library
- Rust-Lightning, not Rusty’s Lightning!
- This crate provides data structures to represent lightning BOLT11 invoices and functions to create, encode and decode these. If you just want to use the standard en-/decoding functionality this should get you started:
Macros§
Structs§
- Payload of the AES success action, as received from the LNURL endpoint
- Wrapper for the decrypted AesSuccessActionData payload
- Wrapped in a [BitcoinAddress], this is the result of parse when given a plain or BIP-21 BTC address.
- Details about a supported currency in the fiat rate feed
- Wrapper around the CurrencyInfo of a fiat currency
- Wrapper for a BOLT11 LN invoice
- Wrapped in a [LnUrlAuth], this is the result of [parse] when given a LNURL-auth endpoint.
- Wrapped in a [LnUrlError], this represents a LNURL-endpoint error.
- Represents a LNURL-pay request.
- Wrapped in a [LnUrlPay], this is the result of parse when given a LNURL-pay endpoint.
- Wrapped in a [LnUrlWithdraw], this is the result of parse when given a LNURL-withdraw endpoint.
- Locale-specific settings for the representation of a currency
- Localized name of a currency
- Key-value pair in the LnUrlPayRequestData, as returned by the LNURL-pay endpoint
- Denominator in an exchange rate
- A route hint for a LN payment
- Details of a specific hop in a larger route hint
- Settings for the symbol representation of a currency
Enums§
- Result of decryption of AesSuccessActionData payload
- Different kinds of inputs supported by parse, including any relevant details extracted from the input
- Error returned by [crate::breez_services::BreezServices::lnurl_auth]
- Contains the result of the entire LNURL interaction, as reported by the LNURL endpoint.
- Error returned by [crate::breez_services::BreezServices::lnurl_pay]
- Generic struct containing the possible LNURL payloads returned when contacting a LNURL endpoint
- LnUrlCallbackStatus specific to LNURL-withdraw, where the success case contains the invoice.
- The different supported bitcoin networks
- Supported success action types
- SuccessAction where contents are ready to be consumed by the caller
Statics§
Traits§
- Trait covering fiat-related functionality
Functions§
- Makes a GET request to the specified
url
and logs on DEBUG: - Wrapper around get_and_log_response that, in addition, parses the payload into an expected type.
- Creates an HTTP client with a built-in connection timeout
- Parses generic user input, typically pasted from clipboard or scanned from a QR.
- Parse a BOLT11 payment request and return a structure contains the parsed fields.
- Performs the third and last step of LNURL-auth, as per https://github.com/lnurl/luds/blob/luds/04.md
- Validates invoice and performs the second and last step of LNURL-pay, as per https://github.com/lnurl/luds/blob/luds/06.md
- Validates invoice and performs the second and last step of LNURL-withdraw, as per https://github.com/lnurl/luds/blob/luds/03.md