LN Toolkit Command

move-balance’ command

move-balance tries to move funds from one of your channels to another of your channels.

This is trickier than it sounds. What it tries to do is build a route out from your node, on the channel you specify as the ‘--from’ channel, out to zero or more other nodes, that comes back to your node on the channel you specify as the ‘--to’ channel.

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 move-balance --from 1633460862503419905 --to 1629436649948643328 --amount 500000 --max-fees-msat 5000

This tries to move 500000sats from your channel with ID 1633460862503419905 to your channel with 1629436649948643328. It will try routes starting with the cheapest, it will not use any routes that cost more than 5000msats, it will keep trying as long as it keeps finding new routes, and it will stop after the first successful transfer of funds.

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 move-balance:
  -amount value
    	amount to move from the 'from' channel to the 'to' 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.
  -final-cltv-delta uint
    	final CLTV delta to use in the routes from the 'from' channel to the 'to' channel. (default 144)
  -from value
    	channel ID 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-fees-msat value
    	maximum fees (in msat) to be spent on the balance move. (default m㋛10,000)
  -max-hops int
    	maximum number of hops in routes used for the balance move. (default 20)
  -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)
  -quiet
    	only show errors and critical messages.
  -server string
    	hostname and port to use when connecting to LND. (default "localhost:10009")
  -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
    	channel ID to move funds to.
  -verbose
    	show additional logging information.
  -version
    	report the version being used.

Like many LN Toolkit commands, move-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 move-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, move-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.