run.sh

Overview

`run.sh` is a robust shell script designed to bootstrap and launch a blockchain node daemon within a containerized environment, typically Kubernetes. It automates the node initialization, configuration, snapshot restoration, and runtime environment setup based on dynamic chain metadata and environment variables.

This script enables flexible deployment across multiple blockchain networks by dynamically fetching chain-specific parameters, managing peer configurations, handling genesis file setup, and accelerating node sync with snapshots. It also integrates optional features like Polkachu seed nodes and debug support, ensuring a seamless and reliable node lifecycle management.

Detailed Explanation

Script Purpose and Functionality

• Dynamically load blockchain chain metadata from a JSON endpoint (CHAIN_JSON).

• Extract crucial parameters such as chain ID, peers, genesis URL, daemon binary name, and node home directory.

• Set up environment variables and project directory paths.

• Configure peer seeds and persistent peers for P2P networking.

• Download and extract snapshot data for fast node synchronization.

• Initialize the blockchain node if not previously initialized, including genesis file download and extraction.

• Optionally overwrite peer seeds in the config file.

• Pre-seed priv_validator_state.json to prevent known Tendermint issues.

• Optionally integrate Polkachu seed nodes.

• Provide debugging aids.

• Finally, execute the blockchain daemon binary with passed arguments.

Implementation Details and Workflow

1. Dynamic Chain Metadata Loading

If the environment variable `CHAIN_JSON` is set, the script fetches the chain metadata JSON and extracts:

• CHAIN_ID — Unique identifier of the blockchain network.

• P2P_SEEDS — Comma-separated list of seed nodes for P2P discovery.

• P2P_PERSISTENT_PEERS — Comma-separated list of persistent peer nodes.

• GENESIS_URL — URL to download the genesis file.

• PROJECT_BIN — Name of the blockchain daemon executable.

• PROJECT_DIR — Node home directory path.

Extraction uses `jq` to parse JSON fields, supporting multiple fallback JSON paths to handle different metadata versions/formats.

2. Environment Variables and Paths Setup

• Defaults are set for PROJECT_BIN and PROJECT_DIR if not found in metadata.

• PROJECT_ROOT points to /root/$PROJECT_DIR, the node's root directory.

• CONFIG_PATH is set to $PROJECT_ROOT/config.

• NAMESPACE is the uppercase form of the daemon binary name, used as prefix for environment variables.

3. Chain ID Validation

The script exits immediately if `CHAIN_ID` is missing, as it is essential for node initialization.

4. Configuring Node Settings

• If MONIKER is set, exports it as ${NAMESPACE}_MONIKER.

• If MAX_NUM_OUTBOUND_PEERS is set, modifies config.toml to update this peer limit.

5. Snapshot Quick Sync Handling

When `SNAPSHOT_QUICKSYNC` is set and the private validator state file is missing, the script:

• Queries the snapshot index JSON to find a snapshot URL matching the chain ID and pruning strategy.

• Determines the snapshot compression format by inspecting the URL extension (tar.gz, tar.lz4, tar.zst, default tar).

• Downloads the snapshot with progress visualization (pv) and decompresses it accordingly.

• Moves extracted blockchain data and optionally WASM files into the correct directories.

• Removes old snapshot data directories to keep the environment clean.

6. Polkachu Seed Node Integration

If `P2P_POLKACHU` is enabled:

• Validates POLKACHU_NETWORK.

• Fetches Polkachu chain info via API.

• If Polkachu seed node service is active, appends Polkachu seed nodes to the existing peer seeds list.

7. Peer Seeds Environment Setup

Exports peer seeds and persistent peers as environment variables prefixed with the namespace (uppercase daemon name), ensuring proper usage by the daemon.

8. Chain Initialization

If the config directory does not exist:

• Runs the daemon binary's init command with the moniker and chain ID.

• Downloads the genesis file from GENESIS_URL.

• Detects compression format of the genesis file and decompresses it as needed (gzip, tar, zip).

• Moves the genesis file into the config directory.

9. Overwrite Seeds in Config

If `OVERWRITE_SEEDS` equals `1`, forcibly overwrites the seeds and persistent peers in the `config.toml` file to ensure the correct P2P configuration.

10. Preseed Private Validator State

Creates a minimal `priv_validator_state.json` file with initial height, round, and step if it does not exist—this avoids startup errors related to missing validator state.

11. Debugging Information

If `DEBUG` is set to `1`, prints all environment variables for troubleshooting.

12. Final Execution

Executes the blockchain daemon binary with all passed arguments (using `exec`), replacing the shell process with the daemon process.

