About Breez

Breez is a self-custodial Lightning-as-a-Service company bringing permissionless, peer-to-peer bitcoin payments to apps and services globally with the free and open-source Breez SDK.

The Breez SDK

The Breez 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.

To provide the best experience for their end-users, developers can choose between the following implementations:

Breez Mobile

Breez Mobile is a full-service, self-custodial Lightning mobile client that makes peer-to-peer bitcoin payments simple. It features a Point-of-Sale mode that turns your wallet into a cash register, letting anyone become a merchant. Plus, it includes a built-in next-generation podcast player, allowing you to support your favorite content creators by streaming sats directly to them.

Introducing Breez Mobile

Breez is a full-service, non-custodial Lightning client. Let’s break that down:

  • Lightning is a bitcoin payment network that reduces transaction times from minutes to milliseconds and transaction fees from several dollars to a few cents or less. Lightning turns bitcoin from digital gold into digital currency while preserving all of the benefits that make bitcoin great.
  • Non-custodial means that Breez doesn’t take possession of users’ money. Many Lightning clients do take possession of their users’ money. They’re basically bitcoin banks. With a non-custodial app like Breez, all users are their own banks. Breez uses a forked version of lnd and Neutrino. The Breez app actually runs a full Lightning node under the hood. Advanced users can interact with the underlying Lightning node by invoking lncli commands in the Preferences> Developers screen.
  • Full-service means that Breez takes care of almost all the technical operations automatically and in the background. Things like channel creation, inbound liquidity, and routing stay under the hood. (But Breez is also open source, so those interested in auditing the technology are welcome to do so!)

Breez includes a Point-of-Sale mode, which transforms the app from a Lightning wallet into a Lightning cash register with the slide of a finger, allowing everyone to become a merchant and accept Lightning payments. It also includes a next-generation podcast player, allowing users to stream sats to their favorite content creators.

Note: the app is still in beta and there is a chance your money will be lost. Only use this app if you are willing to take this risk.

Features

No channel management: zero-conf channels are created on the fly

Breez seamlessly opens channels as needed on-the-fly. Here's how it works:

  1. When the recipient wants to receive a payment but lacks inbound capacity, their Breez app recognizes the lack and issues two invoices using the same preimage: one invoice is issued to the sender (requesting a payment) and a second is issued to the Breez LSP. The amount of the second invoice equals the amount requested from the payer minus a miniscule service fee to Breez for opening the channel the recipient requires. The invoice sent to the sender includes routing instructions, indicating a pseudo-channel between the recipient and the Breez node.
  2. When the sender pays the invoice they received from the recipient, the Breez node intercepts the payment and holds it.
  3. The Breez LSP then opens a channel with the recipient and skips funding confirmation. Then it pays the recipient the second invoice and receives the preimage.
  4. Once the preimage is received from the recipient, Breez settles the payment with the sender.

Breez funds the convenience of zero-conf channel creation by charging a fee.

The channels Breez creates on the fly are actually zero-conf channels. These differ from standard channels in that they can function before they’ve been confirmed on the blockchain. Instead of making users wait until blocks are mined, these channels become active instantly, allowing users to spend their funds immediately after receiving them.

Cloud backup

Like all true Lightning wallets, Breez is a "hot" wallet and thus requires frequent cloud backups. To avoid relying on the availability/existence of the Breez server, we offer automatic backups to Google Drive, iCloud, Nextcloud, or any WebDav server. From a security standpoint, there are also many advantages to saving these backups in a major third-party cloud-storage provider. For more information, see our Backup FAQ.

On-chain transactions

When sending or receiving funds via BTC addresses, Breez uses Submarine Swaps, which allow Breez to support on-chain transactions while maintaining a single balance. In other words, all of the users’ funds are in their Lightning channels, which simplifies the user experience by obviating many functions of a standard BTC wallet.

For more information, see:

On-chain monitoring

Breez uses Neutrino to fetch chain information. Neutrino provides better privacy than current alternatives and allows users to connect to their own Bitcoin nodes via the Preferences > Network screen.

