tendermint.sh

Overview

`tendermint.sh` is a Bash utility script designed to assist in monitoring and validating the synchronization status of a Tendermint-based blockchain daemon relative to a set of reference nodes. Its primary purpose is to query multiple reference nodes for their latest block heights, determine the best (highest) block height among them, and validate whether the local daemon is sufficiently synced within a configurable tolerance.

This script facilitates automated health checks or monitoring workflows by providing key functions that interact with Tendermint nodes’ REST API endpoints (typically exposed on `/status`) and process their JSON status responses.

Detailed Description of Functions

1. get_best_reference_block_height

**Purpose:** Fetches the latest block height from multiple reference Tendermint node URLs and returns the highest block height found.

**Signature:**

get_best_reference_block_height <reference_node_url_1> [<reference_node_url_2> ...]

**Parameters:**

• $@ (list of strings): One or more Tendermint node base URLs (e.g., http://node1:26657), each expected to respond to the /status endpoint.

**Returns:**

• Prints the highest/latest block height (integer) observed among the given reference nodes, or 0 if none respond.

**Implementation Details:**

• Iterates over each URL.

• Uses curl with silent mode, fail-fast, and a 3-second timeout to fetch the JSON status from ${reference_url}/status.

• Parses the JSON using jq to extract .result.sync_info.latest_block_height.

• Compares and stores the maximum block height found.

• Outputs the maximum block height at the end.

**Usage Example:**

best_height=$(get_best_reference_block_height http://node1:26657 http://node2:26657)
echo "Best reference block height is $best_height"

2. get_best_reference_block_height_eval

**Purpose:** Similar to `get_best_reference_block_height`, but instead of URLs, it accepts shell commands (typically `curl` commands) as arguments, evaluates them, and extracts the best block height from their outputs.

**Signature:**

get_best_reference_block_height_eval <status_curl_command_1> [<status_curl_command_2> ...]

**Parameters:**

• $@ (list of strings): Each argument is a shell command string expected to output the JSON status of a Tendermint node (e.g., curl -sf -m 3 http://node1:26657/status).

**Returns:**

• Prints the highest/latest block height (integer) extracted from the evaluated commands’ output, or 0 if none produce valid output.

**Implementation Details:**

• Iterates over each command string.

• Uses eval to execute the command and capture its output.

• Parses output with jq for .result.sync_info.latest_block_height.

• Tracks the maximum block height.

• Outputs the maximum block height at the end.

**Usage Example:**

best_height=$(get_best_reference_block_height_eval "curl -sf -m 3 http://node1:26657/status" "curl -sf -m 3 http://node2:26657/status")
echo "Best reference block height via eval is $best_height"

3. reference_validation

**Purpose:** Validates whether a local Tendermint daemon’s block height is sufficiently synced compared to the best reference block height, considering a tolerance value.

**Signature:**

reference_validation <latest_block_height> <best_reference_block_height> <block_height_tolerance>

**Parameters:**

• latest_block_height (integer): The local daemon’s current block height.

• best_reference_block_height (integer): The highest block height obtained from reference nodes.

• block_height_tolerance (integer): The acceptable block height difference tolerance.

**Returns:**

• Prints a descriptive message about the sync status.

• Exits with status:

  • 0 if the daemon is synced and within tolerance.

  • 1 if synced but outside tolerance.

  • No explicit handling if best_reference_block_height ≤ 0 (no output or exit code).

**Implementation Details:**

• Calculates nominal_block_height = best_reference_block_height - block_height_tolerance.

• Checks if latest_block_height >= nominal_block_height.

• If yes, prints sync confirmation and exits 0.

• Otherwise, prints warning about tolerance breach and exits 1.

**Usage Example:**

reference_validation 12345 12350 5

Output:

daemon is synced and within block height tolerance of reference node

or

daemon is synced, but not within block height tolerance of reference node

Important Implementation Details

• The script relies on curl for HTTP requests and jq for JSON parsing; both must be installed and available on the system.

• Network timeouts in curl are set to 3 seconds to avoid long waits.

• The script uses Bash arithmetic and string comparisons carefully to ensure numeric correctness.

• It does not handle authentication or complex error handling beyond basic connectivity and JSON presence checks.

• The use of eval in get_best_reference_block_height_eval requires careful input control to avoid command injection risks.

Interaction with Other System Components

• This script is typically invoked by monitoring or orchestration components to verify Tendermint daemon synchronization.

• It interacts directly with Tendermint nodes through their REST API endpoints, typically exposed on port 26657 by default.

• The output of this script can be integrated into CI/CD pipelines, systemd health checks, or custom monitoring dashboards.

• It expects external tools curl and jq to parse node statuses.

• It serves as a utility helper and can be sourced or executed standalone in larger automation workflows handling blockchain node management.

Visual Diagram: Flowchart of Main Functions and Workflow

flowchart TD
    Start["Start"]
    GetBestRefBLH[get_best_reference_block_height()]
    GetBestRefBLHEval[get_best_reference_block_height_eval()]
    ReferenceValidation[reference_validation()]
    OutputBestHeight["Output best block height"]
    EvalCmds["Evaluate shell commands"]
    CurlStatus["Curl /status for each reference URL"]
    ParseJSON["Parse JSON for latest_block_height"]
    CompareHeights["Compare & store max block height"]
    CalculateNominal["Calculate nominal_block_height = best - tolerance"]
    CheckSync["Check if local height >= nominal"]
    ExitSuccess["Exit 0 (synced & within tolerance)"]
    ExitWarning["Exit 1 (synced but outside tolerance)"]

    Start --> GetBestRefBLH --> CurlStatus --> ParseJSON --> CompareHeights --> OutputBestHeight
    Start --> GetBestRefBLHEval --> EvalCmds --> ParseJSON --> CompareHeights --> OutputBestHeight
    OutputBestHeight --> ReferenceValidation --> CalculateNominal --> CheckSync
    CheckSync -- Yes --> ExitSuccess
    CheckSync -- No --> ExitWarning

Summary

The `tendermint.sh` script provides essential utilities for assessing the sync state of a Tendermint daemon by querying multiple reference nodes. Its functions enable robust, automated detection of synchronization status while considering tolerance thresholds, making it a valuable tool in blockchain node operations and monitoring toolchains.