LN Toolkit Command

empty-channel’ command

empty-channel tries to move funds from a single specifed channel into several of your other channels.

empty-channel finds your channels with a deficit of funds and tries, one by one, to move funds into them from the channel you specify. Unlike auto-balance, this command doesn’t remove the source channel from processing after the first successful move.

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 empty-channel --from 1629436649948643328 --max-fees-msat 5000 --max-amount 1000000 --max-to-channels 25 --verbose

This tries to move up to 1000000sats (from --max-amount 1000000) to up to 25 of your channels (from --max-from-channels 25) from your channel with ID 1629436649948643328 (from --from 1629436649948643328) and it will not use any routes that cost more than 5000msats (from --max-fees-msat 5000). It will start with the channels it believes has the most need for funds, and it will process each of them until it runs out of channels or it the --to channel becomes empty.

Usage

Here’s the list of parameters it can take:

Usage of empty-channel:
  -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
    	target channel ID to try to move funds from.
  -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' channel that the command should aim to achieve. (default 1)
  -target-fill-to-percentage uint
    	percent-fullness of the 'to' channels that the command should aim to achieve. (default 50)
  -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, empty-channel 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 empty-channel 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, empty-channel 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.