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 four additional methods for helping to rebalance channels:

1. Either you can call lightning-cli rebalanceall to automatically fix all of your channels' liquidity.
2. lightning-cli rebalancestop stops the ongoing rebalanceall.
3. Or you can call lightning-cli rebalance outgoing_scid incoming_scid to rebalance individual channels.
4. lightning-cli rebalancereport shows information: plugin settings, past rebalance stats, etc.

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:

1. 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.
2. The secondary goal is to distribute the remaining liquidity evenly between the big channels.
3. 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 rebalanceall

• OPTIONAL: The min_amount parameter 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 feeratio sets how much the rebalance may cost as a ratio of your default fee. Its default value is 0.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] [retry_for] [maxfeepercent] [exemptfee] [getroute_method]

def rebalance(plugin, outgoing_scid, incoming_scid, msatoshi: Millisatoshi = None, retry_for: int = 60, maxfeepercent: float = 0.5, exemptfee: Millisatoshi = Millisatoshi(5000), getroute_method=None): 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 rebalance

• The outgoing_scid is the short_channel_id of the sending channel,
• The incoming_scid is the short_channel_id of the receiving channel.
• OPTIONAL: The msatoshi parameter 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: retry_for defines the number of seconds the plugin will retry to find a suitable route. Default: 60 seconds.
• OPTIONAL: maxfeepercent is a perecentage limit of the money to be paid in fees and defaults to 0.5.
• OPTIONAL: The exemptfee option can be used for tiny payments which would be dominated by the fee leveraged by forwarding nodes. Setting exemptfee allows the maxfeepercent check to be skipped on fees that are smaller than exemptfee (default: 5000 millisatoshi).
• OPTIONAL: The getroute_method option can be for route search can be 'basic' or 'iterative'.
  'basic': Tries all routes sequentially.
  'iterative': Tries shorter and bigger routes first.

Tips and Tricks for individual rebalance

• To find the correct channel IDs, you can use the summary plugin 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 lightningd logs for further information.
• Channels have a channel_reserve_satoshis value, 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.