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

The first step is to initialize the SDK and start the node:

let mnemonic = Mnemonic::new(Words12, English);
let seed = Seed::new(&mnemonic, "");

let creds = BreezServices::register_node(Network::Bitcoin, seed.as_bytes().to_vec()).await?;
let sdk = BreezServices::init_services(
        BreezServices::default_config(EnvironmentType::Production),
        seed.to_vec(),
        creds.clone(),
        Box::new(AppEventListener {}),
    )
    .await?;

BreezServices::start(rt(), &sdk).await?;

On initializing the SDK, the caller gets its GreenlightCredentials. These are used to interact with the Greenlight LN node running in the cloud. Together with the BIP39 mnemonic, these can be used to restore access to the same cloud node, either in the same app (backup / restore) or in another app using the SDK.

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 steps necessary to initialize the SDK:

  1. BreezServices::init_services to setup the Breez SDK services
  2. BreezServices::start to start the Greenlight node and all needed Breez SDK services

The first step takes the GreenlightCredentials as an argument. There are three ways to get them:

The first step also takes an implementation of EventListener as an argument, which is used to notify the caller of SDK events.

After initializing the Breez SDK services and starting them, the SDK is ready to be used.

B. Sending and receiving Lightning payments

Supported BOLT11 operations are

C. Receiving an on-chain transaction (swap-in)

D. Using LNURL

  1. parse the LNURL endpoint URL to get the workflow parameters.
  2. After getting the user input or confirmation, complete the workflow with BreezServices::lnurl_pay or BreezServices::lnurl_withdraw.

E. Supporting fiat currencies

F. Connecting to an LSP

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

  • Dart
  • Swift
  • Kotlin
  • React-Native

Modules

Bindings for the Dart integration

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
Represents the funds that were on the user side of the channel at the time it was closed.
Configuration for the Breez Services
Details about a supported currency in the fiat rate feed
Wrapper around the CurrencyInfo of a fiat currency
Client-specific credentials to connect to and manage a Greenlight node in the cloud
Details of an invoice that has been paid, included as payload in an emitted BreezEvent
Wrapper for a BOLT11 LN invoice
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.
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
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
Represents a payment, including its PaymentType and PaymentDetails.
Denominator in an exchange rate
Wrapper containing the result of the recommended fees query, in sat/vByte, based on mempool.space data
A route hint for a LN payment
Details of a specific hop in a larger route hint
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 NodeAPI::pull_changed call
UTXO known to the LN node

Enums

Event emitted by the SDK. To listen for and react to these events, use an EventListener when initializing the BreezServices.
State of a Lightning channel
Indicates the different kinds of supported environments for crate::BreezServices.
Different types of supported feerates
Different kinds of inputs supported by parse, including any relevant details extracted from the input
Contains the result of the entire LNURL-pay interaction, as reported by the LNURL endpoint.
Generic struct containing the possible LNURL payloads returned when contacting a LNURL endpoint
Contains the result of the entire LNURL-withdraw interaction, as reported by the LNURL endpoint.
The different supported bitcoin networks
Wrapper for the different types of payments
Different types of supported payments
Different types of supported filters which can be applied when retrieving the transaction list
Supported success action types
SuccessAction where contents are ready to be consumed by the caller
The status of a swap

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 functions affecting the LN node
Trait covering functionality involving swaps

Functions

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.