Bonus guide: Balance of Satoshis

Balance of Satoshis (BoS), created and maintained by LND developper Alex Bosworth, is a tool to work with LND. The most used feature of BoS is the rebalancing command that allows to manage your channels liquidity (which is the main focus of this guide), but BoS contains now many other lightning tools outside liquidity management (such as the creation of a node monitoring Telegram bot which is explained below).

Difficulty: Medium

Status: Tested v3

bos-rebalance

Table of contents

Requirements
Installation
Balance of Satoshis in action
Upgrade
Uninstall
Optional: connect your node to a Telegram bot

Requirements

LND (or LND as part of Lightning Terminal/litd)
Node.js v12.20+

Installation

Check Node.js

Noje.js v16 should have been installed for the BTC RPC Explorer and RTL. We can check our version of Node.js with user “admin”:
```
$ node -v
> v16.13.2
```
If the version is v12 or above, you can move to the next section. If Node.js is not installed, follow this guide to install it.

Create the “bos” user and prepare the directory

Create a new user “bos” and make it a member of the “lnd” group

$ sudo adduser --disabled-password --gecos "" bos
$ sudo adduser bos lnd
$ sudo su - bos

Create symlink to lnd directory
```
$ ln -s /data/lnd /home/bos/.lnd
```
Display the link and check that it’s not shown in red (this would indicate an error)
```
$ ls -la
```

Add the bos binary file location to PATH

$ echo 'export PATH=$PATH:/home/bos/balanceofsatoshis' >> /home/bos/.bashrc
$ source /home/bos/.bashrc

Install

Check the main PGP key of Alex Bosworth, developer of Balance of Satoshis: https://keybase.io/alexbosworth/, i.e. E80D 2F3F 311F D87E

