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

   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:

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

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

   Verify installation:

   which zenith-ansible
   

   For more details about zenith-ansible check this doc

2. Configure Variables

   Configure variables required for this simulation by following this guide.

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

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

   Make sure you are in ansible directory:

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

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

   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:

   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:

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:

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

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

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:

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:

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

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

   Checkout to the latest release

   Create and activate a Python virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   

   Install required Python packages:

   pip install -r requirements.txt
   

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

   export GENERATED_DIR="<path/to/zenith-stack>/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 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:

   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:

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

   cd <path/to/lockdrop-simulation>
   

   Activate venv:

   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. Run Individual Test Modules (Optional)

   You can also run specific test categories:

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

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

Stop validator deployment:

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

Clean up validator deployment:

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:

cd <path/to/lockdrop-simulation>

Clean up Python virtual environment:

# Deactivate virtual environment (if currently active)
deactivate

# Remove virtual environment directory
rm -rf venv