lockdrop-simulation/README.md

# lockdrop-simulation

## Approach

The lockdrop simulation validates the Zenith Network's token distribution mechanism by creating a realistic test environment without requiring real Ethereum data or live participants.

- **Generate mock participants** with proper Ethereum/Zenith addresses and distribute Urbit points (galaxies/stars) based on configurable participation rates
- **Simulate the TGE event** to process participants and generate a genesis file with treasury allocations and unlock schedules as per [distribution-simulate-lockdrop.json](./distribution-simulate-lockdrop.json)
- **Deploy a test zenithd validator** using the simulated genesis file to validate the actual token distribution and accrual implementation
- **Compare expected calculations** (via Jupyter notebook) against live node's API responses to ensure mathematical correctness
- **Provide end-to-end verification** that the entire flow from participant generation to live blockchain queries works correctly in a controlled, reproducible environment

### Simulation Features

- **Urbit Point Allocation**: Uses real Urbit naming conventions and point hierarchy
- **Valid Ethereum Addresses**: Generates Ethereum key pairs for all participants
- **Valid Zenith Addresses**: Generates Zenith addresses for all participants
- **Realistic Attestations**: Create attestations following the expected format
- **Token Calculations**: Treasury calculations for lockdrop participants based on total supply and participant count

## Setup

