lockdrop-simulation/EXPERIMENT.md

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 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:

    # Ubuntu/Debian
    sudo apt install python3-venv python3-dev build-essential
    
    python3 -m ensurepip --version
    

Quick Start

1. Clone and Navigate to Directory

   git clone git@git.vdb.to:LaconicNetwork/lockdrop-simulation.git
   cd lockdrop-simulation
   

2. Run the Experimentation Script

   ./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:

     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