LaconicNetwork/lockdrop-simulation
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Improve directory resolution

Browse Source
This commit is contained in:
Prathamesh Musale 2025-08-18 13:44:21 +05:30
parent 37908aed84
commit f46d5181da
3 changed files with 67 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
EXPERIMENT.md
View File

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

62
README.md
View File

@ -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 <https://git.vdb.to/LaconicNetwork/zenith-stack>
@ -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 <control-node-ip>
```
@ -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 `<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.
@ -161,7 +166,7 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan
```bash
# Navigate to the ansible directory
cd <path/to/zenith-stack>/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: <path/to/zenith-stack>/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 <path/to/zenith-stack>/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: <path/to/zenith-stack>/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 <path/to/zenith-stack>/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 <path/to/zenith-stack>/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 `<path/to/zenith-stack>/generated`:
This will generate following files in `zenith-stack/generated`:
```bash
<path/to/zenith-stack>/generated/
@ -303,9 +308,7 @@ This will generate following files in `<path/to/zenith-stack>/generated`:
└── watcher-events.json # Simulated lockdrop contract events
```
And a base genesis file at `<path/to/zenith-stack>/base-genesis-file/genesis.json`.
Note the path to `<path/to/zenith-stack>/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: <path/to/zenith-stack>/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="<path/to/zenith-stack>/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 <path/to/lockdrop-simulation>
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 <path/to/zenith-stack>/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 <path/to/lockdrop-simulation>
cd $LOCKDROP_SIMULATION_DIR
```
Clean up Python virtual environment:

62
test-runs/README.md
View File

@ -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 <https://git.vdb.to/LaconicNetwork/zenith-stack>
@ -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 <control-node-ip>
```
@ -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 <path/to/zenith-stack>/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: <path/to/zenith-stack>/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 <path/to/zenith-stack>/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: <path/to/zenith-stack>/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 <path/to/zenith-stack>/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 <path/to/lockdrop-simulation>/test-runs/run1/generated <path/to/zenith-stack>/generated
cp -r ./test-runs/run1/generated $ZENITH_STACK_DIR/generated
# Verify
ls <path/to/zenith-stack>/generated
ls $ZENITH_STACK_DIR/generated
# generated-accounts.json generated-participants.json point-allocation-stats.json watcher-events.json
```
@ -260,13 +270,14 @@ ls <path/to/zenith-stack>/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 `<path/to/zenith-stack>/base-genesis-file/genesis.json`.
Note the path to `<path/to/zenith-stack>/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: <path/to/zenith-stack>/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="<path/to/zenith-stack>/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 <path/to/lockdrop-simulation>
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 <path/to/zenith-stack>/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 <path/to/lockdrop-simulation>
cd $LOCKDROP_SIMULATION_DIR
```
Clean up Python virtual environment: