Article posted originally to Y'alls.org where you can tip the author, who posted anonymously.
It was an eye opening moment for me when I realized I don't have to "loop-out" ever time I want to free up some outbound and get some inbound liquidity. Much cheaper to use bos tool -- rebalance. As a note, you node needs to have "circular rebalancing" enabled (in configuration file).
I paid in full for the article, and I found it immensely useful, so I'm posting it here for Stackers.
Enjoy!
BOS Rebalance Explained
Rebalances your channels by moving liquidity between your peers. A rebalance moves local funds from one peer to another peer of yours which helps in gaining inbound liquidity in the channel the funds are leaving and gaining outbound liquidity in the channel the funds are arriving.
Flags
amount
The maximum amount you want to rebalance
out: this flag can take the pubkey or Alias of your peer, its the first hop where you want the funds to leave from.
in
this flag can take the pubkey or Alias of your peer, its the last hop where the funds arrive into.
avoid
this can take pubkey, channel ID or a bos tag (more on this in a separate command below) where you can group multiple pubkeys to avoid while doing a rebalance. Avoid can take filters as well, explained in example below.
in-target-outbound
the amount of outbound you want to target for a peer's channel where the funds are coming into.
out-target-inbound
the amount of inbound you want to target for a peer's channel through which the funds are going out of.
max-fee-rate
the maximum fee rate in ppm that you want to pay for your rebalance
max-fee
the maximum total fees in sats that you want to pay for your rebalance
minutes
the maximum time you want the rebalance to run if it does not succeed or fail within the time you specified. The command will time-out after N number of minutes you specify.
in-filter
the set of in-peers you want the rebalance to filter through, this option is used with bos tags.
out-filter
the set of out-peers you want the rebalance to filter through, this option is used with bos tags.
Example:
bos rebalance --out "WalletOfSatoshi.com" --in "EDON" --out-target-inbound=capacity*0.85 --max-fee-rate 700 --max-fee 2000 --minutes 20 --avoid ban --avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/OR(FEE_RATE<80 , FEE_RATE>500)" --avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/HEIGHT<600000" --avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/opposite_fee_rate<100" --avoid "fee_rate<50/0296b46141cd8baf13f3eff9bb217c5f62ce0a871886559d661af0ef422c042d4b"
Breaking down this example:
--out "WalletOfSatoshi.com"
is the peer's channel where local funds move out from so it's the peer you want to gain inbound.
-- in "EDON"
is the peer's channel where funds leaving from the WalletOfSatoshi.com channel are coming into and local balance is increased or outbound is gained.
--out-target-inbound=capacity*0.85
This flag indicates that you want the channel with WalletOfSatoshi.com to have inbound liquidity of 85% of the total channel capacity, for example, if you have a 1M channel with WoS, you're targetting 850K of inbound. If you want a 50-50 channel with WoS, it would be --out-target-inbound=capacity*0.5 OR --out-target-inbound=capacity/2
--max-fee-rate 700
is the maximum fee rate in ppm you're willing to pay for the total rebalance
--max-fee 2000
is the total maxmimum fee in sats you're willing to pay for the rebalance including base fee. Note: Specify both values during a rebalance, the rebalance will fail if it finds a route and does not satisfy one of the criterias
--minutes 20
the rebalance will time out after 20 minutes of path finding, the time-out occurs if the rebalance does not succeed/fail within the specified time.
--avoid ban
"ban" is the name of the bos tag that I created, a tag can be named anything of your choice and you can add multiple pubkeys to the tag to categorize nodes. In this example, nodes specified in the tag "ban" will be avoided during path finding.
Avoid Filters:
avoid flag can take filter formulas along with a pubkey to filter channels of the pubkey specified during path finding.
Syntax
--avoid pubkey/forumla: If the syntax is pubkey followed by formula, the filter applies to channels of the node specified in the outbound direction.
Syntax
--avoid formula/pubkey: If the syntax is formula followed by pubkey, the filter applies to channels of the node specified in the inbound direction.
Example Breakdown Continued:
--avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/OR(FEE_RATE<80 , FEE_RATE>500)",
the pubkey specified in the filter belongs to WalletOfSatoshi.com, this formula implies you want to avoid all channels of WalletOfSatoshi that they charge less than 80ppm or greater than 500ppm. For example, if you just want to avoid a peer's channels greater than 200ppm the syntax is: --avoid "pubkey/FEE_RATE>200)
--avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/HEIGHT<680000"
the pubkey specified in the filter belongs to WalletOfSatoshi.com, this formula implies you want to avoid all channels of WalletOfSatoshi that were created before the block height of 680000, this block was mined on 2021-04-21 05:58 which implies you want to avoid all your WalletOfSatoshi's channels that were created before that date. The reason for using this could be, all old channels might not be well maintained and might not have liquidity in the direction you want.
--avoid "035e4ff418fc8b5554c5d9eea66396c227bd429a3251c8cbc711002ba215bfc226/opposite_fee_rate<100"
the pubkey specified in the filter belongs to WalletOfSatoshi.com, this formula implies you want avoid all channels of WalletOfSatoshi.com where the opposite_fee_rate is less than 100 or the rate which WalletOfSatoshi's peers charge them to route in the opposite direction, this is the fee rate that does NOT apply to you in the path finding because its in the opposite direction. The purpose of this filter is, a lot of nodes today are using dynamic fee rates to indicate to the network the direction in which they have liquidity using tools like charge-lnd. In the formula, by specifying you want to avoid low fee rates in the opposite direction you're effectively saying you want to avoid channels of WoS that are charging low because the liquidity is on the side of WoS's peers which is not the direction you need it for your rebalance to succeed. If the fee is high in the opposite direction an assumption can be made that liquidity is on WoS's side which is favorable for the success of your rebalance.
Example of inbound 2nd syntax:
--avoid "fee_rate<50/0296b46141cd8baf13f3eff9bb217c5f62ce0a871886559d661af0ef422c042d4b"
the pubkey specified in the filter belongs to EDON, this formula implies you want avoid all channels of coming into EDON that charge less than 50 ppm.
Similar inbound syntax can be applied to all other filters mentioned above.
Note: Avoid formulas can be applied to any node in the graph, it is not limited to just your peers, you can replace the public key with any public key of your choice.
Using --out-filter and --in-filter
If you create bos tags for your peers (check the tags command on how to create tags), you can use them for rebalances. instead of specifying --out and --in peer you can specify a group of nodes you want and bos can pick from those nodes to do rebalances with. Usage: bos rebalance --out-filter "inbound_liquidity<1m" --in-filter "outbound_liquidity<1m" --out-target-inbound=capacity*0.85 --max-fee-rate 700 --max-fee 2000 --minutes 20 --avoid ban