Breez includes a background watcher to help users control the state of their channels. This process notifies users of cheating attempts even when the app is closed, helping them to retrieve their money. The refund period is 720 blocks, so users are automatically protected by simply using their phones at least once every 5 days. The Breez app doesn’t even need to be open, since the watcher runs periodically in the background without any further demands on the user.

Connecting to multiple nodes

By default, Breez creates channels on the fly with the Breez LSP whenever users lack the inbound liquidity to receive a payment. There are, however, several ways to create channels with other nodes in Breez: users can open a channel to their own node, use LNURL-Channel, or run lncli commands from the Developers screen. For more information, see here.

Point-of-Sale

Breez works like a digital cash register for brick-and-mortar businesses and merchants who want to accept Lightning payments. It includes features and a user interface tailored to merchants’ needs, like manager passwords, a catalog of items, fiat display, and the ability to export transaction information. Read this to get started with Breez POS.

Podcast player

Breez comes with a built-in, next-generation podcast player: users can find and subscribe to podcasts, stream payments while listening, and send real-time tips to applaud their favorite creators at their favorite moments. While listening, users can set a rate of how many sats per minute to stream back to the creators. For example, to pay 3000 sats for an hour-long episode, the user would set the rate to 50 sats/min. Setting the rate to 0 lets the user listen for free. Users can also send one-off tips to the creators by pressing the Boost! button and attach a direct message to the podcasters (aka Boostagrams).

For more information about Breez support of Podcating 2.0, read this article. To see streaming sats and boosts in action, check out this video.

Breez includes many more features, like full LNURL support, private mode, payment filters, Connect to Pay, biometric login, fast graph sync, scanning QR code from an image, fiat currencies and Lightning addresses. To learn more, please take a look at our medium publication, GitHub projects, or follow us on Twitter.

To learn more about Breez, please check out our site and our Medium publication.

Troubleshooting Payment Failures

Breez is a non-custodial service that uses lnd and Neutrino under the hood. Routing is done on the client side using the graph information provided by lnd.

No route found/Unable to find path/Timeout

If you are trying to pay an invoice, but you see an error like no route found, unable to find path or timeout errors, please try the following:

  • Make sure you are running the latest version of the app.

  • Try a smaller amount to leave enough sats for routing fees (e.g. 1-2%).

  • Retry paying the invoice. lnd has a function called mission control in its routing algorithm. Mission control improves routing based on previous attempts, so simply retrying a payment might do the trick.

  • Make sure there is no limit set in Preferences > Lightning Fees.

  • Reset the Bitcoin Node by clicking the Reset button on the Preferences > Network screen.

  • Try refreshing the graph information. Click on three dots at the top right of the Preferences > Developers menu, then on Update Graph. Then re-open Breez, keep it in the foreground for a few minutes, and retry the payment.

  • Try refreshing the private channels. Click on three dots at the top right of the Preferences > Developers menu, then on Refresh Private Channels. Then re-open Breez, keep it in the foreground for a few minutes, and retry the payment.

  • Restart the Breez app and wait 30 seconds. Then, click on the getinfo command in the Preferences > Developers > General menu to check whether all the channels are active, which is the case when there's a "0" in the "numOfInactiveChannels" line.

  • Check that Breez has the latest graph information. You can verify this by clicking on the getinfo command in the Preferences > Developers > General menu. If the synced_to_graph line of the output indicates true, then your node is synced with the graph. In case the value is false, keep the app running in foreground for a couple of minutes until it syncs.

  • Try resetting mission control by running the resetmc command from the Preferences > Developers > Payments menu and retry the payment.

  • Advanced users can also debug the routing path by running the Developers > Payments > queryroutes command.

Backup FAQ

Important note

Restore your wallet only if you've lost your device or accidentally uninstalled Breez. Restoring from backup is unlikely to fix problems you may be experiencing with the app.

Does Breez have a backup seed?

Unlike an on-chain wallet, Breez requires continuous backups of the user's current channel states, which necessitates cloud storage (e.g. Google Drive, iCloud, Nextcloud, or any WebDav server) rather than a simple seed phrase to backup/restore. In Breez, an encrypted backup is triggered automatically after whenever a BTC address is generated or a Lightning payment event occurs.

Why does Breez require cloud access?

