Crate breez_sdk_core
source ·Expand description
§Breez SDK
The Breez SDK enables mobile developers to integrate Lightning and bitcoin payments into their apps with a very shallow learning curve. The use cases are endless – from social apps that want to integrate tipping between users to content-creation apps interested in adding bitcoin monetization. Crucially, this SDK is an end-to-end, non-custodial, drop-in solution powered by Greenlight, a built-in LSP, on-chain interoperability, third-party fiat on-ramps, and other services users and operators need.
The Breez SDK provides the following services:
- Sending payments (via various protocols such as: bolt11, keysend, lnurl-pay, lightning address, etc.)
- Receiving payments (via various protocols such as: bolt11, lnurl-withdraw, etc.)
- Fetching node status (e.g. balance, max allow to pay, max allow to receive, on-chain balance, etc.)
- Connecting to a new or existing node.
§Getting Started
First, make sure you have your API Key and Invite Code ready (see API Key and Invite Code section below).
The following code initialize the SDK and make it ready to be used:
let mnemonic = Mnemonic::generate_in(Language::English, 12)?;
let seed = mnemonic.to_seed("");
let invite_code = Some("...".into());
let mut config = BreezServices::default_config(
EnvironmentType::Production,
"your API key".into(),
breez_sdk_core::NodeConfig::Greenlight {
config: GreenlightNodeConfig { partner_credentials: None, invite_code },
},
);
// Customize the config object according to your needs
config.working_dir = "path to an existing directory".into();
// Connect to the Breez SDK make it ready for use
let sdk = BreezServices::connect(
config,
seed.to_vec(),
Box::new(AppEventListener {}),
)
.await?;
We can now receive payments
let invoice = sdk.receive_payment(3000, "Invoice for 3000 sats".into()).await?;
or make payments
let bolt11 = "...";
sdk.send_payment(bolt11.into(), Some(3000)).await?;
At any point we can fetch our balance from the Greenlight node
if let Some(node_state) = sdk.node_info()? {
let balance_ln = node_state.channels_balance_msat;
let balance_onchain = node_state.onchain_balance_msat;
}
or fetch other useful infos, like the current mempool RecommendedFees
let fees: RecommendedFees = sdk.recommended_fees().await?;
These different types of operations are described below in more detail.
§A. Initializing the SDK
There are two simple steps necessary to initialize the SDK:
- BreezServices::default_config to construct the sdk configuration
- BreezServices::connect to connect to your node and start all required Breez SDK services
The first step takes the EnvironmentType and NodeConfig as arguments. Although you can create your own config from scratch it is recommended to use the BreezServices::default_config method and customize it according to your needs. Once the NodeConfig is created it is passed to the BreezServices::connect method along with the seed and and implementation of EventListener which is used to notify the caller of SDK events.
Now your SDK is ready to be used.
§B. Sending and receiving Lightning payments
Supported BOLT11 operations are
- BreezServices::receive_payment to create an invoice
- BreezServices::send_payment to pay an invoice
- BreezServices::send_spontaneous_payment for keysend payments
§C. Receiving an on-chain transaction (swap-in)
- BreezServices::receive_onchain accepting an optional user-selected OpeningFeeParams for the case when the operation requires a new channel with the LSP
- BreezServices::in_progress_swap
- BreezServices::list_refundables to get a list of swaps
- BreezServices::refund to broadcast a transaction for failed or expired swaps
§D. Sending to an on-chain address (swap-out)
- BreezServices::fetch_reverse_swap_fees to get the current swap-out fees
- BreezServices::prepare_onchain_payment to prepare the swap-out
- BreezServices::pay_onchain to start the swap-out
- BreezServices::in_progress_onchain_payments to see any in-progress swaps
§E. Using LNURL
- parse the LNURL endpoint URL to get the workflow parameters.
- After getting the user input or confirmation, complete the workflow with BreezServices::lnurl_pay or BreezServices::lnurl_withdraw.
§F. Supporting fiat currencies
- BreezServices::list_fiat_currencies to get the supported fiat currencies
- BreezServices::fetch_fiat_rates to get the current exchange rates
- BreezServices::recommended_fees for the recommended mempool fees
§G. Connecting to an LSP
- BreezServices::list_lsps to get a list of available LSPs
- BreezServices::connect_lsp to connect to a chosen LSP
- BreezServices::lsp_info to get LspInformation on the currently selected LSP
§H. Utilities
Use parse to parse generic input. The input can come from the user, from a clicked link or from a QR code. The resulting InputType will tell you what the input is and how to treat it, as well as present relevant payload data in a structured form.
§Bindings
- C#
- Dart
- Go
- Kotlin
- Python
- React-Native
- Swift
§API Key and Invite Code
You will need an API Key to use the SDK, as well as an Invite Code when you create a new node.
To get both of them, please contact Breez via email at contact@breez.technology or at https://breez.technology/#contact-us-form
§Support
Join this telegram group.
Modules§
- Bindings for the Dart integration
- 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.
- BreezServices is a facade and the single entry point for the SDK.
- Lightning channel
- Request to check a message was signed by a specific node id.
- Response to a CheckMessageRequest
- Represents the funds that were on the user side of the channel at the time it was closed.
- Configuration for the Breez Services
- Represents a configure node request.
- Represents a connect request.
- Details about a supported currency in the fiat rate feed
- Wrapper around the CurrencyInfo of a fiat currency
- Details of past or ongoing reverse swaps, as stored in the Breez local DB
- Client-specific credentials to connect to and manage a Greenlight node in the cloud
- Device credentials used to authenticate to Greenlight with the current device.
- Details of an invoice that has been paid, included as payload in an emitted BreezEvent
- Wrapper for a BOLT11 LN invoice
- Represents a list payments request.
- Details of a LN payment, as included in a Payment
- 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
- Internal SDK log entry
- Details of supported LSP
- A metadata filter which can be applied when retrieving the transaction list
- Key-value pair in the LnUrlPayRequestData, as returned by the LNURL-pay endpoint
- The node state of a Greenlight LN node running in the cloud.
- Dynamic fee parameters offered by the LSP for opening a new channel.
- Represents a payment, including its PaymentType and PaymentDetails
- Represents a payments external information.
- Represents a payment response.
- Contains fields describing the reverse swap parameters (see ReverseSwapPairInfo), as well as the resulting send and receive amounts.
- We need to prepare a redeem_onchain_funds transaction to know what fee will be charged in satoshis. This model holds the request data which consists of the address to redeem on-chain funds to and the fee rate in. satoshis per vbyte which will be converted to absolute satoshis.
- We need to prepare a redeem_onchain_funds transaction to know what a fee it will be charged in satoshis this model holds the response data, which consists of the weight and the absolute fee in sats
- Denominator in an exchange rate
- Represents a receive payment request.
- Represents a receive payment response.
- Wrapper containing the result of the recommended fees query, in sat/vByte, based on mempool.space data
- Simplified version of FullReverseSwapInfo, containing only the user-relevant fields
- Details about the reverse swap fees and parameters, at this point in time
- A route hint for a LN payment
- Details of a specific hop in a larger route hint
- Represents a send payment request.
- Represents a send payment response.
- Represents a send spontaneous payment request.
- Represents a service health check response.
- Request to sign a message with the node’s private key.
- Response to a SignMessageRequest.
- Summary of an ongoing swap
- Represents the details of an on-going swap.
- Settings for the symbol representation of a currency
- Internal response to a [crate::node_api::NodeAPI::pull_changed] call
- Represents a TLV entry for a keysend payment.
- UTXO known to the LN node
Enums§
- Result of decryption of AesSuccessActionData payload
- Event emitted by the SDK. To listen for and react to these events, use an EventListener when initializing the BreezServices.
- Different providers will demand different behaviours when the user is trying to buy bitcoin.
- State of a Lightning channel
- Indicates the different kinds of supported environments for crate::BreezServices.
- Different types of supported feerates
- Indicates the different service health check statuses.
- 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
- Wrapper for the different types of payments
- The status of a payment
- Different types of supported payments
- Different types of supported filters which can be applied when retrieving the transaction list
- Represents a report issue request.
- The possible statuses of a reverse swap, from the Breez SDK perspective.
- Supported success action types
- SuccessAction where contents are ready to be consumed by the caller
- The status of a swap
Constants§
Statics§
Traits§
- Trait that can be used to react to various BreezEvents emitted by the SDK.
- Trait covering fiat-related functionality
- Trait covering LSP-related functionality
- Trait covering support-related functionality
- Trait covering functionality involving swaps
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
- Attempts to convert the phrase to a mnemonic, then to a seed.
- 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