Merge pull request #606 from input-output-hk/hjeljeli32/readme-demo-improvements

Update README instructions for running the Leios demo

Author: ch1bo

crypto-benchmarks.rs/demo/README.md

@@ -1,96 +1,114 @@
+# Demo Scripts for Leios Crypto Benchmarks
 
+## Setup
 
-# Demo Scripts for Leios Crypto Benchmarks
+From the `demo/` directory, go one level up to the `crypto-benchmarks.rs` directory and build the CLI binary:
 
-This folder contains scripts that orchestrate end-to-end demonstrations of BLS-based vote aggregation and certificate generation/verification for the Leios project.
+```bash
+cd ..
+cargo build --release
+```
 
-## Prerequisites
+**Register the CLI path (while still in `crypto-benchmarks.rs/`)** so all demo scripts can find it:
 
-- Ensure the CLI built from the repository root is available; see `crypto-benchmarks.rs/ReadMe.md` for build instructions and usage details.
-- Ensure Python 3 is available with `cbor2` installed.  
-  For example:
+```bash
+./demo/scripts/00_set_cli.sh -p "$(pwd)/target/release/leios_crypto_benchmarks"
+```
 
-  ```bash
-  python3 -m venv .venv
-  source .venv/bin/activate
-  pip install cbor2
-  ```
+Now return to the `demo/` directory to proceed:
 
-## Workflow
+```bash
+cd demo
+```
 
-The scripts are designed to be run from the `demo/` directory.
+Verify the `.env_cli` file and sanity‑check the CLI:
 
-### Run Step by Step (Manual Mode)
+```bash
+cat scripts/.env_cli
+source scripts/.env_cli
+echo "$CLI"
+$CLI --help
+```
 
-You can run each script individually to understand and control each step of the process for a given number of voters (e.g., 100). Use the `-d` option to specify the output directory (e.g., `run100`).
+Ensure the CLI binary is accessible and working before proceeding.
 
-#### 10_init_inputs.sh
+## Python Environment Setup
 
-Initialize inputs for N voters:
+Create and activate a Python virtual environment, then install the required dependencies:
 
 ```bash
-scripts/10_init_inputs.sh -d run100 --pools 500 --stake 100000 --alpha 9 --beta 1
+python3 -m venv .venv
+source .venv/bin/activate
+pip install flask cbor2
 ```
 
-#### 20_make_registry.sh
+(Flask is required to serve the demo UI, and cbor2 is used for parsing CBOR files.)
+
+## Run a Single End-to-End Demo
 
-Build the registry from initialized inputs:
+From the `demo/` directory, run the combined script to generate a complete demo for a specified number of voters and pools. Ensure `.env_cli` exists in this directory:
+
+(If you haven’t yet, run the **Setup** steps above to build the CLI and create `scripts/.env_cli`.)
 
 ```bash
-./scripts/20_make_registry.sh -d run100 -n 100
+scripts/70_run_one.sh -d run100 -p 500 -n 100 -f 0.75
 ```
 
-#### 30_cast_votes.sh
+This script will:
 
-Cast votes with a specified fraction of voters voting (e.g., 1.0 means all vote):
+1. Initialize inputs
+2. Build the registry
+3. Cast votes
+4. Generate the aggregated certificate
+5. Verify the certificate
+6. Export data for the UI
 
-```bash
-scripts/30_cast_votes.sh -d run100 -f 0.75
-```
+All output files will be placed under `demo/run100/`.
 
-#### 40_make_certificate.sh
+## Launch the Demo UI
 
-Generate the aggregated certificate:
+After generating a demo run, start the UI server from the `demo/` directory:
 
 ```bash
-scripts/40_make_certificate.sh -d run100
+python3 ui/server.py
 ```
 
-#### 50_verify_certificate.sh
+Open your browser at [http://127.0.0.1:5050/ui](http://127.0.0.1:5050/ui) to explore the results.
+
+## Run Step by Step (Manual Mode)
+
+For advanced users who want to control each phase individually, the following scripts can be run sequentially from the `demo/` directory. Use the `-d` option to specify the output directory (e.g., `run100`).
 
-Verify the generated certificate:
+1. **Initialize inputs for N voters:**
 
 ```bash
-scripts/50_verify_certificate.sh -d run100
+scripts/10_init_inputs.sh -d run100 --pools 500 --stake 100000 --alpha 9 --beta 1
 ```
 
-### Run a Single End-to-End Demo
+2. **Build the registry:**
 
 ```bash
-scripts/70_run_one.sh -d run100 -p 500 -n 100 -f 0.75
+scripts/20_make_registry.sh -d run100 -n 100
 ```
 
-This will:
+3. **Cast votes with a fraction of voters participating:**
 
-1. Initialize inputs (`10_init_inputs.sh`)
-2. Build a registry (`20_make_registry.sh`)
-3. Cast votes (`30_cast_votes.sh`)
-4. Make a certificate (`40_make_certificate.sh`)
-5. Verify the certificate (`50_verify_certificate.sh`)
-6. Export data for the UI (`60_export_demo_json.sh`)
+```bash
+scripts/30_cast_votes.sh -d run100 -f 0.75
+```
 
-All files are placed in `demo/run100/`.
+4. **Generate the aggregated certificate:**
 
-### Launch the Demo UI
+```bash
+scripts/40_make_certificate.sh -d run100
+```
 
-After generating a demo run (for example via `scripts/70_run_one.sh`), start the UI server from this directory:
+5. **Verify the generated certificate:**
 
 ```bash
-python3 ui/server.py
+scripts/50_verify_certificate.sh -d run100
 ```
 
-Then open your browser at [http://127.0.0.1:5050/ui](http://127.0.0.1:5050/ui) to explore the results.
-
 ## Notes
 
 - All scripts must be run from within the `demo/` directory.
@@ -101,4 +119,5 @@ Then open your browser at [http://127.0.0.1:5050/ui](http://127.0.0.1:5050/ui) t
   votes_bytes / certificate_bytes
   ```
 
-which illustrates the storage/bandwidth savings achieved by BLS aggregation.
+  which illustrates the storage and bandwidth savings achieved by BLS aggregation.
+- The CLI path is stored in `scripts/.env_cli` (generated by `00_set_cli.sh`). Source it with `source scripts/.env_cli` to make `$CLI` available in your shell.