1. **Install Prerequisites**

    Clone the zenith-stack repository which contains the Ansible playbooks:

    ```bash
    git clone git@git.vdb.to:LaconicNetwork/zenith-stack.git
    ```

    **Note**: Replace `<path/to/zenith-stack>` in the commands below with the actual path where you cloned the zenith-stack repository.

    Run following commands with necessary permissions, as root or through sudo

    Install `zenith-ansible` at `/usr/local/bin`:

    ```bash
    # Download the binary from generic package registry
    curl -L https://git.vdb.to/api/packages/LaconicNetwork/generic/zenith-stack/v0.2.5/zenith-ansible -o /usr/local/bin/zenith-ansible
    ```

    **NOTE**: Make sure `/usr/local/bin` is in your `$PATH`

    Make it executable:

    ```bash
    chmod +x /usr/local/bin/zenith-ansible
    ```

    Verify installation:

    ```bash
    which zenith-ansible
    ```
    <!-- TODO: Update tag -->
    For more details about `zenith-ansible` check this [doc](https://git.vdb.to/LaconicNetwork/zenith-stack/src/tag/v0.2.5/ansible/zenith-ansible-shiv/README.md)

2. **Configure Variables**

    Configure variables required for this simulation by following [this guide](https://git.vdb.to/LaconicNetwork/zenith-stack/src/tag/v0.2.5/ansible/zenith-config-cli/docs/stage1-lockdrop-simulation.md).

    The configuration tool allows flexible simulation parameters:
    - **Participant count**: Configure the total number of mock participants
    - **Galaxy allocation**: Determines how many participants will be validators
    - **Star distribution**: Controls the total star pool available for allocation

3. **Setup Deployment Directories**

    Create the data directory required for simulation (must be same as the path configured for `lockdrop simulation data directory` in previous step to configure variables):

    ```bash
    # For example:
    mkdir -p /home/$USER/stage1-lockdrop-simulation
    ```

    Make sure you are in ansible directory:

    ```bash
    cd <path/to/zenith-stack>/ansible
    ```

    Setup the deployment directories and pull required docker images to generate base genesis file along with other artifacts:

    ```bash
    zenith-ansible -i ./inventories/development/hosts.yml tge-site.yml -e "mode=setup"
    ```

    Setup the deployment directories and pull required docker images to sign the gentx and setup stage 1 validator node:

    ```bash
    zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=setup" --skip-tags onboarding
    ```

## Run Simulation

### Step 1: Simulated Token Genesis Event

Following command allows users to create the base genesis file while simulating lockdrop participants:

```bash
zenith-ansible -i ./inventories/development/hosts.yml tge-site.yml -e "mode=simulate-lockdrop"
```

This will generate base genesis file at `<path/to/zenith-stack>/base-genesis-file/genesis.json`

This will also generate following files in `<path/to/zenith-stack>/generated`:

```bash
<path/to/zenith-stack>/generated/
├── generated-participants.json      # Mock participant data with attestations
├── generated-accounts.json          # Ethereum and Zenith account pairs
├── point-allocation-stats.json      # Statistics about galaxy/star allocation
└── watcher-events.json              # Simulated lockdrop contract events
```

[distribution-simulate-lockdrop.json](./distribution-simulate-lockdrop.json) is used for category-wise allocation of `$Z` with respective vesting/unlock schedules (unlock frequency reduced to 60 seconds or 30 blocks for lockdrop participants for demo purposes).

### Step 2: Genesis Transaction (Gentx) Signing

Since we have generated dummy accounts, we can access there private keys present in `generated-accounts.json`.

Get the private key of first account present in this file:

```bash
# Working directory: <path/to/zenith-stack>/ansible
jq -r '.[0].zenithPrivateKey' ../generated/generated-accounts.json
```

Note this private key down as it will be required in next step.

Now run the playbook to sign the gentx and generate final genesis file:

```bash
zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=sign"
```

Use the private key noted above when prompted.

This will:
- Automatically extract the pubkey of your validator node
- Create a genesis transaction (gentx) using the validator public key and private key
- Combine the base genesis file with the bootstrap validator gentx
- Generate the final genesis file
- Copy final genesis to `<path/to/zenith-stack>/genesis-file/genesis.json`

### Step 3: Start Bootstrap Validator

Now, we can use this genesis file to run the stage 1 validator node:

```bash
zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=start" --skip-tags onboarding
```

After starting the node, verify it's running correctly:

```bash
# Set data directory (should match configuration)
export DATA_DIRECTORY=/absolute/path/to/data/directory

# Check validator logs
laconic-so deployment --dir $DATA_DIRECTORY/mainnet-zenithd-deployment logs zenithd -f
```

### Step 4: Run Lockdrop Distribution Notebook

Execute the Jupyter notebook to perform lockdrop allocation calculations and generate analysis outputs:

1. **Create Virtual Environment and Install Dependencies**

    Clone lockdrop simulation directory:

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

    # Navigate to lockdrop-simulation directory
    cd lockdrop-simulation
    ```

    Checkout to the latest [release](https://git.vdb.to/LaconicNetwork/lockdrop-simulation/releases)

    Create and activate a Python virtual environment:

    ```bash
    python3 -m venv venv
    source venv/bin/activate
    ```

    Install required Python packages:

    ```bash
    pip install -r requirements.txt
    ```

    Configure path to the `generated` directory that was generated in `zenith-stack` repo in above steps:

    ```bash
    export GENERATED_DIR="<path/to/zenith-stack>/generated"
    ```

2. **Execute the Notebook**

    Run the notebook to generate allocation calculations:

    ```bash
    jupyter nbconvert --to notebook --execute --inplace --log-level WARN lockdrop-calculations-simulated.ipynb
    ```

    This will:
    - Process the generated lockdrop participant data
    - Calculate allocation amounts for different lock periods
    - Generate artifacts (`lockdrop_allocations_notebook.json`) for comparison with the data from zenithd node

3. **View Notebook Results (Optional)**

    To view the analysis on generated data, open the notebook in your browser at <http://localhost:8888/notebooks/lockdrop-calculations-simulated.ipynb>:

    ```bash
    jupyter notebook lockdrop-calculations-simulated.ipynb
    ```

    The notebook contains useful visualizations including allocation distributions, lock period analysis, and participant statistics.

### Step 5: Run Simulation Tests

Run comprehensive tests to validate that the zenithd node's TGE allocations and run-time accruals match the notebook results:

1. **Set Environment Variables**

    Configure API endpoints for the running zenithd node:

    ```bash
    export REST_API_ENDPOINT="http://localhost:1317"
    export RPC_API_ENDPOINT="http://localhost:26657"
    ```

2. **Run All Tests**

    Navigate to the lockdrop-simulation directory (if not already there):

    ```bash
    cd <path/to/lockdrop-simulation>
    ```

    Activate `venv`:

    ```bash
    source venv/bin/activate
    ```

    Execute the complete test suite:

    ```bash
    python3 tests/run_all_tests.py
    ```

    This will run tests in the following order:
    - **Allocation Tests**: Compare star, galaxy, and total allocations between notebook and zenithd
    - **Unlock Schedule Tests**: Validate unlock block calculations (considering each point's locking time) and initial unlock amounts
    - **Accrual State Tests**: Verify accrual state calculations at current block height

3. **Run Individual Test Modules** (Optional)

    You can also run specific test categories:

    ```bash
    # Test only allocations
    python3 tests/test_allocations.py

    # Test only unlock schedules
    python3 tests/test_unlock_schedule.py

    # Test only accrual states
    python3 tests/test_accrual_state.py
    ```

4. **Test Output**

    The tests provide detailed tabular output showing:
    - Comparison between notebook calculations and zenithd responses
    - Any differences or mismatches
    - Comprehensive validation of the lockdrop implementation

## Cleanup

### Validator Deployment Cleanup

Go to `ansible` directory:

```bash
cd <path/to/zenith-stack>/ansible
```

Stop validator deployment:

```bash
zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=stop" --skip-tags onboarding
```

Clean up validator deployment:

```bash
zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=cleanup" --skip-tags onboarding -K
```

### Python Virtual Environment Cleanup

Go to `lockdrop-simulation` directory:

```bash
cd <path/to/lockdrop-simulation>
```

Clean up Python virtual environment:

```bash
# Deactivate virtual environment (if currently active)
deactivate

# Remove virtual environment directory
rm -rf venv
```