lnflow/docs/EXPERIMENT_GUIDE.md

Lightning Fee Optimization Experiment Guide

Quick Start

1. Install dependencies:

pip install -r requirements.txt

2. Initialize experiment:

./lightning_experiment.py init --duration 7 --dry-run

3. Check status:

./lightning_experiment.py status

4. Run single test cycle:

./lightning_experiment.py cycle --dry-run

5. Run full experiment:

./lightning_experiment.py run --interval 30 --dry-run

Commands

init - Initialize Experiment

./lightning_experiment.py init [OPTIONS]

Options:
  --duration INTEGER       Experiment duration in days (default: 7)
  --macaroon-path TEXT    Path to admin.macaroon file
  --cert-path TEXT        Path to tls.cert file  
  --dry-run               Simulate without actual fee changes

Example: Initialize 5-day experiment with LND connection

./lightning_experiment.py init --duration 5 --macaroon-path ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon

status - Show Current Status

./lightning_experiment.py status

Shows:

• Current experiment phase
• Elapsed time
• Data collection progress
• Recent activity summary

channels - Show Channel Details

./lightning_experiment.py channels [--group GROUP]

Examples:

./lightning_experiment.py channels                    # All channels
./lightning_experiment.py channels --group control    # Control group only
./lightning_experiment.py channels --group treatment_a # Treatment A only

changes - Show Recent Fee Changes

./lightning_experiment.py changes [--hours HOURS]

Example:

./lightning_experiment.py changes --hours 12  # Last 12 hours

performance - Show Performance Summary

./lightning_experiment.py performance

Shows revenue, flow efficiency, and balance health by experiment group.

cycle - Run Single Cycle

./lightning_experiment.py cycle [OPTIONS]

Options:
  --dry-run               Simulate without actual changes
  --macaroon-path TEXT    Path to admin.macaroon
  --cert-path TEXT        Path to tls.cert

run - Run Continuous Experiment

./lightning_experiment.py run [OPTIONS]

Options:
  --interval INTEGER      Collection interval in minutes (default: 30)
  --max-cycles INTEGER    Maximum cycles to run
  --dry-run              Simulate without actual changes
  --macaroon-path TEXT   Path to admin.macaroon
  --cert-path TEXT       Path to tls.cert

Example: Run for 100 cycles with 15-minute intervals

./lightning_experiment.py run --interval 15 --max-cycles 100 --macaroon-path ~/.lnd/admin.macaroon

report - Generate Report

./lightning_experiment.py report [--output FILE]

Example:

./lightning_experiment.py report --output results.json

reset - Reset Experiment

./lightning_experiment.py reset [--backup]

Experiment Design

Channel Groups

Control Group (40%): No fee changes, baseline measurement Treatment A (30%): Balance-based optimization

• Reduce fees when local balance >80%
• Increase fees when local balance <20%
• Apply inbound fees to control flow direction

Treatment B (20%): Flow-based optimization

• Increase fees on high-flow channels to test elasticity
• Reduce fees on dormant channels to activate

Treatment C (10%): Advanced multi-strategy

• Game-theoretic competitive positioning
• Risk-adjusted optimization
• Network topology considerations

Experiment Phases

1. Baseline (24h): Data collection, no changes
2. Initial (48h): Conservative 25% fee adjustments
3. Moderate (48h): 40% fee adjustments
4. Aggressive (48h): Up to 50% fee adjustments
5. Stabilization (24h): No changes, final measurement

Safety Features

• Automatic Rollbacks: 30% revenue drop or 60% flow reduction
• Maximum Changes: 2 fee changes per channel per day
• Fee Limits: 1-5000 ppm range, max 50% change per update
• Real-time Monitoring: Health checks after each change

Data Collection

Collected Every 30 Minutes

• Channel balances and policies
• Flow reports and fee earnings
• Peer connection status
• Network topology changes

Stored Data

• experiment_data/experiment_config.json - Setup and parameters
• experiment_data/experiment_data.csv - Time series data
• experiment_data/experiment_data.json - Detailed data with metadata
• experiment.log - Operational logs

Example Workflow

1. Development/Testing

# Start with dry-run to test setup
./lightning_experiment.py init --duration 1 --dry-run
./lightning_experiment.py status
./lightning_experiment.py cycle --dry-run

2. Real Experiment

# Initialize with LND connection
./lightning_experiment.py init --duration 7 --macaroon-path ~/.lnd/admin.macaroon

# Run automated experiment
./lightning_experiment.py run --interval 30 --macaroon-path ~/.lnd/admin.macaroon

# Monitor progress (in another terminal)
watch -n 60 './lightning_experiment.py status'

3. Analysis

# Check performance during experiment
./lightning_experiment.py performance
./lightning_experiment.py changes --hours 24

# Generate final report
./lightning_experiment.py report --output final_results.json

Tips

Start Small: Begin with --dry-run to validate setup and logic

Monitor Closely: Check status frequently during first few cycles

Conservative Approach: Use shorter duration (1-2 days) for initial runs

Safety First: Experiment will auto-rollback on revenue/flow drops

Data Backup: Use reset --backup to save data before resetting

Log Analysis: Check experiment.log for detailed operational information

Troubleshooting

"No experiment running": Run init command first

"Failed to connect to LND": Check macaroon path and LND REST API accessibility

"Channel not found": Ensure LND Manage API is running and accessible

Permission errors: Check file permissions for macaroon and cert files

Network errors: Verify URLs and network connectivity to APIs