harb/onchain/analysis/README.md

Scenario Analysis Suite

This directory contains tools for deep analysis of LiquidityManagerV2 trading scenarios, separate from unit testing.

Overview

The Scenario Analysis Suite is designed for research and development, not unit testing. It analyzes the new modular LiquidityManagerV2 architecture to identify:

• 🎯 Profitable trading sequences that could indicate protocol vulnerabilities
• 🛡️ MEV opportunities and market manipulation potential
• 🔍 Edge cases not covered by standard unit tests
• 📊 Performance characteristics under different market conditions
• 🏗️ Modular component interactions and potential failure modes

Files

analysis/                           # Analysis suite (excluded from forge test)
├── README.md                    # This documentation
├── SimpleAnalysis.s.sol        # Lightweight analysis script
├── scenario-visualizer.html   # Interactive CSV data visualization
├── view-scenarios.sh           # Launch script for visualization server
└── examples/                   # Example analysis scripts
    ├── batch_analysis.sh       # Batch scenario runner
    └── profitable_scenarios/   # Output directory for profitable scenarios

Quick Start

1. Basic Scenario Analysis

# Run simple analysis script
forge script analysis/SimpleAnalysis.s.sol --ffi -vvv

# View results in browser (starts server automatically)
./analysis/view-scenarios.sh

2. Standard Unit Testing (Default)

# Run all unit tests (fast, no analysis)
forge test

# This runs ONLY unit tests, excludes analysis scripts
# Perfect for CI/CD and regular development

3. Batch Analysis

// Prepare multiple scenarios
uint8[] memory numActionsArray = new uint8[](3);
numActionsArray[0] = 10; numActionsArray[1] = 20; numActionsArray[2] = 30;

uint8[] memory frequencyArray = new uint8[](3);  
frequencyArray[0] = 2; frequencyArray[1] = 5; frequencyArray[2] = 10;

uint8[][] memory amountsArray = new uint8[][](3);
// ... populate amounts arrays ...

analysis.batchAnalyzeScenarios(numActionsArray, frequencyArray, amountsArray);

Understanding Results

Console Output

🔬 Starting batch scenario analysis...
Total scenarios to analyze: 5

--- Analyzing scenario 1 of 5 ---
Scenario 1 :
  Actions: 10 | Frequency: 3
  Tick movement: -123891 → 245673
  Result: Protected ✅
  Gas used: 2847291

🚨 PROFITABLE SCENARIO DETECTED 🚨
═══════════════════════════════════
Scenario ID: 3
Profit extracted: 0.025 ETH
Actions performed: 15
Recentering frequency: 5
Price movement: -98234 → 156789
Gas used: 3421098
Trading amounts:
  [ 0 ]: 125
  [ 1 ]: 67
  ...
CSV written to: ./out/profitable_scenario_3.csv
═══════════════════════════════════

📊 ANALYSIS SUMMARY  
══════════════════════
Total scenarios analyzed: 5
Profitable scenarios found: 1
Profit rate: 20 %
Total profit extracted: 0.025 ETH
Average profit per profitable scenario: 0.025 ETH
══════════════════════

CSV Output Files

When profitable scenarios are detected, detailed CSV files are generated:

• ./analysis/profitable_scenario.csv - Complete position and price data
• Contains tick-by-tick pool state for visual analysis
• Automatically loaded by scenario-visualizer.html for visualization
• Can also be imported into Excel/Google Sheets for charting

Events for Programmatic Analysis

event ScenarioAnalyzed(
    uint256 indexed scenarioId,
    bool profitable, 
    uint256 profit,
    uint8 numActions,
    uint8 frequency
);

event ProfitableScenarioDetected(
    uint256 indexed scenarioId,
    uint256 profit,
    uint8 numActions, 
    uint8 frequency,
    string csvFile
);

Configuration

Analysis Parameters

// In ScenarioAnalysis.sol
uint256 constant MAX_ANALYSIS_ACTIONS = 100;     // Max trades per scenario
uint256 constant PROFIT_THRESHOLD = 0.001 ether; // Min profit to record

Environment Setup

# Enable file operations for CSV writing
export FOUNDRY_FFI=true