As a Lightning wallet, Breez requires continuous backups of the user's channel states backup to the cloud. From a security standpoint, there are many advantages to saving these backups in a major third-party cloud-storage provider. Even better, with cloud backup users' backup files don't rely on the availability of the Breez server.

Can Google/Apple access my backup information?

Neither company is fully transparent about their data encryption. That's why Breez offers an additional layer of encryption to data backed up in the cloud. To generate a backup phrase, activate Encrypt Backup Data in the Preferences > Security & Backup screen.

Why can't I restore my data in other wallets despite entering the correct encryption key?

Breez's encryption key is not the same as a seed phrase for an on-chain wallet. The Breez key encrypts the user's data stored in the cloud. In order to restore the information, users need access their cloud backups and decrypt them with their individual keys. Currently, Breez backups can only be restored from within the Breez app.

How do I restore from backup?

You can restore from backup inside the Breez app. You'll see a Restore from Backup link under the Let's Breez button on the opening screen. DO NOT RUN A PREVIOUS INSTANCE OF BREEZ AFTER RESTORING ON A NEW DEVICE.

Can I view the backup files in Google Drive/iCloud?

Backup files are stored in a private data directory accessible only through the Breez app. Google Drive users can manage their Breez storage by opening Google Drive in a browser and clicking on Settings > Manage Apps.

Can I switch from Android to iOS and vice versa?

Yes, by storing your backup in Google Drive or on a remove server that is supported on both platforms. To switch cloud provider, use the Store Backup Data in setting on the Preferences > Security & Backup screen.

I can't authenticate to Nextcloud. What can I do?

Create an app password, enter the new app credentials and retry. If the standard Nextcloud URL doesn't work, please try the following:

  • Go you your Nextcloud instance using your browser.
  • Select the Files pane.
  • Scroll down on the left bar and select File Settings.
  • Under WebDAV copy the URL and use it when attempting to sign in.

Do you support pCloud?

Yes, but a business account is required (with WebDav support). The URL should be entered in the following format:

  • pCloud (US): https://webdav.pcloud.com
  • pCloud (EU): https://ewebdav.pcloud.com

Breez says my key is wrong. What can I do?

If Breez says you're entering an incorrect key, then the key you are entering does not match what is saved in the software. Unfortunately, there are few means to recover a key that was recorded inaccurately. Please ensure that you've entered the words in the right order and that all the words are spelled correctly. More than once, the obstacle has turned out to be a small error in entering the words, even a single letter.

Opening Channels

By default, whenever a user lacks sufficient inbound liquidity to receive a payment, Breez creates a channel on the fly connected to the Breez routing node.

However, there are several ways in Breez to create channels with other nodes:

  • Opening a channel from a different node:

    • Use the getinfo_ command by clicking Preferences > Developers > General to retrieve the public key of the mobile node on your device.
    • Click on Preferences > Developers > Peers > connect to connect to another node. Note: for Tor nodes, you first need to enable Tor in Preferences > Network (Android only for now).
    • Open a private channel to the Breez mobile node from the interface of the new node using lncli or similar. Make sure Breez is running in the foreground on your phone while opening the channel.

  • Using LNURL-Channel (see below).

  • Running lncli commands from the Preferences > Developers screen.

Note: creating channels manually is recommended only for advanced users.

LNURL-Channel

LNURL-Channel allows users to use external services, like Bitrefill Thor, LNBIG, and other LSPs to open additional channels simply by scanning a QR code or clicking on a link. In order to use this function, you need to first choose a provider that offers channel-opening services.

Important note:

  • Channel reserve refers to the funds locked in a channel and that can't be transferred until it is closed. Different LSPs set different channel reserves. While Breez sets the channel reserve to 0 on its default channels, other providers will probably use the default setting of 1% of a channel's capacity.

Channel Closures

Payment channels on Lightning can be closed without the user actively closing them. This can happen, for instance, when a peer force-closes a channel. Unilateral force closures can result from, say, nodes on the network that hold funds rather than forwarding them, and the Breez LSP may close your channel after a period of inactivity (at least 45 days without executing a Lightning transaction). Furthermore, there are still bugs in lnd (the Lightning Network implementation Breez uses) that can cause inadvertent channel closures.

