readiness.sh

Overview

`readiness.sh` is a lightweight Bash script designed to check the synchronization status of a local Ethereum beacon node daemon. It performs a health check by querying the node's HTTP API endpoint to determine if the node is fully synchronized with the Ethereum network. This script is typically used as a readiness probe in container orchestration environments (e.g., Kubernetes) or monitoring systems to ensure that the beacon node is ready to serve requests before routing traffic or triggering dependent services.

Detailed Explanation

Script Purpose

Check Node Sync Status: It queries the local Ethereum beacon node's HTTP API to retrieve synchronization status.
Output Result: Prints whether the daemon is synced or still syncing.
Exit Codes: Returns 0 if synced (indicating readiness), or 1 if still syncing or if an error occurs (indicating not ready).

Script Breakdown

#!/bin/bash

SYNCING=$(curl -sf http://localhost:3500/eth/v1/node/syncing) || exit 1
IS_SYNCING=$(echo "$SYNCING" | jq -r '.data.is_syncing')

if [[ $IS_SYNCING == false ]]; then
  echo "daemon-beacon is synced"
  exit 0
fi

echo "daemon-beacon is still syncing"
exit 1

Step-by-step Explanation

Step	Description
	Fetch Sync Status: Uses `curl` to silently (`-s`) fetch JSON data from `http://localhost:3500/eth/v1/node/syncing`. The `-f` flag causes `curl` to fail silently on server errors. If this request fails, the script exits immediately with code `1`.
	Parse JSON: Uses `jq` to extract the `.data.is_syncing` boolean field from the JSON response. This field indicates whether the node is currently syncing.
	Check Sync State: If `is_syncing` is `false`, meaning the node is fully synced, the script prints "daemon-beacon is synced" and exits with code `0`.
	Sync in Progress: Otherwise, prints "daemon-beacon is still syncing" and exits with code `1`.

Parameters and Return Values

This script does not accept any command-line parameters. It relies on the local beacon node API being accessible at `http://localhost:3500`.

Output / Exit Code	Meaning
Prints `"daemon-beacon is synced"` and exits with `0`	Beacon node is fully synchronized and ready.
Prints `"daemon-beacon is still syncing"` and exits with `1`	Beacon node is still syncing, not ready yet.
No output and exits with `1`	Failed to retrieve sync status (e.g., node down or API unreachable).

Usage Example

This script can be used in shell environments or integrated into container readiness probes.

# Run readiness check manually
./readiness.sh

# Example output when synced:
# daemon-beacon is synced

# Example output when still syncing:
# daemon-beacon is still syncing

Integration in Kubernetes Readiness Probe

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

Implementation Details and Algorithms

HTTP Status Handling: The use of curl -f ensures that HTTP errors (4xx or 5xx) cause immediate failure, preventing false positives.
JSON Parsing: The script relies on jq to parse the JSON response safely and extract the relevant boolean field.
Exit Code Semantics: Conforms to Unix conventions where 0 means success (ready) and non-zero means failure (not ready).

This simple polling algorithm provides an effective readiness check without complex state management or retries.

Interactions with Other System Components

Beacon Node: Queries the beacon node's REST API running locally on port 3500. This node must expose the /eth/v1/node/syncing endpoint.
Monitoring/Orchestration Tools: Used by container orchestrators (Kubernetes, Docker Swarm) or monitoring systems to decide when the beacon node is ready to serve traffic.
Dependencies: Requires curl and jq utilities installed and accessible in the environment where the script runs.

Mermaid Flowchart Diagram

flowchart TD
    A[Start] --> B{Call API: /eth/v1/node/syncing}
    B -- Success --> C[Parse JSON to get is_syncing]
    B -- Failure --> F[Exit 1: API unreachable or error]

    C --> D{is_syncing == false?}
    D -- Yes --> E[Print "daemon-beacon is synced"]
    D -- No --> G[Print "daemon-beacon is still syncing"]

    E --> H[Exit 0: Node ready]
    G --> F

Summary

`readiness.sh` is a concise and robust readiness check script tailored for Ethereum beacon nodes. It enables automated systems to detect when the node is fully synchronized and ready to handle workload, improving reliability and orchestration efficiency. Its minimal dependencies and straightforward logic make it easy to maintain and integrate into various deployment environments.

Step	Description
	Fetch Sync Status: Uses `curl` to silently (`-s`) fetch JSON data from `http://localhost:3500/eth/v1/node/syncing`. The `-f` flag causes `curl` to fail silently on server errors. If this request fails, the script exits immediately with code `1`.
	Parse JSON: Uses `jq` to extract the `.data.is_syncing` boolean field from the JSON response. This field indicates whether the node is currently syncing.
	Check Sync State: If `is_syncing` is `false`, meaning the node is fully synced, the script prints "daemon-beacon is synced" and exits with code `0`.
	Sync in Progress: Otherwise, prints "daemon-beacon is still syncing" and exits with code `1`.