🤓 Guide: How to Use Boltz Client's Autoswap to Automate Your Lightning Liquidity Management
This step-by-step guide walks you through hooking up Boltz Client with your CLN or LND node and configuring Autoswap to manage Lightning liquidity on your behalf using unfairly cheap Liquid Swaps 🌊
Managing Lightning channel liquidity is not fun, especially if Lightning or Bitcoin is not your main business. And even then it’s not fun.
Today we released Boltz Client 2.1.0 “Autoswap”, which delivers “Lightning that just works” for your own Lightning node, featuring our “unfairly cheap” Liquid Swaps. This release implements the Liquid Rebalancing Triangle in an automated fashion, meaning, for the very popular use case to maintain inbound liquidity, it rebalances into Liquid and then, based on your settings, moves bitcoin from Liquid back to the mainchain. With which you can then open more Lightning channels.
For Whom Is This Guide?
This guide is written for tech-savvy operators of Lightning nodes that are used in a professional context, like merchants accepting Lightning payments for their goods, Bitcoin ATM operators allowing Lightning payouts, or fully-fledged exchanges that allow Lightning deposits and withdrawals.
What Is the Goal of This Guide?
The goal of this guide is to create a setup that keeps Lightning channels in a configured balance range to allow for reliable operations with predictably cheap rebalancing costs using Liquid Swaps. The idea is to perform many rebalancing swaps using Liquid and only periodically swap back to the mainchain, e.g. based on the accumulated amount of L-BTC or mainchain miner fee level.
But how does one go about installation, setup and configuration?
Grab a cup of coffee and let’s dive in 👇
Installation
Boltz Client is available for Linux amd64 and arm64 platforms, the two platforms almost all Lightning nodes are running on nowadays. Head over to the Boltz Client release page and download the latest release binaries for your platform, extract the binaries, verify them, and place them in a folder of your choice. If you are doing all this via terminal, these are the commands you want to use:
wget https://github.com/BoltzExchange/boltz-client/releases/download/v2.1.0/boltz-client-linux-amd64-v2.1.0.tar.gztar -xvzf boltz-client-linux-amd64-v2.1.0.tar.gzmvthe binaries to your preferred permanent location, e.g.~/boltz-clientadd the binaries to your PATH by adding the line
export PATH="/home/satoshi/boltz-client:$PATH"to the end of your.bashrcfile (don’t forget tosource .bashrcafterwards)
Give it a test spin by running boltzd, which will terminate with an error but proves that Boltz Client works on your system and conveniently creates the default data directory ~/.boltz already.
We recommend creating a systemd boltzd.service file to launch Boltz Client:
# A sample systemd service file for Boltz Client
[Unit]
Description=Boltz Client Daemon
[Service]
ExecStart=/home/satoshi/boltz-client/boltzd
ExecStop=/home/satoshi/boltz-client/boltzcli stop
# Replace these with the user:group that will run Boltz Client
User=satoshi
Group=satoshi
# Try restarting Boltz Client if it stops due to a failure
Restart=on-failure
RestartSec=60
[Install]
WantedBy=multi-user.targetIf you prefer building from source or using docker, refer to the docs.
Setup
Next up is connecting Boltz Client to your Lightning node. Change to the Boltz Client data directory (~/.boltz by default) and create a new configuration file called boltz.toml with the following content
If you are running CLN:
[CLN]
datadir = "~/.lightning"If you are running LND:
[LND]
datadir = "~/.lnd"Pointing Boltz Client to your Lightning node’s data directory is all it should take to successfully connect. Should you be running your node with non-default ports, certificate locations or on a different machine, check our sample config file for advanced connection configuration options.1
Now we are ready to start Boltz Client via sudo systemctl start boltzd. boltzcli getinfo should print an output similar to the following showing the connected Lightning node’s public key:
$ boltzcli getinfo
{
"version": "v2.1.0-daac977",
"node": "LND",
"network": "mainnet",
"nodePubkey": "020d9126d568b8f0605ed65eda28c4b843bb66282a0921d721f88b8a46cbd4e221",
"autoSwapStatus": "disabled",
"blockHeights": {
"btc": 849707,
"liquid": 2919031
},
"tenant": {
"id": "1",
"name": "admin"
}
}If the command returns an error instead, you can follow the logs for the root cause with e.g. journalctl -n 100 -f -u boltzd or by simply opening boltz.log located in the Boltz Client data directory. If you need help with debugging, feel free to reach out in the #help channel on our Discord Server.
For an overview of all available cli commands, simply run boltzcli.
Autoswap Configuration
Congrats, now that we have Boltz Client running and connected to our Lightning node, we can start configuring Autoswap! 🙌
Before we start though, let’s record our current channel and wallet balances:
$ boltzcli wallet list
{
"wallets": [
{
"id": "2",
"name": "LND",
"currency": "BTC",
"readonly": false,
"balance": {
"total": "2990606",
"confirmed": "2990606",
"unconfirmed": "0"
},
"tenantId": "1"
},
]
}
$ lncli channelbalance
{
"balance": "3073517",
"pending_open_balance": "0",
"local_balance": {
"sat": "3073517",
"msat": "3073517340"
},
"remote_balance": {
"sat": "42488",
"msat": "42488660"
}
}As one can see, we currently hold a bit less than 3 million sats in LND’s internal mainchain wallet and have a very imbalanced channel balance with about 3 million sats local outbound and only 42488 sats remote inbound liquidity.
To familiarize ourselves with the available Autoswap options, we run boltzcli autoswap. The command we are looking for is called setup, the interactive setup flow to configure Autoswap.
The first decision boltzcli autoswap setup asks us to take is if we want to:
maintain inbound liquidity via reverse, e.g. if you are a merchant and need to be able to receive Lightning payments reliably,
maintain outbound liquidity via normal, e.g. if you are running a Bitcoin ATM that accepts FIAT and needs to be able to send Lightning payments reliably,
maintain both, e.g. if you are operating a Bitcoin exchange and offer Lightning deposits and withdrawals and need to be able to send and receive reliably
Let’s now imagine we are operating an online merchant selling amazing hats for sats and need to be able to reliably receive Lightning payments. We do not have the need to send Lightning payments out. Our current channel balance is not great for this use case as we currently only can receive up to 42488 sats, which is barely the price of one hat. Our desired channel balance is basically the exact opposite - all of our channel balance on the remote side of the channel as inbound liquidity. Consequently, we are continuing with the first option “reverse” to manage our inbound liquidity.
Next up is selecting the destination wallet, which also determines if we are swapping to Liquid or to the mainchain (both are supported by Boltz Client). We want to swap to Liquid to benefit from reliably cheap network fees and avoid rebalancing costs spiraling out of control when mainchain miner fees rise. As Boltz Client ships with an integrated Liquid wallet system, it let’s us create a new Liquid wallet right within the setup flow:
? Select wallet which should be used for swaps Create New
? Select wallet which should be used for swaps LBTC
? Enter a name for the new wallet liquid
? Do you want to provide a wallet password to encrypt your wallet, which will be required on startup? No
New wallet created!
Mnemonic:
dragon minute height hurry oil power must imitate twice brick term festival
We highly recommend to import the mnemonic shown above into an external wallet like Blockstream Green (https://blockstream.com/green). This serves as backup and allows you to view transactions and control your funds.Next, we install Blockstream Green on a different computer (or phone) and import the mnemonic from the output.
As the CLI response stated, importing the mnemonic into Green is important for two reasons:
The second device serves as backup of your Liquid wallet should something happen to your Boltz Client installation or device
Green enables you to see wallet transactions and manually send to or receive from this wallet, features which Boltz Client doesn’t support.
Next, setup asks us to decide if we want to specify our minimum inbound liquidity in sats or in percentage of our total channel capacity. We choose percentage and go with the default 25% threshold. This means that once our inbound liquidity hit the minimum threshold of 25% inbound liquidity (or, in nominal terms, a bit more than 750k sats of our 3 million sats channel), Boltz Client starts rebalancing our channel.
Next we set a budget, the maximum amount we want to spend on fees, applicable for a certain budget period. We are going with 50k sats over 7 days rolling. Lastly, Boltz Client informs us that the target when executing swaps is 100% inbound liquidity, which is exactly what we want as an online merchant, have all our liquidity available as inbound liquidity.
Here the summary of our config:
? Which type of swaps should be executed? reverse
? Select wallet which should be used for swaps liquid
? How do you want to specify values? percentage
? What is the minimum percentage of total capacity you want to keep as your inbound balance? 25
? In which interval should the fee budget of the auto swapper be reset? (days) 7
? How many sats do you want to spend max on fees per budget interval? 50000
Config was saved successfully!
Autoswap will target 100% inbound balance when executing swaps.That’s it for Liquid Swaps - the configuration of the first edge of the Liquid Rebalancing Triangle is done!
Setup now asks us if we want to configure the second edge of the triangle, Chain Swaps from Liquid back to the mainchain too. We do, and apply the following config:
? Do you want to setup chain swaps as well? Yes
? Select source wallet liquid
? Select target wallet LND
? What is the maximum amount of sats you want to accumulate before a chain swap is started? 1000000
? In which interval should the fee budget of the auto swapper be reset? (days) 7
? How many sats do you want to spend max on fees per budget interval? 50000
Config was saved successfully!This config instructs Autoswap to swap all L-BTC back to our LND’s internal mainchain wallet once our Liquid balance reaches 1 million sats. We set the maximum fee budget to the same 50k sats per 7-day rolling period.
Finally, Autoswap informs us about the swap immediately being executed after enabling. Quick check of the numbers shows us, that the swap amount of 3011144 is slightly less than our current 3073520 sats outbound liqudity. This is because Autoswap has to account for Lightning’s channel reserve. We enable Autoswap.
Based on above config the following swaps will be performed:
{
"lightning": [
{
"amount": "3011144",
"feeEstimate": "7528",
"dismissedReasons": [],
"type": "reverse",
"channel": null
}
],
"chain": []
}
? Do you want to enable autoswap now? (y/N) yThat’s it for Chain Swaps - the configuration of the second edge of the Liquid Rebalancing Triangle is done too!
We start monitoring ongoing swaps via boltzcli swapinfostream to receive updates about the upcoming swap we were informed about. One can also follow Boltz Client’s logs via journalctl -f -u boltzd for a more detailed trace.
While monitoring progress of the swap, we can see that after the swap was executed successfully, our Lightning channel balance pracically inverted, which is precisely what we wanted. We now have >3 million sats available as inbound liquidity and only a little remainder of 62373 sats left as outbound liquidity. Our imaginary online shop is ready to sell hats 🤠
$ lncli channelbalance
{
"balance": "62373",
"pending_open_balance": "0",
"local_balance": {
"sat": "62373",
"msat": "62373340"
},
"remote_balance": {
"sat": "3053632",
"msat": "3053632660"
}
}The Liquid part of the swap was sent to our newly created Liquid wallet and since it’s about 3 million sats in value, the balance of our Liquid wallet now exceeds the previously set 1 million sats threshold and a chain swap is triggered, moving our Bitcoin from Liquid back to the mainchain. boltzcli listswaps shows us the summary after both swaps went through:
In Green we can confirm an incoming Liquid transaction of about 3 million sats from the first reverse swap from Lightning to Liquid and an outgoing transaction of a little bit less than 3 million sats of the second swap, moving our funds from Liquid back to the mainchain. Boltz Client is currently configured to leave a buffer of about 10000 sats in our Liquid wallet, but it’ll be able to swap everything down to the last satoshi soon. You can follow the implementation of this feature on GitHub here.
Finally, we confirm that LND’s internal mainchain wallet successfully received about 3 million sats as the final destination.
$ lncli walletbalance
{
"total_balance": "5979386",
"confirmed_balance": "5979386",We are now free to use our mainchain Bitcoin to open new channels, completing the third leg of the Liquid Rebalancing Triangle.
What’s Next for Boltz Client?
Many more issues to be crunched and bugs to be fixed as we are rolling out this release.
Decreasing Liquid network fees even further.
Monitoring mainchain miner fee levels to automatically swap back to the mainchain when it’s cheap.
Boltz Client flagship feature: our upcoming BTCPay plugin. It’ll enable all of this directly from within the BTCPay UI and even allow to accept Lightning payments without running a Lightning node.
Note: One Boltz Client instance can only manage one Lightning node at a time. To manage multiple Lightning nodes, create multiple Boltz Client instances.