Parameters and Usage

Usage Example

export CHAIN_JSON="https://example.com/chain-metadata.json"
export MONIKER="mynode"
export SNAPSHOT_QUICKSYNC="https://snapshots.example.com/index.json"
export MAX_NUM_OUTBOUND_PEERS=50
export DEBUG=1

./run.sh start

This example will:

• Fetch chain metadata from the given URL.

• Initialize the node with moniker mynode.

• Download and extract a quicksync snapshot if available.

• Configure maximum outbound peers.

• Print debugging information.

• Finally, run the daemon binary with the argument start.

Interaction with Other System Components

• Kubernetes
  This script is typically used as the container entrypoint (or within an entrypoint wrapper) in Kubernetes StatefulSets managing blockchain nodes. It ensures nodes are properly initialized before becoming ready.

• Daemon Binary
  The script invokes the blockchain daemon binary (e.g., gaiad, osmosisd) to perform initialization and finally to run the node.

• Snapshot Services
  It interacts with snapshot index services (JSON APIs) and snapshot archives to accelerate node synchronization.

• Polkachu API
  When Polkachu integration is enabled, it queries the Polkachu API to dynamically append seed nodes.

• Configuration Files
  The script modifies config.toml and places the genesis file in the config directory, directly affecting node network and genesis configuration.

Important Implementation Notes

• Error Handling
  The script uses set -e to exit immediately on any command failure, ensuring errors do not go unnoticed.

• Debug Support
  When DEBUG=2, shell tracing (set -x) is enabled for step-by-step command output.

• Idempotency
  Checks for existing config and data files prevent reinitialization and data overwrite on restarts.

• Snapshot Extraction
  Supports multiple compression formats transparently and uses pv for progress display.

• Priv Validator State Pre-seeding
  Prevents Tendermint startup errors by ensuring the existence of priv_validator_state.json.

• Use of Standard Tools
  Relies on ubiquitous UNIX tools (curl, jq, sed, tar, wget, pv) for portability.

Mermaid Diagram: Flowchart of Daemon Initialization and Startup Process

flowchart TD
  Start[Start Container / Script] --> LoadMetadata{Is CHAIN_JSON set?}
  LoadMetadata -- Yes --> FetchMetadata[Fetch Chain Metadata JSON]
  FetchMetadata --> ExtractConfig[Extract Chain ID, Peers, Genesis URL, etc.]
  LoadMetadata -- No --> SkipMetadata[Skip Metadata Loading]

  ExtractConfig --> CheckConfigDir{Config directory exists?}
  SkipMetadata --> CheckConfigDir

  CheckConfigDir -- No --> InitChain[Run daemon init with moniker and chain ID]
  InitChain --> DownloadGenesis{Is GENESIS_URL set?}
  CheckConfigDir -- Yes --> SkipInit[Skip Chain Initialization]
  SkipInit --> DownloadGenesis

  DownloadGenesis -- Yes --> DownloadAndExtract[Download & extract genesis file]
  DownloadGenesis -- No --> SkipGenesis[Skip Genesis Download]

  DownloadAndExtract --> ConfigurePeers[Set seeds and persistent peers in config.toml]
  SkipGenesis --> ConfigurePeers

  ConfigurePeers --> CheckSnapshot{Is SNAPSHOT_QUICKSYNC set?}
  CheckSnapshot -- Yes --> DownloadSnapshot[Download and extract snapshot]
  CheckSnapshot -- No --> SkipSnapshot[Skip Snapshot]

  DownloadSnapshot --> PreseedPrivVal[Preseed priv_validator_state.json if missing]
  SkipSnapshot --> PreseedPrivVal

  PreseedPrivVal --> PolkachuCheck{Is P2P_POLKACHU enabled?}
  PolkachuCheck -- Yes --> PolkachuFetch[Fetch Polkachu seed nodes and append]
  PolkachuCheck -- No --> SkipPolkachu[Skip Polkachu Integration]

  PolkachuFetch --> ExecuteDaemon[Execute daemon binary with arguments]
  SkipPolkachu --> ExecuteDaemon

  ExecuteDaemon --> End[Daemon Running]

Summary

The `run.sh` script is a critical infrastructure component facilitating automated, flexible, and reliable blockchain node deployment. It abstracts complex initialization workflows, dynamically configures node parameters from metadata, manages fast synchronization via snapshots, and integrates with external services such as Polkachu. Its design emphasizes idempotency, portability, and seamless integration with container orchestration platforms, making it a foundational piece in the system's operational lifecycle.