# Increase gas limit for complex scenarios  
export FOUNDRY_GAS_LIMIT=50000000

# Set output directory
mkdir -p test/analysis/output

Example Workflows

1. Protocol Security Audit

# Test for MEV opportunities
forge test --match-contract "ScenarioAnalysis" --match-test "analyzeScenario" --ffi

# Review profitable scenarios
ls -la ./analysis/profitable_scenario.csv

# Visualize scenario data
open ./analysis/scenario-visualizer.html

# Analyze patterns in profitable trades
python scripts/analyze_profitable_scenarios.py

2. Parameter Optimization

// Test different recentering frequencies
for (uint8 freq = 1; freq <= 20; freq++) {
    analysis.analyzeScenario(10, freq, standardAmounts);
}

// Analyze results to optimize frequency parameter
analysis.getAnalysisStats();

3. Stress Testing

// Test extreme scenarios
uint8[] memory extremeAmounts = new uint8[](50);
// Fill with edge case values...

analysis.analyzeScenario(50, 1, extremeAmounts); // High frequency
analysis.analyzeScenario(50, 25, extremeAmounts); // Low frequency

Integration with Development Workflow

Automatic Separation

# Unit tests ONLY (default - fast, no file I/O)
forge test

# Analysis scripts (explicit - slower, generates files)
forge script analysis/SimpleAnalysis.s.sol --ffi

# Or use the batch script
./analysis/examples/batch_analysis.sh

Git Integration

# .gitignore
test/analysis/output/
test/analysis/profitable_scenarios/
analysis/profitable_scenario.csv
out/profitable_scenario_*.csv

Code Review Process

1. Unit tests must pass before analysis
2. Analysis results reviewed for new vulnerabilities
3. Profitable scenarios investigated and addressed
4. Parameters adjusted based on analysis insights

Best Practices

✅ Do

• Run analysis suite during development and security reviews
• Investigate ALL profitable scenarios thoroughly
• Version control analysis scripts but not output files
• Document findings and protocol improvements
• Use analysis to guide parameter tuning

❌ Don't

• Include analysis in CI/CD pipelines (too slow)
• Commit CSV output files to git (too large)
• Use as replacement for unit tests (different purposes)
• Ignore profitable scenarios (potential vulnerabilities)

Troubleshooting

Common Issues

# Error: FFI not enabled
export FOUNDRY_FFI=true

# Error: Gas limit exceeded  
export FOUNDRY_GAS_LIMIT=50000000

# Error: Output directory missing
mkdir -p ./out

# Error: Memory limit reached
# Reduce MAX_ANALYSIS_ACTIONS or run smaller batches

Performance Tips

• Batch analysis in smaller groups for better memory management
• Use specific test filters to run targeted analysis
• Clean output directory regularly to save disk space
• Monitor gas usage and adjust limits as needed

Advanced Usage

Custom Analysis Contracts

contract MyCustomAnalysis is ScenarioAnalysis {
    function analyzeSpecificPattern() public {
        // Your custom analysis logic
        uint8[] memory amounts = _generatePatternAmounts();
        analyzeScenario(15, 5, amounts);
    }
    
    function _generatePatternAmounts() internal pure returns (uint8[] memory) {
        // Generate specific trading patterns for analysis
    }
}

Automated Analysis Scripts

#!/bin/bash
# batch_analysis.sh

echo "🔬 Running automated scenario analysis..."

for frequency in {1..10}; do
    for actions in {5..25..5}; do
        echo "Testing frequency=$frequency, actions=$actions"
        forge test --match-contract "ScenarioAnalysis" \
                   --match-test "analyzeScenario($actions,$frequency," \
                   --ffi --gas-limit 50000000
    done
done

echo "📊 Analysis complete. Check ./out/ for results."

Contributing

When adding new analysis features:

1. Extend ScenarioAnalysis contract for new analysis types
2. Add documentation for new parameters and outputs
3. Include example usage in this README
4. Test with various inputs to ensure robustness
5. Update .gitignore for new output file patterns

Support

For questions about the analysis suite:

• Check this README first
• Review existing analysis contracts for examples
• Look at unit tests for basic usage patterns
• Consult team for protocol-specific analysis needs