lnflow/docs/README.md

Lightning Fee Optimizer

An intelligent Lightning Network channel fee optimization agent that analyzes your channel performance and suggests optimal fee strategies to maximize returns.

Features

• Real-time Data Analysis: Ingests comprehensive channel data from LND Manage API
• Intelligent Optimization: Uses machine learning-inspired algorithms to optimize fees based on:
  • Channel flow patterns
  • Historical earnings
  • Balance distribution
  • Demand elasticity estimation
• Multiple Strategies: Conservative, Balanced, and Aggressive optimization approaches
• Detailed Reporting: Rich terminal output with categorized recommendations
• Risk Assessment: Confidence levels and impact projections for each recommendation

Installation

# Clone the repository
git clone <repo-url>
cd lightning-fee-optimizer

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Requirements

• LND Manage API: Running at http://localhost:18081 (or configured URL)
• Python 3.8+
• Synced Lightning Node: Must be synced to the blockchain

Quick Start

1. Test the connection:

python test_optimizer.py

2. Run analysis only (no recommendations):

python -m src.main --analyze-only

3. Generate optimization recommendations:

python -m src.main --dry-run

4. Save recommendations to file:

python -m src.main --output recommendations.json

Command Line Options

python -m src.main [OPTIONS]

Options:
  --api-url TEXT           LND Manage API URL [default: http://localhost:18081]
  --config PATH           Configuration file path
  --analyze-only          Only analyze channels without optimization
  --dry-run              Show recommendations without applying them
  --verbose, -v          Enable verbose logging
  --output, -o PATH      Output recommendations to file
  --help                 Show this message and exit

Configuration

Create a config.json file to customize optimization parameters:

{
  "api": {
    "base_url": "http://localhost:18081",
    "timeout": 30
  },
  "optimization": {
    "min_fee_rate": 1,
    "max_fee_rate": 5000,
    "high_flow_threshold": 10000000,
    "low_flow_threshold": 1000000,
    "high_balance_threshold": 0.8,
    "low_balance_threshold": 0.2,
    "fee_increase_factor": 1.5
  },
  "dry_run": true
}

How It Works

1. Data Collection

• Fetches comprehensive channel data via LND Manage API
• Includes balance, flow reports, fee earnings, and policies
• Collects 7-day and 30-day historical data

2. Channel Analysis

The system calculates multiple performance metrics:

• Profitability Score: Based on net profit and ROI
• Activity Score: Flow volume and consistency
• Efficiency Score: Earnings per unit of flow
• Flow Efficiency: How balanced bidirectional flow is
• Overall Score: Weighted combination of all metrics

3. Channel Categorization

Channels are automatically categorized:

• High Performers: >70 overall score
• Profitable: Positive earnings >100 sats
• Active Unprofitable: High flow but low fees
• Inactive: <1M sats monthly flow
• Problematic: Issues requiring attention

4. Optimization Strategies

Conservative Strategy

• Minimal fee changes
• High flow preservation weight (0.8)
• 20% maximum fee increase

Balanced Strategy (Default)

• Moderate fee adjustments
• Balanced flow preservation (0.6)
• 50% maximum fee increase

Aggressive Strategy

• Significant fee increases
• Lower flow preservation (0.3)
• 100% maximum fee increase

5. Recommendation Generation

For each channel category, different optimization approaches:

High Performers: Minimal increases to test demand elasticity Underperformers: Significant fee increases based on flow volume Imbalanced Channels: Fee adjustments to encourage rebalancing Inactive Channels: Fee reductions to attract routing

Example Output

Lightning Fee Optimizer

Checking node connection...
📦 Current block height: 906504

Fetching channel data...
Found 41 channels

🔬 Analyzing channel performance...
Successfully analyzed 41 channels

╭────────────────────────────── Network Overview ──────────────────────────────╮
│ Total Channels: 41                                                             │
│ Total Capacity: 137,420,508 sats                                              │
│ Monthly Earnings: 230,541 sats                                                │
│ Monthly Costs: 15,230 sats                                                    │
│ Net Profit: 215,311 sats                                                      │
╰────────────────────────────────────────────────────────────────────────────────╯

High Performers: 8 channels
┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━┓
┃ Channel       ┃ Alias          ┃ Score ┃ Profit ┃  Flow ┃
┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━┩
│ 779651x576x1  │ WalletOfSatoshi│  89.2 │ 36,385 │158.8M │
│ 721508x1824x1 │ node_way_jose  │  87.5 │  9,561 │ 65.5M │
└───────────────┴────────────────┴───────┴────────┴───────┘

Generating fee optimization recommendations...

╭────────────────────────── Fee Optimization Results ──────────────────────────╮
│ Total Recommendations: 23                                                      │
│ Current Monthly Earnings: 230,541 sats                                        │
│ Projected Monthly Earnings: 287,162 sats                                      │
│ Estimated Improvement: +24.6%                                                 │
╰────────────────────────────────────────────────────────────────────────────────╯

Data Sources

The optimizer uses the following LND Manage API endpoints:

• /api/status/ - Node status and health
• /api/channel/{id}/details - Comprehensive channel data
• /api/channel/{id}/flow-report/last-days/{days} - Flow analysis
• /api/node/{pubkey}/details - Peer information

Integration with Balance of Satori

If you have Balance of Satori installed, you can use the recommendations to:

1. Manually apply fee changes: Use the recommended fee rates
2. Rebalancing decisions: Identify channels needing liquidity management
3. Channel management: Close underperforming channels, open new ones

Safety Features

• Dry-run by default: Never applies changes automatically
• Conservative limits: Prevents extreme fee adjustments
• Confidence scoring: Each recommendation includes confidence level
• Impact estimation: Projected effects on flow and earnings

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

Troubleshooting

Connection Issues:

• Verify LND Manage API is running
• Check API URL configuration
• Ensure node is synced

No Recommendations:

• Verify channels have sufficient historical data
• Check that channels are active
• Review configuration thresholds

Performance Issues:

• Reduce the number of channels analyzed
• Use configuration to filter by capacity
• Enable verbose logging to identify bottlenecks

License

MIT License - see LICENSE file for details.