readiness.sh

Overview

`readiness.sh` is a Bash script designed to serve as a readiness probe for a blockchain node daemon—specifically, an Avalanche C-Chain node. The script determines if the node is ready to serve traffic by checking its synchronization status and network connectivity. It performs several checks including:

Whether readiness probing is disabled.
Node syncing status via JSON-RPC.
Number of connected peers.
Current block height compared against trusted reference nodes to ensure the node is sufficiently up-to-date.

Based on these checks, the script exits with appropriate status codes indicating readiness (exit 0) or unavailability (exit 1).

Detailed Explanation

Variables

Variable	Description
`DISABLE_READINESS_PROBE`	Path to a file that, if present, disables readiness checking (`/data/disable_readiness`).
`BLOCK_HEIGHT_TOLERANCE`	Allowed difference in block height between the node and reference nodes (default: 5).

Script Workflow and Commands

Disable readiness probe check
```
if [[ -f "$DISABLE_READINESS_PROBE" ]]; then
  echo "readiness probe disabled"
  exit 0
fi
```
- If the file /data/disable_readiness exists, the script prints a message and immediately exits with success.
- This allows manual override to disable readiness checks.
Source environment variables
```
source /evm.sh
```
- Sources external script /evm.sh which presumably sets necessary environment variables or functions (e.g., get_best_reference_block_number and reference_validation).
- Note: The definitions of these functions are external and expected to be available.

Retrieve syncing status and peers info

ETH_SYNCING=$(curl -sf -d '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' -H 'Content-Type:application/json;' http://localhost:9650/ext/bc/C/rpc) || exit 1
INFO_PEERS=$(curl -sf -d '{"jsonrpc":"2.0","method":"info.peers","params":[],"id":1}' -H 'Content-Type:application/json;' http://localhost:9650/ext/info) || exit 1

Uses curl to send JSON-RPC requests to local Avalanche node endpoints.
eth_syncing returns syncing status (false if fully synced).
info.peers returns info about connected peers, including peer count.

Parse results
```
SYNCING=$(echo $ETH_SYNCING | jq -r '.result')
NUM_PEERS=$(echo $INFO_PEERS | jq -r '.result.numPeers')
```
- Parses JSON responses using jq to extract:
  - SYNCING: boolean or syncing info.
  - NUM_PEERS: number of connected peers.
Logic based on syncing and peer status
- If the node is not syncing (SYNCING == false) and has peers:
  - Fetch current block number from the node:
```
eth_blockNumber=$(curl -sf -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' -H 'Content-Type: application/json' http://localhost:9650/ext/bc/C/rpc) || exit 1
current_block_number_hex=$(echo $eth_blockNumber | jq -r '.result')
current_block_number=$(($current_block_number_hex))
```
    - Block number is returned as a hexadecimal string and converted to decimal.
  - Fetch the highest block number from trusted public Avalanche C-Chain RPC endpoints:
```
best_reference_block_number=$(get_best_reference_block_number https://api.avax.network/ext/bc/C/rpc https://avalanche-c-chain.publicnode.com https://avalanche.public-rpc.com)
```
    - get_best_reference_block_number is an external function expected to query the given RPCs and return the highest block height.
  - Validate the node's block height against the best reference with tolerance:
```
reference_validation daemon $current_block_number $best_reference_block_number $BLOCK_HEIGHT_TOLERANCE
```
    - reference_validation checks if the node's block number is within BLOCK_HEIGHT_TOLERANCE of the reference block number.
    - Exits with failure if validation fails.
  - If all checks pass, print readiness success:
```
echo "daemon is synced, with $NUM_PEERS peers"
exit 0
```
- If the node is synced but has no peers:
```
echo "daemon is synced, but has no peers"
exit 1
```
- If still syncing:
```
echo "daemon is still syncing"
exit 1
```

Important Implementation Details

Use of JSON-RPC: The script communicates with the Avalanche node using JSON-RPC over HTTP to query the node status and blockchain information.
Peer and Sync status: The script relies on both syncing status and the number of peers to determine readiness, ensuring the node is connected and caught up.
Block height validation: To prevent false positives where a node reports synced but is behind the network, it compares the local block height against a set of reliable public RPC endpoints.
External dependencies:
- jq for JSON parsing.
- Functions get_best_reference_block_number and reference_validation sourced from /evm.sh.
- curl for HTTP requests.
Exit codes:
- 0 indicates readiness.
- 1 indicates not ready or an error.

Interaction with Other System Components

/evm.sh script: This file must be present and provide key functions used for reference block number retrieval and validation.
Avalanche node: The script queries the local Avalanche C-Chain node's RPC endpoints at localhost:9650.
External RPC endpoints: Trusted Avalanche public RPC URLs are used for cross-validation.
Container or orchestration system: This script is intended to be used as a readiness probe, typically in container orchestration environments (e.g., Kubernetes), to determine if the node pod/container is ready to receive traffic.

Usage Example

This script is usually run by the container orchestration platform as a readiness probe:

./readiness.sh

If the script exits with status 0, the node is ready.
If it exits with status 1, the node is not ready.

A manual override can be done by creating the disable file:

touch /data/disable_readiness
./readiness.sh
# Output: readiness probe disabled
# Exit code: 0

Mermaid Flowchart Diagram

flowchart TD
    A[Start] --> B{File /data/disable_readiness exists?}
    B -- Yes --> C[Print "readiness probe disabled"]
    C --> D[Exit 0]
    B -- No --> E[Source /evm.sh]
    E --> F[Query eth_syncing via JSON-RPC]
    F --> G[Query info.peers via JSON-RPC]
    G --> H[Parse SYNCING and NUM_PEERS]
    H --> I{SYNCING == false?}
    I -- No --> J[Print "daemon is still syncing"]
    J --> K[Exit 1]
    I -- Yes --> L{NUM_PEERS > 0?}
    L -- No --> M[Print "daemon is synced, but has no peers"]
    M --> K
    L -- Yes --> N[Query eth_blockNumber]
    N --> O[Convert block number hex to decimal]
    O --> P[get_best_reference_block_number from public RPCs]
    P --> Q[reference_validation (local vs reference block number)]
    Q --> R[Print "daemon is synced, with NUM_PEERS peers"]
    R --> D

Summary

The `readiness.sh` script is a critical health check utility that verifies an Avalanche C-Chain node's readiness by combining syncing status, peer connectivity, and block height validation against trusted sources. It is designed for use in production environments to ensure that only healthy and synchronized nodes are marked ready for service. The script is modular and extensible by sourcing external functions from `/evm.sh`, allowing for maintainability and flexibility.