evm.sh

Overview

[evm.sh](/projects/291/69100) is a Bash script utility designed to assist in Ethereum blockchain node synchronization validation. Its primary purpose is to compare the latest block numbers reported by multiple reference Ethereum nodes (via JSON-RPC calls) and determine the "best" or highest block number among them. Additionally, it validates whether a given service's current block height is synchronized within a specified tolerance relative to this best reference block number.

This script is useful in blockchain environments where multiple nodes or services need to be monitored for sync status against reliable reference nodes to ensure data consistency and network health.

Functions

1. get_best_reference_block_number()

Purpose

Queries multiple Ethereum JSON-RPC endpoints to fetch their latest block numbers (`eth_blockNumber`) and returns the highest block number found among them.

Parameters

• Accepts a variable number of Ethereum JSON-RPC URLs as positional parameters ($@).

Behavior

• For each provided URL, the function:

  • Sends a JSON-RPC POST request to retrieve the latest block number.

  • Parses the JSON response using jq to extract the block number (in hexadecimal).

  • Converts the hexadecimal block number to decimal.

  • Keeps track of the highest block number found.

• Returns (echoes) the highest block number (decimal) after checking all references.

Return Value

• Outputs the highest block number (integer) found across all given URLs.

• If no valid block numbers are retrieved, returns 0.

Usage Example

best_block=$(get_best_reference_block_number "http://node1:8545" "http://node2:8545")
echo "Highest block among references: $best_block"

2. reference_validation()

Purpose

Validates if a given service/node's current block number is synchronized within an acceptable block height tolerance relative to the best reference block number.

Parameters

Behavior

• Checks if the best reference block number is greater than zero (i.e., valid).

• Computes a nominal block number by subtracting the tolerance from the best reference block number.

• Compares the current block number against the nominal value.

  • If current block number is greater than or equal to nominal block number:

    • Prints a success message that the service is synced within tolerance.

    • Exits with status code 0 (success).

  • Otherwise:

    • Prints a warning that the service is synced but outside the tolerance.

    • Exits with status code 1 (failure).

• If the best reference block number is zero or invalid, the function does nothing (returns silently).

Return Value

• Prints a status message to stdout.

• Exits the script with 0 (success) or 1 (failure) based on the sync validation.

Usage Example

reference_validation "my-eth-node" 1234567 1234570 5
# Output: my-eth-node is synced within block height tolerance of reference node

Implementation Details and Algorithms

• Block Number Retrieval: Uses curl to perform a JSON-RPC POST request to each reference node's endpoint with the eth_blockNumber method. The response is parsed with jq to extract the block number in hex format.

• Hexadecimal to Decimal Conversion: The hex block number string is converted to decimal using Bash arithmetic ($(($current_block_number_hex))).

• Best Block Selection: Iterates over all provided nodes and continuously updates the best block number if a higher number is found.

• Tolerance Validation: The tolerance parameter allows defining how many blocks behind the best reference a service can be while still considered "in sync." This is critical for scenarios where some lag is acceptable due to network or processing delays.

Interaction with Other Parts of the System

• This script is likely invoked by monitoring or orchestration tools that manage Ethereum node health.

• It interacts with external Ethereum nodes via JSON-RPC endpoints to fetch real-time blockchain data.

• The output and exit codes from reference_validation can be used by higher-level scripts or system monitors to trigger alerts, logs, or automated remediation.

• Does not depend on other scripts in the project but requires jq and curl installed on the system.

• Could be integrated into CI/CD pipelines or monitoring dashboards for blockchain infrastructure.

Visual Diagram

flowchart TD
    A[Start: Input Ethereum JSON-RPC URLs] --> B[get_best_reference_block_number]
    B --> C{For each URL}
    C -->|Send JSON-RPC eth_blockNumber| D[curl POST Request]
    D --> E[Parse JSON response with jq]
    E --> F[Extract and convert block number to decimal]
    F --> G{Is current block number > best_reference_block_number?}
    G -- Yes --> H[Update best_reference_block_number]
    G -- No --> I[Keep current best_reference_block_number]
    H --> C
    I --> C
    C --> J[Return best_reference_block_number]

    J --> K[reference_validation]
    K --> L[Calculate nominal_block_number = best_reference_block_number - tolerance]
    L --> M{Is current_block_number >= nominal_block_number?}
    M -- Yes --> N[Print synced within tolerance; Exit 0]
    M -- No --> O[Print synced but outside tolerance; Exit 1]

Summary

The [evm.sh](/projects/291/69100) script is a lightweight and effective tool for Ethereum node synchronization validation purposes. It leverages standard CLI tools (`curl`, `jq`) to communicate with Ethereum nodes and perform block height comparisons, providing clear feedback on synchronization status relative to reference nodes. This makes it valuable for operational monitoring and ensuring Ethereum infrastructure reliability.