ksedgwic/clboss v0.17.0

v0.17.0: Reason to Rebalance

on GitHub

CLBOSS v0.17.0 "Reason to Rebalance" replaces the built-in rebalancers with a new engine that runs on Core Lightning's askrene router through the external xrebalance plugin, ranks channel-open candidates by their earnings record, and makes most options settable at runtime.

Posts

• What's new in CLBOSS v0.17.0: a short summary for busy operators.
• Watching CLBOSS rebalance: the log greps that show it working.

What changed

• Rebalancing moves to a new engine, xrebalance: circular rebalances planned from each peer's earnings record and executed through the external xrebalance plugin on CLN's askrene min-cost-flow router. Cycles run on a Poisson clock and on demand when a forward drains a channel. Pricing is strict: a cycle's fee budget comes from what the involved peers actually earn. docs/xrebalance_overview.md explains how a cycle is decided and what the tuning options change.
• The built-in rebalancer (JIT, earnings, initial, FundsMover, clboss-movefunds) is removed. JIT rebalancing is removed deliberately: holding an incoming HTLC while a rebalance runs delays the whole payment path; demand-triggered cycles cover the same need without holding HTLCs. If you relied on JIT rebalancing, please open an issue describing your case.
• Channel-open candidates are ranked by their earnings track record (keepers first, unknowns next, underperformers last); among unknowns, peers advertising splicing are preferred. clboss-track-record <nodeid> shows the verdict.
• Many options are dynamic: lightning-cli setconfig changes them without a restart, and bad values are rejected instead of silently ignored.
• New contrib tools: clboss-xrebalance-view (the rebalancer's view of your node and the request the next cycle would send) and cln-plugin-bounce.
• A missing xrebalance plugin logs a warning once an hour, and clboss-status gains an xrebalancer entry with the plugin state.

Requirements and upgrading from 0.16.x

• Core Lightning v26.04 or later (v25.09 is the hard floor; below v26.04 CLBOSS starts with a warning). Operators on older Core Lightning should stay on CLBOSS 0.16.x.
• Install the xrebalance plugin, v0.4.5 or later, and load it alongside CLBOSS -- see "The xrebalance plugin" under Installing in the README. Without it CLBOSS runs everything except rebalancing.
• Remove clboss-max-rebalance-fee-ppm from your configuration; lightningd refuses to start on an unknown option.
• Development builds from between 0.16.x and this release created persistent askrene layers; see "Upgrading from 0.16.x" in CHANGELOG.md to remove them. Release builds of 0.16.x and the release candidates created none.

Reporting

• The XRebalancer: log lines describe every cycle (candidates, floor, request, and the transfer summary). Please include them, your clboss-xrebalance-* settings, and the CLN and plugin versions in reports.

See CHANGELOG.md for details.