clboss/contrib

Contributed CLBOSS Utilities

Installing

There are two ways to install the requirements:

• poetry
• nix

Poetry

There are two ways to install poetry:

• pipx
• official installer

Pipx

# Install pipx
sudo apt update
sudo apt install pipx
pipx install poetry

Or, click here for the official installer

Once poetry is installed, install the Python dependencies:

# The following commands need to be run as the user who will be running
# the clboss utility commands (connecting to the CLN RPC port)

# Install clboss contrib utilities
poetry shell
poetry install

Nix

If you have nix, you can just do, from the project root:

nix-shell contrib-shell.nix

Then before running the commands below, be sure to do:

cd contrib/

Running

./clboss-earnings-history

./clboss-recent-earnings

./clboss-routing-stats

./clboss-forwarding-stats

./recently-closed

./clboss-askrene-layer-summary

./cln-plugin-bounce <plugin-name>...

The `clboss-routing-stats` and `clboss-forwarding-stats` scripts now accept `--days` to limit
how many days of earnings history are considered when ranking channels.

Script Details

• clboss-earnings-history now supports additional options:
  • --csv-file <file> writes the raw earnings data as CSV.
  • --graph-file <file> generates a PNG plot of net earnings.
  • --bucket lets you aggregate by day, week, fortnight, month, or quarter.
• clboss-forwarding-stats summarizes channel forwarding data and can be restricted with --days.
• clboss-routing-stats ranks peers using recent earnings data and also accepts the --days option.
• recently-closed lists channels that closed within the last N days, also controlled via --days.
• clboss-askrene-layer-summary rolls an askrene layer's raw constraint dump up into a breadth/depth census: how many distinct channel-directions the layer knows about and how many constraint entries are stacked on each, with --top N resolving the busiest directions to node aliases. Works on any persistent layer (clboss by default) and can replay a captured askrene-listlayers dump offline via --input.
• cln-plugin-bounce stops and restarts running plugins without restarting lightningd. plugin stop needs a plugin's exact registered name, which for versioned installs includes the version string; the script looks each one up from plugin list, stops the named plugins in the order given, and starts them again in reverse order, so the list order encodes any shutdown dependency between them. Restarts use the unversioned sibling path when one exists (usually a symlink maintained by the install script), so a repointed symlink brings up the new version. Plugin names are the arguments not starting with -; every other argument is passed to lightning-cli (e.g. --signet --lightning-dir=...), so names and options may appear in any order. Plain POSIX sh plus jq, so unlike a shell alias it also works under sudo.
• fee-log-parser is a parser that streams DEBUG-level logging and writes a sqlite database containing fee algorithm information. CLBOSS now records the same schema in its internal database (data.clboss, tables feemon_peers and feemon_change_events) during normal operation.
• clboss-feemon-history is a CLBOSS command that returns per-peer fee modifier history between optional since/before timestamps.
• clboss-feemon-peers is a CLBOSS command that returns peer nodeids with fee monitor history between optional since/before timestamps.
• feemon-validate compares fee-log-parser sqlite history against clboss-feemon-history per peer over a requested time window. It reports per-peer progress, prints compact timestamp diagnostics for missing/extra records, prints full-record diagnostics for field mismatches, and exits non-zero when discrepancies are found. Default external DB path is ./clboss-fee-info.sqlite3 and default timestamp tolerance is 60 seconds. Default float tolerance is 1e-5 and is scaled by value magnitude (tol * max(1, |a|, |b|)) to avoid false mismatches from JSON float rendering precision (notably mult_product). Derived integer fields est_base and est_ppm use a relative tolerance with default 1e-3 (--int-rel-tolerance) so small rounding effects at large magnitudes do not trigger mismatches. --since/--before accept Unix epoch seconds in addition to the existing human-readable time formats. Naive timestamps are interpreted in local time; Unix epoch input is UTC; explicit timezone offsets are honored.
• plot-fees plots fee-related time series for a peer from merged fee monitor data: API history (clboss-feemon-history) plus legacy sqlite history (fee-log-parser). When both sources cover a period, API records are preferred and sqlite is used only for earlier history. By default it uses API data only; pass --db to include legacy sqlite history. --peer accepts a nodeid, alias (via lightning-cli/listnodes), or SCID (via lightning-cli/listpeerchannels). The combo view includes a daily earnings panel (incoming/outgoing msat per day) when lightning-cli is available, and the incoming-earnings/outgoing-earnings views render those panels on their own. In the theory panel, a theory_center line is drawn only where API records include price_center; legacy-only spans omit that line. Use --title to override the plot title (defaults to the peer label; pass empty to omit).
• plot-aggregate plots aggregate percentile summaries from merged fee monitor data (API preferred over overlapping legacy sqlite history). By default it uses API data only; pass --db to include legacy sqlite history. Views include baseline-base, baseline-ppm, size, balance, theory, advertised-base, advertised-ppm, earnings, and a combo view. Each view shows daily p00/p10/p25/p50/p75/p90/p100 percentiles across nodes. The earnings view uses clboss-earnings-history all to compute net earnings percentiles (sat/day). In API mode, peer discovery uses clboss-feemon-peers [since] [before] so windowed aggregate plots include peers that were active during the selected period (even if currently closed).