# Simulation Test Runs

This directory contains pre-generated data and outputs from simulation test runs. These can be used to reproduce test results using existing participant data instead of generating it afresh.

## Table of Contents

- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Configuration](#configuration)
  - [Service Configuration](#service-configuration)
  - [View Configuration](#view-configuration)
- [Setup](#setup)
- [Run Simulation](#run-simulation)
  - [Step 0: Place Existing Generated Data](#step-0-place-existing-generated-data)
  - [Step 1: Simulated Token Genesis Event](#step-1-simulated-token-genesis-event)
  - [Step 2: Genesis Transaction (Gentx) Signing](#step-2-genesis-transaction-gentx-signing)
  - [Step 3: Start Validator Node](#step-3-start-validator-node)
  - [Step 4: Run Lockdrop Distribution Notebook](#step-4-run-lockdrop-distribution-notebook)
  - [Step 5: Run Simulation Tests](#step-5-run-simulation-tests)
- [Compare Results](#compare-results)
- [Cleanup](#cleanup)

## Overview

This directory contains the following simulation test runs with pre-generated data and test suite outputs:
- run1: [run1/output.log](./run1/output.log)
- run2: [run2/output.log](./run2/output.log)
- run3: [run3/output.log](./run3/output.log)

To reproduce the results from any one of the test runs, follow these steps to run through the simulation with existing generated data.

## Prerequisites

- Software Requirements

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

- Repository Access: SSH access to <https://git.vdb.to/LaconicNetwork/zenith-stack>

- If you are logging in to the host using SSH, make sure to use agent forwarding:

  ```bash
  # Example
  ssh -A <user>@<control-node-ip>
  ```

- Set zenith-stack version to use:

  ```bash
  ZENITH_STACK_VERSION=v0.2.23
  ```

  Check [releases](https://git.vdb.to/LaconicNetwork/zenith-stack/releases) page for version history.

- **lockdrop-simulation repository**

  Clone the lockdrop simulation repository containing the simulation test suite and test runs:

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

  # Set repo directory path for further usage
  export LOCKDROP_SIMULATION_DIR=$(pwd)/lockdrop-simulation
  ```

- **zenith-stack repository**

  Clone the zenith-stack repository containing required Ansible playbooks:

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

  # Set repo directory path for further usage
  export ZENITH_STACK_DIR=$(pwd)/zenith-stack

  # Checkout to the required version
  cd $ZENITH_STACK_DIR
  git checkout $ZENITH_STACK_VERSION
  ```

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

- **zenith-ansible binary**

  **Note**: Set `OUTPUT_DIR` in the following command to output directory of your choice.

  You may need to run the following commands with necessary permissions, as root or through sudo.

  ```bash
  # Download the binary from generic package registry
  OUTPUT_DIR=~/bin
  mkdir -p $OUTPUT_DIR

  curl -L -o $OUTPUT_DIR/zenith-ansible https://git.vdb.to/api/packages/LaconicNetwork/generic/zenith-stack/$ZENITH_STACK_VERSION/zenith-ansible
  ```

  Make it executable:

  ```bash
  chmod +x $OUTPUT_DIR/zenith-ansible
  ```

  Add `OUTPUT_DIR` to your PATH:

  ```bash
  export PATH="$OUTPUT_DIR:$PATH"
  ```

  Verify installation:

  ```bash
  which zenith-ansible

  zenith-ansible --help
  ```

  **Always run zenith-ansible from the ansible directory on the control node.**

- **configure-zenith-vars binary**

  `configure-zenith-vars` is an interactive CLI tool to simplify the configuration process.

  ```bash
  # Navigate to the ansible directory
  cd $ZENITH_STACK_DIR/ansible

  # Run a playbook to install configure-zenith-vars
  # Use the same OUTPUT_DIR used for zenith-ansible
  zenith-ansible install-config-cli --install-dir "${OUTPUT_DIR}"
  ```

  Verify installation:

  ```bash
  which configure-zenith-vars

  # Working directory: zenith-stack/ansible
  configure-zenith-vars --help
  ```

  **Always run configure-zenith-vars from the ansible directory on the control node**: The CLI creates `inventories/` directory relative to your current working directory by default.

## Configuration

Before running a lockdrop simulation for Stage 1 of the Zenith Stack, we need to configure the required parameters.

```bash
# Navigate to ansible directory where `inventories` directory is present
cd $ZENITH_STACK_DIR/ansible

configure-zenith-vars --stage stage1-lockdrop-simulation
```

Set **`Generate fresh participants data` to `false`** since we will be using existing generated data from a test run.

This interactive tool will guide you through configuring all the necessary variables for your lockdrop simulation deployment.

**To update or edit the generated configuration**, simply re-run the `configure-zenith-vars` command before proceeding with further system setup.

### Service Configuration

**Genesis Generator Configuration**

- **Data directory for lockdrop simulation deployments**: Absolute path to the parent directory where deployments for lockdrop simulation will be created.

- **Ethereum RPC endpoint**: RPC endpoint for fetching current ETH block height.

  ```bash
  Example: https://eth.rpc.laconic.com/<API_KEY>
  ```

**Bootstrap Validator Configuration**

- **Bootstrap validator data directory**: Absolute path to the parent directory where the bootstrap validator deployment will be created (**use the same parent directory as set for Genesis Generator**).

- **Validator display name (moniker)**: Human-readable validator name for the simulation (default: ZodNode).

**Gentx Signer Configuration**

- **Gentx signer data directory**: Absolute path to the parent directory where gentx will be signed and the genesis file created (**use the same parent directory as set for Genesis Generator**).

### View Configuration

To view existing variables configuration, run with `list` flag:

```bash
# Working directory: zenith-stack/ansible
configure-zenith-vars --stage stage1-lockdrop-simulation --list

# Select `development` environment when prompted
```

## Setup

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

```bash
# Make sure you are in ansible directory
cd $ZENITH_STACK_DIR/ansible

export DATA_DIRECTORY=$(grep 'data_directory:' inventories/development/group_vars/tge.yml | awk '{print $2; exit}')
mkdir -p $DATA_DIRECTORY
```

Now, run required system setup (installs docker and laconic-so):

```bash
# sudo access required for installing docker
zenith-ansible system-setup -i dev -s stage1 --skip-tags onboarding,explorer
```

If your machine did not have Docker installed before, the above command will install it. On Ubuntu, you will need to activate the `docker` group for your current shell:

```bash
newgrp docker
```

This is a one time operation required to be performed after installing docker.

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

```bash
zenith-ansible setup -i dev -s tge
```

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

```bash
zenith-ansible setup -i dev -s stage1 --skip-tags onboarding,explorer
```

These steps will create following in the [configured](#view-configuration) deployments directory:
- `mock-lockdrop-watcher-deployment`
- `stage1-zenithd-deployment`

## Run Simulation

Now that all the deployment directories are setup, we are ready to run the simulation.

### Step 0: Place Existing Generated Data

Copy the generated folder from your chosen test run to zenith-stack:

```bash
# Navigate to the lockdrop-simulation repo directory
cd $LOCKDROP_SIMULATION_DIR

# Remove any existing data from previous runs
rm -rf $ZENITH_STACK_DIR/generated

# Example for run1
cp -r ./test-runs/run1/generated $ZENITH_STACK_DIR/generated

# Verify
ls $ZENITH_STACK_DIR/generated

# generated-accounts.json  generated-participants.json  point-allocation-stats.json  watcher-events.json
```

### Step 1: Simulated Token Genesis Event

Since we've placed existing generated data in zenith-stack, following command skips generating any new data. It creates a base genesis file with treasury initialized with the participants data:

```bash
# Navigate back to ansible directory in zenith-stack
cd $ZENITH_STACK_DIR/ansible

zenith-ansible simulate-lockdrop -i dev -s tge
```

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

[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 dummy accounts from the test run, 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: 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 sign -i dev -s stage1
```

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 Validator Node

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

```bash
zenith-ansible start -i dev -s stage1 --skip-tags onboarding,explorer
```

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

```bash
# Check validator logs
laconic-so deployment --dir $DATA_DIRECTORY/stage1-zenithd-deployment logs zenithd
```

Now we have a zenithd node running with the simulated participants data.

### Step 4: Run Lockdrop Distribution Notebook

Now we can execute the reference Jupyter notebook to perform lockdrop allocation calculations on the test participants data and produce analysis outputs. The notebook output is used further in the simulation test suite.

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

    Create and activate a Python virtual environment:

    ```bash
    # Navigate to the directory where you had cloned the lockdrop-simulation repo
    cd $LOCKDROP_SIMULATION_DIR

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

    Install required Python packages:

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

    Export path to the `generated` directory in `zenith-stack` repo from [Step 1](#step-1-simulated-token-genesis-event):

    ```bash
    export GENERATED_DIR=$ZENITH_STACK_DIR/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 lockdrop participants data from chosen test run
    - Calculate allocation amounts for different lock periods
    - Generate artifacts (`lockdrop_allocations_notebook.json`) for comparison with the data from zenithd node

### Step 5: Run Simulation Tests

Now we can run the comprehensive test suite to validate that the zenithd node's TGE allocations match notebook results and run-time accruals happen as expected.

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

    Activate `venv`:

    ```bash
    # Navigate to the lockdrop-simulation repo directory
    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. **View Lockdrop Distribution Notebook Results (Optional)**

    To view the analysis on generated data, open it using jupyter:

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

    This should automatically open the notebook 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 from server logs and load `lockdrop-calculations-simulated.ipynb`.

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

## Compare Results

After running the tests, compare your output from the tests above to output from the chosen test run (eg. `test-runs/run1/output.log`):

- Allocations: The allocations comparisons (`STAR ALLOCATIONS COMPARISON`, `GALAXY ALLOCATIONS COMPARISON` and `TOTAL ALLOCATIONS COMPARISON`) should match exactly as the TGE process is time-invariant
- Token unlock schedules:
  - Since the chain from your run starts at a later time than that from the original test run, the effective calculated unlock schedule for points will be different
  - In `UNLOCK BLOCKS COMPARISON`, the `Expected Blocks` (your run) should be `<` `Expected Blocks` (test run)
  - In `INITIAL UNLOCK AMOUNTS COMPARISON`, the `Expected ($sZ)` (your run) should be `>` `Expected ($sZ)` (test run)
- Accrual states: Since this checks accrual state at time of running the test, in `TOTAL UNLOCKED AT BLOCK X`, the `Expected ($sZ)` will be different across runs

If all the tests pass and above conditions hold, it confirms that the simulation produces consistent results.

## Cleanup

### Validator Deployment

Navigate to the Ansible directory:

```bash
cd $ZENITH_STACK_DIR/ansible
```

Stop validator deployment:

```bash
zenith-ansible stop -i dev -s stage1 --skip-tags onboarding,explorer
```

Clean up validator deployment:

```bash
zenith-ansible cleanup -i dev -s stage1 --skip-tags onboarding,explorer
```

### Python Virtual Environment

Go to the `lockdrop-simulation` directory:

```bash
cd $LOCKDROP_SIMULATION_DIR
```

Clean up Python virtual environment:

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

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