init.sh

Overview

[init.sh](/projects/291/68855) is a shell script designed to initialize and run the **Nitro** node software for the Arbitrum One blockchain (chain ID 42161). The script handles starting the Nitro node with specific configuration parameters, managing its lifecycle, and gracefully stopping the process upon receiving termination signals.

This script plays a critical role in the deployment and operation of the Nitro node, which is a key component for interacting with the Arbitrum blockchain network. It configures network endpoints, API exposure, logging, and operational flags needed for the node to function correctly within the environment.

Detailed Breakdown

Script Execution Environment

#!/bin/sh
set -e
[ "$DEBUG" = "true" ] && set -x

Runs the script using the POSIX-compatible shell /bin/sh.
set -e causes the script to exit immediately if any command exits with a non-zero status, ensuring failure propagation.
If the environment variable DEBUG is set to "true", set -x enables execution tracing, printing each command before it is executed (useful for debugging).

Functions

`start()`

Starts the Nitro node process with a specific set of command-line options.

Implementation

start() {
  /usr/local/bin/nitro \
  --chain.id 42161 \
  --chain.name arb1 \
  --parent-chain.connection.url $L1_RPC_ENDPOINT \
  --parent-chain.blob-client.beacon-url $L1_BEACON_ENDPOINT \
  --init.url 'https://snapshot.arbitrum.foundation/arb1/nitro-pruned.tar' \
  --init.download-path /data/tmp \
  --persistent.chain /data \
  --auth.jwtsecret /jwt.hex \
  --file-logging.enable='false' \
  --http.addr 0.0.0.0 \
  --http.port 8547 \
  --http.api eth,net,web3,debug,txpool,arb \
  --http.vhosts '*' \
  --http.corsdomain '*' \
  --ws.addr 0.0.0.0 \
  --ws.port 8548 \
  --ws.api eth,net,web3,debug,txpool,arb \
  --ws.origins '*' \
  --node.staker.enable='false' \
  --execution.tx-lookup-limit 0 &
  PID="$!"
}

Parameters

None (relies on environment variables for dynamic values).

Behavior

Runs the binary /usr/local/bin/nitro in the background (&).
Configures:
- Blockchain network settings:
  - --chain.id 42161: Arbitrum One network ID.
  - --chain.name arb1: Network name.
- Parent chain endpoints:
  - $L1_RPC_ENDPOINT: URL for L1 RPC endpoint.
  - $L1_BEACON_ENDPOINT: Beacon URL for blob client communication.
- Initialization snapshot:
  - Downloads initial chain snapshot from a fixed URL.
  - Saves snapshot temporarily under /data/tmp.
- Persistent storage path: /data
- JWT secret file path: /jwt.hex (for authentication).
- Logging:
  - File logging disabled (false).
- HTTP RPC server:
  - Binds to all interfaces (0.0.0.0).
  - Listens on port 8547.
  - Enables APIs: eth,net,web3,debug,txpool,arb.
  - Allows all host headers and CORS domains.
- WebSocket server:
  - Binds to all interfaces.
  - Port 8548.
  - Same APIs as HTTP.
  - Allows all origins.
- Node staker functionality disabled.
- Execution transaction lookup limit set to 0.
Stores the background process ID in the variable PID.

Returns

None explicitly.
Sets a global PID variable representing the Nitro process.

Usage Example

start
# Nitro node starts running in background with configured settings

`stop()`

Gracefully stops the Nitro node process.

Implementation

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

Parameters

None.

Behavior

Prints a message indicating it is sending a termination signal to the Nitro process.
Sends SIGTERM to the process identified by PID.
Waits in a loop until the process terminates:
- kill -0 $PID checks if the process is still running.
- Sleeps 1 second between checks.
Ensures clean shutdown of Nitro node.

Returns

None.

Usage Example

stop
# Sends SIGTERM to Nitro node and waits for it to exit

Signal Handling

