readiness.sh

Overview

`readiness.sh` is a Bash script designed to serve as a readiness probe for a blockchain node service, likely within a containerized or orchestrated environment (e.g., Kubernetes). Its primary function is to determine whether the blockchain node is fully synced and ready to handle requests by comparing the node's current block height against external reference nodes. This check helps prevent traffic routing to nodes that are still syncing and not yet up-to-date.

The script performs the following key tasks:

• Checks for a disable flag to bypass readiness checks.

• Queries the local Ethereum-compatible node for its syncing status and block number.

• Retrieves the best block number from external reference nodes.

• Validates if the local node’s block height is within an acceptable tolerance of the reference nodes.

• Exits with a status code indicating readiness (0) or not ready (1).

Detailed Explanations

Constants and Variables

• DISABLE_READINESS_PROBE
  File path (/data/disable_readiness) whose presence disables the readiness probe check.

• BLOCK_HEIGHT_TOLERANCE
  Integer value (15) defining the maximum allowable difference in block height between the local node and reference nodes to still consider the node "ready."

Script Workflow and Key Commands

1. Readiness Probe Disable Check

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

• If the file /data/disable_readiness exists, the script immediately exits with success (0), effectively disabling readiness checks.

• This allows manual override of readiness behavior.

2. Environment Setup

source /evm.sh

• Sources an external script /evm.sh which is expected to define helper functions, notably:

  • get_best_reference_block_number

  • reference_validation

*(Note: These functions are not defined within `readiness.sh`, so they must exist in `/evm.sh`.)*

3. Query Local Node Sync Status

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

• Sends a JSON-RPC request to the local node on port 8547 asking if the node is syncing (eth_syncing method).

• Parses the JSON response to extract the .result field.

• If the curl command fails, script exits with error (1).

4. If Node Is Not Syncing

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:8547) || 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://nova.arbitrum.io/rpc https://arbitrum-nova.publicnode.com)
  
  reference_validation daemon $current_block_number $best_reference_block_number $BLOCK_HEIGHT_TOLERANCE
fi

• If the node is not syncing (false), it fetches the current block number via the eth_blockNumber method.

• Converts the block number from hex to decimal.

• Calls get_best_reference_block_number passing two external RPC endpoints as references to get the highest block number reported by these nodes.

• Calls reference_validation with parameters:

  • daemon - possibly a mode or service name

  • current_block_number - local node’s block height

  • best_reference_block_number - highest external block height

  • BLOCK_HEIGHT_TOLERANCE - acceptable block height difference

• The reference_validation function likely checks if the local node’s height is within tolerance and exits accordingly.

5. If Node Is Still Syncing or Validation Fails

echo "daemon is still syncing"
exit 1

• If node is syncing or validation does not exit earlier, the script prints a message and exits with failure (1), signaling the node is not ready.

Functions and Methods

The script itself does not define its own functions but depends on the following functions presumed to exist in `/evm.sh`:

get_best_reference_block_number

• Purpose: Queries multiple external reference RPC endpoints to determine the highest block number available.

• Parameters: List of RPC URLs (e.g., https://nova.arbitrum.io/rpc https://arbitrum-nova.publicnode.com)

• Returns: The highest block number (decimal) among the provided references.

• Usage:

  best_reference_block_number=$(get_best_reference_block_number <rpc_url_1> <rpc_url_2> ...)
  

reference_validation

• Purpose: Validates the local node’s block height against the reference block height considering a tolerance.

• Parameters:

  1. Mode or service name (e.g., daemon)

  2. Local node block number (integer)

  3. Reference block number (integer)

  4. Block height tolerance (integer)

• Returns: Probably exits script with 0 if within tolerance, otherwise 1.

• Usage:

  reference_validation daemon $current_block_number $best_reference_block_number $BLOCK_HEIGHT_TOLERANCE
  

Important Implementation Details

• RPC Endpoint: The script assumes the Ethereum-compatible node's JSON-RPC interface is accessible at http://localhost:8547.

• JSON Handling: Uses jq to parse JSON responses.

• Hexadecimal to Decimal Conversion: Converts block number from hex string (e.g., 0x10d4f) to decimal using shell arithmetic.

• Tolerance Logic: The readiness depends not only on the local node reporting synced but also on how close its block height is compared to trusted external nodes.

• Fail-Fast: On any curl failure or inability to parse data, the script exits immediately with failure, indicating not ready.

• Disable Mechanism: Presence of /data/disable_readiness file disables readiness probing, useful for maintenance or manual override.

Interaction with Other Parts of the System

• /evm.sh: This file is a critical dependency providing helper functions. The readiness script cannot function properly without it.

• Ethereum-Compatible Node: The script queries a local blockchain node’s JSON-RPC interface for syncing state and block number.

• External Reference Nodes: Uses public RPC endpoints of Arbitrum Nova to validate local node sync status by cross-checking block heights.

• Container Orchestration / Monitoring: Typically used by Kubernetes or similar platforms as a readiness probe command to determine pod readiness for load balancing and lifecycle management.

Usage Example

If running manually, the script can be executed to check if the node is ready:

./readiness.sh

• Returns exit code 0 if ready.

• Returns exit code 1 if not ready or syncing.

• Prints readiness probe disabled if disabled.

Mermaid Flowchart Diagram

flowchart TD
    A[Start] --> B{Check disable file?}
    B -- Yes --> C[Print "readiness probe disabled"] --> D[Exit 0]
    B -- No --> E[Source /evm.sh]
    E --> F[Query local node eth_syncing]
    F --> G{Syncing?}
    G -- Yes --> H[Print "daemon is still syncing"] --> I[Exit 1]
    G -- No --> J[Query local node eth_blockNumber]
    J --> K[Get best reference block number]
    K --> L[Call reference_validation with local & ref blocks]
    L --> M{Validation result}
    M -- Pass --> N[Exit 0]
    M -- Fail --> H

Summary

`readiness.sh` is a critical utility script that determines the readiness of a blockchain node by verifying its sync status and block height against trusted reference nodes. It integrates tightly with external helper scripts and Ethereum-compatible RPC endpoints to provide a robust readiness check mechanism suitable for orchestrated environments. Its use of a disable flag and tolerance window provides flexibility and resilience in operational scenarios.