readiness.sh

Overview

`readiness.sh` is a shell script designed as a **readiness probe** for a Bitcoin (or Bitcoin-like) blockchain node daemon running inside a containerized environment (e.g., Kubernetes). Its primary purpose is to verify whether the node is sufficiently synchronized with the blockchain network and actively connected to peers, thus determining if it is "ready" to serve API requests or participate in further processing.

Key functionalities include:

• Checking if readiness probes are temporarily disabled via a sentinel file.

• Querying the local Bitcoin daemon RPC interface for:

  • Current number of peer connections.

  • Blockchain synchronization status (local block height vs. network block height).

• Applying a block height tolerance to allow minor lag.

• Ensuring the node has at least one active peer.

• Returning appropriate exit codes to signal readiness (0) or not ready (1) to Kubernetes.

This script enables Kubernetes to manage pod lifecycle intelligently by routing traffic only to nodes that are ready and healthy.

Detailed Explanation of Script Components

Constants and Variables

• DISABLE_READINESS_PROBE=/data/disable_readiness

  Path of a sentinel file which, if present, disables readiness checks. This allows operators to bypass readiness verification for maintenance or debugging.

• TOLERANCE=1

  Number of blocks the node is allowed to lag behind the network's latest block height before being considered out-of-sync.

Logic Flow

1. Disable Check

   if [[ -f "$DISABLE_READINESS_PROBE" ]]; then
     echo "readiness probe disabled"
     exit 0
   fi
   

   If the disable file exists, the script immediately exits with status 0 (success), indicating readiness is bypassed.

2. RPC Queries

   Fetches blockchain data via JSON-RPC calls to the local Bitcoin node:

   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
   

   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
   

   • getconnectioncount returns the number of active P2P connections.

   • getblockchaininfo returns detailed blockchain status, including block height and header count.

   If either `curl` fails (e.g., node down or unreachable), the script exits with `1` indicating failure.

3. Parsing JSON Responses

   Extracts relevant information from the JSON responses using jq:

   PEERS=$(echo $CONNECTION_COUNT | jq -r '.result')
   NODE_LATEST_BLOCK_HEIGHT=$(echo $BLOCKCHAIN_INFO | jq -r '.result.blocks')
   NETWORK_LATEST_BLOCK_HEIGHT=$(echo $BLOCKCHAIN_INFO | jq -r '.result.headers')
   

   • PEERS: Number of connected peers.

   • NODE_LATEST_BLOCK_HEIGHT: Local node's current block height.

   • NETWORK_LATEST_BLOCK_HEIGHT: Latest known block header on network.

4. Synchronization Check with Tolerance

   Defines nominal acceptable block height considering tolerance:

   NOMINAL_BLOCKS=$(( $NETWORK_LATEST_BLOCK_HEIGHT - $TOLERANCE ))
   

   The node's block height must be greater than or equal to this value to be considered synced.

5. Decision Logic

   if (( $NODE_LATEST_BLOCK_HEIGHT >= $NOMINAL_BLOCKS )); then
     if (( $PEERS > 0 )); then
       echo "node is synced with $PEERS peers"
       exit 0
     fi
   
     echo "node is synced, but has no peers"
     exit 1
   fi
   
   echo "node is still syncing"
   exit 1
   

   • If synced and has peers → readiness success (exit 0).

   • If synced but zero peers → readiness failure (exit 1).

   • If not synced → readiness failure (exit 1).

Parameters

This script does not accept command-line parameters; however, it relies on internal constants:

These can be customized by editing the script or mounting files into the container.

Return Values / Exit Codes

• 0: Node is ready (synced and has peers) or readiness probe disabled.

• 1: Node is not ready (either still syncing or no peers) or RPC calls failed.

Kubernetes interprets these codes to manage pod readiness state.

Usage Example

In Kubernetes Pod spec, this script is typically configured as a readiness probe command. For example:

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

When Kubernetes executes this script:

• If it exits 0, the pod is marked ready and receives traffic.

• If it exits non-zero, the pod is marked not ready and is excluded from service endpoints.

Important Implementation Details and Algorithms

• Fail-Fast Behavior: The script immediately exits with failure if any RPC call fails (curl with -sf and || exit 1), ensuring false positives are minimized.

• Tolerance-Based Sync Check: Allows the node to lag by 1 block to avoid transient readiness failures caused by slight network delays.

• Peer Connectivity Check: Ensures the node is participating actively in the P2P network, which is critical for data propagation and reliability.

• Disable Readiness File: Supports operational flexibility by allowing operators to override readiness checks without redeployment or pod restart.

Interaction with Other System Components

• Blockchain Daemon Node: Communicates over HTTP RPC at http://localhost:8332 with authentication (user:password) to query node status.

• Kubernetes: This script is configured as a readiness probe in the Kubernetes Pod spec of the Bitcoin node container. Kubernetes relies on its exit code to decide pod readiness.

• Monitoring and Alerting: Failure of this probe triggers alerts and pod restarts, ensuring node availability and synchronization.

• Potential Integration with Other Probes: Complementary to liveness probes that check node responsiveness and startup probes that check initial sync.

Visual Diagram: Flowchart of readiness.sh Logic

flowchart TD
    Start[Start readiness.sh script] --> CheckDisable{Disable File Present?}
    CheckDisable -- Yes --> Disabled[Print "readiness probe disabled"\nExit 0]
    CheckDisable -- No --> QueryConnections[Query getconnectioncount RPC]
    QueryConnections --> QueryBlockchainInfo[Query getblockchaininfo RPC]
    QueryBlockchainInfo --> ParseData[Parse JSON for Peers & Block Heights]
    ParseData --> CalcNominal[Calculate Nominal Block Height\n(NETWORK - TOLERANCE)]
    CalcNominal --> CheckSync{Is NODE_BLOCK >= NOMINAL_BLOCKS?}
    CheckSync -- No --> Syncing[Print "node is still syncing"\nExit 1]
    CheckSync -- Yes --> CheckPeers{Are PEERS > 0?}
    CheckPeers -- Yes --> Ready[Print "node is synced with PEERS peers"\nExit 0]
    CheckPeers -- No --> NoPeers[Print "node is synced, but has no peers"\nExit 1]

Summary

`readiness.sh` is a lightweight, efficient readiness probe script tailored for Bitcoin-compatible blockchain nodes. By validating both blockchain sync status within a tolerance and active peer connectivity, it ensures that only nodes ready to serve valid and timely blockchain data receive traffic. Its integration with Kubernetes probe mechanisms supports automated, reliable container orchestration and fault recovery.

This script exemplifies a straightforward yet robust approach to blockchain node health management within containerized environments.

End of Document