Install the best circular-route rebalancing tool for the Lightning Network

go version

• Note: Versions of Go higher than the one used in this tutorial may not work with Regolancer.

1. Install Go

1. Go to the official Go website: https://golang.org/dl/
2. Download the appropriate Go version for your system (usually amd64).

3. Install Go following the instructions provided on the website. On Linux, for example, you can follow the commands below to install Go (assuming version 1.23.2; adjust the version if necessary):

wget https://go.dev/dl/go1.22.4.linux-amd64.tar.gz 

sudo tar -C /usr/local -xzf go1.22.4.linux-amd64.tar.gz 

export PATH=$PATH:/usr/local/go/bin

4. Check if Go was installed correctly by running:

go version

This should return the Go version installed:

5. To ensure Go is set up correctly and the binary is accessible from anywhere, add the ~/go/bin path to your PATH. Add the following line to your ~/.bashrc file (or ~/.zshrc depending on your shell):

sudo nano ~/.bashrc

# Add after the last line:

export PATH=$PATH:$HOME/go/bin

6. After adding this line, update the terminal:

source ~/.bashrc

2. Install Regolancer

1. Now that Go is installed, you can install Regolancer using the go install command. This command will download the source code of Regolancer and compile it for your machine. Run the following command in the terminal:

go install github.com/rkfg/regolancer

2. Check if Regolancer was installed correctly by running the following command to see its help options:

regolancer --help

Usage:
  regolancer [OPTIONS]

Application Options:
--------------------
Config:
  -f, --config                 config file path

Node Connection:
  -c, --connect                connect to lnd using host:port
  -t, --tlscert                path to tls.cert to connect
      --macaroon-dir           path to the macaroon directory
      --macaroon-filename      macaroon filename
  -n, --network                bitcoin network to use

Common:
      --pfrom                  channels with less than this inbound liquidity percentage will be considered as source channels
      --pto                    channels with less than this outbound liquidity percentage will be considered as target channels
  -p, --perc                   use this value as both pfrom and pto from above
  -a, --amount                 amount to rebalance
      --rel-amount-to          calculate amount as the target channel capacity fraction (for example, 0.2 means you want to achieve at most 20% target channel local balance)
      --rel-amount-from        calculate amount as the source channel capacity fraction (for example, 0.2 means you want to achieve at most 20% source channel remote balance)
  -b, --probe-steps            if the payment fails at the last hop try to probe lower amount using this many steps
      --allow-rapid-rebalance  if a rebalance succeeds the route will be used for further rebalances until criteria for channels is not satifsied
      --min-amount             if probing is enabled this will be the minimum amount to try
  -i, --exclude-channel-in     (DEPRECATED) don't use this channel as incoming (can be specified multiple times)
  -o, --exclude-channel-out    (DEPRECATED) don't use this channel as outgoing (can be specified multiple times)
      --exclude-from           don't use this node or channel as source (can be specified multiple times)
      --exclude-to             don't use this node or channel as target (can be specified multiple times)
  -e, --exclude-channel        (DEPRECATED) don't use this channel at all (can be specified multiple times)
  -d, --exclude-node           (DEPRECATED) don't use this node for routing (can be specified multiple times)
      --exclude                don't use this node or your channel for routing (can be specified multiple times)
      --exclude-channel-age    don't use channels opened less than this number of blocks ago
      --to                     try only this channel or node as target (should satisfy other constraints too; can be specified multiple times)
      --from                   try only this channel or node as source (should satisfy other constraints too; can be specified multiple times)
      --fail-tolerance         a payment that differs from the prior attempt by this ppm will be cancelled
      --allow-unbalance-from   (DEPRECATED) let the source channel go below 50% local liquidity, use if you want to drain a channel; you should also set --pfrom to >50
      --allow-unbalance-to     (DEPRECATED) let the target channel go above 50% local liquidity, use if you want to refill a channel; you should also set --pto to >50
  -r, --econ-ratio             economical ratio for fee limit calculation as a multiple of target channel fee (for example, 0.5 means you want to pay at max half the fee you might earn for routing out of the target channel)
      --econ-ratio-max-ppm     limits the max fee ppm for a rebalance when using econ ratio
  -F, --fee-limit-ppm          don't consider the target channel fee and use this max fee ppm instead (can rebalance at a loss, be careful)
  -l, --lost-profit            also consider the source channel fee when looking for profitable routes so that route_fee < target_fee * econ_ratio - source_fee

Node Cache:
      --node-cache-filename    save and load other nodes information to this file, improves cold start performance
      --node-cache-lifetime    nodes with last update older than this time (in minutes) will be removed from cache after loading it
      --node-cache-info        show red and cyan 'x' characters in routes to indicate node cache misses and hits respectively

