This comprehensive simulation framework analyzes the impact of different token airdrop strategies on market dynamics. It models user behavior, market cycles, and complex vesting mechanisms to evaluate strategy effectiveness based on final token price and supply metrics.
# Market Parameters
INITIAL_TOKENS = 1_000_000_000 # Total supply
INITIAL_PRICE = 0.10 # USD per token
NUM_USERS = 500 # Simulation participants
SIMULATION_STEPS = 1024 # Market iterations
# User Archetypes with realistic distribution
USER_ARCHETYPES = {
"SPECULATOR": {
"base_buy_prob": 0.65, "base_sell_prob": 0.85,
"price_sensitivity": 0.9, "market_influence": 0.8,
"description": "High frequency traders"
},
"HODLER": {
"base_buy_prob": 0.25, "base_sell_prob": 0.05,
"price_sensitivity": 0.1, "market_influence": 0.2,
"description": "Long-term holders"
},
# ... more archetypes
}
# Market Dynamics
MARKET_CYCLES = {
'phase_duration': 256, # Steps per market phase
'amplitude': 0.15, # Price volatility
'frequency': 2*np.pi/SIMULATION_STEPS
}
Clone the repository:
bash
git clone <repository-url>
cd sim-airdrop
Install dependencies:
bash
pip install -r requirements.txt
Run the simulation: ```bash # Using CLI (recommended) sim-airdrop run --num-users 500 --steps 1024
# Using Python module python -m src.main ```
The simulator now includes a comprehensive CLI:
# Run simulation with custom parameters
sim-airdrop run --num-users 1000 --steps 2048 --max-strategies 20
# Generate visualizations from existing results
sim-airdrop visualize results/airdrop_simulation_results.csv
# Generate example strategies
sim-airdrop generate-strategies --num-strategies 10
# Create configuration template
sim-airdrop create-config-template
# Validate configuration file
sim-airdrop validate-config config.json
The enhanced simulator generates comprehensive reports:
src/
├── cli.py # Command-line interface
├── config.py # Configuration parameters
├── main.py # Main execution script
├── simulation.py # Core simulation engine
├── strategies.py # Strategy generation
├── helpers.py # Utility functions
├── data_generation.py # User data generation
├── data_prep.py # User preparation
├── validation.py # Input validation
├── logger.py # Logging system
├── visualization.py # Plotting and dashboards
└── tests/ # Comprehensive test suite
Create a JSON configuration file:
{
"num_users": 1000,
"steps": 2048,
"initial_tokens": 1000000000,
"initial_price": 0.15,
"max_strategies": 15,
"log_level": "INFO"
}
Run with custom config:
sim-airdrop run --config-file config.json
The simulator generates detailed strategy comparisons including: - Final price and supply metrics - Parameter sensitivity analysis - Performance rankings - Statistical summaries
The modular architecture allows easy extension: - Add new user archetypes - Implement custom vesting schedules - Create new airdrop strategies - Add market dynamics
| Strategy | Final Price | Final Supply | Improvement |
|---|---|---|---|
| Strategy_3 | $0.1229 | 1,004,958K | 22.9% |
| Strategy_1 | $0.0504 | 989,984K | -49.6% |
| Strategy_4 | $0.1002 | 999,970K | 0.2% |
Run the comprehensive test suite:
# Run all tests
pytest src/tests/ -v
# Run with coverage
pytest src/tests/ --cov=src --cov-report=html
# Run specific test categories
pytest src/tests/test_simulation.py -v
pytest src/tests/test_helpers.py -v
1. Import Errors
# Ensure you're in the correct directory
cd /path/to/sim-airdrop
# Install dependencies
pip install -r requirements.txt
2. Memory Issues
# Reduce simulation size
sim-airdrop run --num-users 100 --steps 512
3. Visualization Errors
# Ensure plotly dependencies
pip install plotly kaleido
For large simulations:
- Reduce num_users and steps
- Use --max-strategies to limit strategy generation
- Consider running on a machine with more RAM
This project is licensed under the MIT-0 License - see the LICENSE file for details.
For questions or issues: - Create an issue on GitHub - Check the troubleshooting section - Review the configuration examples
🎯 Ready to optimize your airdrop strategy? Run your first simulation!
sim-airdrop run --max-strategies 10
Browse the source repository