lockdrop-simulation/test-runs

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
• Prerequisites
• Configuration
  • Service Configuration
  • View Configuration
• Setup
• Run Simulation
  • Step 0: Place Existing Generated Data
  • Step 1: Simulated Token Genesis Event
  • Step 2: Genesis Transaction (Gentx) Signing
  • Step 3: Start Validator Node
  • Step 4: Run Lockdrop Distribution Notebook
  • Step 5: Run Simulation Tests
• Compare Results
• Cleanup

Overview

This directory contains the following simulation test runs with pre-generated data and test suite outputs:

• run1: run1/output.log
• run2: run2/output.log
• run3: 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 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
      

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

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

• Set zenith-stack version to use:

  ZENITH_STACK_VERSION=v0.2.16
  

  Check releases page for version history.

• lockdrop-simulation repository

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

  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:

  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.

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

  chmod +x $OUTPUT_DIR/zenith-ansible
  

  Add OUTPUT_DIR to your PATH:

  export PATH="$OUTPUT_DIR:$PATH"
  

  Verify installation:

  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.

  # 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}" -K
  

  Verify installation:

  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.

# 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.

  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:

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

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

# sudo access required for installing docker
zenith-ansible system-setup -i dev -s stage1 -K --skip-tags onboarding

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:

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:

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:

zenith-ansible setup -i dev -s stage1 --skip-tags onboarding

These steps will create following in the configured 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:

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

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

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

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:

zenith-ansible start -i dev -s stage1 --skip-tags onboarding

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

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

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

   pip install -r requirements.txt
   

   Export path to the generated directory in zenith-stack repo from Step 1:

   export GENERATED_DIR=$ZENITH_STACK_DIR/generated
   

2. Execute the Notebook

   Run the notebook to generate allocation calculations:

   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:

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

2. Run All Tests

   Activate venv:

   # Navigate to the lockdrop-simulation repo directory
   source venv/bin/activate
   

   Execute the complete test suite:

   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:

   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:

   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:

cd $ZENITH_STACK_DIR/ansible

Stop validator deployment:

zenith-ansible stop -i dev -s stage1 --skip-tags onboarding

Clean up validator deployment:

zenith-ansible cleanup -i dev -s stage1 --skip-tags onboarding -K

Python Virtual Environment

Go to the lockdrop-simulation directory:

cd $LOCKDROP_SIMULATION_DIR

Clean up Python virtual environment:

# Deactivate virtual environment (if currently active)
deactivate

# Remove virtual environment directory
rm -rf venv