However, users never lose control of their funds (provided they are above dust value) even in the case of force closures. When a channel is closed, the funds are swept to an on-chain address. Typically, it takes 144 blocks (about 24 hours) before the funds from the closed channel appear in a user's local wallet. Once the funds appear in the user's local wallet, Breez displays an interface that allows the user to redeem them, and a warning icon will appear in the top right of the home screen. If no warning icon is displayed, it probably means that the process is still underway.

For more information regarding the closing process:

  1. The Closed Channel transaction in the payments list should display a detailed status. Please wait 144 confirmations (about 24 hours) after the initial closed channel transaction, at which point the second, sweep transaction (i.e. the transfer from the closed channel to the local Breez wallet) should be displayed.
  2. Consult the output of the pendingchannels command by clicking Preferences > Developers > Channels > pendingchannels.

'Pending Closed Channel' status seems stuck for a few days

Sometimes on-chain synchronization issues cause the sweep transaction to fail, and the process of closing a channel gets "stuck" at pending. To resolve this issue, please try the following:

  1. Click the Refresh Information button in the Pending Closed Channel dialog.
  2. Click 'Exit Breez'.
  3. Reopen Breez and keep the app running in the foreground for at least 15 minutes and prevent the device from going into sleep mode.

This process should re-synchronize your channel and broadcast the sweep transaction, which will enable you to redeem your funds. If that doesn't help, please contact our support: contact@breez.technology.

Can I download the Breez Mobile APK?

Yes, you can download the APK directly from our GitHub repository. It requires Android 7.0 or greater and a 64-bit device. Click here to view the latest release.

Adding Funds via Submarine Swaps

Submarine swaps allow users to transfer on-chain funds to Lightning without trust or counterparty risk, which is exactly how Breez uses them.

Submarine swaps are designed such that the funds in the address provided can only be spent if a Lightning transaction is executed to the user's node within 288 blocks (about 48 hours). If no Lightning transaction is executed by this deadline, the user can redeem the funds when the time lock expires.

Note for advanced users: The script for a submarine swap can be exported from Breez by long-clicking the QR code of the address.

Why does Breez use Submarine Swaps?

Submarine swaps allow Breez to support on-chain transactions while maintaining a single balance. In other words, all of the users' funds are on their Lightning nodes, so there's no need to maintain a separate BTC wallet within Breez, which greatly simplifies the user experience.

Limitations

  • Sending more funds than the specified limit (shown in Breez below the address) will trigger a refund since no submarine swap may exceed the recipient's channel capacity.
  • Sending a small amount to a submarine swap address may trigger a refund because users could theoretically spend the funds even if Breez has already executed a Lightning transaction. The reason is that Breez cannot always ensure the on-chain transaction is confirmed before the time lock expires.
  • Each transaction must be completed with a new, single-use address. Sending multiple transactions to the same address will trigger a refund.

How can users claim their refunds?

If users are unable to claim their funds via Lightning within 288 blocks, a Get Refund option will appear in the Breez side-menu after the deadline (about 48 hours after the on-chain transaction has been confirmed). Click on it and enter an on-chain BTC address when prompted. The funds will be sent to the address entered.

How to close channels in Breez?

In order to close payment channels in Breez, click through Preferences > Developers > Channels > closeallchannels. Funds that were contained in those channels will be available in the Breez app once the closing transactions are confirmed on-chain.

Warning: funds will only be available for redemption if the balance exceeds the on-chain transaction cost.

What fees are there in Breez?

Sending Lightning Payments

Routing fees depend on the available path and for some channels are higher depending on the distribution of liquidity throughout the network. Users can limit fees either as a flat maximum or as a percentage of the transaction amount by clicking Preferences > Lightning Fees and entering the values desired.

Please note, however, that limiting fees may cause payments to fail.

Receiving Lightning payments

Receiving a Lightning payment in Breez incurs no fees for the receiver, unless a new channel is required.

Channel creation

When a new channel is required to accommodate an incoming payment, Breez charges 0.4% of the amount received, with a dynamic minimum fee (based on the current mempool fees). For more information, see the Channel creation on the fly section of this blog post.

