.gitignore

@@ -0,0 +1,4 @@
+venv
+__pycache__
+generated
+.ipynb_checkpoints

README.md

@@ -30,30 +30,34 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan
 
     **Note**: Replace `<path/to/zenith-stack>` in the commands below with the actual path where you cloned the zenith-stack repository.
 
-    Go to the directory where playbooks are located:
+    Run following commands with necessary permissions, as root or through sudo
 
-    ```bash
-    cd <path/to/zenith-stack>/ansible
-    ```
-
-    Install `zenith-ansible`:
+    Install `zenith-ansible` at `/usr/local/bin`:
 
     ```bash
     # Download the binary from generic package registry
-    curl -OJ https://git.vdb.to/api/packages/LaconicNetwork/generic/zenith-stack/v0.2.4/zenith-ansible
+    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:
 
     ```bash
-    chmod +x ./zenith-ansible
+    chmod +x /usr/local/bin/zenith-ansible
     ```
 
-    For more details about `zenith-ansible` check this [doc](./ansible/zenith-ansible-shiv/README.md)
+    Verify installation:
+
+    ```bash
+    which zenith-ansible
+    ```
+    <!-- TODO: Update tag -->
+    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](../ansible/zenith-config-cli/docs/stage1-lockdrop-simulation.md).
+    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
@@ -66,7 +70,7 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan
 
     ```bash
     # For example:
-    mkdir /home/$USER/stage1-lockdrop-simulation
+    mkdir -p /home/$USER/stage1-lockdrop-simulation
     ```
 
     Make sure you are in ansible directory:
@@ -78,13 +82,13 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan
     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"
+    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
+    zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=setup" --skip-tags onboarding
     ```
 
 ## Run Simulation
@@ -94,15 +98,15 @@ The lockdrop simulation validates the Zenith Network's token distribution mechan
 Following command allows users to create the base genesis file while simulating lockdrop participants:
 
 ```bash
-./zenith-ansible -i ./inventories/development/hosts.yml tge-site.yml -e "mode=simulate-lockdrop"
+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>/lockdrop-simulation/generated`:
+This will also generate following files in `<path/to/zenith-stack>/generated`:
 
 ```bash
-lockdrop-simulation/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
@@ -119,7 +123,7 @@ Get the private key of first account present in this file:
 
 ```bash
 # Working directory: <path/to/zenith-stack>/ansible
-jq -r '.[0].zenithPrivateKey' ../lockdrop-simulation/generated/generated-accounts.json
+jq -r '.[0].zenithPrivateKey' ../generated/generated-accounts.json
 ```
 
 Note this private key down as it will be required in next step.
@@ -127,7 +131,7 @@ 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:
 
 ```bash
-./zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=sign"
+zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=sign"
 ```
 
 Use the private key noted above when prompted.
@@ -144,7 +148,7 @@ This will:
 Now, we can use this genesis file to run the stage 1 validator node:
 
 ```bash
-./zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=start" --skip-tags onboarding
+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:
@@ -163,12 +167,17 @@ Execute the Jupyter notebook to perform lockdrop allocation calculations and gen
 
 1. **Create Virtual Environment and Install Dependencies**
 
-    Navigate to the lockdrop-simulation directory:
+    Clone lockdrop simulation directory:
 
     ```bash
-    cd <path/to/zenith-stack>/lockdrop-simulation
+    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
@@ -182,6 +191,12 @@ 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:
+
+    ```bash
+    export GENERATED_DIR="<path/to/zenith-stack>/generated"
+    ```
+
 2. **Execute the Notebook**
 
     Run the notebook to generate allocation calculations:
@@ -197,7 +212,7 @@ Execute the Jupyter notebook to perform lockdrop allocation calculations and gen
 
 3. **View Notebook Results (Optional)**
 
-    To view the analysis on generated data, open the notebook in your browser:
+    To view the analysis on generated data, open the notebook in your browser at <http://localhost:8888/notebooks/lockdrop-calculations-simulated.ipynb>:
 
     ```bash
     jupyter notebook lockdrop-calculations-simulated.ipynb
@@ -223,7 +238,7 @@ Run comprehensive tests to validate that the zenithd node's TGE allocations and
     Navigate to the lockdrop-simulation directory (if not already there):
 
     ```bash
-    cd <path/to/zenith-stack>/lockdrop-simulation
+    cd <path/to/lockdrop-simulation>
     ```
 
     Activate `venv`:
@@ -278,13 +293,13 @@ cd <path/to/zenith-stack>/ansible
 Stop validator deployment:
 
 ```bash
-./zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=stop" --skip-tags onboarding
+zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=stop" --skip-tags onboarding
 ```
 
 Clean up validator deployment:
 
 ```bash
-./zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=cleanup" --skip-tags onboarding -K
+zenith-ansible -i ./inventories/development/hosts.yml stage1-site.yml -e "mode=cleanup" --skip-tags onboarding -K
 ```
 
 ### Python Virtual Environment Cleanup
@@ -292,7 +307,7 @@ Clean up validator deployment:
 Go to `lockdrop-simulation` directory:
 
 ```bash
-cd <path/to/zenith-stack>/lockdrop-simulation
+cd <path/to/lockdrop-simulation>
 ```
 
 Clean up Python virtual environment:

lockdrop-calculations-simulated.ipynb

@@ -487,7 +487,9 @@
    ],
    "source": [
     "# Load events from watcher file\n",
-    "watcher_events_path = './generated/watcher-events.json'\n",
+    "import os\n",
+    "\n",
+    "watcher_events_path = os.path.join(os.getenv('GENERATED_DIR', './generated'), 'watcher-events.json')\n",
     "events = load_watcher_events(watcher_events_path)\n",
     "lock_stats = analyze_lockdrop_events(events)\n",
     "\n",

tests/base_test.py

@@ -18,6 +18,7 @@ class BaseAllocationTest(unittest.TestCase):
         """Load data once for all tests"""
         cls.rest_api_endpoint = os.getenv('REST_API_ENDPOINT')
         cls.rpc_api_endpoint = os.getenv('RPC_API_ENDPOINT')
+        cls.generated_dir = os.getenv('GENERATED_DIR', './generated')
 
         if not cls.rest_api_endpoint:
             raise unittest.SkipTest("REST_API_ENDPOINT environment variable not set")
@@ -25,9 +26,9 @@ class BaseAllocationTest(unittest.TestCase):
             raise unittest.SkipTest("RPC_API_ENDPOINT environment variable not set")
 
         # Load data files
-        with open('./generated/watcher-events.json', 'r') as f:
+        with open(f'{cls.generated_dir}/watcher-events.json', 'r') as f:
             cls.watcher_events = json.load(f)
-        with open('./generated/generated-participants.json', 'r') as f:
+        with open(f'{cls.generated_dir}/generated-participants.json', 'r') as f:
             cls.participants = json.load(f)
         with open('lockdrop_allocations_notebook.json', 'r') as f:
             cls.notebook_allocations = json.load(f)