readiness.sh

Overview

`readiness.sh` is a Bash script designed to serve as a readiness probe for a blockchain node, specifically for a Bitcoin-like node exposing JSON-RPC on localhost port 8332. The primary purpose of this script is to check if the node is ready to serve requests by verifying:

Whether readiness checks are disabled via a sentinel file.
The node's connectivity to peers.
The synchronization status of the node compared to the network's latest block height.

The script exits with status code `0` when the node is ready and `1` when it is not, making it suitable for integration into container orchestration platforms like Kubernetes as a readiness probe.

Detailed Explanation

Constants and Variables

DISABLE_READINESS_PROBE
Path to the sentinel file (/data/disable_readiness) that disables the readiness probe when present.
TOLERANCE
Numeric tolerance (default: 1) allowing the node to be considered "synced" even if it is behind the latest network block height by up to this number of blocks.
CONNECTION_COUNT
Stores the JSON-RPC response from the node's getconnectioncount method, which returns the number of connected peers.
BLOCKCHAIN_INFO
Stores the JSON-RPC response from the node's getblockchaininfo method, which provides details such as current block height and network block headers.
PEERS
Extracted number of connected peers from CONNECTION_COUNT.
NODE_LATEST_BLOCK_HEIGHT
The node's current block height extracted from BLOCKCHAIN_INFO.
NETWORK_LATEST_BLOCK_HEIGHT
The latest known block height on the network extracted from BLOCKCHAIN_INFO.
NOMINAL_BLOCKS
Nominal block height threshold for readiness, considering the tolerance.

Script Workflow

Check for readiness disable file
If the file /data/disable_readiness exists, the script prints "readiness probe disabled" and exits with status 0. This allows manual or external disabling of readiness checks.
Retrieve connection count
Uses curl with JSON-RPC to call the getconnectioncount method on the local node. If the call fails, the script exits with status 1 (not ready).
Retrieve blockchain info
Uses curl with JSON-RPC to call the getblockchaininfo method on the local node. On failure, exits with status 1.
Parse JSON values using jq
Extracts:
- Number of peers (.result from getconnectioncount).
- Node’s current block height (blocks field).
- Network's latest block height (headers field).
Calculate readiness condition
Determines the nominal block height threshold by subtracting the tolerance from the network latest block height.
Evaluate readiness
- If the node’s block height is at least the nominal value:
  - If peers > 0 → print "node is synced with X peers" and exit 0.
  - Else → print "node is synced, but has no peers" and exit 1.
- Else (node behind nominal blocks) → print "node is still syncing" and exit 1.

Implementation Details

JSON-RPC Calls
The script uses curl to send JSON-RPC requests to the node's HTTP interface. Authentication is done via basic auth with hardcoded credentials (user:password). The content-type is set to application/json.
Error Handling
If any curl call fails (non-2xx HTTP status or connection failure), the script immediately exits with status 1.
Tolerance Concept
The readiness check allows the node to lag behind the latest network block height by a small number of blocks (TOLERANCE=1) to avoid false negatives during slow block propagation.
Peer Connectivity
A node with zero peers is considered unsatisfactory for readiness despite being synced, as it cannot propagate or receive new blocks effectively.

Usage Example

This script can be used as a Kubernetes readiness probe in a Pod spec:

readinessProbe:
  exec:
    command: ["/bin/bash", "/path/to/readiness.sh"]
  initialDelaySeconds: 10
  periodSeconds: 15

When the probe exits with `0`, Kubernetes considers the container ready to serve traffic.

Interactions with Other System Components

Bitcoin Node JSON-RPC Server
This script relies on the node exposing JSON-RPC on http://localhost:8332 and requires valid credentials (user:password). This means the script must run on the same host or container as the node.
External Configuration
The presence of the file /data/disable_readiness affects the script's behavior, allowing external processes or operators to disable readiness checks without modifying the script.
Container Orchestration
Typically integrated as a readiness probe in Kubernetes or similar systems, influencing container lifecycle and traffic routing.

Summary

Step	Description	Exit Code
Disable file present	Skip readiness check	0
JSON-RPC `getconnectioncount` fails	Node unreachable or down	1
JSON-RPC `getblockchaininfo` fails	Node unreachable or down	1
Node synced & peers > 0	Node ready	0
Node synced & peers == 0	Node ready but isolated	1
Node syncing (behind network)	Node not ready	1

Mermaid Flowchart Diagram

flowchart TD
    A[Start: readiness.sh script] --> B{Is /data/disable_readiness file present?}
    B -- Yes --> C[Print "readiness probe disabled" and exit 0]
    B -- No --> D[Call getconnectioncount via JSON-RPC]
    D -->|Success| E[Call getblockchaininfo via JSON-RPC]
    D -->|Fail| F[Exit 1]
    E -->|Success| G[Parse peers, node block height, network block height]
    E -->|Fail| F
    G --> H[Calculate nominal blocks = network_latest - tolerance]
    H --> I{Is node_latest_block_height >= nominal_blocks?}
    I -- No --> J[Print "node is still syncing" and exit 1]
    I -- Yes --> K{Are peers > 0?}
    K -- Yes --> L[Print "node is synced with X peers" and exit 0]
    K -- No --> M[Print "node is synced, but has no peers" and exit 1]

Summary

This script provides a simple yet effective readiness check for a Bitcoin-like node by combining network connection status and blockchain sync status. It is easily configurable via the sentinel file and can be integrated into deployment environments to ensure traffic is only directed to fully ready nodes.

End of documentation for readiness.sh