lnflow/README.md

Lightning Policy Manager

Next-generation Lightning Network channel fee optimization with advanced inbound fee strategies, machine learning, and automatic rollback protection.

Overview

Lightning Policy Manager is an intelligent fee management system that enhances the popular charge-lnd tool with:

• Advanced inbound fee strategies (beyond simple discounts)
• Automatic rollback protection for safety
• Machine learning optimization from historical data
• Revenue maximization focus vs simple rule-based approaches
• High-performance gRPC integration with REST fallback
• Comprehensive security with method whitelisting
• Complete charge-lnd compatibility

Quick Start

1. Setup Environment

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Setup secure gRPC (optional, for better performance)
./scripts/setup_grpc.sh

2. Generate Configuration

# Create a sample policy configuration
./lightning_policy.py generate-config my_policy.conf

3. Test Policies (Dry Run)

# Test your policies without applying changes
./lightning_policy.py -c my_policy.conf apply --dry-run

4. Apply Policies

# Apply fee changes via high-performance gRPC
./lightning_policy.py -c my_policy.conf apply

# Or use REST API
./lightning_policy.py --prefer-rest -c my_policy.conf apply

Key Features

Intelligent Inbound Fee Strategies

[balance-drain-channels]
chan.min_ratio = 0.8              # High local balance
strategy = balance_based
inbound_fee_ppm = -100            # Encourage inbound flow

Automatic Rollback Protection

[revenue-channels]
strategy = revenue_max
enable_auto_rollback = true       # Monitor performance
rollback_threshold = 0.25         # Rollback if revenue drops >25%

High-Performance gRPC

• 10x faster fee updates than REST
• Native LND interface (same as charge-lnd)
• Automatic fallback to REST if gRPC unavailable
• Secure by design - only fee management operations allowed

Advanced Analytics

• Policy performance tracking
• Revenue optimization reports
• Channel analysis and insights
• Historical data learning

Security Features

• Method whitelisting - only fee management operations allowed
• Runtime validation - dangerous operations blocked
• Comprehensive audit - all operations logged
• No fund movement - only channel fee updates
• Production-ready - enterprise security standards

Documentation

• Lightning Policy Guide - Complete feature overview
• Security Analysis - Comprehensive security audit
• gRPC Integration - High-performance setup guide
• Experiment Guide - Advanced experimentation

CLI Commands

# Policy Management
./lightning_policy.py apply          # Apply policies
./lightning_policy.py status         # Show policy status
./lightning_policy.py rollback       # Check/execute rollbacks
./lightning_policy.py daemon --watch # Run in daemon mode

# Analysis & Reports
./lightning_policy.py report         # Performance report
./lightning_policy.py test-channel   # Test specific channel

# Configuration
./lightning_policy.py generate-config # Create sample config

Configuration Options

# gRPC (preferred - 10x faster)
--lnd-grpc-host localhost:10009      # LND gRPC endpoint
--prefer-grpc                        # Use gRPC (default)

# REST API (fallback)  
--lnd-rest-url https://localhost:8080 # LND REST endpoint
--prefer-rest                         # Force REST API

# Authentication
--lnd-dir ~/.lnd                     # LND directory
--macaroon-path admin.macaroon       # Macaroon file

Testing

# Run tests
python -m pytest test_optimizer.py

# Test with your configuration
./lightning_policy.py -c your_config.conf apply --dry-run

# Test specific channel
./lightning_policy.py -c your_config.conf test-channel CHANNEL_ID

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure security standards are maintained
6. Submit a pull request

License

This project enhances and builds upon the open-source charge-lnd tool while adding significant new capabilities for Lightning Network fee optimization.

Related Projects

• charge-lnd - Original fee management tool
• LND - Lightning Network Daemon

---

Supercharge your Lightning Network channel fee management with intelligent, automated optimization!