harb/onchain/analysis/README.md

# KRAIKEN Liquidity Analysis

Analysis tools for testing the three-position anti-arbitrage strategy using random fuzzing to discover profitable trading scenarios.

## Quick Start

1. **Run the analysis** (includes parameter validation + random fuzzing):
   ```bash
   forge script analysis/SimpleAnalysis.s.sol --ffi --via-ir
   ```

2. **Start visualization server**:
   ```bash
   cd analysis && python3 -m http.server 8000
   ```

3. **View results** at `http://localhost:8000/scenario-visualizer.html`

## How It Works

The analysis script uses **random fuzzing** like the historical `testScenarioFuzz` function to discover profitable trading scenarios:

- **Random Parameters**: Generates random trading amounts, frequencies, and sentiment parameters
- **Historical Logic**: Uses exact trading logic from the working historical tests
- **Early Exit**: Stops immediately after finding the first profitable scenario
- **CSV Generation**: Creates detailed trading sequence data for visualization

## Analysis Commands

### Full Analysis (Recommended)
```bash
forge script analysis/SimpleAnalysis.s.sol --ffi --via-ir
```
Runs both parameter validation and random fuzzing analysis.

### Parameter Validation Only
Modify the `run()` function to comment out `runSentimentFuzzingAnalysis()` if you only want to test parameter configurations.

## Files

- `SimpleAnalysis.s.sol` - Main analysis script with random fuzzing
- `scenario-visualizer.html` - Web-based position visualization  
- `profitable_scenario.csv` - Generated when profitable scenarios are found
- `view-scenarios.sh` - HTTP server launcher (alternative to python server)

## Analysis Output

### Console Output
- Parameter validation results for bull/neutral/bear market conditions
- Random fuzzing attempts with generated parameters
- Profitable scenario detection and stopping logic

### CSV Data
When profitable scenarios are found, generates `profitable_scenario.csv` containing:
- Trading sequence (buy/sell/recenter actions)
- Position data (Floor/Anchor/Discovery liquidity amounts)
- Price tick information
- Token distribution across positions

### Visualization
Interactive HTML dashboard showing:
- Position ranges and token distributions
- Uniswap V3 liquidity calculations
- Trading sequence progression
- Anti-arbitrage strategy effectiveness

## Random Fuzzing Details

The script generates random parameters for each test:
- **Actions**: 6-12 trading actions per scenario
- **Frequency**: 1-5 recenter frequency  
- **Amounts**: 50-255 basis values (scaled to ether)
- **Sentiment**: Random capital inefficiency, anchor share, width, discovery depth

This approach mirrors the historical `testScenarioFuzz` function that successfully found profitable scenarios in the original codebase.

## Troubleshooting

### No Profitable Scenarios Found
- The anti-arbitrage protection is working effectively
- Try increasing `maxAttempts` in `runSentimentFuzzingAnalysis()` for more fuzzing attempts
- Check console output for parameter validation results

### Script Execution Issues
- Ensure you're using the full script command (not `-s` function selection)
- The `setUp()` function is required for proper contract initialization
- Use `--via-ir` flag for complex contract compilation

### Visualization Issues
- Start the HTTP server from the `analysis/` directory
- Check that `profitable_scenario.csv` exists before viewing
- Browser security may block local file access - use the HTTP server