diff --git a/EXPERIMENT.md b/EXPERIMENT.md index d031b3d..64ea427 100644 --- a/EXPERIMENT.md +++ b/EXPERIMENT.md @@ -16,7 +16,7 @@ This guide explains how to use the interactive notebook to experiment with diffe python3 -m ensurepip --version # Ubuntu/Debian - sudo apt-get install python3-venv + sudo apt install python3-venv python3-dev build-essential ``` ## Quick Start diff --git a/README.md b/README.md index ab9a299..8959cab 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan python3 -m ensurepip --version # Ubuntu/Debian - sudo apt-get install python3-venv + sudo apt install python3-venv python3-dev build-essential ``` - Repository Access: SSH access to @@ -86,6 +86,7 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan - If you are logging in to the host using SSH, make sure to use agent forwarding: ```bash + # Example ssh -A ``` @@ -103,6 +104,9 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan ```bash git clone git@git.vdb.to:LaconicNetwork/lockdrop-simulation.git + + # Set repo directory path for further usage + LOCKDROP_SIMULATION_DIR=$(pwd)/lockdrop-simulation ``` - **zenith-stack repository** @@ -112,13 +116,14 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan ```bash git clone git@git.vdb.to:LaconicNetwork/zenith-stack.git + # Set repo directory path for further usage + ZENITH_STACK_DIR=$(pwd)/zenith-stack + # 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. @@ -161,7 +166,7 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan ```bash # Navigate to the ansible directory - cd /ansible + cd $ZENITH_STACK_DIR/ansible # Run a playbook to install configure-zenith-vars # Use the same OUTPUT_DIR used for zenith-ansible @@ -173,7 +178,7 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan ```bash which configure-zenith-vars - # Working directory: /ansible + # Working directory: zenith-stack/ansible configure-zenith-vars --help ``` @@ -185,7 +190,7 @@ Before running a lockdrop simulation for Stage 1 of the Zenith Stack, we need to ```bash # Navigate to ansible directory where `inventories` directory is present -cd /ansible +cd $ZENITH_STACK_DIR/ansible configure-zenith-vars --stage stage1-lockdrop-simulation ``` @@ -221,20 +226,20 @@ It allows flexible simulation parameters: **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). +- **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 (can use the same parent directory as set for Genesis Generator). +- **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: /ansible +# Working directory: zenith-stack/ansible configure-zenith-vars --stage stage1-lockdrop-simulation --list # Select `development` environment when prompted @@ -245,18 +250,18 @@ configure-zenith-vars --stage stage1-lockdrop-simulation --list 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 -# For example: -mkdir -p /home/$USER/stage1-lockdrop-simulation +# Make sure you are in ansible directory +cd $ZENITH_STACK_DIR/ansible + +DATA_DIRECTORY=$(grep 'data_directory:' inventories/development/group_vars/stage1.yml | awk '{print $2; exit}') +mkdir -p $DATA_DIRECTORY ``` Now, run required system setup (installs docker and laconic-so): ```bash -# Make sure you are in ansible directory -cd /ansible - # sudo access required for installing docker -zenith-ansible -i ./inventories/development/hosts.yml ./stage1-site.yml -e "mode=system-setup" -K +zenith-ansible -i ./inventories/development/hosts.yml ./stage1-site.yml -e "mode=system-setup" -K --skip-tags onboarding ``` Setup the deployment directories and pull required docker images to generate base genesis file along with other artifacts: @@ -284,7 +289,7 @@ Now that all the deployment directories are setup, we are ready to run the simul Remove any existing data from previous runs: ```bash -rm -rf /generated +rm -rf $ZENITH_STACK_DIR/generated ``` 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: @@ -293,7 +298,7 @@ Following command generates the simulated participants with respective point loc zenith-ansible -i ./inventories/development/hosts.yml tge-site.yml -e "mode=simulate-lockdrop" ``` -This will generate following files in `/generated`: +This will generate following files in `zenith-stack/generated`: ```bash /generated/ @@ -303,9 +308,7 @@ This will 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). +And a base genesis file at `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). @@ -316,7 +319,7 @@ Since we have generated dummy accounts, we can access there private keys present Get the private key of first account present in this file: ```bash -# Working directory: /ansible +# Working directory: zenith-stack/ansible jq -r '.[0].zenithPrivateKey' ../generated/generated-accounts.json ``` @@ -348,9 +351,6 @@ zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=s After starting the node, verify it's running correctly: ```bash -# 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 ``` @@ -367,7 +367,7 @@ Now we can execute the reference Jupyter notebook to perform lockdrop allocation ```bash # Navigate to the directory where you had cloned the lockdrop-simulation repo - cd lockdrop-simulation + cd $LOCKDROP_SIMULATION_DIR python3 -m venv venv source venv/bin/activate @@ -382,7 +382,7 @@ Now we can execute the reference Jupyter notebook to perform lockdrop allocation Export path to the `generated` directory in `zenith-stack` repo from [Step 1](#step-1-simulated-token-genesis-event): ```bash - export GENERATED_DIR="/generated" + export GENERATED_DIR=$ZENITH_STACK_DIR/generated ``` 2. **Execute the Notebook** @@ -423,10 +423,10 @@ Now we can run the comprehensive test suite to validate that the zenithd node's 2. **Run All Tests** - Navigate to the lockdrop-simulation directory (if not already there): + Navigate to the lockdrop-simulation repo directory (if not already there): ```bash - cd + cd $LOCKDROP_SIMULATION_DIR ``` Activate `venv`: @@ -475,7 +475,7 @@ Now we can run the comprehensive test suite to validate that the zenithd node's Navigate to the Ansible directory: ```bash -cd /ansible +cd $ZENITH_STACK_DIR/ansible ``` Stop validator deployment: @@ -492,10 +492,10 @@ zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=c ### Python Virtual Environment -Go to the `lockdrop-simulation` directory: +Navigate to the `lockdrop-simulation` repo directory: ```bash -cd +cd $LOCKDROP_SIMULATION_DIR ``` Clean up Python virtual environment: diff --git a/test-runs/README.md b/test-runs/README.md index ef29fe4..57c15cf 100644 --- a/test-runs/README.md +++ b/test-runs/README.md @@ -45,7 +45,7 @@ To reproduce the results from any one of the test runs, follow these steps to ru python3 -m ensurepip --version # Ubuntu/Debian - sudo apt-get install python3-venv + sudo apt install python3-venv python3-dev build-essential ``` - Repository Access: SSH access to @@ -53,6 +53,7 @@ To reproduce the results from any one of the test runs, follow these steps to ru - If you are logging in to the host using SSH, make sure to use agent forwarding: ```bash + # Example ssh -A ``` @@ -70,6 +71,9 @@ To reproduce the results from any one of the test runs, follow these steps to ru ```bash git clone git@git.vdb.to:LaconicNetwork/lockdrop-simulation.git + + # Set repo directory path for further usage + LOCKDROP_SIMULATION_DIR=$(pwd)/lockdrop-simulation ``` - **zenith-stack repository** @@ -79,6 +83,9 @@ To reproduce the results from any one of the test runs, follow these steps to ru ```bash git clone git@git.vdb.to:LaconicNetwork/zenith-stack.git + # Set repo directory path for further usage + ZENITH_STACK_DIR=$(pwd)/zenith-stack + # Checkout to the required version cd zenith-stack git checkout $ZENITH_STACK_VERSION @@ -128,7 +135,7 @@ To reproduce the results from any one of the test runs, follow these steps to ru ```bash # Navigate to the ansible directory - cd /ansible + cd $ZENITH_STACK_DIR/ansible # Run a playbook to install configure-zenith-vars # Use the same OUTPUT_DIR used for zenith-ansible @@ -140,7 +147,7 @@ To reproduce the results from any one of the test runs, follow these steps to ru ```bash which configure-zenith-vars - # Working directory: /ansible + # Working directory: zenith-stack/ansible configure-zenith-vars --help ``` @@ -152,7 +159,7 @@ Before running a lockdrop simulation for Stage 1 of the Zenith Stack, we need to ```bash # Navigate to ansible directory where `inventories` directory is present -cd /ansible +cd $ZENITH_STACK_DIR/ansible configure-zenith-vars --stage stage1-lockdrop-simulation ``` @@ -183,20 +190,20 @@ This interactive tool will guide you through configuring all the necessary varia **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). +- **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 (can use the same parent directory as set for Genesis Generator). +- **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: /ansible +# Working directory: zenith-stack/ansible configure-zenith-vars --stage stage1-lockdrop-simulation --list # Select `development` environment when prompted @@ -207,18 +214,18 @@ configure-zenith-vars --stage stage1-lockdrop-simulation --list 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 -# For example: -mkdir -p /home/$USER/stage1-lockdrop-simulation +# Make sure you are in ansible directory +cd $ZENITH_STACK_DIR/ansible + +DATA_DIRECTORY=$(grep 'data_directory:' inventories/development/group_vars/stage1.yml | awk '{print $2; exit}') +mkdir -p $DATA_DIRECTORY ``` Now, run required system setup (installs docker and laconic-so): ```bash -# Make sure you are in ansible directory -cd /ansible - # sudo access required for installing docker -zenith-ansible -i ./inventories/development/hosts.yml ./stage1-site.yml -e "mode=system-setup" -K +zenith-ansible -i ./inventories/development/hosts.yml ./stage1-site.yml -e "mode=system-setup" -K --skip-tags onboarding ``` Setup the deployment directories and pull required docker images to generate base genesis file along with other artifacts: @@ -246,11 +253,14 @@ Now that all the deployment directories are setup, we are ready to run the simul Copy the generated folder from your chosen test run to zenith-stack: ```bash +# Navigate to the lockdrop-simulation repo directory +cd $LOCKDROP_SIMULATION_DIR + # Example for run1 -cp -r /test-runs/run1/generated /generated +cp -r ./test-runs/run1/generated $ZENITH_STACK_DIR/generated # Verify -ls /generated +ls $ZENITH_STACK_DIR/generated # generated-accounts.json generated-participants.json point-allocation-stats.json watcher-events.json ``` @@ -260,13 +270,14 @@ ls /generated 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 -i ./inventories/development/hosts.yml tge-site.yml -e "mode=simulate-lockdrop" ``` This will generate 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 @@ -276,7 +287,7 @@ Since we have dummy accounts from the test run, we can access there private keys Get the private key of first account present in this file: ```bash -# Working directory: /ansible +# Working directory: zenith-stack/ansible jq -r '.[0].zenithPrivateKey' ../generated/generated-accounts.json ``` @@ -308,9 +319,6 @@ zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=s After starting the node, verify it's running correctly: ```bash -# 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 ``` @@ -327,7 +335,7 @@ Now we can execute the reference Jupyter notebook to perform lockdrop allocation ```bash # Navigate to the directory where you had cloned the lockdrop-simulation repo - cd lockdrop-simulation + cd $LOCKDROP_SIMULATION_DIR python3 -m venv venv source venv/bin/activate @@ -342,7 +350,7 @@ Now we can execute the reference Jupyter notebook to perform lockdrop allocation Export path to the `generated` directory in `zenith-stack` repo from [Step 1](#step-1-simulated-token-genesis-event): ```bash - export GENERATED_DIR="/generated" + export GENERATED_DIR=$ZENITH_STACK_DIR/generated ``` 2. **Execute the Notebook** @@ -383,10 +391,10 @@ Now we can run the comprehensive test suite to validate that the zenithd node's 2. **Run All Tests** - Navigate to the lockdrop-simulation directory (if not already there): + Navigate to the lockdrop-simulation repo directory: ```bash - cd + cd $LOCKDROP_SIMULATION_DIR ``` Activate `venv`: @@ -426,7 +434,7 @@ If all the tests pass and above conditions hold, it confirms that the simulation Navigate to the Ansible directory: ```bash -cd /ansible +cd $ZENITH_STACK_DIR/ansible ``` Stop validator deployment: @@ -446,7 +454,7 @@ zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=c Go to the `lockdrop-simulation` directory: ```bash -cd +cd $LOCKDROP_SIMULATION_DIR ``` Clean up Python virtual environment: