diff --git a/onchain/analysis/README.md b/onchain/analysis/README.md new file mode 100644 index 0000000..78b815a --- /dev/null +++ b/onchain/analysis/README.md @@ -0,0 +1,327 @@ +# Scenario Analysis Suite + +This directory contains tools for deep analysis of LiquidityManager trading scenarios, separate from unit testing. + +## Overview + +The Scenario Analysis Suite is designed for **research and development**, not unit testing. It helps 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 + +## 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 + +```bash +# 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) + +```bash +# 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 + +```solidity +// 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 + +```solidity +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 + +```solidity +// 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 + +```bash +# 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 + +```bash +# 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 + +```solidity +// 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 + +```solidity +// 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 + +```bash +# 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 +# .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 + +```bash +# 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 + +```solidity +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 + +```bash +#!/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 \ No newline at end of file diff --git a/onchain/analysis/SimpleAnalysis.s.sol b/onchain/analysis/SimpleAnalysis.s.sol new file mode 100644 index 0000000..cf217ad --- /dev/null +++ b/onchain/analysis/SimpleAnalysis.s.sol @@ -0,0 +1,121 @@ +// SPDX-License-Identifier: GPL-3.0-or-later +pragma solidity ^0.8.19; + +/** + * @title Simple Scenario Analysis for LiquidityManager + * @notice Lightweight analysis script for researching profitable trading scenarios + * @dev Separated from unit tests to focus on research and scenario discovery + * Run with: forge script analysis/SimpleAnalysis.s.sol --ffi + */ + +import "../test/LiquidityManager.t.sol"; + +contract SimpleAnalysis is LiquidityManagerTest { + + uint256 public scenariosAnalyzed; + uint256 public profitableScenarios; + + /// @notice Entry point for forge script execution + function run() public { + console.log("Starting LiquidityManager Scenario Analysis..."); + console.log("This will analyze trading scenarios for profitability."); + + // Example analysis with predefined parameters + uint8[] memory amounts = new uint8[](10); + amounts[0] = 100; amounts[1] = 50; amounts[2] = 75; + amounts[3] = 120; amounts[4] = 30; amounts[5] = 90; + amounts[6] = 45; amounts[7] = 110; amounts[8] = 60; amounts[9] = 80; + + runAnalysis(10, 3, amounts); + + console.log("Analysis complete. Check statistics:"); + (uint256 total, uint256 profitable) = getStats(); + console.log("Total scenarios:", total); + console.log("Profitable scenarios:", profitable); + } + + /// @notice Analyzes a trading scenario for profitability + /// @dev Records CSV data if profitable - THIS IS NOT A UNIT TEST + function runAnalysis(uint8 numActions, uint8 frequency, uint8[] memory amounts) public { + // Bound inputs + vm.assume(numActions > 3 && numActions <= 50); + vm.assume(frequency > 0 && frequency < 20); + vm.assume(amounts.length >= numActions); + + // Setup + _setupCustom(false, 50 ether); + + uint256 balanceBefore = weth.balanceOf(account); + + // Execute trading sequence (need to convert memory to calldata) + _executeRandomTradingSequenceWrapper(numActions, frequency, amounts); + + uint256 balanceAfter = weth.balanceOf(account); + + scenariosAnalyzed++; + + // Check profitability + if (balanceAfter > balanceBefore) { + profitableScenarios++; + uint256 profit = balanceAfter - balanceBefore; + + console.log("[ALERT] Profitable scenario found!"); + console.log("Profit:", vm.toString(profit)); + console.log("Actions:", numActions); + console.log("Frequency:", frequency); + + // Write CSV for analysis to analysis folder + writeCSVToFile("./analysis/profitable_scenario.csv"); + } + + console.log("Scenario", scenariosAnalyzed, balanceAfter > balanceBefore ? "PROFIT" : "SAFE"); + } + + /// @notice Wrapper to handle memory to calldata conversion + function _executeRandomTradingSequenceWrapper(uint8 numActions, uint8 frequency, uint8[] memory amounts) internal { + // Create a simple trading sequence without the complex calldata dependency + uint8 f = 0; + + for (uint i = 0; i < numActions && i < amounts.length; i++) { + uint256 amount = (uint256(amounts[i]) * 1 ether) + 1 ether; + uint256 harbergBal = harberg.balanceOf(account); + + // Execute trade based on current balances + if (harbergBal == 0) { + amount = amount % (weth.balanceOf(account) / 2); + amount = amount == 0 ? weth.balanceOf(account) / 10 : amount; + if (amount > 0) buy(amount); + } else if (weth.balanceOf(account) == 0) { + sell(amount % harbergBal); + } else { + if (amount % 2 == 0) { + amount = amount % (weth.balanceOf(account) / 2); + amount = amount == 0 ? weth.balanceOf(account) / 10 : amount; + if (amount > 0) buy(amount); + } else { + sell(amount % harbergBal); + } + } + + // Periodic recentering + if (f >= frequency) { + recenter(false); + f = 0; + } else { + f++; + } + } + + // Final cleanup + uint256 finalHarbBal = harberg.balanceOf(account); + if (finalHarbBal > 0) { + sell(finalHarbBal); + } + recenter(true); + } + + /// @notice Get analysis statistics + function getStats() public view returns (uint256 total, uint256 profitable) { + return (scenariosAnalyzed, profitableScenarios); + } +} \ No newline at end of file diff --git a/onchain/analysis/examples/batch_analysis.sh b/onchain/analysis/examples/batch_analysis.sh new file mode 100755 index 0000000..0d872cc --- /dev/null +++ b/onchain/analysis/examples/batch_analysis.sh @@ -0,0 +1,39 @@ +#!/bin/bash + +# Batch Scenario Analysis Script +# This script runs multiple analysis scenarios to discover profitable trading patterns + +echo "🔬 Starting Batch Scenario Analysis for LiquidityManager" +echo "=======================================================" + +# Ensure output directory exists +mkdir -p ./out + +# Enable FFI for file operations +export FOUNDRY_FFI=true + +echo "📋 Running Unit Tests First (ensure protocol safety)..." +forge test -q + +if [ $? -ne 0 ]; then + echo "❌ Unit tests failed. Fix issues before running analysis." + exit 1 +fi + +echo "✅ Unit tests passed. Proceeding with scenario analysis..." + +echo "🔍 Running Simple Analysis Script..." +forge script analysis/SimpleAnalysis.s.sol --ffi -v + +echo "📊 Analysis Results:" +echo "Check ./analysis/ directory for any profitable_scenario.csv files" +echo "These indicate potentially exploitable trading sequences" +echo "" +echo "🌐 To view visualizations, run:" +echo " ./analysis/view-scenarios.sh" + +echo "🎯 To investigate specific scenarios, modify the analysis contract" +echo "and run targeted tests with custom parameters." + +echo "✅ Batch analysis complete!" +echo "Review any profitable scenarios for potential protocol improvements." \ No newline at end of file diff --git a/onchain/analysis/profitable_scenario.csv b/onchain/analysis/profitable_scenario.csv new file mode 100644 index 0000000..477865a --- /dev/null +++ b/onchain/analysis/profitable_scenario.csv @@ -0,0 +1,5 @@ +precedingAction, currentTick, floorTickLower, floorTickUpper, floorEth, floorHarb, anchorTickLower, anchorTickUpper, anchorEth, anchorHarb, discoveryTickLower, discoveryTickUpper, discoveryEth, discoveryHarb +slide,-123891,-127600,-127400,8499599430370969075,0,-127400,-120200,1500400569629030923,376940880662598418828125,-120200,-109200,0,6912345395033737460873377, +buy 200000000000000000000,887271,-127600,-127400,8499599430370969075,0,-127400,-120200,3389210182401516632,0,-120200,-109200,72196604834010135093,0, +sell 7289286275696335879701502,-123228,-127600,-127400,8499599430370969075,0,-127400,-120200,1814349250155627618,304048017905635060031107,-120200,-109200,0,6912345395033737460873377, +slide,-123228,-182200,-182000,8766690645795410165,0,-126800,-119600,1547258034731186526,352446257880687465062044,-119600,-108600,0,6462197221092285823162907, \ No newline at end of file diff --git a/onchain/analysis/scenario-visualizer.html b/onchain/analysis/scenario-visualizer.html new file mode 100644 index 0000000..858343e --- /dev/null +++ b/onchain/analysis/scenario-visualizer.html @@ -0,0 +1,293 @@ + + +
+ + +