readiness.sh

Overview

`readiness.sh` is a Bash script designed to act as a readiness probe for an Ethereum Layer 2 node (specifically an Optimism "op-node"). In Kubernetes or containerized environments, readiness probes are used to determine if a service is ready to receive traffic.

This script checks whether the `op-node` is fully synced with the Ethereum mainnet by:

Optionally disabling the readiness probe based on a file flag.
Querying the node's sync status via JSON-RPC.
Validating that the node's synced block heights meet a defined tolerance.
Reporting readiness status accordingly.

If the node is synchronized within acceptable thresholds, the script exits successfully (exit code 0), indicating readiness. Otherwise, it exits with failure (exit code 1), signaling the node is still syncing.

Detailed Explanation

Constants and Variables

Name	Purpose
`DISABLE_READINESS_PROBE`	File path `/data/disable_readiness` used to disable the readiness check if present.
`BLOCK_HEIGHT_TOLERANCE`	Numeric value `5` defining acceptable block height difference tolerance.
`SYNC_STATUS`	Holds JSON response from querying the node's sync status via JSON-RPC call.
`QUEUED_UNSAFE_L2_HEIGHT`	Extracted block number representing the "queued unsafe" L2 block height.

Script Workflow

Disable Readiness 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 successfully, effectively disabling the readiness check. This can be used for maintenance or troubleshooting.
Load Environment:
```
source /evm.sh
```
Sources environment variables and functions from /evm.sh. This file likely defines necessary utilities such as get_best_reference_block_number and variables like $L1_RPC_ENDPOINT.

Fetch Sync Status:

SYNC_STATUS=$(curl -s -d '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' -H 'Content-Type: application/json' http://localhost:9545)

Sends a JSON-RPC request to the local op-node on port 9545 requesting the current synchronization status.

Parse L2 Block Height:
```
QUEUED_UNSAFE_L2_HEIGHT=$(echo $SYNC_STATUS | jq -r .result.queued_unsafe_l2.number)
```
Extracts the block number of the "queued unsafe" L2 block from the sync status JSON response using jq.
Determine Sync State:
- If QUEUED_UNSAFE_L2_HEIGHT is 0, the node is considered synced enough to proceed with further validation.
- Otherwise, it is still syncing.
Validate Reference Blocks and Sync:
If synced:
```
current_l1_block_number=$(echo $SYNC_STATUS | jq -r .result.current_l1.number)
best_reference_block_number=$(get_best_reference_block_number $L1_RPC_ENDPOINT https://ethereum.publicnode.com https://eth-mainnet.g.alchemy.com/v2/demo)

reference_validation op-node $current_l1_block_number $best_reference_block_number $BLOCK_HEIGHT_TOLERANCE

echo "op-node is synced"
exit 0
```
- Retrieves the current L1 block number from the sync status.
- Calls a utility function get_best_reference_block_number (from /evm.sh) with multiple L1 RPC endpoints to determine the most reliable L1 block number.
- Calls reference_validation (also assumed to be from /evm.sh) with the node name, current L1 block number, best reference block number, and tolerance. This likely checks if the node's L1 block reference is within tolerance to the best reference.
- Prints success message and exits with 0.
If Not Synced:
```
echo "op-node is still syncing"
exit 1
```
Prints that the node is still syncing and exits with a failure code 1.

Important Implementation Details

Uses JSON-RPC over HTTP to query the op-node locally.
Uses jq to parse JSON output precisely in shell script.
Implements a tolerance-based sync validation to handle minor block height discrepancies.
Integrates external environment utilities (/evm.sh) for shared functions and variables.
Supports dynamic disabling of readiness probe via presence of a file, allowing operational flexibility.

Usage Examples

This script is primarily intended to be run as a Kubernetes readiness probe command or a periodic health check:

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

Alternatively, it can be run manually to check node readiness:

$ ./readiness.sh
op-node is synced
$ echo $?
0

or if node is syncing:

$ ./readiness.sh
op-node is still syncing
$ echo $?
1

Interaction with Other Parts of the System

/evm.sh: This script sources /evm.sh, which is expected to define:
- $L1_RPC_ENDPOINT: URL of primary Layer 1 Ethereum RPC endpoint.
- get_best_reference_block_number: Function that queries multiple L1 RPC endpoints to identify the best block number.
- reference_validation: Function that validates the difference between the node's L1 block and the best reference block against a tolerance.
Optimism Node (op-node): The script queries the local op-node JSON-RPC server running on port 9545 to check sync status.
Kubernetes / Container Orchestration: This script is designed as a readiness probe, which Kubernetes uses to determine if the pod/container is ready to serve traffic.

Mermaid Flowchart Diagram

flowchart TD
    A[Start] --> B{Check /data/disable_readiness exists?}
    B -- Yes --> C[Print "readiness probe disabled"]
    C --> D[Exit 0]
    B -- No --> E[Source /evm.sh]
    E --> F[Query op-node sync status (JSON-RPC)]
    F --> G[Parse queued_unsafe_l2.number]
    G --> H{queued_unsafe_l2.number == 0?}
    H -- No --> I[Print "op-node is still syncing"]
    I --> J[Exit 1]
    H -- Yes --> K[Parse current_l1.number]
    K --> L[Call get_best_reference_block_number with L1 endpoints]
    L --> M[Call reference_validation with op-node, current_l1, best_ref, tolerance]
    M --> N[Print "op-node is synced"]
    N --> D[Exit 0]

Summary

`readiness.sh` is a critical utility script used to determine the readiness state of an Optimism Layer 2 node by checking syncing progress and validating block height synchronization with Ethereum mainnet references. It leverages JSON-RPC queries, tolerance-based validation, and external helper functions to provide an accurate and flexible readiness signal for container orchestration systems like Kubernetes.