init.sh

Overview

`init.sh` is a shell script designed to manage the lifecycle of an Ethereum-compatible blockchain daemon (`geth`) within a containerized environment. Its primary purpose is to:

• Install necessary dependencies (bash, curl, jq) before starting the daemon.

• Launch the geth node client as a background process with a predefined set of runtime configurations.

• Handle Unix signals (SIGTERM, SIGINT) to gracefully stop the daemon.

• Keep the container alive by waiting on the daemon process, ensuring proper Kubernetes integration with readiness and liveness probes.

This script is a critical component in the Daemon Node Management subsystem, enabling robust and controlled execution of the blockchain node within multi-blockchain coinstack deployments.

Detailed Explanation

Shell Environment Setup

#!/bin/sh
set -e

• #!/bin/sh declares this as a POSIX-compliant shell script.

• set -e instructs the shell to exit immediately if any command exits with a non-zero status, preventing silent failures.

Dependency Installation

apk add bash curl jq

• Uses Alpine Linux's package manager apk to install:

  • bash: for advanced shell scripting features.

  • curl: for HTTP requests (commonly used for health checks or API interactions).

  • jq: a lightweight JSON processor (useful for parsing JSON data if needed).

These dependencies ensure the environment is ready for any downstream scripts or commands requiring these utilities.

Function: start_coin_bg

start_coin_bg() {
  geth \
    --$NETWORK \
    --authrpc.jwtsecret /jwt.hex \
    --syncmode full \
    --datadir /data \
    --db.engine pebble \
    --http \
    --http.addr 0.0.0.0 \
    --http.port 8545 \
    --http.api eth,net,web3,debug,txpool,engine \
    --http.vhosts '*' \
    --http.corsdomain '*' \
    --ws \
    --ws.addr 0.0.0.0 \
    --ws.port 8546 \
    --ws.api eth,net,web3,debug,txpool,engine \
    --ws.origins '*' \
    --state.scheme path \
    --history.transactions 0 \
    --ipcdisable \
    --nat none &
  PID="$!"
}

• Purpose: Launch geth (Go Ethereum client) in the background with specific runtime flags.

• Key Flags Explained:

  • --$NETWORK: Injects the network type dynamically from the environment variable NETWORK. This controls which blockchain network (e.g., mainnet, rinkeby) to connect to.

  • --authrpc.jwtsecret /jwt.hex: Specifies the path to the JWT secret file for authenticating the Engine API (used in consensus clients).

  • --syncmode full: Runs a full node that downloads all blocks and state.

  • --datadir /data: Sets the data directory for blockchain storage.

  • --db.engine pebble: Uses Pebble as the underlying key-value database engine for improved performance.

  • --http / --ws: Enables HTTP and WebSocket RPC servers, exposing APIs.

  • --http.addr 0.0.0.0 and --ws.addr 0.0.0.0: Bind RPC servers to all network interfaces, allowing external access within container networks.

  • --http.port 8545 and --ws.port 8546: Standard ports for Ethereum clients.

  • --http.api and --ws.api: Enable specific JSON-RPC modules needed for blockchain interaction, debugging, transaction pools, and engine APIs.

  • --http.vhosts '*' and --http.corsdomain '*': Allow cross-origin requests and hostnames for RPC.

  • --ws.origins '*': Permits WebSocket connections from any origin.

  • --state.scheme path: Uses path-based state trie storage.

  • --history.transactions 0: Disables transaction history to optimize storage.

  • --ipcdisable: Disables IPC (inter-process communication) sockets for security or container compatibility.

  • --nat none: Disables NAT traversal.

• Background Execution: The trailing & runs the process in the background.

• PID Capture: Captures the process ID (PID) of the background job for later management.

Function: stop_coin

stop_coin() {
  echo "Catching signal and sending to PID: $PID"
  kill $PID
  while $(kill -0 $PID 2>/dev/null); do
    sleep 1
  done
}

• Purpose: Gracefully stops the running geth process.

• Behavior:

  • Sends a SIGTERM signal to the geth process using kill $PID.

  • Enters a loop that continuously checks if the process is still running using kill -0 $PID.

  • Sleeps 1 second between checks to allow the process to exit cleanly.

• This ensures the node finishes any necessary cleanup and flushes state before container shutdown.

Main Execution Flow

start_coin_bg

trap 'stop_coin' SIGTERM SIGINT

wait $PID

• start_coin_bg is called to launch the daemon process.

• Trap signals: The script sets traps for SIGTERM and SIGINT to invoke stop_coin for graceful shutdown.

• Wait on PID: The script waits for the background geth process to exit, keeping the container alive as long as the daemon runs.

Usage Example

This script is generally invoked as the `ENTRYPOINT` or `CMD` in a container running an Ethereum-compatible node. Typical usage:

# Environment variable specifying network, e.g., mainnet, goerli
export NETWORK=mainnet

# Run the script (usually container startup)
./init.sh

• The script installs dependencies, starts the node, and manages its lifecycle with signal handling.

• Kubernetes or container orchestrators send termination signals to trigger clean shutdown.

Important Implementation Details

• Error Handling: set -e ensures the script aborts on any failure, avoiding half-started states.

• Background Process Management: Capturing $! immediately after starting geth is crucial for signal management.

• Signal Trapping: Properly handling SIGTERM and SIGINT avoids abrupt node termination, which could corrupt data.

• Dependency Installation on Startup: Installing bash, curl, and jq at runtime allows lightweight base images and flexibility.

• Environment Variable Usage: The $NETWORK variable enables this script to be reusable across different Ethereum networks without code changes.

• RPC and WS Configuration: The node is configured to be accessible widely within container networks, enabling external services (indexers, APIs) to connect.

Integration with the System

• Part of the Daemon Node Management layer in a multi-blockchain coinstack environment.

• Used inside a container image that runs the Ethereum node client (geth).

• Provides the foundational blockchain data source for:

  • Indexer services that consume blockchain events.

  • API servers that query the blockchain state and submit transactions.

• Supports Kubernetes lifecycle management by handling termination signals gracefully.

• Relies on environment variables and mounted secrets (/jwt.hex) for configuration and authentication.

• Works in concert with readiness and liveness probes that monitor the geth RPC endpoints or container health.

Visual Diagram

flowchart TD
    A[Start Container] --> B[Install Dependencies (bash, curl, jq)]
    B --> C[Invoke start_coin_bg]
    C --> D[Launch geth daemon (background)]
    D --> E[Capture geth PID]
    E --> F[Wait on geth PID]
    F -->|SIGTERM or SIGINT Received| G[Invoke stop_coin]
    G --> H[Send SIGTERM to geth PID]
    H --> I[Poll geth process until exited]
    I --> J[Exit Script and Container]

Summary

`init.sh` encapsulates the lifecycle management logic for an Ethereum node container, ensuring:

• Proper dependency setup.

• Configured launch of the geth daemon with network-specific parameters.

• Graceful shutdown on termination signals.

• Container stability by waiting on the daemon process.

This script is a reusable, robust foundation for running Ethereum nodes in containerized blockchain infrastructure, aligning with Kubernetes best practices and the broader multi-blockchain node management framework.