Crate breez_sdk_liquid

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, None).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.

§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.

Re-exports§

pub use lwk_wollet::bitcoin;
pub use lwk_wollet::elements;

Modules§

error
grpc
input_parser
invoice
lightning: Rust-Lightning, not Rusty’s Lightning!
lightning_invoice: 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:
lightning_with_bolt12: Rust-Lightning, not Rusty’s Lightning!
liquid
logger
model
moonpay
persist
plugin
prelude
receive_swap
sdk
signer
specs
tonic_wrap
wallet

Macros§

ensure_sdk
get_updated_fields
with_connection_retry: Executes the given grpc call function. If an error is returned that indicates the connection broke, the call is tried again.

Structs§

AesSuccessActionData: Payload of the AES success action, as received from the LNURL endpoint
AesSuccessActionDataDecrypted: Wrapper for the decrypted AesSuccessActionData payload
ApiKeyInterceptor
BitcoinAddressData: Wrapped in a [BitcoinAddress], this is the result of parse when given a plain or BIP-21 BTC address.
BoltzSwapperUrls
BreezServer
CallbackResponse
CurrencyInfo: Details about a supported currency in the fiat rate feed
ExternalInputParser: Configuration for an external input parser
FiatCurrency: Wrapper around the CurrencyInfo of a fiat currency
LNInvoice: Wrapper for a BOLT11 LN invoice
LNOffer
LiquidAddressData
LnOfferBlindedPath
LnUrlAuthRequestData: Wrapped in a [LnUrlAuth], this is the result of [parse] when given a LNURL-auth endpoint.
LnUrlErrorData: Wrapped in a [LnUrlError], this represents a LNURL-endpoint error.
LnUrlPayErrorData
LnUrlPayRequest: Represents a LNURL-pay request.
LnUrlPayRequestData: Wrapped in a [LnUrlPay], this is the result of parse when given a LNURL-pay endpoint.
LnUrlPaySuccessData
LnUrlWithdrawRequest
LnUrlWithdrawRequestData: Wrapped in a [LnUrlWithdraw], this is the result of parse when given a LNURL-withdraw endpoint.
LnUrlWithdrawSuccessData
LocaleOverrides: Locale-specific settings for the representation of a currency
LocalizedName: Localized name of a currency
MessageSuccessActionData
MetadataItem: Key-value pair in the LnUrlPayRequestData, as returned by the LNURL-pay endpoint
MoonpayProvider
Rate: Denominator in an exchange rate
ReqwestRestClient
RouteHint: A route hint for a LN payment
RouteHintHop: Details of a specific hop in a larger route hint
ServiceConnectivityError
Symbol: Settings for the symbol representation of a currency
UrlSuccessActionData

Enums§

AesSuccessActionDataResult: Result of decryption of AesSuccessActionData payload
Amount
DeserializeError
InputType: Different kinds of inputs supported by parse, including any relevant details extracted from the input
InvoiceError
LnUrlAuthError: Error returned by [crate::breez_services::BreezServices::lnurl_auth]
LnUrlCallbackStatus: Contains the result of the entire LNURL interaction, as reported by the LNURL endpoint.
LnUrlError
LnUrlPayError: Error returned by [crate::breez_services::BreezServices::lnurl_pay]
LnUrlRequestData: Generic struct containing the possible LNURL payloads returned when contacting a LNURL endpoint
LnUrlWithdrawError
LnUrlWithdrawResult: LnUrlCallbackStatus specific to LNURL-withdraw, where the success case contains the invoice.
Network: The different supported bitcoin networks
ServiceConnectivityErrorKind
SuccessAction: Supported success action types
SuccessActionProcessed: SuccessAction where contents are ready to be consumed by the caller
URISerializationError
ValidatedCallbackResponse

Statics§

PRODUCTION_BREEZSERVER_URL
STAGING_BREEZSERVER_URL

Traits§

BuyBitcoinProviderApi
FiatAPI: Trait covering fiat-related functionality
LnurlAuthSigner
RestClient

Functions§

add_routing_hints
build_pay_callback_url
build_withdraw_callback_url
get_and_check_success
get_derivation_path
invoice_pubkey: Try to take payee pubkey from the tagged fields, if doesn’t exist recover it from the signature
parse: Parses generic user input, typically pasted from clipboard or scanned from a QR.
parse_bolt12_offer
parse_invoice: Parse a BOLT11 payment request and return a structure contains the parsed fields.
parse_json
parse_liquid_address
parse_with_rest_client
perform_lnurl_auth: Performs the third and last step of LNURL-auth, as per https://github.com/lnurl/luds/blob/luds/04.md
validate_invoice
validate_lnurl_pay: Validates invoice and performs the second and last step of LNURL-pay, as per https://github.com/lnurl/luds/blob/luds/06.md
validate_lnurl_withdraw: Validates invoice and performs the second and last step of LNURL-withdraw, as per https://github.com/lnurl/luds/blob/luds/03.md
validate_network
validate_request
validate_user_input

Type Aliases§

Aes256CbcDec
Aes256CbcEnc
InvoiceResult
LnUrlResult