diff --git a/README.md b/README.md index 49320b2..c1dae26 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,27 @@ # lockdrop-simulation +This repository includes the simulation of Zenith Network's token lockdrop distribution and tests to validate the simulation run. It simulates a realistic lockdrop scenario using mock participants and validates token allocation calculations against a live zenithd node. + +## Table of Contents + +- [Overview](#overview) + - [Interactive Experimentation](#interactive-experimentation) + - [Full Simulation and Validation](#full-simulation-and-validation) +- [Approach](#approach) + - [Simulation Features](#simulation-features) +- [Prerequisites](#prerequisites) +- [Configuration](#configuration) + - [Generated Files](#generated-files) + - [View Configuration](#view-configuration) +- [Setup](#setup) +- [Run Simulation](#run-simulation) + - [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) +- [Cleanup](#cleanup) + ## Overview This repository provides two main ways to work with lockdrop calculations: @@ -11,7 +33,7 @@ For independent experimentation with lockdrop allocation scenarios, see [EXPERIM - Test various scenarios (balanced, five-year focused, short-term focused, etc.) - Export timestamped results for analysis -### Full Simulation & Validation +### Full Simulation and Validation Continue reading below for the complete simulation workflow that validates token distribution against a live zenithd node. @@ -22,6 +44,7 @@ Continue reading below for the complete simulation workflow that validates token 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 +- **Generate watcher events** to simulate Ethereum Lockdrop contract interactions - **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 @@ -35,92 +58,199 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan - **Realistic Attestations**: Create attestations following the expected format - **Token Calculations**: Treasury calculations for lockdrop participants based on total supply and participant count +## Prerequisites + +- Set zenith-stack version to use: + + ```bash + ZENITH_STACK_VERSION=v0.2.9 + ``` + + 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: + + ```bash + git clone git@git.vdb.to:LaconicNetwork/lockdrop-simulation.git + ``` + +- **zenith-stack repository** + + Clone the zenith-stack repository containing required Ansible playbooks: + + ```bash + git clone git@git.vdb.to:LaconicNetwork/zenith-stack.git + + # Checkout to the required version + cd zenith-stack + git checkout $ZENITH_STACK_VERSION + ``` + + **Note**: Replace `` 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. Make sure that it exists and is in your [`PATH`](https://unix.stackexchange.com/a/26059). + + 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 + 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 + ``` + + 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 /ansible + + # Run a playbook to install configure-zenith-vars + # Use the same OUTPUT_DIR used for zenith-ansible + zenith-ansible install-zenith-config-cli.yml -e "cli_install_dir=${OUTPUT_DIR}" -K + ``` + + Verify installation: + + ```bash + which configure-zenith-vars + + # Working directory: /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 /ansible + +configure-zenith-vars --stage stage1-lockdrop-simulation +``` + +Set **`Generate fresh participants data` to `true`**. + +This interactive tool will guide you through configuring all the necessary variables for your lockdrop simulation deployment. + +It 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 + +**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/ + ``` + +- **Number of participants**: Total number of mock participants to generate for simulation (default: 400). + +- **Galaxy count**: Number of galaxies to allocate among participants - determines validator count in real scenario (default: 200). + +- **Star count**: Number of stars to allocate among participants - each participant needs at least 1 (default: 2000). + +**Bootstrap Validator Configuration** + +- **Bootstrap validator data directory**: Absolute path to the parent directory where the bootstrap validator deployment will be created (can 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 (can use the same parent directory as set for Genesis Generator). + +### Generated Files + +The CLI tool generates the following configuration files: + +- `ansible/inventories/development/group_vars/stage1.yml` - Stage 1 specific configuration +- `ansible/inventories/development/group_vars/tge.yml` - Genesis Generator configuration with simulation parameters + +### View Configuration + +To view existing variables configuration, run with `list` flag: + +```bash +# Working directory: /ansible +configure-zenith-vars --stage stage1-lockdrop-simulation --list + +# Select `development` environment when prompted +``` + ## Setup -1. **Install Prerequisites** +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): - Clone the zenith-stack repository which contains the Ansible playbooks: +```bash +# For example: +mkdir -p /home/$USER/stage1-lockdrop-simulation +``` - ```bash - git clone git@git.vdb.to:LaconicNetwork/zenith-stack.git - ``` +Setup the deployment directories and pull required docker images to generate base genesis file along with other artifacts: - **Note**: Replace `` in the commands below with the actual path where you cloned the zenith-stack repository. +```bash +# Make sure you are in ansible directory: +cd /ansible - Run following commands with necessary permissions, as root or through sudo +zenith-ansible -i ./inventories/development/hosts.yml tge-site.yml -e "mode=setup" +``` - Install `zenith-ansible` at `/usr/local/bin`: +Setup the deployment directories and pull required docker images to sign the gentx and setup stage 1 validator node: - ```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 - ``` +```bash +zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=setup" --skip-tags onboarding +``` - **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 - ``` - - 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 /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 - ``` +These steps will create following in the [configured](#view-configuration) deployments directory: +- `mock-lockdrop-watcher-deployment` +- `mainnet-zenithd-deployment` ## Run Simulation +Now that all the deployment directories are setup, we are ready to run the simulation. + ### Step 1: Simulated Token Genesis Event -Following command allows users to create the base genesis file while simulating lockdrop participants: +Following command generates the simulated participants with respective point lockup events. It also creates a base genesis file with treasury initialized with the participants data: ```bash zenith-ansible -i ./inventories/development/hosts.yml tge-site.yml -e "mode=simulate-lockdrop" ``` -This will generate base genesis file at `/base-genesis-file/genesis.json` - -This will also generate following files in `/generated`: +This will generate following files in `/generated`: ```bash /generated/ @@ -130,6 +260,10 @@ This will also generate following files in `/generated`: └── watcher-events.json # Simulated lockdrop contract events ``` +And a base genesis file at `/base-genesis-file/genesis.json` + +Note the path to `/generated` directory as it will be required in [Step 4](#step-4-run-lockdrop-distribution-notebook). + [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 @@ -160,7 +294,7 @@ This will: - Generate the final genesis file - Copy final genesis to `/genesis-file/genesis.json` -### Step 3: Start Bootstrap Validator +### Step 3: Start Validator Node Now, we can use this genesis file to run the stage 1 validator node: @@ -171,33 +305,27 @@ zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=s After starting the node, verify it's running correctly: ```bash -# Set data directory (should match configuration) -export DATA_DIRECTORY=/absolute/path/to/data/directory +# Set deployments data directory (should match configuration) +DATA_DIRECTORY=/absolute/path/to/deployments/directory # Check validator logs laconic-so deployment --dir $DATA_DIRECTORY/mainnet-zenithd-deployment logs zenithd -f ``` +Now we have a zenithd node running with the simulated participants data. + ### Step 4: Run Lockdrop Distribution Notebook -Execute the Jupyter notebook to perform lockdrop allocation calculations and generate analysis outputs: +Now we can execute the reference Jupyter notebook to perform lockdrop allocation calculations on the generated data and produce analysis outputs. The notebook output is used further in the simulation test suite. 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 + # Navigate to the directory where you had cloned the lockdrop-simulation repo + cd lockdrop-simulation + python3 -m venv venv source venv/bin/activate ``` @@ -208,7 +336,7 @@ Execute the Jupyter notebook to perform lockdrop allocation calculations and gen pip install -r requirements.txt ``` - Configure path to the `generated` directory that was generated in `zenith-stack` repo in above steps: + Export path to the `generated` directory in `zenith-stack` repo from [Step 1](#step-1-simulated-token-genesis-event): ```bash export GENERATED_DIR="/generated" @@ -239,7 +367,7 @@ Execute the Jupyter notebook to perform lockdrop allocation calculations and gen ### 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: +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** @@ -295,13 +423,13 @@ Run comprehensive tests to validate that the zenithd node's TGE allocations and The tests provide detailed tabular output showing: - Comparison between notebook calculations and zenithd responses - Any differences or mismatches - - Comprehensive validation of the lockdrop implementation + - Validation of the lockdrop implementation ## Cleanup -### Validator Deployment Cleanup +### Validator Deployment -Go to `ansible` directory: +Navigate to the Ansible directory: ```bash cd /ansible @@ -319,9 +447,9 @@ 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 +### Python Virtual Environment -Go to `lockdrop-simulation` directory: +Go to the `lockdrop-simulation` directory: ```bash cd