LNDg - GUI for LND Data Analysis and Node Management

Welcome to LNDg, an advanced web interface designed for analyzing Lightning Network Daemon (LND) data and automating node management tasks.

Table of Contents

• Installation
  • 1-Click Installation
  • Docker Installation
  • Manual Installation
• Updating LNDg
  • Docker Update
  • Manual Update
• Configuration
  • Backend Controller Setup
  • Webserver Setup (Optional)
  • PostgreSQL Setup (Optional)
  • Important Notes
• Key Features
  • Track Peer Events
  • Batch Channel Opens
  • Watch Tower Management
  • Fee Rate Suggestions
  • New Peer Suggestions
  • Channel Performance Metrics
  • Password Protected Login
  • Auto-Rebalance Action Suggestions
  • AR-Autopilot Setting
  • HTLC Failure Stream
  • API Backend
  • Peer Reconnection
• Auto-Fees
  • Auto-Fees Settings
  • Auto-Fees Notes
• Auto-Rebalancer
  • Understanding Auto-Rebalancer
  • Auto-Rebalancer Settings
  • Additional Customization Options
  • Steps to Start the Auto-Rebalancer
• Preview Screens

Installation

Choose your preferred installation method:

1-Click Installation

Easily install LNDg directly from popular platforms like Umbrel, Citadel, Start9, and RaspiBlitz. Follow the instructions provided by your chosen platform.

Docker Installation

This method requires Docker and Docker Compose to be installed on your system.

1. Prepare Installation:

# Clone the repository
git clone https://github.com/cryptosharks131/lndg.git

# Change directory to the repository
cd lndg

# Customize the docker-compose.yaml file
nano docker-compose.yaml

Replace the contents of docker-compose.yaml with your desired volume paths and settings. An example configuration is shown below:

services:
  lndg:
    build: .
    volumes:
      # Adjust paths according to your setup
      - /home/<user>/.lnd:/root/.lnd:ro
      - /home/<user>/<path-to>/lndg/data:/app/data:rw
    command:
      - sh
      - -c
      # Customize network ('mainnet' or 'testnet') and RPC address/port if needed
      - python initialize.py -net 'mainnet' -rpc '127.0.0.1:10009' -wn && python controller.py runserver 0.0.0.0:8889 > /var/log/lndg-controller.log 2>&1
    # Use host network mode for simplicity, adjust if needed
    network_mode: "host"

2. Build and Deploy:

# Build and deploy the Docker container in detached mode
docker-compose up -d

# Retrieve the admin password for the initial login
cat data/lndg-admin.txt

• This example configuration will host LNDg at http://<your-machine-ip>:8889.
• Log in to LNDg using the username lndg-admin and the password retrieved from data/lndg-admin.txt.

Manual Installation

This method provides a hands-on approach to setting up LNDg.

1. Install LNDg:

# Clone the repository
git clone https://github.com/cryptosharks131/lndg.git

# Change directory
cd lndg

# Ensure Python virtualenv is installed (example for Debian/Ubuntu)
sudo apt update && sudo apt install -y virtualenv

# Set up a Python 3 virtual environment
virtualenv -p python3 .venv

# Install required dependencies
.venv/bin/pip install -r requirements.txt

# Initialize settings (use --help for options)
# Add -wn or --whitenoise to serve static files if not using a separate webserver
.venv/bin/python initialize.py -wn

# Install whitenoise if the -wn flag was used
.venv/bin/pip install whitenoise

# Retrieve the admin password
cat data/lndg-admin.txt

# Run the development server (adjust IP/port if needed)
.venv/bin/python manage.py runserver 0.0.0.0:8889

• The initial login user is lndg-admin. The password is in data/lndg-admin.txt.
• Access LNDg at http://<your-machine-ip>:8889.

2. Setup Backend Controller:

The controller.py script manages backend database updates, automated rebalancing, HTLC stream data, and p2p trade secrets. Set it up to run persistently using systemd (recommended) or supervisord.

• Systemd:

  • Option 1 (Script): sudo bash systemd.sh
  • Option 2 (Manual): Manual Systemd Setup Instructions

• Supervisord:

  • Configure Supervisord: .venv/bin/python initialize.py -sd
  • Install Supervisord: .venv/bin/pip install supervisor
  • Start Supervisord: supervisord

Alternatively, use your preferred task scheduler (like cron) to run controller.py.

Updating LNDg

Docker Update

# Navigate to the lndg directory
cd lndg

# Stop the current containers
docker-compose down

# Rebuild the image without using cache
docker-compose build --no-cache

# Start the updated containers
docker-compose up -d

# OPTIONAL: Remove unused Docker objects
docker system prune -f

Manual Update