The Breez SDK fees are different. Please use the LSP information API to retrieve the fees structure for your specific LSP.

Currently, Breez adds 50k sats of inbound liquidity to the amount received in an incoming payment. For example, if you receive 50k sats, and a new channel is required, Breez will create a new channel on the fly with a capacity of 100k sats.

Please note that the app displays a notification when a new channel is required and a setup fee will be incurred. For Lightning transactions, the notification will appear in the Receive via Invoice screen and again under the invoice QR code. For on-chain transactions, it will apppear under the address QR code in the Receive via BTC Address screen.

There are no additional fees to continue using the channels created.

Receiving from a BTC Address

Receiving from BTC address involves a trustless submarine swap. Check the limits below the QR code before sending funds.

No additional fees are incurred unless a new channel is required.

Send to a BTC Address

Sending to a BTC address involves a trustless reverse swap. Reverse swaps require a minimum transaction amount of 50k sats. Please note that in a high fees environment, the minimum amount may be higher.

Further, Boltz, the reverse swap provider, charges a fixed service fee of 0.5% plus an additional mining fee, which is based on the current bitcoin mempool usage.

Streaming sats to podcasts

Breez charges no more than 5% of the sats listeners stream to creators.

Using the sendcoins command

Please note that the functionality described here is best left to advanced users.

In some cases, like channel closures, users' funds might be deposited automatically into Breez's built-in (on-chain) Bitcoin wallet. If this occurs, we strongly recommend sending the funds to a secure BTC address as soon as possible. Breez offers an Unexpected Funds screen to facilitate this process.

However, the funds may not suffice to initiate a transaction and cover the fees incurred. To send the funds with a minimal fee, enter the following command in the Preferences > Developers screen:

sendcoins --sweepall=1 --addr=dest-btc-address --sat_per_byte=10

Bitcoin Node Synchronization

By default, Breez uses the following node to connect to the Bitcoin network:

bb1.breez.technology

However, any Bitcoin node that supports block filters (BIP 157) can be used. This site lists alternative nodes.

My sync is stuck at 0%, what can I do?

If your node isn't syncing to the network, try the following steps:

  • Reset the Bitcoin node by clicking Preferences > Network > Reset.
  • Disconnect any VPN or other intermediary software that might be interfering with network traffic.
  • Try recovering the chain information. Click on three dots at the top right of the Preferences > Developers menu, then on Recover Chain Information. Then re-open Breez, keep it in the foreground till the sync is finished (might take a long time).
  • Try syncing with a different node listed here and entering it in the Preferences > Network screen. Choose a regular IP address, not a Tor (.onion) address.

Connecting to a Bitcoin Node

Breez can be connected to any Bitcoin node that supports BIP 157. Bitcoin Core has supported BIP 157 since v0.21. Note: for Tor nodes, you first need to enable Tor in Preferences > Network (Android only for now).

The following configuration flags needs to be added to bitcoin.conf:

blockfilterindex=1
peerblockfilters=1

How to Get Started with Breez POS?

What is Breez POS?

Breez is a full-service, non-custodial Lightning app. Let’s break that down:

  • Lightning is a bitcoin payment network that reduces transaction times from minutes to milliseconds and transaction fees from several dollars to a few cents or less. Lightning turns bitcoin from digital gold into digital currency while preserving all of the benefits that make bitcoin great.
  • Non-custodial means that Breez doesn’t take possession of users’ money. Many Lightning apps do take possession of their users’ money. They’re basically bitcoin banks. With a non-custodial app like Breez, all users are their own banks.
  • Full-service means that Breez takes care of almost all the technical operations automatically and in the background. Things like channel creation, inbound liquidity, and routing stay under the hood. (But Breez is also open source, so those interested in auditing the technology are welcome to do so!)

Breez POS is short for our point-of-sale mode. In other words, Breez works like a digital cash register for businesses and merchants who want to accept Lightning payments (in addition to its “standard” mode, which is like the digital version of a leather wallet for bitcoin, and a next-generation podcast player). Now let’s look at how to set Breez up as a Lightning cash register for your business.

How to get started with Breez?

The first step is to download the app. It’s available for Android and iOS (install TestFlight and click the link from your device).

