readiness.sh

Overview

`readiness.sh` is a Bash script designed to serve as a readiness probe for an **Optimism Layer 2 (L2) Ethereum scaling solution node** (`op-node`). Its primary function is to determine whether the node is fully synced and ready to serve traffic or still in the process of synchronizing.

This script is intended to be used in containerized or orchestrated environments (like Kubernetes), where readiness probes dictate whether the node should receive traffic. It performs the following key checks:

Detailed Explanation

Constants and Variables

Script Workflow and Logic

  1. Check for disable file:
    If /data/disable_readiness file exists, print "readiness probe disabled" and exit with code 0 (ready).

  2. Load environment variables and utility functions:
    Sources /evm.sh, assumed to contain utility functions (get_best_reference_block_number, reference_validation) and environment variables (e.g., L1_RPC_ENDPOINT).

  3. Query sync status:
    Uses curl to send a JSON-RPC request to http://localhost:9545 with method optimism_syncStatus to retrieve sync status JSON.

  4. Parse queued unsafe L2 block height:
    Extracts .result.queued_unsafe_l2.number from the JSON response using jq.

  5. Evaluate sync status:

    • If QUEUED_UNSAFE_L2_HEIGHT == 0, i.e., no blocks are queued unsafe, the node is nearly or fully synced.

    • Retrieves the current L1 block number from .result.current_l1.number.

    • Calls get_best_reference_block_number with multiple L1 RPC endpoints to determine the best current L1 block number.

    • Calls reference_validation with op-node, current L1 block number, best reference block number, and tolerance to validate sync status.

    • If validation passes, echo "op-node is synced" and exit 0.

  6. If queued unsafe blocks exist:
    The node is still syncing; echo "op-node is still syncing" and exit with code 1.

Functions and External Calls

This script depends on functions and variables defined in `/evm.sh`:

get_best_reference_block_number

reference_validation

Usage Example

To manually run the readiness check, execute:

./readiness.sh

This script is designed to be integrated as a readiness probe script in container orchestrators (e.g., Kubernetes):

readinessProbe:
  exec:
    command:
    - /bin/bash
    - /path/to/readiness.sh
  initialDelaySeconds: 10
  periodSeconds: 30

Implementation Details and Algorithms

Interaction with Other Components

Visual Diagram

The following flowchart illustrates the main functional flow of `readiness.sh`:

flowchart TD
    A[Start] --> B{Is disable file present?}
    B -- Yes --> C[Print "readiness probe disabled"]
    C --> D[Exit 0]
    B -- No --> E[Source /evm.sh]
    E --> F[Query sync status from op-node]
    F --> G[Parse queued_unsafe_l2.number]
    G --> H{Is queued_unsafe_l2.number == 0?}
    H -- No --> I[Print "op-node is still syncing"]
    I --> J[Exit 1]
    H -- Yes --> K[Get current_l1_block_number]
    K --> L[Get best_reference_block_number from L1 endpoints]
    L --> M[Call reference_validation with tolerance]
    M --> N[Print "op-node is synced"]
    N --> D

Summary

`readiness.sh` is a critical utility script for assessing the readiness of an Optimism L2 node by checking sync status via JSON-RPC. It performs smart validation by comparing the node’s sync state with trusted L1 references and includes a disable mechanism for operational flexibility. The script integrates tightly with the environment via `/evm.sh` and external L1 RPC services, making it a robust component in the deployment and orchestration of Optimism nodes.