Progress pill
Technical

Breez SDK - Nodeless

Liquid Bootcamp Essentials

Breez SDK - Nodeless

  • Introduction to Breez Liquid SDK
  • Payment Architectures: Submarine Swaps
  • Developer Interface and Automated Management

Introduction to Breez Liquid SDK

The Breez Liquid SDK is a self-custodial, open-source toolkit designed to bridge the gap between the Liquid Network and the broader Bitcoin ecosystem. Its primary mission is to abstract the complexities of Lightning Network node management and atomic swaps, allowing developers to build frictionless financial applications.
Built with a "mobile-first" philosophy, the core logic is written in Rust for performance and safety, but it utilizes UniFFI (Unified Foreign Function Interface) to provide native bindings for Kotlin, Swift, Python, C#, Dart, and Flutter. This ensures that developers can integrate Bitcoin functionality into their preferred environment without managing low-level cryptographic operations.
Supported Transaction Types: The SDK operates with Liquid as its "home base." It excels at three specific operations:
  1. Liquid-to-Liquid: Direct on-chain transfers.
  2. Liquid-to-Lightning: Paying Lightning invoices using Liquid funds.
  3. Liquid-to-Bitcoin: Swapping funds directly to the Bitcoin mainchain.
Note: The SDK does not support direct Lightning-to-Lightning or Bitcoin-to-Bitcoin transactions. It is strictly a Liquid-centric tool.

Payment Architectures: Submarine Swaps

To achieve interoperability between Liquid, Lightning, and Bitcoin without centralized custodians, Breez relies on Submarine Swaps. These are atomic operations where a transaction either completes successfully on both networks or fails on both, ensuring funds are never lost in transit.

Lightning Send (Submarine Swap)

When a user pays a Lightning invoice, the SDK broadcasts a "lock-up" transaction on the Liquid Network. This effectively puts the funds in escrow. The swap provider (Boltz) detects this, pays the Lightning invoice, and then uses the payment preimage (the cryptographic receipt) to claim the locked Liquid funds.

Lightning Receive (Reverse Submarine Swap)

Receiving Lightning is the inverse process. The user generates an invoice, and the swap provider locks funds on the Lightning Network. The SDK monitors this process via WebSockets. Once the lock is confirmed, the SDK automatically executes a claim transaction to move the equivalent funds into the user's Liquid wallet.

Cross-Chain Bitcoin

For Liquid-to-Bitcoin transfers, the architecture uses a "dual-swap" mechanism. Lock-up transactions occur on both chains simultaneously. The sender claims funds on Bitcoin, while the receiver claims funds on Liquid. This enables trustless bridging without reliance on federated peg-outs or centralized exchanges.

Developer Interface and Automated Management

The Breez SDK simplifies the developer experience by condensing complex financial flows into a standardized three-step process: Connect, Prepare, and Execute.
  1. Connect: Initializes the wallet, syncs with the blockchain using the Liquid Wallet Kit (LWK), and establishes WebSocket connections for real-time monitoring.
  2. Prepare: Before committing funds, this step calculates and returns all associated network fees and swap costs, allowing the UI to present a clear total to the user.
  3. Execute: This step constructs the transaction, broadcasts it, and initiates the swap.

Automated Safety Mechanisms

One of the SDK's most critical features is Automated Refund Management. In the event of a network failure or a non-cooperative counterparty, funds could theoretically become stuck in a time-locked contract. The SDK abstracts the recovery logic entirely. It monitors the state of every swap; if a swap fails or times out, the SDK automatically constructs and broadcasts the refund transaction to return funds to the user's wallet.
Additionally, the SDK handles Metadata Resolution. It merges off-chain swap data (provided by the Boltz swapper) with on-chain transaction history. This ensures that the user's transaction history is human-readable, displaying invoice details and payment context rather than just raw hexadecimal transaction hashes.
Quiz
Quiz1/5
What happens when a reverse submarine swap fails or times out in the Breez SDK architecture?