⚡ ln-health

Lightning Node Health Score — Diagnose and score your Lightning Network node in seconds.

┌──────────────────────────────────────────────────────────┐
│            ⚡  LIGHTNING NODE HEALTH SCORE  ⚡            │
├──────────────────────────────────────────────────────────┤
│ Node:  SatoshiRouter                                     │
│ Back:  LND                                               │
├──────────────────────────────────────────────────────────┤
│ OVERALL SCORE   A                                        │
│ [██████████████████████████░░░] 91/100                   │
│ Excellent! Your node is in great shape.                  │
├──────────────────────────────────────────────────────────┤
│ CHECKS                                                   │
│                                                          │
│ ✓  Sync Status          ▪▪▪▪▪▪▪▪▪▪▪▪  100/100           │
│ ✓  Channel Health       ▪▪▪▪▪▪▪▪▪▪▪░   90/100           │
│ ✓  Liquidity Balance    ▪▪▪▪▪▪▪▪▪▪▪░   88/100           │
│ ✓  Routing Activity     ▪▪▪▪▪▪▪▪▪▪▪▪  100/100           │
│ ✓  Fee Policy           ▪▪▪▪▪▪▪▪▪▪░░   85/100           │
│ ✓  Peer Diversity       ▪▪▪▪▪▪▪▪▪▪▪▪  100/100           │
│ ⚠  Backup Reminder      ▪▪▪▪▪▪▪▪░░░░   70/100           │
└──────────────────────────────────────────────────────────┘

Features

• 7 health checks covering sync, channels, liquidity, routing, fees, peers, and backups
• Grades A–F with detailed explanations and fix suggestions
• LND and Core Lightning support
• JSON output for scripting and monitoring
• Nostr post generator — copy-paste ready with hashtags
• Demo mode — try it without a real node
• Zero dependencies — pure Python 3.9+

Checks

Check	Weight	What it measures
Sync Status	20%	Chain + graph sync state
Channel Health	20%	Active vs inactive channels
Liquidity Balance	20%	Local/remote liquidity ratio
Routing Activity	15%	Forwards + fees in last 30 days
Fee Policy	10%	Fee sanity (not too high/low)
Peer Diversity	10%	Number of connected peers
Backup Reminder	5%	Static reminder to check backups

Quick Start

Option 1 — pip install (recommended)

pip install ln-health
ln-health --backend lnd

Option 2 — from source

git clone https://github.com/shadowbipnode/ln-health
cd ln-health
pip install -e .
ln-health --backend lnd

Option 3 — run directly

git clone https://github.com/shadowbipnode/ln-health
cd ln-health
python -m ln_health --backend lnd

Try without a real node (demo mode)

python -m ln_health.demo good      # A-grade node
python -m ln_health.demo average   # C-grade node
python -m ln_health.demo bad       # F-grade node

Usage

usage: ln-health [-h] [--backend {lnd,cln}]
                 [--lncli LNCLI] [--rpc-server RPC_SERVER]
                 [--macaroon MACAROON] [--tls-cert TLS_CERT]
                 [--network {mainnet,testnet,regtest,simnet}]
                 [--lightning-cli LIGHTNING_CLI] [--rpc-file RPC_FILE]
                 [--output {pretty,json,nostr}] [--verbose] [--no-color]

Examples

# Default LND (uses lncli from PATH)
ln-health --backend lnd

# LND with custom paths
ln-health --backend lnd \
  --rpc-server localhost:10009 \
  --macaroon ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon \
  --tls-cert ~/.lnd/tls.cert

# Core Lightning
ln-health --backend cln

# Full verbose output (all check details)
ln-health --backend lnd --verbose

# JSON output
ln-health --backend lnd --output json

# JSON + jq
ln-health --backend lnd --output json | jq '.total_score'

# Generate a Nostr post
ln-health --backend lnd --output nostr

# Testnet
ln-health --backend lnd --network testnet

# No colors (for logging)
ln-health --backend lnd --no-color

Share on Nostr

