Genesis_Verification

Genesis Creation and Verification Process

This document outlines the procedure for creating and verifying the genesis state for the Resonance testnet. The process uses deterministic runtime builds from GitHub releases to ensure transparency and reproducibility.

Genesis Creation Process

The genesis file creation process is automated by the scripts/genesis_generate_spec.sh script, which generates the live-resonance.json file by building a base chain spec locally and then replacing the runtime code with a deterministic WASM artifact from a specific GitHub release.

Prerequisites

• Clean git working directory (no uncommitted changes)
• Access to GitHub API (for downloading release artifacts)
• curl, jq, and standard build tools installed

Step-by-Step Process

Step 1: Prepare Release Tag

Before generating genesis, ensure you have a GitHub release with runtime artifacts built using srtool (Substrate Runtime Tool). These releases should contain:

• quantus-runtime-v{SPEC_VERSION}.compact.compressed.wasm

Step 2: Run Genesis Generation Script

Execute the genesis generation script with the desired release tag:

./scripts/genesis_generate_spec.sh v0.X.Y-test-genesis

Step 3: What the Script Does

The script performs the following automated steps:

1. Environment Verification

   • Checks that the working directory is clean
   • Fetches latest tags from origin

2. Checkout Release Tag

   • Creates a new branch genesis/{RELEASE_TAG}
   • Switches to the specified release tag

3. Build Node Locally

   • Executes cargo build --release --package quantus-node
   • This builds the node binary from the checked-out source code

4. Generate Base Chain Specification

   • Executes: ./target/release/quantus-node build-spec --chain live_resonance_local --raw > node/src/chain-specs/live-resonance.json
   • The live_resonance_local identifier refers to the chain specification defined in the code
   • The --raw flag generates a raw JSON file with embedded WASM runtime

5. Download and Replace Runtime Code

   • Queries GitHub API to determine the spec_version from release assets
   • Downloads the deterministic compressed WASM: quantus-runtime-v{SPEC_VERSION}.compact.compressed.wasm
   • Converts the WASM file to hexadecimal format
   • Directly replaces the runtime code in the generated JSON using jq:

     jq '.genesis.raw.top."0x3a636f6465" = $wasm_hex' chain-spec.json

   • The key 0x3a636f6465 represents the :code storage key where runtime code is stored

Step 4: Review and Commit

After the script completes:

• Review the generated node/src/chain-specs/live-resonance.json file
• Commit the changes to the new branch
• Create a pull request to merge into main branch

Key Benefits of This Approach

1. Deterministic Runtime: Uses srtool-generated WASM artifacts that are identical across different build environments
2. Transparent Process: The runtime replacement is explicit and verifiable
3. Code-based Genesis: Initial state comes from the checked-out code, ensuring consistency
4. Auditability: The process is scripted and uses version-controlled artifacts

Genesis Verification Process

The verification process confirms that a running node's genesis runtime matches the published release artifacts. This is handled by the scripts/genesis_verification.sh script.

Prerequisites

• Running node with RPC access (must be archive node or have genesis state access)
• curl, jq, and xxd installed
• Knowledge of the release tag used to generate the genesis

Verification Steps

Step 1: Run Verification Script

Execute the verification script with the appropriate parameters:

./scripts/genesis_verification.sh --release-tag v0.X.Y-test-genesis --node-url http://localhost:9944

Optional parameters:

• --artifact-name: Specify exact WASM artifact name if multiple exist

Step 2: What the Script Does

The verification script performs the following steps:

1. Download Release Artifact

   • Queries GitHub API to find WASM artifacts ending in .compact.compressed.wasm
   • Downloads the artifact from the specified release tag from the Quantus-Network/chain-ru-test repository
   • If multiple artifacts exist, prompts for specific artifact name

2. Convert Artifact to Hex

   • Uses xxd -p to convert the downloaded WASM file to hexadecimal
   • Adds 0x prefix to match RPC response format

3. Query Genesis Runtime from Node

   • Critical: Queries the genesis block (0x0), not current state
   • Uses RPC call: state_getStorage with key :code (0x3a636f6465)
   • This retrieves the runtime WASM that was embedded in the genesis block

4. Compare WASM Strings

   • Performs byte-for-byte comparison of the hex strings
   • Displays beginning and end of each hex string for debugging
   • Generates SHA256 hashes for easier comparison if mismatch occurs

Step 3: Interpret Results

Success: If the hex strings match exactly, the verification confirms that:

• The node's genesis runtime is identical to the published release artifact
• The network was initialized with the expected runtime version

Failure: If there's a mismatch, possible causes include:

• Wrong release tag specified
• Genesis was generated from a different runtime version
• Node is not an archive node and lacks genesis state access
• Network corruption or tampering

Important Notes

1. Genesis vs Current State: This verification checks the genesis runtime, not the current network state. Runtime upgrades after genesis will not affect this verification.

2. Archive Node Requirement: The node must have access to genesis state. Full archive nodes or nodes with genesis state retention are required.

3. Deterministic Builds: The verification relies on srtool-generated artifacts being deterministic across build environments.

4. Repository: The scripts use the Quantus-Network/chain-ru-test repository for downloading artifacts.

Troubleshooting

Common Issues

1. "Node is not an archive node": Ensure your node has genesis state access
2. "Multiple WASM artifacts found": Use --artifact-name to specify the exact file
3. "Failed to download artifact": Verify release tag exists and contains WASM artifacts in the chain-ru-test repository
4. Hash mismatch: Check if the correct release tag was used for genesis generation

Debug Information

The verification script provides debug output including:

• First and last 60 characters of each hex string
• SHA256 hashes of both WASM versions
• HTTP status codes for download attempts
• RPC response validation