readiness.sh

Overview

`readiness.sh` is a shell script designed to serve as a Kubernetes readiness probe for an Ethereum daemon node. Its primary purpose is to verify whether the Ethereum node running locally is fully synchronized with the Ethereum mainnet and ready to serve API requests.

The script performs a synchronization check by querying the local Ethereum node via JSON-RPC to determine if it is still syncing. If the node reports it is no longer syncing, the script fetches the current block height from the local node and cross-validates this against multiple external trusted Ethereum RPC endpoints ("reference nodes") to ensure the node's block height is within an acceptable tolerance of the network's latest block height. If all checks pass, the script exits with a success status (0), indicating readiness. Otherwise, it signals failure (exit 1).

This mechanism prevents Kubernetes from routing traffic to an out-of-sync node, thereby enhancing service reliability and data consistency.

Detailed Explanation

Script Workflow

  1. Disable Readiness Check via File Sentinel

    The script first checks for the existence of the file /data/disable_readiness.

    • If present, it immediately prints "readiness probe disabled" and exits with status 0 (success), effectively bypassing readiness checks.

    • This mechanism allows manual override during maintenance or debugging without disrupting the Kubernetes readiness lifecycle.

  2. Source External Utility Script

    It sources the script /evm.sh, which provides utility functions including get_best_reference_block_number and reference_validation. These functions are responsible for querying external reference nodes and validating block height synchronization.

  3. Set Block Height Tolerance

    Defines a tolerance threshold of 5 blocks (BLOCK_HEIGHT_TOLERANCE=5) which represents the maximum allowable lag behind the network's best block height before considering the node out of sync.

  4. Query Local Node Syncing Status

    Sends a JSON-RPC request to the local node's HTTP endpoint (http://localhost:8545) with the method eth_syncing.

    • The eth_syncing RPC method returns either false (not syncing) or an object describing syncing progress.

  5. Evaluate Syncing Status

    • If the node reports false (not syncing), the script proceeds to fetch the current block number from the local node by calling the eth_blockNumber RPC method.

    • Converts the returned hex block number to an integer.

  6. Fetch Best Reference Block Number

    Calls get_best_reference_block_number with three trusted Ethereum RPC endpoints:

    • https://ethereum.publicnode.com

    • https://eth-mainnet.g.alchemy.com/v2/demo

    • https://rpc.ankr.com/eth

    This function queries the block number from each endpoint and returns the highest (best) block number among them.

  7. Reference Validation

    Invokes reference_validation with parameters:

    • "daemon" to indicate the context.

    • Local node's current block number.

    • Best reference block number.

    • Block height tolerance.

    This function compares the local node's block number against the reference block height, considering the tolerance. If the local node falls outside the tolerance window, the validation fails.

  8. Exit Codes and Output

    • If all validation steps pass, the script prints "daemon is synced" and exits with 0.

    • If the node is still syncing or any command fails, it prints "daemon is still syncing" and exits with 1.

Functions and Methods

While the script itself does not declare explicit functions, it uses two key utility functions sourced from `/evm.sh`:

1. get_best_reference_block_number [URL1 URL2 URL3 ...]

2. reference_validation <context> <local_block_number> <reference_block_number> <tolerance>

Important Implementation Details

Interaction with Other System Components

Usage Example

This script is not intended to be executed manually in typical operations but is invoked automatically by Kubernetes. However, for testing, an operator could run:

./readiness.sh

Mermaid Diagram - Workflow of readiness.sh

flowchart TD
  Start[Start readiness.sh script] --> CheckDisable{Is /data/disable_readiness present?}
  CheckDisable -- Yes --> Disabled[Print "readiness probe disabled" & exit 0]
  CheckDisable -- No --> QuerySyncing[Send eth_syncing RPC to local node]
  QuerySyncing --> ParseSync[Parse syncing status from response]
  ParseSync -- "false" --> QueryBlockNum[Send eth_blockNumber RPC to local node]
  ParseSync -- not "false" --> Syncing[Print "daemon is still syncing" & exit 1]
  QueryBlockNum --> ParseBlockNum[Parse block number (hex to int)]
  ParseBlockNum --> GetReferenceBlocks[Call get_best_reference_block_number with external RPCs]
  GetReferenceBlocks --> ReferenceValidation[Call reference_validation]
  ReferenceValidation --> Validated{Is local block within tolerance?}
  Validated -- Yes --> Synced[Print "daemon is synced" & exit 0]
  Validated -- No --> NotSynced[Print "daemon is still syncing" & exit 1]

Summary

This script is a critical component in maintaining the health and availability of Ethereum daemon services within a containerized or orchestrated environment.