Generate a ready-to-copy Nostr post with your node score:

ln-health --backend lnd --output nostr

For Docker users:

ln-health --backend lnd --lncli "/home/$USER/lnd-cli-wrapper.sh" --output nostr

Example output:

⚡ Lightning Node Health Score

Node: shadowbip
Score: 70/100  Grade: C  🟡

✅ Sync Status: 100/100
✅ Channel Health: 100/100
⚠️ Liquidity Balance: 75/100
⚠️ Routing Activity: 25/100
⚠️ Fee Policy: 55/100
⚠️ Peer Diversity: 55/100

Checked with ln-health 🛠️
github.com/shadowbipnode/ln-health

#Bitcoin #Lightning #LightningNetwork #NodeRunner

Copy the output and paste it into your Nostr client (Primal, Damus, Coracle, etc.).

Note: The tool does NOT automatically publish to Nostr. You copy and paste manually for security reasons (your private key never leaves your Nostr client).

Node runner setups

Docker (LND container)

Create a wrapper script to run lncli inside the container:

cat > ~/lnd-cli-wrapper.sh << 'EOF'
#!/bin/bash
docker exec lnd lncli "$@"
EOF
chmod +x ~/lnd-cli-wrapper.sh

Run ln-health:

ln-health --backend lnd --network mainnet --lncli "/home/$USER/lnd-cli-wrapper.sh"

Alternative method (using RPC and mounted files):

ln-health --backend lnd \
  --network mainnet \
  --rpc-server localhost:10009 \
  --macaroon /home/$USER/.lnd/data/chain/bitcoin/mainnet/admin.macaroon \
  --tls-cert /home/$USER/.lnd/tls.cert

Umbrel

cd ~/umbrel/app-data/lightning/data/lnd
ln-health --backend lnd \
  --macaroon ./chain/bitcoin/mainnet/admin.macaroon \
  --tls-cert ./tls.cert

RaspiBlitz

ln-health --backend lnd \
  --macaroon /mnt/hdd/lnd/data/chain/bitcoin/mainnet/admin.macaroon \
  --tls-cert /mnt/hdd/lnd/tls.cert

Start9 (Embassy OS)

ln-health --backend lnd \
  --rpc-server <your-embassy-ip>:10009 \
  --macaroon <path-to-macaroon> \
  --tls-cert <path-to-cert>

myNode

ln-health --backend lnd \
  --macaroon /home/bitcoin/.lnd/data/chain/bitcoin/mainnet/admin.macaroon \
  --tls-cert /home/bitcoin/.lnd/tls.cert

Automate with cron

Add to your crontab to get daily scores:

# Daily health check at 9am, save to log
0 9 * * * /usr/local/bin/ln-health --backend lnd --no-color >> ~/ln-health.log 2>&1

# Weekly Nostr-ready report
0 8 * * 1 /usr/local/bin/ln-health --backend lnd --output nostr >> ~/nostr-weekly.txt

JSON output schema

{
  "node_alias": "SatoshiRouter",
  "node_pubkey": "02abc...",
  "backend": "LND",
  "timestamp": "2025-01-01 09:00:00 UTC",
  "total_score": 91,
  "grade": "A",
  "summary": "Excellent! Your node is in great shape.",
  "checks": [
    {
      "name": "Sync Status",
      "score": 100,
      "status": "ok",
      "detail": "Chain synced ✓ | Graph synced ✓ | Block #850001",
      "suggestion": ""
    }
  ]
}

Contributing

PRs welcome! Ideas for next features:

• Watchtower check
• HTLCs in-flight analysis
• Channel age scoring
• Telegram / email alerts
• Web dashboard
• HTLC success rate check
• Mempool fee awareness

git clone https://github.com/shadowbipnode/ln-health
cd ln-health
pip install -e ".[dev]"
pytest tests/

License

MIT — free to use, modify, share.

---

Built with ⚡ — Share your score on Nostr!

#Bitcoin #Lightning #LightningNetwork #NodeRunner