Prathamesh Musale
8f0724d552
Reviewed-on: #5 Co-authored-by: Prathamesh Musale <prathamesh.musale0@gmail.com> Co-committed-by: Prathamesh Musale <prathamesh.musale0@gmail.com>
140 lines
4.7 KiB
Markdown
140 lines
4.7 KiB
Markdown
# Lockdrop Allocation Experimentation
|
|
|
|
This guide explains how to use the interactive notebook to experiment with different lockdrop participation scenarios and understand how various distributions affect token allocations.
|
|
|
|
## Prerequisites
|
|
|
|
- Ubuntu 22 or 24
|
|
|
|
- **Note**: Other platforms are not supported yet for deployment
|
|
|
|
- [Python3](https://wiki.python.org/moin/BeginnersGuide/Download) `3.12.x` >= `python3 --version` >= `3.8.10` (the Python3 shipped in Ubuntu 20+ is good to go)
|
|
|
|
- Make sure that `ensurepip` is available for creating virtual environments:
|
|
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt install python3-venv python3-dev build-essential
|
|
|
|
python3 -m ensurepip --version
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
1. **Clone and Navigate to Directory**
|
|
|
|
```bash
|
|
git clone git@git.vdb.to:LaconicNetwork/lockdrop-simulation.git
|
|
cd lockdrop-simulation
|
|
```
|
|
|
|
2. **Run the Experimentation Script**
|
|
|
|
```bash
|
|
./run_experiment.sh
|
|
```
|
|
|
|
This script will:
|
|
- Automatically create a Python virtual environment
|
|
- Install all required dependencies
|
|
- Automatically launch the Jupyter notebook with the experimentation interface in you browser
|
|
|
|
If jupyter is running on a remote host, you can tunnel the port `8888` to load the notebook in your local browser:
|
|
|
|
```bash
|
|
ssh <user>@<control-node-ip> -L localhost:8888:localhost:8888 -Nv
|
|
```
|
|
|
|
Open the URL having a unique token from server logs and load `lockdrop-calculations.ipynb`
|
|
|
|
3. **Use the Interactive Interface**
|
|
|
|
Once the notebook has been opened in your browser, execute it by clicking "Run All Cells" from `Run` tab in order to start experimenting with different participation scenarios.
|
|
|
|
## Using the Interactive Interface
|
|
|
|
### Input Controls
|
|
|
|
- **Star Participation**: Adjust participation numbers for stars across 1-5 year lock durations
|
|
- **Galaxy Participation**: Adjust participation numbers for galaxies across 1-5 year lock durations
|
|
- **Preset Scenarios**: Use the dropdown to quickly load common scenarios:
|
|
- **Balanced**: Even distribution across all lock periods
|
|
- **Five-year focused**: Most participants choose maximum lock duration
|
|
- **Short-term focused**: Most participants choose shorter lock durations
|
|
- **Low participation**: Reduced overall participation scenario
|
|
|
|
### Action Buttons
|
|
|
|
- **🔄 Calculate Allocations**: Run calculations and display comprehensive analysis
|
|
- **💾 Export Results**: Save experimental results to timestamped JSON file
|
|
|
|
## Understanding the Analysis Output
|
|
|
|
The notebook provides detailed analysis including:
|
|
|
|
### 1. Participation Distribution
|
|
- Breakdown of participants by lock period
|
|
- Participation rates for stars and galaxies
|
|
- Total participant counts
|
|
|
|
### 2. Allocation Calculations
|
|
- Base allocations accounting for actual participation
|
|
- Quanta-adjusted allocations per participant
|
|
- Calculations on rounding errors resulting from quanta usage
|
|
|
|
### 3. Penalty System Analysis
|
|
- Impact of lock duration on allocations before bonuses
|
|
- Penalty rates for each lock period
|
|
- Allocation percentages relative to maximum
|
|
|
|
### 4. Bonus Pool Calculations
|
|
- How penalties redistribute to 5-year participants
|
|
- Bonus amounts per 5-year participant
|
|
- Total bonus pool distribution
|
|
|
|
### 5. Final Allocations & Verification
|
|
- Complete allocation breakdown by lock period
|
|
- Z tokens per block calculations
|
|
- Allocation verification and rounding error tracking
|
|
|
|
### 6. Visualizations
|
|
- Participation distribution charts
|
|
- Allocation comparison graphs
|
|
- Lock period analysis plots
|
|
|
|
## Experimenting with Scenarios
|
|
|
|
### Quick Start with Presets
|
|
|
|
1. Select a preset from the dropdown (e.g., "Five-year focused")
|
|
2. Click "🔄 Calculate Allocations"
|
|
3. Review the analysis output
|
|
4. Try different presets to compare scenarios
|
|
|
|
### Custom Scenarios
|
|
|
|
1. Manually adjust participation numbers
|
|
2. Ensure total participants don't exceed maximum available (65,280 stars, 256 galaxies)
|
|
3. Click "🔄 Calculate Allocations"
|
|
4. Use "💾 Export Results" to save interesting configurations
|
|
|
|
## Exported Results
|
|
|
|
Export files contain:
|
|
- **Metadata**: Timestamp, source notebook, participation parameters
|
|
- **Allocations**: Complete calculation results in JSON format
|
|
- **File naming**: `lockdrop_calculations_result_YYYYMMDD_HHMMSS.json`
|
|
|
|
These files can be used for:
|
|
- Further analysis
|
|
- Sharing experimental configurations
|
|
- Testing different scenarios
|
|
- Integration with other tools
|
|
|
|
## Troubleshooting
|
|
|
|
- **Import errors**: Ensure all dependencies are installed via `pip install -r requirements.txt`
|
|
- **Widget display issues**: Restart notebook kernel and re-run cells
|
|
- **Calculation errors**: Check that participation numbers don't exceed limits
|
|
- **Export failures**: Ensure write permissions in the notebook directory
|