diff --git a/README.md b/README.md index e849a1c..94a1c74 100644 --- a/README.md +++ b/README.md @@ -4,70 +4,107 @@ Tool for pretty printing and optimizing Lightning Network channels. ![screenshot](screenshot.png) +## Features + +* Displays channel balances with visual ratio bars, sorted by outbound liquidity +* Shows local and remote fee rates, base fees, uptime, last forward time, and earned fees +* Supports dynamic fee policy based on channel balance (incentivize rebalancing) +* Integrates with [Lightning Terminal](https://terminal.lightning.engineering/) for node scores and good peer detection +* Optionally displays HTLC limits, channel IDs, disabled status, and forwarding statistics +* Filter and split view for public/private channels +* Supports LND (via `lncli` and REST API) and Core Lightning (CLN) +* Color-coded output: local-opened channels in blue, remote-opened in yellow + ## Installation 1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) 2. `uv sync` 3. `uv run ./suez` +## Usage + +``` +uv run ./suez [OPTIONS] +``` + +### Options + +| Option | Default | Description | +|---|---|---| +| `--client` | `lnd` | Lightning client to use (`lnd`, `c-lightning`, `lnd-rest`) | +| `--client-args` | | Extra arguments to pass to the client CLI (repeatable) | +| `--base-fee` | `0` | Set base fee (msat) | +| `--fee-rate` | `0` | Set fee rate (ppm) | +| `--fee-spread` | `0.0` | Fee spread multiplier for balance-based fee adjustment | +| `--time-lock-delta` | `40` | Set time lock delta | +| `--channels` | `all` | Which channels to show (`all`, `public`, `private`, `split`) | +| `--show-remote-fees` | off | Show estimate of remote fees earned | +| `--show-scores` | off | Show node scores from Lightning Terminal | +| `--show-good-peers` | off | Show good inbound/outbound peers from Lightning Terminal | +| `--show-chan-ids` | off | Show channel IDs | +| `--show-forwarding-stats` | off | Show forwarding counts and success percentages (CLN) | +| `--show-minmax-htlc` | off | Show min and max HTLC amounts | +| `--show-disabled` | off | Show whether channels are disabled | + +Options can also be set via environment variables with the `SUEZ_` prefix (e.g. `SUEZ_FEE_RATE=500`). + ## Channel fee policy -You can set channel fees by passing `--base-fee` and `--fee-rate` parameters. +You can set channel fees by passing `--base-fee` and `--fee-rate` parameters: -For example: +``` +uv run ./suez --base-fee 1000 --fee-rate 200 +``` -`uv run ./suez --base-fee 1000 --fee-rate 200` +The fee policy adjusts rates based on each channel's balance using `--fee-spread`: -You can override the channel fee policy by changing the `FeePolicy` class. +* Channels with mostly **local** balance get a **lower** fee rate (encourage outbound flow) +* Channels with mostly **remote** balance get a **higher** fee rate (discourage outbound flow) +* **Balanced** channels stay close to the specified fee rate -Example implementation does the following: +The spread is controlled by `--fee-spread` (default `0.0` = no spread). For example: -* sets lower fee rate for channels with mostly local balance -* sets higher fee rate for channels with mostly remote balance -* sets medium (close to specified) fee rate for balanced channels +``` +uv run ./suez --base-fee 1000 --fee-rate 500 --fee-spread 1.8 +``` -You control the spread via the `--fee-spread` argument. By default `--fee-spread` is set to 0.0 (no spread). - -For example: - -`uv run ./suez --base-fee 1000 --fee-rate 500 --fee-spread 1.8` - -This will set the fee rate above 500 for channels with mostly remote balance and below 500 -for channels with mostly local balance. +You can customize the fee calculation by modifying the `FeePolicy` class in `feepolicy.py`. ## Lightning node support -Currently, Suez supports LND (both via `lncli` and via the REST API) and c-lightning. +### LND via `lncli` (default) -By default it uses LND (`lncli`). +``` +uv run ./suez +``` -You can use it with c-lightning as follows: +### LND via REST API -`uv run ./suez --client=c-lightning` +``` +SSL_CERT_FILE= uv run ./suez \ + --client=lnd-rest \ + --client-args=rpcserver=https://: \ + --client-args=macaroonpath= \ + --client-args=tlscertpath= +``` -You can connect to LND using the REST API as follows: +### Core Lightning (CLN) -`SSL_CERT_FILE= uv run ./suez --client=lnd-rest --client-args=rpcserver=https://: --client-args=macaroonpath= --client-args=tlscertpath=` +``` +uv run ./suez --client=c-lightning +``` -If you need to pass additional options to the lncli/lightning-cli you can do so: +### Passing extra client arguments -(single argument) +Use `--client-args` (repeatable) to pass additional options to the underlying CLI: -`uv run ./suez --client=c-lightning --client-args=--conf=/usr/local/etc/lightningd-bitcoin.conf` +``` +uv run ./suez --client=c-lightning --client-args=--conf=/usr/local/etc/lightningd-bitcoin.conf +``` -(multiple arguments) - -`uv run ./suez --client-args=--rpcserver=host:10009 --client-args=--macaroonpath=admin.macaroon --client-args=--tlscertpath=tls.cert` - -Adding support requires writing a client similar to `lndclient.py` and instantiating it in `suez.py`. - -## Donate - -You can tip me some satoshis via [tippin.me/@pavolrusnak](https://tippin.me/@pavolrusnak) - -or you can donate via Spontaneous AMP Payment (data field encodes `tip=suez`): - -`lncli sendpayment --amt 10000 --amp --dest 0385218f0e307b6a0e989d2a717d346942d96b4fd550e937de5f8ffe1568510a18 --data 7629168=7375657a` +``` +uv run ./suez --client-args=--rpcserver=host:10009 --client-args=--macaroonpath=admin.macaroon --client-args=--tlscertpath=tls.cert +``` ## License