$ gpg --receive-keys E80D2F3F311FD87E
> [gpg: key E80D2F3F311FD87E: public key "Alex Bosworth <alex.bosworth@gmail.com>" imported
> gpg: Total number processed: 1
> gpg:               imported: 1

Still with user “bos”, download the source code and install it

$ git clone https://github.com/alexbosworth/balanceofsatoshis.git
$ cd balanceofsatoshis

Find the most recent tag and verify the signature. Add the --tags option to select even a lightweight/non-annotated tag. Add the --abbrev=0 option to remove any long-format tag names.

$ VERSION=$(git tag | sort --version-sort | tail -n 1); echo $VERSION
> v12.4.1
$ git verify-tag $VERSION
> gpg: Good signature from "Alex Bosworth <alex.bosworth@gmail.com>" [unknown]
> gpg: WARNING: This key is not certified with a trusted signature!
> gpg:          There is no indication that the signature belongs to the owner.
> Primary key fingerprint: DE23 E73B FA8A 0AD5 587D  2FCD E80D 2F3F 311F D87E

Install Balance of Satoshis locally
```
$ npm install
> [...]
```
Check the version with the -V option
```
$ bos -V
> v12.4.1
```

Balance of Satoshis in action

To use Balance of Satoshis, we will use the “bos” user.

Introduction

To see a list of all available commands run the following command

$ bos help
> bos 12.4.1
>
> USAGE
>
>   bos <command> [options]
>
> COMMANDS
>
>   accounting <category>               Get an accounting rundown
>   [...]

To see detailed information about an individual command, add the name of the command, e.g. with the command rebalance

$ bos help rebalance
> bos 12.4.1
>
> USAGE
>
>   bos rebalance
>   Change the liquidity profile of two peers
> [...]

Get a short report of your LN node with pubkey, alias, local capacity, mempool information and recent routing activity
```
$ bos report
```

Get a list of your channels with peer alias, local and remote balances and your peers fee rates towards your node (the local and remote balances are colour-coded with balances <1M sats in white, >1M sats in green and 4M sats in bolded green, to help identify channels that might require rebalancing)

$ bos peers
> │ Alias                      │ Inbound    │ In Fee       │ Outbound   │
> ├────────────────────────────┼────────────┼──────────────┼────────────┤
> │ euclid                     │ 0.00283195 │ 0.00% (7)    │ 0.00956736 ┤
> [...]

Circular rebalancing

Circular rebalancing allows to send satoshis out through one channel (which has too little inbound liquidity) and back through another channel (which has too little outbound liquidity).

A good illustration is provided in Chapter 5 of ‘Mastering the Lightning Network’ by Antonopoulos et al. (source) (Alice (A), is your node, Bob (B) and and Chan (C) are two peers with whom you have an opened channel with):

circular-rebalancing

To rebalance a channel with high outbound (e.g., your channel with node B) and a channel with high inbound (e.g., your channel with node C), use the rebalance command.
```
$ bos rebalance --amount [AMOUNT_IN_SATS] --max-fee-rate [TOTAL_MAX_FEE_RATE_OF_REBALANCING] --in [NODE_C_PUBKEY] --out [NODE_B_PUBKEY]
```

E.g. using the example above:

with node B being the Bitrefill node,
node C being the CoinOS node
rebalancing 50,000 sats
with a maximum fee rate that you are ready to pay of 100 ppm max

$ bos rebalance --amount 50000 --max-fee-rate 100 --in 02868e12f320073cad0c2959c42559fbcfd1aa326fcb943492ed7f02c9820aa399 --out 03d607f3e69fd032524a867b288216bfab263b6eaee4e07783799a6fe69bb84fac

Some rebalancing can take a very long time. A timeout can be specified for the command to terminate gracefully by adding the --minutes option.

$ bos rebalance --minutes [NUMBER_OF_MINUTES] --amount [AMOUNT_IN_SATS] --max-fee-rate [TOTAL_MAX_FEE_RATE_OF_REBALANCING] --in [NODE_C_PUBKEY] --out [NODE_B_PUBKEY]

If you notice that a node in the tried paths is repeatedly the cause of failures, you can ask BoS to ignore this node during path finding by adding the --avoid option

$ bos rebalance --minutes [number_of_minutes] --amount [AMOUNT_IN_SATS] --max-fee-rate [TOTAL_MAX_FEE_RATE_OF_REBALANCING] --avoid [NODE_PUBKEY] --in [NODE_C_PUBKEY] --out [NODE_B_PUBKEY]

Other commands

There are many additional options that can be used to improve the likelihood of a successful circular rebalancing. There are also many addditonal commands in addition to the rebalancing command. More information on all bos commands can be found in:

The BoS Github repository
This unofficial documentation repo (note that this page might not be kept up-to-date)

You can also join the Balance of Satoshis Telegram group to get support: https://t.me/balanceofsatoshis

Upgrade

Log in with the “bos” user and upgrade Balance of Satoshis with npm
```
$ sudo su - bos
$ cd balanceofsatoshis
```
Check what version you are using currently (e.g. here v12.4.1)
```
$ bos -V
> 12.4.1
```
Update the local repository by downloading the new commits from the source repository and check if a new tag/version is available (e.g. here v99.99.9)
```
$ git fetch
> [...]
> * [new tag]         v99.99.9   -> v99.99.9
```
Find the most recent tag. Add the --tags option to select even a lightweight/non-annotated tag. Add the --abbrev=0 option to remove any long-format tag names.
```
$ VERSION=$(git tag | sort --version-sort | tail -n 1); echo $VERSION
> v12.4.1
```
Remove any potential uncommited changes to your local branch to avoid issues when checking out the new tag
```
$ git reset --hard HEAD
> HEAD is now at 1b2a38d add docs for coop close on open
```

Switch to new branch identified with git fetch (i.e. v99.99.9) and check that it is now the most recent tag

$ git checkout $VERSION
> Previous HEAD position was 1b2a38d add docs for coop close on open
> HEAD is now at dd58fc0 [...]
$ git describe --tags --abbrev=0
> v99.99.9

Check the GPG signature of the new version

$ git verify-tag $VERSION
> [...]
> gpg: Good signature from "Alex Bosworth <alex.bosworth@gmail.com>" [unknown]
> gpg: WARNING: This key is not certified with a trusted signature!
> gpg:          There is no indication that the signature belongs to the owner.
> Primary key fingerprint: DE23 E73B FA8A 0AD5 587D  2FCD E80D 2F3F 311F D8

Install the new version and check this it has been installed properly
```
$ npm install
> [...]
$ bos -V
> v99.99.9
```
Upgrade the Telegram bot by restarting it (optional). Log out of the “bos” user and restart the bos-telegram.service
```
 $ exit
 $ sudo systemctl restart bos-telegram.service
```
Verify updated version by typing /version in TG bot chat.

🤖 Running version: 13.15.0

🤖 Latest version: 13.15.0

Uninstall

If you want to uninstall Balance of Satoshis:

Optional: connect your node to a Telegram bot

Balance of Satoshis allows connecting a node to a Telegram bot to receive updates about routing forwards, channel opening and closing events, successful rebalancing payments, payments received, keysend messages etc. It also saves a copy of channel.backup (SCB) each time there is a channel being opened or closed.

bos-tg-bot

Requirements: a Telegram account

Create a new TG bot with the BotFather

Open Telegram, in the general search box look for the @BotFather bot and start a conversation with the bot.
Type /start
Type /newbot and follow the instructions (choose a bot name, username)
Once the bot is created, the BotFather will give you a HTTP API token, copy it and keep it somewhere safe (like in a password manager). Note that if you lose this token, you could always get it agin by typing /myBot in the BotFather feed.
You also get a link to your bot (in the form: t.me/[your_bot_username]) click on it and it will redirect you to your new bot feed. Keep Telegram opened.

Tor Proxy (requires v11.50.1+)

To avoid leaking our node IP address to Telegram, we can tell bos to use Tor (or VPN) using the flag --use-proxy <file>.

As user “bos”, create and edit a new file proxy_agent.json. Insert host and port of your Tor (or VPN or other proxy) instance. Save (Ctrl+O) and exit (Ctrl+X)
```
$ sudo su - bos
$ nano balanceofsatoshis/proxy_agent.json
```
```
 {
    "host": "127.0.0.1",
    "port": 9050
 } 
```

Use bos to connect your node to the bot

Change to the “bos” user
```
$ sudo su - bos
```

Now, we are going to request bos to connect our node to the TG bot via proxy

$ bos telegram --use-proxy /home/bos/balanceofsatoshis/proxy_agent.json

When prompted, enter the HTTP API token that the @BotFather gave you earlier
Go to your new TG bot feed and type /connect. Your bot will give you a connection code
Copy the connection code and paste it in your SSH session in the second prompt that bos created. You should get a connection message on both your SSH session and your TG bot feed. In the SSH session:
```
> is_connected: true
```
Your TG bot will now receive notifications from your nodes for various events as described in the introduction.
Leave the temporary session by pressing Ctrl+C and log out of the “bos” user
```
$ exit
```

Permanent connection and autostart on boot

Now we’ll make sure our Telegram Bot command starts as a systemd service on the Raspberry Pi so it’s always running.

As user “admin”, create the service file.

$ sudo nano /etc/systemd/system/bos-telegram.service

Paste the following configuration. Replace YourConnectionCode with your own connection code provided by your bot above. Save and exit.

# /etc/systemd/system/bos-telegram.service

[Unit]
Description=bos-telegram
Wants=lnd.service
After=lnd.service

[Service]
ExecStart=/home/bos/balanceofsatoshis/bos telegram --connect YourConnectionCode --use-proxy /home/bos/balanceofsatoshis/proxy_agent.json
User=bos
Restart=always
TimeoutSec=120
RestartSec=30
StandardOutput=null
StandardError=journal

[Install]
WantedBy=multi-user.target

Note: A new option was added to change the display of amounts (satoshis) from 0.00011111 to 11,111 or 11.111 (depending on your locale): --use-small-units. To enable this, add it to the command bos telegram:
```
[...]
ExecStart=/home/bos/balanceofsatoshis/bos telegram --use-small-units --connect YourConnectionCode --use-proxy /home/bos/balanceofsatoshis/proxy_agent.json
[...]
```

Enable the service, start it and check the status of the service. You should also receive a connection message from your TG bot (‘Connect to …’).

$ sudo systemctl enable bos-telegram.service
$ sudo systemctl start bos-telegram.service
$ systemctl status bos-telegram.service
> bos-telegram.service - bos-telegram
>   Loaded: loaded (/etc/systemd/system/bos-telegram.service; enabled; vendor preset: enabled)
>   Active: active (running) since Fri 2021-12-03 13:52:06 GMT; 8s ago
> Main PID: 4682 (node)
>    Tasks: 11 (limit: 4164)
>      CPU: 7.981s
>   CGroup: /system.slice/bos-telegram.service
>           `-4682 node /home/bos/.npm-global/bin/bos telegram --connect YourConnectionCode --use-proxy /home/bos/balanceofsatoshis/proxy_agent.json

To monitor the live logging output use the following command. Exit with Ctrl+C.
```
$ sudo journalctl -f -u bos-telegram
```
Check that the program is running in the background: Go to your Telegram bot and type /version, it should return your currently installed version of bos and the latest available version.

Bos Telegram bot in action

The bot will notify you of the following events on your LN node:
- 💵 - A payment being received (if it’s a keysend with a message, the message will be decoded and displayed
- 💰 - Routing/forward events
- ☯️ - Sucessful rebalancing payment you initiated
- 🌹 - A new channel being opened to your node
- 🥀 - A channel closing
- You’ll receive an actual SCB backup file (that can be downloaded) after each new channel opening or closing
- ⛓ - A pending onchain payment being received
- 🤖 - A reply to a command you invoke (see list of commands below)
In your Telegram bot type /help to list the list of available commands:
- /backup - Get node backup file
- /blocknotify - Notification on next block
- /connect - Connect bot
- /costs - View costs over the past week
- /earnings - View earnings over the past week
- /invoice - Make an invoice
- /liquidity with - View node liquidity
- /mempool - BTC mempool report
- /pay - Pay an invoice
- /pending - View pending channels, probes, and forwards
- /version - View the current bot version

« Back: + Lightning