Rebalance plugin
This plugin moves liquidity between your channels using circular payments
Installation
For general plugin installation instructions see the repos main README.md
Usage
Once the plugin is installed and active, there are two additional methods to rebalance channels:
- Either you can call
lightning-cli rebalanceallto automatically fix all of your channels' liquidity. - Or you can call
lightning-cli rebalance outgoing_scid incoming_scidto rebalance individual channels.
Automatic rebalance
A lightning node usually has multiple channels of different sizes. The node can perform best if all channels have {enough_liquidity} for both directions. So the rebalance has multiple purposes with different priority:
- The primary goal is to ensure all channels have
{enough_liquidity}for both direction, or if a given channel is too small for that, then it has a 50/50 liquidity ratio. - The secondary goal is to distribute the remaining liquidity evenly between the big channels.
- For the long run, it is very important to do this economically. So the fees of fixing liquidity have to be cheaper than the fees of transaction forwards, which can ruin the liquidity again. (This assumes your node has some rational fee setting.) This way the automatic rebalance can run regularly, and your node can earn more on transaction forwarding than spend for rebalancing.
If the plugin cannot find a cheap enough circular route to rebalancing economically, then it does nothing by default. To not to cause a loss for users.
Rebalancing strategy
As a first step, depending on the actual situation, there is a need to get a value of {enough_liquidity}. The plugin searches for a maximum possible threshold. For which all channels theoretically can be balanced beyond this threshold. Or smaller than threshold * 2 channels can be balanced to a 50/50 ratio. {enough_liquidity} will be half of this maximum threshold.
The next step is to calculate {ideal_ratio} for big channels. Beyond the {enough_liquidity} threshold, big channels should share the remaining liquidity evenly, so every big channels' liquidity ratio should be close to the {ideal_ratio}.
After we know the current {enough_liquidity} threshold and {ideal_ratio}, the plugin checks every possible channel pairs to seek a proper rebalance opportunity. If it finds a matching pair, it calls the individual rebalance method for them. If the rebalance fails, the plugin tries again with a lesser amount, until it reaches the minimum rebalancable amount, or the rebalance succeeds.
This process may take a while. Automatic rebalance can run for hours in the background, but you can stop it anytime with lightning-cli rebalancestop.
Parameters for automatic rebalance
- OPTIONAL: The
min_amountparameter sets the minimum rebalancable amount in millisatoshis. The parameter also can be specified in other denominations by appending a valid suffix, i. e. '1000000sat', '0.01btc' or '10mbtc'. The default value is '50000sat'. - OPTIONAL: The
feeratiosets how much the rebalance may cost as a ratio of your default fee. Its default value is0.5, which means it can use a maximum of half of your node's default fee.
Tips and Tricks for automatic rebalance
- It may work only with well-connected nodes. You should have several different channels to use it with a good chance for success.
- Your node should have some rational default fee setting. If you use cheaper fees than your neighbors, it probably cannot find a cheap enough circular route to rebalance.
Individual channel rebalance
You can use the lightning-cli to rebalance channels like this:
lightning-cli rebalance outgoing_scid incoming_scid [msatoshi] [maxfeepercent] [retry_for] [exemptfee]
If you want to skip/default certain optional parameters but use others, you can
use always the lightning-cli -k (key=value) syntax like this:
lightning-cli rebalance -k outgoing_scid=1514942x51x0 incoming_scid=1515133x10x0 maxfeepercent=1
Parameters for individual rebalance
- The
outgoing_scidis the short_channel_id of the sending channel, - The
incoming_scidis the short_channel_id of the receiving channel. - OPTIONAL: The
msatoshiparameter sets the amount in milli-satoshis to be transferred. If the parameter is left out, the plugin will calucate an amount that will balance the channels 50%/50%. The parameter can also be given in other denominations by appending i.e. '1000000sat', '0.01btc' or '10mbtc'. - OPTIONAL:
maxfeepercentis a perecentage limit of the money to be paid in fees and defaults to 0.5. - OPTIONAL:
retry_fordefines the number of seconds the plugin will retry to find a suitable route. Default: 60 seconds. - OPTIONAL: The
exemptfeeoption can be used for tiny payments which would be dominated by the fee leveraged by forwarding nodes. Settingexemptfeeallows themaxfeepercentcheck to be skipped on fees that are smaller than exemptfee (default: 5000 millisatoshi).
Tips and Tricks for individual rebalance
- To find the correct channel IDs, you can use the
summaryplugin which can be found here. - The ideal amount is not too big, but not too small: it is difficult to find a route for a big payment, however some node refuses to forward too small amounts (i.e. less than a thousand msatoshi).
- After some failed attempts, may worth checking the
lightningdlogs for further information. - Channels have a
channel_reserve_satoshisvalue, which is usually 1% of the channel's total balance. Initially, this reserve may not be met, as only one side has funds; but the protocol ensures that there is always progress toward meeting this reserve, and once met, it is maintained. Therefore you cannot rebalance a channel to be completely empty or full.