LN Toolkit Command

auto-balance’ command

auto-balance tries to move funds from channels with too much to channels with too little.

auto-balance is like an iterative version of move-balance. It tries to find the channels most in need of funds, and the channels most capable of providing those funds, then it tries to move funds between those two sets of channels.

For example, if it finds channels A, B and C have too low a local balance, and channels Z, X and Y have too high a local balance, it will try to move funds between them by:

If a transfer succeeds, both the successful from and to channels are removed from further transations for the current auto-balance run.

Caveats

The nature of Lightning routing means it may not be able to find such a route, or the route may not actually be capable of routing the funds, or it may just fail with a TemporaryChannelFailure, or it may time out, or your Lightning node may be using outdated policy/pricing information from one of the nodes, or... Well, there are lots of reasons routing funds might fail.

Example

Here’s a simple example of running the command:

lntoolkit auto-balance -max-search-time 1m --max-fees-msat 5000 --max-amount 1000000 --max-from-channels 5 --max-to-channels 5

This will try to match up to 5 ‘in need’ channels (specified as --max-to-channels 5) with 5 ‘capable’ channels (specified as --max-from-channels 5), and try to move at most 1000000 (specified as --max-amount 1000000) from one channel to the other, while spending no more than 5000msats on fees for each transfer (specified as --max-fees-msat 5000), and spending no more than 1 minute finding each route.

Alternatively, you can override the heuristics choosing to or from channels by specifying exactly which channels you want it to use on the command line. For example, this command will try to move funds from one of the top 20 fullest channels to the channel with ID 1631373989433769985:

lntoolkit auto-balance --max-search-time 1m --max-fees-msat 5000 --max-amount 1000000 --max-from-channels 20 --to 1631373989433769985 --verbose

--to and --from can be specified multiple times for a single auto-balance command, so this command will try to move funds from one of the channels 1629051820876103680, 1629419057760567297 or 1633460862503419905, to one of the channels 1631373989433769985, 1629436649948643328 or 1594825123416113152:

lntoolkit auto-balance --max-search-time 1m --max-fees-msat 5000 --max-amount 1000000 --max-moves 1 --from 1629051820876103680 --from 1629419057760567297 --from 1633460862503419905 --to 1631373989433769985 --to 1629436649948643328 --to 1594825123416113152

Usage

Some important aspects of the routing are configurable. Some parameters I find particularly useful are --max-search-time, --max-hops, --max-fees-msat and --max-routes.

Here’s the list of parameters it can take:

Usage of auto-balance:
  -amount value
    	specific amount (in sats) to move from the 'from' channel to the 'to' channel, rather than the calculated/heuristic amount.
  -certificate string
    	path and filename of the TLS certificate to use when connecting to LND. (default "~/.lnd/tls.cert")
  -dry-run
    	if specified, route(s) will be calculated but no funds will be transferred.
  -exclude value
    	specific channel IDs to exclude from 'to' or 'from' channel lists. This parameter can be specified multiple times per command.
  -final-cltv-delta uint
    	final CLTV delta to use in the routes from the 'from' channel to the 'to' channel. (default 144)
  -from value
    	specific channel IDs to move funds from (overrides heuristics determining capable channels). This parameter can be specified multiple times per command.
  -from-fullness-threshold-percentage uint
    	minimum percentage full the channel must be to be deemed capable of being a source of balance. (default 75)
  -macaroon string
    	path and filename of the macaroon to use when connecting to LND. (default "~/.lnd/data/chain/bitcoin/testnet/admin.macaroon")
  -max-amount value
    	maximum amount (in sats) to try to move from one channel to another. (default ㋛100,000)
  -max-fees-msat value
    	maximum fees (in msat) to be spent on the balance move. (default m㋛10,000)
  -max-from-channels uint
    	maximum number of channels to try to use as a source of balance. (default 5)
  -max-hops int
    	maximum number of hops in routes used for the balance move. (default 20)
  -max-moves uint
    	maximum number of balance moves to perform. (default 5)
  -max-routes int
    	maximum number of routes to try (cheapest first) when trying to move the balance. (default 20)
  -max-search-time duration
    	maximum length of time waiting while searching for the next route. (default 30s)
  -max-to-channels uint
    	maximum number of channels to try to use as a destination for balance. (default 5)
  -quiet
    	only show errors and critical messages.
  -server string
    	hostname and port to use when connecting to LND. (default "localhost:10009")
  -target-empty-from-percentage uint
    	percent-fullness of the 'from' channels that the command should aim to achieve. (default 50)
  -target-fill-to-percentage uint
    	percent-fullness of the 'to' channel that the command should aim to achieve. (default 99)
  -timeout duration
    	timeout to use when connecting to LND. (default 30s)
  -tip value
    	tip amount (in satoshis) to the developer as a thank-you (Tip is only paid if an action is performed.)
  -to value
    	specific channel IDs to move funds to (overrides heuristics determining needy channels). This parameter can be specified multiple times per command.
  -to-emptiness-threshold-percentage uint
    	maximum percentage full the channel must be to be deemed capable of being a destination for balance. (default 25)
  -verbose
    	show additional logging information.
  -version
    	report the version being used.

Like many LN Toolkit commands, auto-balance can take a --dry-run parameter to go through the motions of connecting and deriving routes, but without actually sending the funds. This will show you what the command will try to do, but auto-balance has no way of knowing which, if any, routes will succeed so it just keeps going until it reaches another termination condition.

Like all LN Toolkit commands, auto-balance can take a --verbose flag to greatly increase the amount of diagnostic output it creates (including JSON representations of routes, if you like that kind of thing). It can also take a --tip <amount> parameter if you want to tip me some satoshis.

Heuristics

A channel is deemed ‘in need’ (i.e. being a to channel) if its percentage ‘fullness’ is less than the --max-to-balance-percentage parameter (default value: 25).

A channel is deemed ‘capable’ (i.e. being a from channel) if its percentage ‘fullness’ is greater than the --min-from-balance-percentage parameter (default value: 75).

To change these to only choose ‘to’ channels less than 20% full, and ‘from’ channels greater than 80% full, use a command such as:

lntoolkit auto-balance --max-fees-msat 5000 --max-amount 1000000 --max-to-balance-percentage 20 --min-from-balance-percentage 80