# 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