# Navigate to the lndg directory
cd lndg

# Pull the latest changes
git pull

# Install any new dependencies
.venv/bin/pip install -r requirements.txt

# Apply any database migrations
.venv/bin/python manage.py migrate

# Restart the LNDg service (web server and controller)
# Example for systemd:
# sudo systemctl restart lndg-web.service
# sudo systemctl restart lndg-controller.service
# If using supervisord:
# supervisorctl restart lndg-web
# supervisorctl restart lndg-controller
# If using the development server, stop and restart it:
# .venv/bin/python manage.py runserver 0.0.0.0:8889

If using a webserver like Nginx with uWSGI (see below), restart the uWSGI service:

sudo systemctl restart uwsgi.service

Configuration

Backend Controller Setup

As mentioned in the Manual Installation, the controller.py needs to run persistently. Use systemd or supervisord for reliable operation.

Webserver Setup (Optional)

For continuous operation and better performance, especially in non-DEBUG mode, use a dedicated webserver like Nginx instead of the Django development server. Using a webserver also handles static file serving, making the whitenoise dependency optional.

A helper script is included for setting up Nginx:

sudo bash nginx.sh

Remember to restart the uwsgi.service after updates if using this setup.

PostgreSQL Setup (Optional)

LNDg uses SQLite3 by default. You can configure it to use a PostgreSQL database for potentially better performance in high-usage scenarios.

See the Postgres Setup Guide for instructions.

Important Notes

1. Custom LND Settings: If not using default LND settings (e.g., non-default ports, network), use flags during initialize.py (check --help) or edit lndg/settings.py directly.
2. Static Files (Manual Install): If running manually without a separate webserver (like Nginx), you MUST use the -wn flag with initialize.py and install whitenoise to serve static files (.css, .js). Running the development server (manage.py runserver) with DEBUG=False without whitenoise or a webserver will cause issues.
3. Updating Settings: Modify lndg/settings.py directly or re-run initialize.py <options> -f to update settings.
4. Admin Credentials: Manage login credentials via the admin interface at http://<your-lndg-ip:port>/lndg-admin.
5. Firewall: Ensure your firewall allows incoming connections on the port LNDg is running on (default: 8889).

Key Features

Track Peer Events

Monitor changes your peers make to channel policies and track connection events for your open channels.

Batch Channel Opens

Open up to 10 channels simultaneously in a single transaction, potentially reducing on-chain fees.

Watch Tower Management

Add, monitor, and remove watchtowers connected to your LND node.

Fee Rate Suggestions

Receive suggestions for adjusting outbound fee rates based on the last 7 days of payment and forwarding data. Enable Auto-Fees to act on these suggestions automatically. Note: Allow ~24 hours after a manual change before making another adjustment on the same channel.

New Peer Suggestions

Get recommendations for new peers based on your node's successful routing history, considering:

• Volume Score: Based on the count and volume of transactions routed through the peer.
• Savings By Volume (ppm): Estimated sats saved on rebalances if peered directly, relative to the volume routed through the peer.

Channel Performance Metrics

Aggregate payment and forwarding data provides:

