👋Introduction

Boltz Client connects to CLN or LND nodes and allows for fully unattended channel rebalancing or accepting Lightning payments without running a node, using Boltz API. It is composed of boltzcli and boltzd.

Design principles:

• CLI-first: fine-grained control and enhanced setup UX via boltzcli

• CLN-first: first-class citizen support for CLN in addition to LND

• Liquid-first: leverages fee-efficient Lightning -> Liquid swaps in addition to Bitcoin swaps

• Self-contained: create/import Liquid and mainchain wallets, swap to read-only wallets

Main Components

boltzd

boltzd is a daemon that should run alongside of your lightning node. It connects to your lightning node and the Boltz API to create and execute swaps.

boltzcli

boltzcli is the CLI tool to interact with the gRPC interface that boltzd exposes.

Installation

Binaries

Boltz Client is available for linux on amd64 and arm64. Download the latest binaries from the release page. If you are on another platform, use the docker image below.

Docker

Boltz Client is also available as docker image. Assuming your lnd macaroon and certificate are placed in ~/.lnd, run:

docker create -v ~/.boltz:/root/.boltz -v ~/.lnd:/root/.lnd --name boltz-client boltz/boltz-client:latest
docker start boltz-client
docker exec boltz-client boltzcli getinfo

Building from source

To build, Go version 1.21 or higher is required. Boltz Client also has C dependencies, which means a C compiler has to be installed to compile the daemon successfully.

Boltz Client depends on GDK by blockstream, which can be either dynamically or statically linked. The recommended way to build from source is linking dynamically as a static link requires compiling gdk as well.

Run make build to build the daemon and CLI. The binaries will be placed at the current path.

You can also run make install which will place the binaries into your GOBIN ($HOME/go/bin by default) directory.

Setup

Binaries for the latest release of Boltz Client can be found on the release page. If no binaries are available for your platform, you can build them yourself with the instructions above.

Configuration

Configuration can be done via CLI params or a TOML configuration file (by default located in ~/.boltz/boltz.toml). We suggest starting off with the sample configuration file, which can be found here.

boltzd requires a connection to a lightning node, which can be CLN or LND. If you set configuration values for both, you can specify which to use with the node param.

To view all CLI flags use --help.

LND

The LND node to which the daemon connects has to be version v0.10.0-beta or higher. Also, LND needs to be compiled with these build flags (official binaries from Lightning Labs releases include them):

• invoicerpc (hold invoices)

• routerrpc (multi path payments)

• chainrpc (block listener)

• walletrpc (fee estimations)

By default, boltzd will attempt to connect to lnd running at localhost:10009 (lnd.host and lnd.port) and looking for certificate and macaroon inside the data directory ~/.lnd (lnd.datadir).

You can manually set the location of the tls certificate (lnd.certificate) and admin macaroon (lnd.macaroon) instead of speciyfing the data directory as well.

CLN

The daemon connects to CLN through gRPC. You need start CLN with the --grpc-port CLI flag, or set it in your config:

• --cln.port same port as used for --grpc-port

• --cln.host host of the machine CLN is running on

• --cln.datadir data directory of cln (~/.lightning by default)

You can manually set the paths of cln.rootcert, cln.privatekey and cln.certchain instead of speciyfing the data directory as well. You might have to set the cln.servername option as well, if you are using a custom certificate.

CLI

We recommend running boltzcli completions to setup autocompletions for the CLI (only supported for zsh and bash).

Macaroons

The macaroons for the gRPC server of boltzd can be found in the macaroons folder inside the data directory of the daemon. By default, that data directory is ~/.boltz on Linux.