A protocol-faithful simulator for the Aave V3 lending protocol that accurately models lending, borrowing, liquidation mechanics, and health factor calculations. The simulator has been validated against real-world transaction data and demonstrates high accuracy in predicting liquidations and tracking user positions. For detailed information on the actual protocol, refer to the official Aave V3 documentation.

This simulator implements core Aave V3 mechanics including:

• Supply/Deposit collateral and Borrow against collateral
• Repay debt and Withdraw collateral
• Liquidation mechanics with 5% bonus
• Health factor calculations (standard and enhanced with oracle delays, volatility adjustments, and interest projections)
• Dynamic interest rate calculations (two-slope model matching Aave V3)
• Historical threshold and price tracking

The simulator has been validated against a real Polygon transaction dataset, demonstrating high accuracy in:

• Predicting liquidations using enhanced health factor calculations
• Tracking user positions (collateral, debt, health factors) over time
• Modeling transaction feasibility and state transitions

The simulator has been validated against real-world transaction data using:

• Chronological holdout strategy: Predicting future transactions based on historical data
• Liquidation-focused holdout strategy: Predicting liquidations based on pre-liquidation state
• Multiple HF calculation methods: Standard, oracle-delayed, and enhanced (worst-case scenario) health factors
• Comprehensive metrics: Prediction accuracy, correlation analysis, and state feasibility scoring

Validation results include detailed visualizations and metrics comparing simulator predictions with actual transactions.

📖 See Simulator Validation Guide for detailed validation methodology and Validation Analysis for comprehensive results.

1. Clone the repository

   git clone <repository-url>
   cd Aave-Simulator

2. Set up Python environment

   conda create -n aave-simulator python=3.10
   conda activate aave-simulator
   pip install -r requirements.txt

3. Configure

   cp config.json.example config.json
   # Edit config.json with your paths

Run simulations with sample profiles:

./scripts/run_simulations.sh

This processes user profiles and generates results in results/simulation-results/ with organized output:

• logs/ - Execution logs
• charts/ - Visualization dashboards
• user_state/ - Final state JSON files

📖 See Simulator Guide for detailed usage.

Run validation against real transaction data:

# Full validation with parallel processing
./scripts/run_validation.sh --strategy both --background

# Quick validation
./scripts/run_validation.sh --strategy chronological

📖 See Simulator Validation Guide for details.

Generate user profiles from transaction data:

./scripts/generate_liquidated_profiles.sh

📖 See Profile Generation Guide for details.

Health Factor = (Total Collateral × Liquidation Threshold) / Total Debt

• HF > 1.0: Position is safe
• HF = 1.0: At liquidation threshold
• HF < 1.0: Position can be liquidated

The simulator supports multiple HF calculation methods:

1. Standard HF: Current prices at timestamp
2. Standard HF with Oracle Delay: Accounts for price oracle update delays
3. Enhanced HF: Worst-case scenario with oracle delays, volatility adjustments, and interest projections

📖 See Health Factor Guide for detailed documentation.

Two-slope interest rate model (matching Aave V3):

• Optimal utilization: 80%
• Dynamic rates based on utilization
• Steep increase above optimal utilization

Comprehensive documentation is available in the docs/ folder:

• Simulator Guide - How to run simulations
• Simulator Validation - Validation methodology and usage
• Validation Analysis - Validation results and insights
• Profile Generation - Generating user profiles from transaction data
• Health Factor Guide - Health factor calculations and methods

• Price History - Extracting and using real market price data
• Liquidation Threshold - Liquidation threshold tracking
• Chain Data Fetching - Fetch user state from blockchain

📖 See Documentation Index for complete documentation list.

Aave-Simulator/
├── docs/                        # Comprehensive documentation
├── scripts/                     # Shell scripts for common tasks
│   ├── run_simulations.sh      # Run simulations (parallel processing)
│   ├── run_validation.sh       # Run validation
│   └── generate_liquidated_profiles.sh
├── tools/                       # Python CLI tools
│   ├── run_simulation.py       # Simulation engine
│   ├── validate_simulator.py   # Validation script
│   └── generate_profiles.py    # Profile generation
├── simulator/                   # Core simulation logic
│   ├── protocol.py             # AaveV3Simulator
│   └── reserve_config.py       # Reserve configuration
├── visualization/               # Visualization modules
├── data/                        # Sample profiles and cached data
└── results/                     # Generated results (gitignored)

Feel free to submit issues, fork the repository, and create pull requests for any improvements.

See LICENSE file for details.