trap 'stop' TERM INT

Registers the stop function to be called when the script receives SIGTERM or SIGINT signals.
Enables graceful shutdown on container stop, user interrupt (Ctrl+C), or system termination.

Script Execution Flow

start
wait $PID

Calls start to launch the Nitro node in the background.
Calls wait $PID to block the script until the Nitro process exits.
This design allows the script to manage the lifecycle of the Nitro node process and handle signals properly.

Important Implementation Details

Dynamic Configuration via Environment Variables: The script expects two important environment variables to be set before execution:
- L1_RPC_ENDPOINT: The RPC endpoint URL for the L1 Ethereum chain.
- L1_BEACON_ENDPOINT: The beacon URL used by the blob client to communicate with the L1 chain.
These values are essential for Nitro to connect to the parent chain and synchronize state.
Snapshot Initialization: Instead of starting from genesis, Nitro downloads a pruned snapshot (nitro-pruned.tar) at startup, speeding up synchronization.
API Exposure: Both HTTP and WebSocket RPC APIs expose a rich set of namespaces (eth,net,web3,debug,txpool,arb), allowing external clients to interact with the Nitro node for various purposes.
Security Considerations: The JWT secret (/jwt.hex) is used to secure authentication for the node APIs.
Disabling Staker Mode: Node staker functionality is disabled, indicating this node is not participating in staking but rather serving as a full node.
Signal Handling: The script traps termination signals and gracefully shuts down Nitro, avoiding unclean exits that could corrupt data.

Interaction with Other System Components

Nitro Binary: The script controls the lifecycle of the /usr/local/bin/nitro executable, which is the actual node software.
Environment Variables: Relies on environment variables to configure network connections, making it flexible for different deployment environments.
Storage Volumes: Reads from and writes to persistent storage volumes under /data and /data/tmp, typically mounted from host or container volumes for data persistence.
API Clients: Exposes RPC and WS APIs for clients such as wallets, explorers, or other blockchain tools to interact with the Arbitrum chain via this node.
Parent Chain (L1 Ethereum): Connects to Ethereum mainnet endpoints to sync and verify transactions and state.

Visual Diagram

flowchart TD
    Start["start() function"]
    Nitro["/usr/local/bin/nitro executable"]
    EnvVars[L1_RPC_ENDPOINT, L1_BEACON_ENDPOINT]
    InitURL["Snapshot URL\n'https://snapshot.arbitrum.foundation/arb1/nitro-pruned.tar'"]
    Storage["Persistent Storage (/data, /data/tmp)"]
    APIs["HTTP & WebSocket APIs\n(eth, net, web3, debug, txpool, arb)"]
    Trap["trap 'stop' TERM INT"]
    StopFunc["stop() function"]

    Start --> Nitro
    Nitro -->|Uses| EnvVars
    Nitro -->|Downloads snapshot from| InitURL
    Nitro -->|Stores data in| Storage
    Nitro --> APIs
    Trap --> StopFunc
    StopFunc --> Nitro
    Nitro -->|Background process PID stored in| PID["PID variable"]
    Start -->|Stores PID| PID
    StopFunc -->|Sends SIGTERM to| PID

Summary

init.sh is a robust, minimal shell script for controlling the lifecycle of the Nitro node software.
It sets up the node with network, storage, logging, and API parameters suitable for running an Arbitrum One full node.
The script handles graceful termination and supports debugging via environment-controlled tracing.
It forms a critical operational part of the system by managing the Nitro node process within container or server environments.

Usage Notes

Ensure environment variables L1_RPC_ENDPOINT and L1_BEACON_ENDPOINT are set before executing the script.
Run the script in an environment where /usr/local/bin/nitro binary and the persistent storage paths are accessible.
Use the DEBUG=true environment variable to enable detailed command logging for troubleshooting.
This script is suitable for containerized environments where signal propagation and process management need explicit handling.

End of Documentation for init.sh