Breez can back itself up automatically to Google Drive, iCloud or any WebDav server.

Note that each device runs its own Lightning node. You can run POS mode on as many devices as you’d like, but the balances will remain separate.

With the app open, click on the icon at the top left to find the Point of Sale mode.

Setting up POS

Click that icon at the top left, and click Point of Sale > POS Settings.

The Manager Password

In the POS Settings, you have the option to create a manager password. The manager password makes it impossible to send outgoing payments from the Breez app without authorization. Sales staff will only be able to receive payments from the device. Note that if you're using this option, you might also want to prevent access to Breez's backup, so using an external WebDav account (e.g. Nextcloud) is recommended for this use case.

The Items List

The items list is a catalog of items for sale and their prices. There are two ways to add items to the list:

  • To enter items one at a time, click on Items near the top of the main POS view, then on the “+” sign at the bottom right. Here you can enter the name of a single type of item, the price (displayed in the currency equivalent of your choice), and the SKU (a unique internal identifier for that type of item; it’s optional).
  • To enter many items at once, click on the calculator icon at the top left, then Point of Sale > Preferences > POS Settings, and then click on the three dots to the right of Items List, and then on Import from CSV. This will allow you to import a CSV file that you prepared in advance containing your items’ names, prices, and SKUs.

Fiat Display

Breez only sends and receives bitcoin, and for most transactions on Lightning, which tend to be for smaller amounts, the sum is usually displayed in Satoshis, a.k.a. sats (1 BTC = 100,000,000 sats). However, many merchants find it practical to be able to see (and tell customers) the value of the purchase displayed in the local fiat currency.

In the main POS view, the currency currently being displayed is visible on the right side (default is SAT). There is also a drop-down list of other currencies available to display. To add or remove currencies from this drop-down list, click on Point of Sale > Preferences > Fiat Currencies. Then simply check the currencies you would like to have in your drop-down menu and uncheck those you would like to omit.

The values displayed are from yadio, a respected outlet for exchange-rate data, and they’re updated in near real time. But remember: whatever currency value is currently being displayed, the payment itself is in bitcoin.

Charging an Order

To compose the order, either add items from the item list or simply enter a sum in the keypad. Then click on Charge at the top of the main POS view. You will then see a QR code that the customer can scan with their Lightning app, that you can share directly from another app on your device, or that you can copy and paste where necessary.

On scanning that code or clicking on the shared/pasted invoice, the customer will see the invoice in their Lightning app and have the option to pay it and settle the transaction immediately.

Once you see the Payment approved! animation in the Breez app on the merchant’s device, you can click on the printer icon to generate a receipt for the customer. To use a receipt printer in Android, try using this driver. Note that you can also print past transactions via the Transactions screen.

Sales Report

To view a daily/weekly/monthly report of your sales (for accounting purposes or others), click on the icon in the top left, and then click on Transactions. Click on the Report icon to display the report and the Calendar icon to change the selected date range.

Exporting Transactions

To view a list of the payments received in Breez, click on the icon in the top left, and then click on Transactions. Click on the three dots on the top right, then on Export to export a list of incoming payments in CSV format. To restrict the list to a certain period of time, click on the calendar icon to set a date range.

Printing Receipts

To print a sale receipt, click on the print icon on the top right of the payment confirmation dialog. Alternatively, click on the icon in the top left, and then click on Transactions. Locate the sale to print, open it and click the top right print icon.

Note: use this driver to print on a portable 58mm/80mm Bluetooth/USB thermal printer.

I want to learn more

  • For more information on Lightning and Breez, check out our blog.
  • For more technical tips on how to get the most out of the app and perform common operations, check out our documentation.
  • If you get stuck and can’t find the answer in any of our help literature, you can find us on Telegram or send us an email.
  • If you want to see some demonstration videos of the Breez POS mode in action made by our fans and users, here is a great short one, and here is a longer, more detailed one.

How do I add my podcast to Breez?

Breez uses the Podcast Index APIs and displays podcasts that added a Lightning value block to their feeds. To add your podcast to the library of available podcasts in Breez, search for your podcast in the Podcast Index, click on the Lightning icon, and follow the instructions.