1. Outbound Flow: Amount routed outbound vs. amount rebalanced in.
2. Revenue: Total earned, profit (revenue - cost), and assisted revenue (earned due to this channel's inbound).
3. Inbound Flow: Amount routed inbound vs. amount rebalanced out.
4. Updates: Number of channel updates (correlates to channel.db size).

A dedicated P&L page tracks overall node metrics and profitability.

Password Protected Login

Initial username is lndg-admin. Change it via the /lndg-admin page.

Auto-Rebalance Action Suggestions

LNDg suggests actions to optimize Auto-Rebalancing (AR).

AR-Autopilot Setting

Enable this setting (AR-Autopilot) to automatically implement the suggestions from the AR Actions page.

HTLC Failure Stream

Listen for and record HTLC failure events to the dashboard.

API Backend

Access data programmatically via the /api endpoint. Available resources include: payments, paymenthops, invoices, forwards, onchain, peers, channels, rebalancer, settings, pendinghtlcs, failedhtlcs. Append ?format=json for JSON output.

Peer Reconnection

Automatically attempts to reconnect to peers associated with inactive channels (max once every 3 minutes per peer).

Auto-Fees

LNDg can automatically update channel fees based on performance suggestions.

Auto-Fees Settings

Customize Auto-Fees (AF) behavior via the settings page:

• AF-Enabled: Set to 1 to enable Auto-Fees globally. Individual channels must also be enabled.
• AF-FailedHTLCs: Minimum daily failed HTLC count to potentially trigger a fee increase (based on flow).
• AF-Increment: Base increment size (ppm) for fee changes. Suggestions are multiples of this value.
• AF-MaxRate: Maximum fee rate (ppm) AF can set.
• AF-MinRate: Minimum fee rate (ppm) AF can set.
• AF-Multiplier: Multiplies the AF-Increment for larger fee adjustments.
• AF-UpdateHours: Minimum hours between AF adjustments for a single channel (default: 24).
• AF-LowLiqLimit: Outbound liquidity (%) threshold below which the "Low Liquidity" fee algorithm applies.
• AF-ExcessLimit: Outbound liquidity (%) threshold above which the "Excess Liquidity" fee algorithm applies.

Auto-Fees Notes

1. AF adjustments occur only if AF-UpdateHours have passed since the last LNDg fee update for that channel.
2. Channels below AF-LowLiqLimit% outbound liquidity may see fee increases based on failed HTLCs and incoming flow.
3. Channels above AF-ExcessLimit% outbound liquidity may see fee decreases based on lack of flow or assisted revenue.
4. Channels between these limits adjust based on overall flow patterns.
5. View AF change history in the "Autofees" tab.

Auto-Rebalancer

Automatically manage channel liquidity to maintain outbound capacity on profitable routes. See the Quick Start Guide.

Understanding Auto-Rebalancer

The goal is to move funds (rebalance) into the local side (outbound capacity) of channels that frequently route payments out successfully. This ensures liquidity is available to earn routing fees.

Auto-Rebalancer Settings

Configure Auto-Rebalancer (AR) globally:

• AR-Enabled: Set to 1 to activate AR (default: 0).
• AR-Target%: Default rebalance amount as a percentage of channel capacity (e.g., 0.05 means 5%). Used if not set per-channel (default: 5).
• AR-Time: Maximum time (minutes) to search for a rebalance route (default: 5).
• AR-MaxFeeRate: Absolute maximum fee rate (ppm) allowed for any rebalance attempt (default: 100).
• AR-MaxCost%: Maximum rebalance fee limit as a percentage of the target inbound channel's current outbound fee rate (e.g., 0.65 means 65%) (default: 65).
• AR-Outbound%: Channels with more outbound liquidity than this percentage are considered potential sources for rebalancing funds from (default: 75). They must also not be targeted for receiving inbound liquidity.

Additional Customization Options

• AR-Autopilot: Set to 1 to automatically act on AR suggestions (default: 0).
• AR-WaitPeriod: Time (minutes) to wait before retrying a rebalance on a channel after a failure (default: 30).
• AR-Variance: Randomly vary the target rebalance amount by this percentage (default: 0).
• AR-Inbound%: Default inbound target (iTarget%) for newly monitored channels (default: 100).
• AR-APDays: Number of days of historical data for Autopilot decisions (default: 7).
• AR-Workers: Number of parallel rebalance attempts to run concurrently (default: 1).

Steps to Start the Auto-Rebalancer

1. Configure Target Channels (Receiving Inbound Liquidity): a. Go to the "Active Channels" section on the LNDg dashboard. b. Identify channels you want to refill with outbound liquidity (these are your profitable outbound routes). c. Click the "Enable" button in the far-right column for these target channels. d. The page will refresh, showing AR-Target: 100%. e. Adjust the AR-Target percentage for each channel. This represents the desired remote (inbound) liquidity percentage. E.g., 0.60 means you want 60% inbound / 40% outbound liquidity. Press Enter to save. f. Important: Enable all channels valuable for outbound routing, even if you don't actively target them for refilling. Set their AR-Target to 100% to prevent AR from using them as a source for rebalancing funds away from them.

2. Update Global Settings: a. Go to the "Update Auto Rebalancer Settings" section. b. Set Enabled: 1 to activate the rebalancer. c. Configure other global settings (Target Amount (%), Target Time (min), Target Outbound Above (%), Global Max Fee Rate (ppm), Max Cost (%)) as needed. d. Click "OK" to submit.

3. Monitor Rebalances: a. Check the "Last 10 Rebalance Requests" section to view the queue and status of attempts.

Notes on AR Logic:

• Rebalances aim to decrease inbound liquidity below the channel-specific AR-Target%.
• Channels with outbound liquidity above the global AR-Outbound% are potential sources to push funds from, unless they are themselves enabled with an AR-Target.
• Successful attempts or failures due to incorrect payment info are retried immediately.
• Other failures trigger a wait period (AR-WaitPeriod) before retrying on that channel.

Preview Screens

Main Dashboard

Separate Screens (Performance, Peers, Balances, etc.)

Manage Auto-Fees / Get Suggestions

Batch Open Channels

Suggestions (Peers, Rebalancer Actions)

API Browser (/api)

View Keysend Messages

(Requires accept-keysend=true in lnd.conf)