readiness.sh

Overview

`readiness.sh` is a shell script acting as a **readiness probe** for an Ethereum Virtual Machine (EVM)-based blockchain node daemon, specifically tailored for Optimism in this instance. Its primary role is to verify if the node is fully synchronized with the blockchain network and ready to serve traffic.

The script:

• Checks if readiness probing is temporarily disabled via a file flag.

• Queries the local node's synchronization status using JSON-RPC calls (eth_syncing and eth_blockNumber).

• Obtains block heights from multiple external reference nodes to validate the local node's reported block height.

• Compares the local node's block height against the best external reference, considering a configurable block height tolerance.

• Exits with 0 if the node is considered ready (synced), or 1 if not.

This readiness check is commonly integrated into Kubernetes pod specifications as a readiness probe, enabling Kubernetes to determine when the node can properly receive traffic.

Detailed Explanation

Variables and Constants

• DISABLE_READINESS_PROBE
  Path to a file (/data/disable_readiness) that, if present, disables readiness checking. This is a manual override mechanism for maintenance or debugging.

• BLOCK_HEIGHT_TOLERANCE
  Numeric tolerance for block height difference between local node and reference nodes (set to 25 in this script). This accounts for minor lag or network delays.

Execution Flow

1. Disable Probe Check

   if [[ -f "$DISABLE_READINESS_PROBE" ]]; then
     echo "readiness probe disabled"
     exit 0
   fi
   

   If the disable file exists, the script immediately exits with status 0, signaling readiness is forcibly granted.

2. Source Utility Script

   source /evm.sh
   

   Imports shared functions (e.g., get_best_reference_block_number and reference_validation) used for EVM chains, enabling code reuse and consistency.

3. Set Block Height Tolerance

   BLOCK_HEIGHT_TOLERANCE=25
   

   Defines how many blocks behind the node can be compared to reference nodes before being considered out of sync.

4. Check Node Sync Status

   ETH_SYNCING=$(curl -sf -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
   -H 'Content-Type: application/json' http://localhost:8545) || exit 1
   SYNCING=$(echo $ETH_SYNCING | jq -r '.result')
   

   Calls the Ethereum JSON-RPC eth_syncing method.

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

   • The .result field is extracted:

     • false means node is synced.

     • Otherwise, node is still syncing.

5. If Node Synced, Validate Block Height Against Reference Nodes

   if [[ $SYNCING == false ]]; then
     eth_blockNumber=$(curl -sf -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
     -H 'Content-Type: application/json' http://localhost:8545) || exit 1
     current_block_number_hex=$(echo $eth_blockNumber | jq -r '.result')
     current_block_number=$(($current_block_number_hex))
   
     best_reference_block_number=$(get_best_reference_block_number https://mainnet.optimism.io https://optimism.publicnode.com https://opt-mainnet.g.alchemy.com/v2/demo)
   
     reference_validation daemon $current_block_number $best_reference_block_number $BLOCK_HEIGHT_TOLERANCE
   
     echo "daemon is synced"
     exit 0
   fi
   

   • Queries local node's current block number (eth_blockNumber returns hex).

   • Converts hex block number to decimal.

   • Calls get_best_reference_block_number with 3 public Optimism RPC endpoints to fetch the highest observed block number.

   • Runs reference_validation function to compare local and reference block numbers within the allowed tolerance.

   • If validation passes, outputs "daemon is synced" and exits with 0 (ready).

   • If any call fails or validation fails, the script exits with 1.

6. If Node Still Syncing

   echo "daemon is still syncing"
   exit 1
   

   Indicates the node is not ready yet, so the readiness probe fails.

Functions and Methods (from /evm.sh)

This script sources `/evm.sh`, which provides key functions:

• get_best_reference_block_number <url1> <url2> ...
  Queries multiple public RPC endpoints and returns the highest block number reported. This guards against false positives by relying on multiple reference nodes.

• reference_validation <context> <local_block> <reference_block> <tolerance>
  Compares local block height to the reference block height, allowing for the configured tolerance. Exits with failure if the difference exceeds tolerance.

Note: The script assumes `/evm.sh` is present and correctly implemented.

Usage Example

A Kubernetes pod spec for an Optimism node container may include:

readinessProbe:
  exec:
    command:
    - /bin/bash
    - /path/to/readiness.sh
  initialDelaySeconds: 10
  periodSeconds: 15
  failureThreshold: 3

This configuration runs `readiness.sh` periodically to verify the node readiness before routing traffic.

Important Implementation Details

• Fail-Fast Behavior:
  The script exits immediately with non-zero on any critical failure (e.g., RPC call failure), ensuring Kubernetes detects unready states promptly.

• Block Height Parsing:
  Ethereum JSON-RPC returns block number in hexadecimal (e.g., 0x12ab). The script converts it to decimal using shell arithmetic.

• Reference Node Validation:
  Reliance on trusted public RPC endpoints reduces risk of false readiness signals due to local node issues or network partitions.

• Disable File Mechanism:
  The presence of /data/disable_readiness allows operators to bypass readiness checks without redeployment, facilitating maintenance.

• Minimal Dependencies:
  Uses standard Linux tools: curl for HTTP requests, jq for JSON parsing, and shell built-ins.

Interaction with Other Components

• Kubernetes:
  The script is invoked by Kubernetes readiness probes to manage pod readiness lifecycle.

• Local Node Daemon:
  Communicates with the local blockchain node via JSON-RPC HTTP endpoint (http://localhost:8545).

• External Reference Nodes:
  Queries multiple public RPC endpoints for block height validation.

• Utility Script /evm.sh:
  Provides shared functions for EVM blockchain probes.

Mermaid Flowchart: readiness.sh Workflow

flowchart TD
    Start[Start Script] --> CheckDisableFile{Does /data/disable_readiness exist?}
    CheckDisableFile -- Yes --> DisabledExit[Print "readiness probe disabled"\nExit 0]
    CheckDisableFile -- No --> QueryEthSyncing[Query eth_syncing RPC]
    QueryEthSyncing --> SyncingResult{.result == false?}
    SyncingResult -- No --> SyncingExit[Print "daemon is still syncing"\nExit 1]
    SyncingResult -- Yes --> QueryBlockNumber[Query eth_blockNumber RPC]
    QueryBlockNumber --> ConvertHex[Convert hex block number to decimal]
    ConvertHex --> GetReference[Call get_best_reference_block_number with public RPCs]
    GetReference --> ValidateReference[Call reference_validation with local & reference blocks]
    ValidateReference --> ValidationResult{Validation Passed?}
    ValidationResult -- No --> ValidationFail[Exit 1]
    ValidationResult -- Yes --> SuccessExit[Print "daemon is synced"\nExit 0]

This flowchart illustrates the decision points and main operations of the `readiness.sh` script.

Summary

`readiness.sh` is a robust readiness probe script designed to ensure an Optimism node daemon is fully synchronized and ready to serve client requests. It employs a combination of local node status checks and external reference validation with configurable tolerances, integrates with Kubernetes health probes, and supports operational flexibility via a disable flag. Its reliance on shared utility functions (`/evm.sh`) promotes maintainability and consistency across EVM chain probes.

End of documentation for readiness.sh