readiness.sh

Overview

`readiness.sh` is a Bash script designed as a readiness probe for a blockchain daemon node, specifically targeting an Ethereum-compatible node running locally (on `localhost:8545`). Its primary purpose is to determine whether the node is sufficiently synchronized and connected to peers to be considered "ready" for operation.

The script performs the following key checks:

• Detects if the readiness probe is disabled via a specific file flag.

• Queries the node’s syncing status and peer count via JSON-RPC calls.

• If synced, compares the node’s current block number against reference public blockchain nodes to validate synchronization within a given tolerance.

• Returns exit codes and messages indicating readiness status for use in orchestration platforms like Kubernetes.

This ensures that the node is not only synced locally but also in alignment with the broader blockchain network, preventing premature readiness signals.

Detailed Explanation

Constants and Variables

Script Logic Flow

1. Disable Check
   If the file /data/disable_readiness exists, the script immediately exits with status 0, indicating readiness probe is disabled.

2. Environment Setup
   Sources /evm.sh for environment variables or helper functions (expected to define functions such as get_best_reference_block_number and reference_validation).

3. Node Status Queries
   Uses curl to query local node JSON-RPC endpoints:

   • eth_syncing to check if the node is syncing.

   • net_peerCount to get the number of connected peers.

4. Readiness Decision

   • If syncing is false and there is at least one peer connected:

     • Retrieves the current block number from the local node.

     • Calls get_best_reference_block_number with a randomized choice of Binance Smart Chain public RPC nodes to get the highest block number among them.

     • Calls reference_validation to compare local block number and reference block number within tolerance.

     • Exits with 0 if checks pass.

   • If synced but no peers, exits with 1.

   • If syncing is still ongoing, exits with 1.

Functions and Methods

The script references two external functions that must be defined in `/evm.sh` or sourced elsewhere:

get_best_reference_block_number

• Purpose: Queries multiple reference public nodes to determine the highest current block number among them.

• Parameters: A list of URLs for public RPC nodes.

• Returns: The highest block number (integer) found across the reference nodes.

• Usage Example:

best_reference_block_number=$(get_best_reference_block_number https://node1 https://node2 https://node3)

reference_validation

• Purpose: Validates that the local node's block number is within an acceptable tolerance compared to a reference block number.

• Parameters:

  • daemon (string): Identifier for the node type or context.

  • current_block_number (int): Block number from the local node.

  • best_reference_block_number (int): Highest block number from reference nodes.

  • tolerance (int): Allowed difference in block height.

• Returns: None explicitly, but expected to exit or log error if validation fails.

• Usage Example:

reference_validation daemon 12345678 12345690 15

Important Implementation Details

• Disabling readiness probe: Allows external control to bypass readiness checks by creating a simple file at /data/disable_readiness.

• Randomized public node selection: To balance load across multiple public RPC endpoints, random indices are used to select one of four possible nodes per service provider.

• Use of JSON-RPC: The script interacts with Ethereum JSON-RPC API endpoints using curl with POST requests and parses JSON responses with jq.

• Exit codes:

  • 0 indicates the node is ready or the readiness probe is disabled.

  • 1 indicates the node is not ready due to syncing or lack of peers.

Interaction with Other System Components

• /evm.sh: This script relies on /evm.sh for utility functions (get_best_reference_block_number and reference_validation), which encapsulate the logic for comparing block numbers with reference nodes.

• Local Ethereum-compatible daemon: The script queries the local daemon via JSON-RPC on http://localhost:8545.

• Public RPC nodes: Uses external public RPC endpoints (Binance Smart Chain nodes) as references to validate the local node's synchronization status.

• Orchestrator / Container Platform: Typically invoked as a Kubernetes readiness probe or similar health check mechanism to control pod lifecycle based on node readiness.

Usage Example

# Run readiness check manually
./readiness.sh

# Output examples:
# readiness probe disabled
# daemon is synced, with 5 peers
# daemon is synced, but has no peers
# daemon is still syncing

Mermaid Flowchart Diagram

The following flowchart illustrates the main decision workflow of the `readiness.sh` script:

flowchart TD
    Start([Start])

    CheckDisable{File /data/disable_readiness exists?}
    ExitDisabled[echo "readiness probe disabled"\nexit 0]

    QuerySyncing[Query eth_syncing]
    QueryPeers[Query net_peerCount]

    IsSyncing{Syncing == false?}
    HasPeers{PeerCount > 0?}

    GetLocalBlock[Get local eth_blockNumber]
    GetReferenceBlock[Get best reference block number\n(from public nodes)]

    ValidateBlocks[reference_validation\n(local vs reference)]

    Ready[echo "daemon is synced, with $PEER_COUNT peers"\nexit 0]
    NoPeers[echo "daemon is synced, but has no peers"\nexit 1]
    Syncing[echo "daemon is still syncing"\nexit 1]

    ErrorExit1[exit 1 on curl failure]

    Start --> CheckDisable
    CheckDisable -- Yes --> ExitDisabled
    CheckDisable -- No --> QuerySyncing
    QuerySyncing -- Fail --> ErrorExit1
    QuerySyncing -- Success --> QueryPeers
    QueryPeers -- Fail --> ErrorExit1
    QueryPeers -- Success --> IsSyncing

    IsSyncing -- No --> Syncing
    IsSyncing -- Yes --> HasPeers
    HasPeers -- No --> NoPeers
    HasPeers -- Yes --> GetLocalBlock
    GetLocalBlock --> GetReferenceBlock
    GetReferenceBlock --> ValidateBlocks
    ValidateBlocks --> Ready

Summary

`readiness.sh` is a critical readiness probe script for an Ethereum-compatible blockchain node. It robustly checks the node's sync status and peer connectivity, validates synchronization against external reference nodes, and integrates with orchestration platforms to signal operational readiness. Its modular design, leveraging external utility scripts and public RPC endpoints, ensures accuracy and scalability within blockchain infrastructure deployments.