If you are having trouble registering, try to post in this telegram group.

If you don't have a Lightning node and don't want to self-host, we recommend running a hosted podcast node from Voltage.

Resources

'Listen-on-Breez' Badge

To encourage your listeners to listen to your podcast on Breez, we've created this Listen on Breez badge.

Here's an example that links to the No Agenda podcast (note this link will work only from a mobile device):


To generate a direct link to your podcast, simply open your podcast in the Breez app and use the Share button to get the link.

Resources

Breez SDK

Implementations of the Breez SDK

To provide the best experience for end-users, developers can choose between the following implementations:

Breez SDK - Native (Greenlight Implementation)

For documentation related to the Breez SDK - Native (Greenlight Implementation), please see:

Breez SDK - Nodeless (Liquid Implementation)

For documentation related to the Breez SDK - Nodeless (Liquid Implementation), please see:

Pricing

The Breez SDK is free for developers.

Support

Community support is provided on Telegram. If you need to contact the Breez team directly, email us.

Overview for Developers

The Breez app is comprised of two main layers:

  • Breez Mobile: the UI layer written in Flutter
  • Breez Library: the business logic written in golang. This layer also refers to all Lightning Network dependencies.

Breez Library

The Breez library is implemented in golang and is responsible for the application's business logic, Lightning/on-chain flows, and LND tight integration.

  • The library is compiled and packaged using gobind, which creates a binding layer (the "binding" package) and a wrapping API in both java and swift that allow it to be invoked from the Android and iOS apps.
  • To build the library in Android using go1.19.x or above, follow these instructions.
  • All the functions/interfaces (APIs) that need to be exposed to the Breez mobile app are contained in this file.

Breez Mobile

  • A Flutter implementation is responsible for the UI.
  • To manage its state and its internal business logic, the app uses the BLoC pattern, which uses streams.
  • UI logic is handled in objects called BLoCs. Every domain has its own BLoC.
  • Services is a directory that contains the implementation for various stateless services that are injected via injector.dart and are to be used from BLoCs only.

The rest of the code is pure UI, which uses Sinks to push data and Streams to read data:

  • Widgets is a generic widgets directory.
  • Routes contains the pages of the app.

Communication (calling functions) between Flutter to golang occurs via this bridge. These functions are defined on both layers and protobuf structures, and they are are used as parameters.

Adding a function to the Breez Library

Define the endpoint in Breez Library (golang):

  1. Use protoc version 3.15.8
  2. Use protoc-gen-go v1.28.0
  3. Define the protobuf structure in golang
  4. Compile the proto: protoc --proto_path=data --go_out=. --go-grpc_out=. data/messages.proto
  5. Add the endpoint to the binding package

Define the caller in Breez Mobile (flutter):

  1. Compile the protobuf files in Flutter: protoc --dart_out=grpc:lib/services/breezlib/data/ -I<path to messages.proto>
  2. Add the function in breez_bridge.dart

Your Development Environment

We recommend you setup a simnet environment before testing your code on mainnet.

Running Breez in simnet

Developing Breez mobile requires Breez backend services to be up and running. As there are a few services that are configured to run in parallel, configuring everything from scratch might be tedious. Although we recommend that developers familiarize themselves with each of the services and the overall architecture, we do provide a quick solution to run all Breez services in a simnet environment that developers can connect to from their self-compiled Breez mobile app. These are the required backend services:

  • LSP node: a Lightning node that opens a channel with the Breez mobile app.
  • LSPD: an LSP daemon that interacts with Breez server and provides information about its node and services.
  • Breez Server: the main service that interacts with the Breez mobile app.
  • btcd/bitcoind: a Bitcoin node utilizing Neutrino (BIP 157).
  • SubSwap node: a node that provides submarine-swap services (adding funds to Breez via an on-chain address).

Running Breez's simnet cluster

We've created a docker-compose file that configures and runs all the backend services. It exposes the necessary endpoints to the Breez mobile app, similar to a production environment. This script runs the cluster. Before running this script, please configure it as follows:

  1. Change the DEV_HOST_IP env variable to the host IP address (it should run in the same network as the mobile device).
  2. Change the TEST_DIR value to a directory where all the containers' persistent data will be stored.

