readiness.sh

Overview

`readiness.sh` is a Bash script designed to serve as a readiness probe for a blockchain node (likely a Bitcoin node, given the JSON-RPC methods and port used). Its primary purpose is to verify whether the node is ready to handle requests by checking two key conditions:

Whether the node is sufficiently synced with the blockchain network.
Whether the node currently has active peer connections.

The script queries the node's JSON-RPC API endpoints to obtain the current connection count and blockchain synchronization status. Based on these metrics, it determines and reports the readiness state, which can be used by container orchestration platforms (like Kubernetes) or monitoring tools to decide if the node is ready to receive traffic or perform operations.

If a specific file (`/data/disable_readiness`) exists, the readiness probe is disabled and the script immediately exits successfully.

Detailed Explanation

Variables

DISABLE_READINESS_PROBE: Path to a file which, if present, disables the readiness probe.
TOLERANCE: An integer that defines the acceptable lag in blocks between the node's latest block height and the network's latest block height before considering the node as "synced."
CONNECTION_COUNT: Stores JSON-RPC response for the number of active connections.
BLOCKCHAIN_INFO: Stores JSON-RPC response for blockchain synchronization information.
PEERS: Extracted number of peer connections from CONNECTION_COUNT.
NODE_LATEST_BLOCK_HEIGHT: The current block height of the node.
NETWORK_LATEST_BLOCK_HEIGHT: The latest block height known on the network.
NOMINAL_BLOCKS: The threshold block height for considering the node "synced" (network height minus tolerance).

Script Logic and Workflow

Readiness Probe Disabled Check
```
if [[ -f "$DISABLE_READINESS_PROBE" ]]; then
  echo "readiness probe disabled"
  exit 0
fi
```
If the file /data/disable_readiness exists, the script logs that the readiness probe is disabled and exits with a success status (0).

Fetch Connection Count

The script sends a JSON-RPC request to the node's API to get the number of active peer connections:

CONNECTION_COUNT=$(curl -sf -H 'content-type: application/json' -u user:password -d '{ "jsonrpc": "2.0", "id": "probe", "method": "getconnectioncount", "params": [] }' http://localhost:8332) || exit 1

If the request fails, the script exits with a failure status (1).

Fetch Blockchain Information

Similarly, it queries blockchain synchronization info:

BLOCKCHAIN_INFO=$(curl -sf -H 'content-type: application/json' -u user:password -d '{ "jsonrpc": "2.0", "id": "probe", "method": "getblockchaininfo", "params": [] }' http://localhost:8332) || exit 1

Again, failure leads to exit status 1.

Parse JSON Responses
Using jq, the script extracts:
- Number of peers: .result from getconnectioncount
- Node's latest block height: .result.blocks from getblockchaininfo
- Network's latest block height: .result.headers from getblockchaininfo

Determine Synced Status

The node is considered synced if:

NODE_LATEST_BLOCK_HEIGHT >= NETWORK_LATEST_BLOCK_HEIGHT - TOLERANCE

Check Peer Connections and Output Status
- If the node is synced and has more than 0 peers, the script outputs:
```
node is synced with X peers
```
  and exits with 0 (success).
- If the node is synced but has no peers, it outputs:
```
node is synced, but has no peers
```
  and exits with 1 (failure), signaling an issue despite sync.
- If the node is not synced, it outputs:
```
node is still syncing
```
  and exits with 1.

Usage Example

Assuming this script is part of a containerized blockchain node deployment, it would typically be invoked periodically by a container orchestrator to verify readiness:

$ ./readiness.sh
node is synced with 8 peers
$ echo $?
0

If the node is still syncing:

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

If the readiness probe is disabled (presence of `/data/disable_readiness`):

$ touch /data/disable_readiness
$ ./readiness.sh
readiness probe disabled
$ echo $?
0

Important Implementation Details

Authentication: The script uses HTTP Basic Auth (-u user:password) for JSON-RPC requests. Credentials are hardcoded, which is a security risk for production environments. Ideally, these should be injected via environment variables or secure secrets management.
Error Handling: The script immediately exits with failure (1) if curl commands fail (e.g., if the node is unreachable). This is critical to prevent false positive readiness signals.
Tolerance Parameter: The TOLERANCE=1 allows the node to be considered synced if it is within 1 block of the network's latest block height. This accounts for minor network propagation delays.
JSON Parsing: Relies on jq for extracting data from JSON responses. This tool must be installed on the host/container.
Disable Probe Flag: The presence of the disable file allows manual override of readiness checks, useful during maintenance or troubleshooting.

Interaction with Other System Components

Blockchain Node: The script communicates directly with the blockchain node's JSON-RPC API (on port 8332) to retrieve real-time status.
Container Orchestrator / Monitoring System: Typically, this script would be used as a readiness probe in Kubernetes or similar systems. The probe’s exit code determines whether the node is considered ready to receive traffic.
External Configuration: The script currently has hardcoded credentials and endpoint. In a full system, these would likely be parameterized or injected via environment variables or config maps.

Mermaid Flowchart Diagram

The following flowchart summarizes the main functional workflow of `readiness.sh`:

flowchart TD
    A[Start] --> B{Is /data/disable_readiness present?}
    B -- Yes --> C[Print "readiness probe disabled"\nExit 0]
    B -- No --> D[Fetch connection count via JSON-RPC]
    D -->|Fail| E[Exit 1]
    D --> F[Fetch blockchain info via JSON-RPC]
    F -->|Fail| E
    F --> G[Parse peers, node block height,\nnetwork block height]
    G --> H{Is node block height >= network block height - tolerance?}
    H -- No --> I[Print "node is still syncing"\nExit 1]
    H -- Yes --> J{Are peers > 0?}
    J -- Yes --> K[Print "node is synced with X peers"\nExit 0]
    J -- No --> L[Print "node is synced, but has no peers"\nExit 1]

Summary

`readiness.sh` is a utility script that performs health checks on a blockchain node to determine its readiness state. It combines network status (peer connections) and blockchain sync status to provide a comprehensive readiness signal. Its design is simple and effective for integration with containerized environments and monitoring systems, though it would benefit from improvements in configuration management and security for production use.