readiness.sh

Overview

`readiness.sh` is a Bash script designed to act as a Kubernetes readiness probe or a general health check for an Ethereum-compatible blockchain node daemon. Its primary purpose is to determine whether the local blockchain node is fully synchronized with the network and ready to serve requests.

The script performs the following key tasks:

• Checks if readiness probing is disabled by the presence of a specific file.

• Queries the local Ethereum node's JSON-RPC interface to determine synchronization status.

• If the node appears synced, cross-validates the node's current block height against trusted external reference nodes.

• Exits with a status code indicating whether the node is ready (exit 0) or still syncing (exit 1).

This script helps orchestrators like Kubernetes decide when to route traffic to the node or restart it if it is not yet ready.

Detailed Explanation

Variables

Script Workflow

1. Disable Check
   The script first checks if the file /data/disable_readiness exists.

   • If present, it prints "readiness probe disabled" and exits with status code 0, indicating readiness regardless of sync status.

2. Load Environment
   It sources /evm.sh which is assumed to contain environment variables or helper functions like get_best_reference_block_number and reference_validation.

   • These functions are critical for cross-checking block heights against reference nodes.

3. Check Sync Status
   It performs a JSON-RPC call to the local node at http://localhost:8545 with the eth_syncing method.

   • If the call fails, the script exits with code 1 (not ready).

   • If the node reports false, it means the node is not syncing and is considered fully synced.

4. Validate Block Height Against Reference Nodes
   When the node reports synced:

   • Retrieves the current block number from the node using eth_blockNumber JSON-RPC call.

   • Converts block number from hex to decimal.

   • Calls get_best_reference_block_number with URLs of external reference RPC endpoints to get the highest block height among them.

   • Calls reference_validation with parameters: "daemon", current block number, best reference block number, and the block height tolerance.

     • This validates the node is within an acceptable range of the reference block height.

     • If validation passes, the script prints "daemon is synced" and exits 0.

     • If validation fails, assumed to exit non-zero internally, causing readiness to fail.

5. Node Still Syncing
   If eth_syncing returns a syncing status (not false), the script prints "daemon is still syncing" and exits 1.

Functions / Methods

This script depends on external functions presumably defined in `/evm.sh`:

get_best_reference_block_number

**Purpose:** Queries multiple external blockchain RPC endpoints and returns the highest block number among them.

**Parameters:**

• List of RPC URLs (e.g., https://mainnet.base.org, https://base-rpc.publicnode.com, https://base.llamarpc.com)

**Returns:**

• The highest block number (integer) reported by the reference nodes.

**Usage Example:**

best_block=$(get_best_reference_block_number https://mainnet.base.org https://base-rpc.publicnode.com https://base.llamarpc.com)

reference_validation

**Purpose:** Validates that the local node's block number is within a specified tolerance of the reference block number.

**Parameters:**

• A string identifier (e.g., "daemon")

• Local node block number (integer)

• Reference best block number (integer)

• Block height tolerance (integer)

**Returns:**

• Exits with 0 if validation passes (within tolerance).

• Exits non-zero if validation fails.

**Usage Example:**

reference_validation daemon 1234567 1234590 25

Important Implementation Details

• Use of JSON-RPC:
  The script uses curl to send JSON-RPC POST requests to Ethereum node endpoints, specifically the eth_syncing and eth_blockNumber methods, which are standard Ethereum JSON-RPC calls.

• JSON Parsing with jq:
  The script uses jq to parse JSON responses and extract relevant fields.

• Block Height Tolerance:
  The script allows a block height tolerance of 25 blocks to account for minor delays or forks before marking the node as out of sync.

• Fail Fast on RPC failure:
  If any curl commands fail (node unreachable or RPC errors), the script exits immediately with a non-zero status, indicating readiness failure.

• Extensibility via /evm.sh:
  Core helper functions are abstracted out to /evm.sh, enabling reuse and separation of concerns.

Interaction with Other System Components

• Local Ethereum Node:
  The script queries the local node running on http://localhost:8545 to check syncing status and block number.

• External Reference Nodes:
  Uses external RPC endpoints (https://mainnet.base.org, https://base-rpc.publicnode.com, https://base.llamarpc.com) as references for block height validation.

• /evm.sh Script:
  Provides essential helper functions such as get_best_reference_block_number and reference_validation. This file must be present and sourced correctly for the script to function.

• Kubernetes or Container Orchestrator:
  Intended usage as a readiness probe script, informing the orchestrator whether the node pod/container is ready for traffic.

Usage Example

Run the script manually to check readiness:

./readiness.sh

# Possible outputs:
# readiness probe disabled
# daemon is synced
# daemon is still syncing

Exit code 0 indicates ready; exit code 1 indicates not ready.

Mermaid Diagram: Flowchart of Main Functions and Workflow

flowchart TD
    A[Start] --> B{Disable Readiness Probe?}
    B -- Yes --> C[Print "readiness probe disabled"] --> Z[Exit 0]
    B -- No --> D[Source /evm.sh]
    D --> E[Call eth_syncing RPC]
    E --> F{Is SYNCING == false?}
    F -- Yes --> G[Call eth_blockNumber RPC]
    G --> H[Get current block number]
    H --> I[get_best_reference_block_number with reference URLs]
    I --> J[reference_validation daemon current_block best_reference BLOCK_HEIGHT_TOLERANCE]
    J --> K[Print "daemon is synced"] --> Z
    F -- No --> L[Print "daemon is still syncing"] --> Y[Exit 1]
    E -- RPC fail --> Y
    G -- RPC fail --> Y

Summary

`readiness.sh` is a concise, robust readiness probe script tailored for Ethereum-compatible blockchain nodes. It smartly combines local node sync checks with cross-validation against external reliable nodes to ensure accurate readiness reporting. Its design supports disabling via a file flag and relies on external helper scripts for modularity. This script is essential for maintaining high availability and correctness in blockchain node deployments within containerized environments.