Note this script uses jq, which must installed in your environment.

Connecting from mobile:

To connect from mobile, these configuration files should be placed under the conf directory:

  • breez.conf: replace the <DEV_HOST_IP> with your cluster IP address.
  • lnd.conf: replace the <DEV_HOST_IP> with your cluster IP address.

Receiving payments

A container named alice is configured as part of the cluster, and it runs another Breez client app. This container should be used to send payments to your mobile node using the command line. Run the following commands in order to open a channel and receive a payment:

  • From your mobile app, generate a payment request via Receive > Receive via Invoice.
  • From your terminal:
  1. Retrieve the LSP node pubkey:

docker exec dev-breez "/lnd/lncli" -network=simnet getinfo | jq '.identity_pubkey'

  1. Generate 6 blocks:

docker exec dev-btcd /start-btcctl.sh generate 6

  1. Generate a btc address for Alice:

docker exec dev-alice "/root/go/bin/lncli" --network simnet newaddress np2wkh

  1. Send coins from the LSP node to Alice:

docker exec dev-breez "/lnd/lncli" -network=simnet sendcoins <alice_address> 20000000

  1. Generate 6 blocks:

docker exec dev-btcd /start-btcctl.sh generate 6

  1. Open a channel from Alice to the LSP node:

docker exec dev-alice "/root/go/bin/lncli" -network=simnet openchannel --node_key <lsp pubkey> --local_amt=200000 --connect=10.5.0.3:9735 --private

  1. Generate blocks to confirm the channel:

docker exec dev-btcd /start-btcctl.sh generate 6

  1. Send a Lightning payment:

docker exec dev-alice "/root/go/bin/lncli" -network=simnet payinvoice -f --pay_req <payment_request>

If the test is successful, the LSP node should open a channel to your mobile app and send the payment. You should see the payment in the transactions list in your mobile app.

Adding a WebLN widget with LNURL-Auth

Breez integrates various WebLN widgets in its Apps screen. When a widget also needs to authenticate the user using LNURL-Auth, the following process must be executed:

Getting the LNURL-Auth URL

  1. The vendor provides Breez with a predefined endpoint to get a valid LNURL for authentication (the same URL users typically get by scanning a QR code). Breez executes a GET request to this URL, and the vendor should respond with a JSON payload similar to:  {“lnurl_auth”:“lnurl1dp68gurn8ghj7ctsdyhxkmmvd35kgetj9eu8j730wccj7ct4w35z7etcw3jhymnpdshkcmjld3hkw6tw8a6xzeead3hkw6twye4nz0fkvv6kzepjx3skgefcxvmrvdf5xsuxvvp3xcenvdnzv9jk2en9xp3njcfexfjnze3evenr2cfhv93rjvehx56n2wrrxqckxvpjxgmrs2ayx7u”}
  2. Breez then extracts the LNURL from the JSON payload and initiates the LNURL-Auth process as defined in the spec.
  3. On step 3 of the LNURL-Auth protocol, Breez appends a query parameter jwt=true to the request.
  4. The vendor service should then detect the jwt query parameter and respond with a jwt property as part of the json payload, for example: {“status”: “OK”, “token”: [token]}

Using the jwt token in a web page

  1. Breez opens the vendor web page in a web view and appends the token=[token] to the query parameters of the URL.
  2. The vendor authenticates and logs the user in according to the token provided.

Bounties

Active Bounties

Breez is offering bounties for the tasks listed below. Relevant PRs must be reviewed and merged before developers can claim the bounty listed. To inquire about status of a bounty, to contribute to a bounty, or to propose a new bounty, please send us an email.

Please read the Overview for Developers before getting started.

No active bounties

Translating Breez into an unsupported language

To translate the Breez interface into a new language:

  • Click here for all the app strings.
  • To add a new language, simply copy the app_en.arb file and and change its suffix to the new language's code. For example:
    • English: app_en.arb
    • Portuguese: app_pt.arb
    • Spanish: app_es.arb
  • Translate the strings into the new language.
  • Open a PR with the new app_xy.arb file.
  • Our developers will review and integrate the new language to the Breez code base.