Timeouts:
      --timeout-rebalance      max rebalance session time in minutes
      --timeout-attempt        max attempt time in minutes
      --timeout-info           max general info query time (local channels, node id etc.) in seconds
      --timeout-route          max channel selection and route query time in seconds

Others:
  -s, --stat                   save successful rebalance information to the specified CSV file
  -v, --version                show program version and exit
      --info                   show rebalance information
  -h, --help                   Show this help message

3. Configuring the config.json File

1. Create a configuration file for Regolancer, typically named config.json. This file contains the parameters needed for Regolancer to know which channels to rebalance and the fee/route options.

sudo mkdir ~/regolancer

sudo nano ~/regolancer/config.json

2. Copy and paste the following configuration:

{
    "macaroon_dir": "/data/lnd/data/chain/bitcoin/mainnet/",
    "macaroon_filename": "admin.macaroon",
    "network": "mainnet",
    "tlscert": "/data/lnd/tls.cert",
    "econ_ratio": 0.80,
    "amount": 201000,
    "min_amount": 5000,
    "probe_steps": 15,
    "allow-rapid-rebalance": true,
    "pfrom": 90,
    "pto": 30,
    "stat": "rebalances.csv",
    "lost_profit": true,
    "exclude_from": [],
    "to": [],
    "timeout_rebalance": 900,
    "timeout_attempt": 60,
    "timeout_info": 30,
    "timeout_route": 180
}

• macaroon_dir: Directory where the macaroon file is located, needed for authentication with the lnd daemon.
• macaroon_filename: Name of the macaroon file, typically admin.macaroon.
• network: Network your node is running on, set to mainnet.
• tlscert: Path to the TLS certificate used for secure communication between Regolancer and lnd.
• econ_ratio: Economic ratio for fee calculation. 0.80 means rebalancing will be attempted if the cost is up to 80% of the outbound channel fee.
• amount: Default amount for rebalancing (201,000 sats).
• min_amount: Minimum amount to rebalance (5,000 sats).
• probe_steps: Number of steps for probing routes (15 steps).
• allow-rapid-rebalance: Enables fast rebalancing without additional time limits.
• pfrom: Inbound liquidity percentage allowed from a source channel for rebalancing (90%).
• pto: Outbound liquidity minimum required in a target channel for rebalancing (30%).
• stat: File where rebalance statistics will be saved (rebalances.csv).
• lost_profit: Whether to calculate lost profit from failed rebalances (set to true).
• timeout_rebalance: Max time in seconds for the entire rebalance session (900 seconds).
• timeout_attempt: Max time in seconds for each attempt (60 seconds).
• timeout_info: Max time in seconds to gather node information (30 seconds).
• timeout_route: Max time in seconds to calculate the rebalance route (180 seconds).

3. Running Regolancer: With the configuration ready, you can run Regolancer using the config file you created. Replace /path/to/your/config.json with the full path to your configuration file.

regolancer --config /path/to/your/config.json

# example:
regolancer --config /home/admin/regolancer/config.json

4. Using Node Cache (optional): This option allows Regolancer to store node information for faster queries on future runs

regolancer --config /path/to/your/config.json --node-cache-filename /path/to/cache.dat

5. Set Additional Parameters (optional):

regolancer --config /path/to/your/config.json --node-cache-lifetime 720

# Cache valid for 12 hours

4. BONUS: Regolancer-Controller By BRLN

5. Running the Controller as a Service

1. Create the Service File

1. First, create the systemd service file:

sudo nano /etc/systemd/system/regolancer-controller.service

2. Paste the following content into the file:

[Unit]
Description=Regolancer Controller
After=lnd.service

[Service]
ExecStart=/usr/bin/python3 /path/to/regolancer-controller/regolancer-controler.py
WorkingDirectory=/path/to/regolancer-controller/
Restart=always
User=<user>
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

• Replace /path/to/regolancer-controller/ with the correct path to the regolancer-controller.py script.
• Replace <user> with the user who should run the service.
• Save and close the file (Ctrl + O to save, Ctrl + X to exit).

2. Reload Systemd Services

1. After creating the file, reload the systemd services so the new service is recognized:

sudo systemctl daemon-reload

3. Start and Enable the Service

1. To start the service:

sudo systemctl start regolancer-controller.service

2. To enable the service at boot:

sudo systemctl enable regolancer-controller.service

4. Check Service Status

1. To check if the service is running correctly:

sudo systemctl status regolancer-controller.service

5. View Service Logs

1. To check the service logs for troubleshooting:

sudo journalctl -fu regolancer-controller

2. To view logs from the beginning:

sudo journalctl -xeu regolancer-controller