Ink Node

Forked and customized from https://github.com/smartcontracts/simple-optimism-node

A Docker Compose setup for running an Ink node on the repository's current op-geth-based stack, plus the supporting healthcheck and monitoring services.

Current Status

This repository currently ships an op-geth execution client. The instructions below are the current op-geth runbook for this Compose stack, not the long-term recommendation.

Per Optimism, op-geth support ends on May 31, 2026, and nodes still running it at the L1 Glamsterdam hardfork will not be able to follow the canonical chain. op-node is not being deprecated. See the op-geth deprecation notice and the op-reth configuration guide.

If you operate a production or long-lived node, start planning an op-reth migration now. Run it in parallel, validate it over a meaningful window, and prepare a fresh snapshot before the hardfork window. Treat this as an operator-owned migration rather than something to delay until a later sequencer-side client switch.

This repository does not yet ship an op-reth Compose path. Before it can, the repo still needs:

• a validated op-reth service, image, and entrypoint in docker-compose.yml
• an op-node engine endpoint that no longer points at http://op-geth:8551
• archive init and snapshot handling that can consume op-reth snapshots where available. The checked Sepolia Ink Gelato index already exposes reth/full/datadir artifacts, but this repo does not use them yet and the checked mainnet Ink index still only exposes geth archives
• healthcheck and monitoring updates, which still target op-geth and the opgeth InfluxDB database
• env and port naming that no longer assumes op-geth, such as PORT__OP_GETH_* and envs/*/op-geth.env

Recommended Hardware

Mainnet

• 16GB+ RAM
• 2 TB SSD (NVME recommended)
• 100 Mbps+ download

Testnet

• 16GB+ RAM
• 500 GB SSD (NVME recommended)
• 100 Mbps+ download

Prerequisites

• Docker Engine and Docker Compose v2 on Linux, or Docker Desktop on macOS and Windows
• Working L1 execution RPC and L1 beacon API endpoints for the Ethereum network that matches your target Ink network
• Enough free disk for your chosen node type

On Apple Silicon, the healthcheck sidecar runs as linux/amd64. Docker Desktop handles this automatically, but the first startup can take longer.

Ubuntu install

If you are not logged in as root, log out and back in after adding yourself to the docker group.

sudo apt-get update
sudo apt-get upgrade -y

sudo apt-get install -y curl gnupg ca-certificates lsb-release

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker $(whoami)

Verify Docker after logging back in:

docker ps

Quick Start

1. Clone the repo

git clone https://github.com/inkonchain/node
cd node

2. Copy the env template

cp .env.example .env

3. Edit .env

For the lowest-friction first run on the current op-geth stack, start with ink-sepolia and a full node:

NETWORK_NAME=ink-sepolia
NODE_TYPE=full
OP_NODE__RPC_ENDPOINT=<your Sepolia execution RPC>
OP_NODE__L1_BEACON=<your Sepolia beacon API>
OP_NODE__RPC_TYPE=basic
HEALTHCHECK__REFERENCE_RPC_PROVIDER=https://rpc-gel-sepolia.inkonchain.com

Configuration notes:

• NETWORK_NAME: ink-sepolia or ink-mainnet
• NODE_TYPE=full: starts from an empty local datadir. This is the validated first-run path in this repo
• NODE_TYPE=archive: resolves the newest archival geth datadir for the current op-geth stack from the Gelato ChainSnap index for your network, downloads the matching .sha256, verifies the archive, and extracts it during bedrock-init
• OP_NODE__RPC_TYPE=basic: the right default for generic providers; use alchemy, quicknode, or erigon only when your provider requires it
• .env overrides the same variable for services that load .env in docker-compose.yml, including op-geth, op-node, healthcheck, and bedrock-init
• envs/<network>/op-node.env already supplies the network P2P defaults, so most first-time setups only need the .env values above
• PORT__OP_NODE_P2P changes the published host port in docker-compose.yml. The in-container op-node listener still uses 9003
• For ink-mainnet, switch the healthcheck reference RPC to https://rpc-gel.inkonchain.com
• Advanced wrapper inputs such as OVERRIDE_HOLOCENE and EXTENDED_ARG live in .env.example. The shell entrypoints append them to both op-geth and op-node, so leave them empty unless you know the flag is compatible with the process you want to change

4. Start the stack

docker compose up -d --build

This pulls the service images, builds the local bedrock-init image, creates a JWT, and starts:

• bedrock-init (one-time init)
• op-geth (current execution client in this repo)
• op-node
• healthcheck
• prometheus
• grafana
• influxdb

op-geth and op-node both wait for bedrock-init to create /shared/initialized.txt. If the stack looks stuck, check bedrock-init first.

Validate Startup

Check service status

docker compose ps

Expect the long-running services to be Up. bedrock-init is a one-time init container, so it will usually disappear from default docker compose ps output once it exits. If you want to confirm it finished successfully, run docker compose ps -a and check that bedrock-init exited with code 0.

Check the key logs

docker compose logs --tail 50 bedrock-init op-geth op-node

Good startup signals:

• bedrock-init on first boot: Creating JWT... and Creating Bedrock flag...
• bedrock-init on restart with existing volumes: Bedrock node already initialized
• op-geth: HTTP server started
• op-node: Rollup node started

Smoke test the RPC endpoints

Execution RPC for the current op-geth service:

curl -fsS -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' http://127.0.0.1:9993

Rollup node RPC:

curl -fsS -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"rpc_modules","params":[],"id":1}' http://127.0.0.1:9545

On ink-sepolia, a healthy reply includes the optimism, opp2p, and health modules.

Sync status:

curl -fsS -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' http://127.0.0.1:9545

On a brand-new full node, this is the best early signal that the rollup node is moving forward. Look for current_l1 and head_l1 values to advance even while local L2 block height is still 0x0.

Healthcheck metrics:

curl -fsS http://127.0.0.1:7300/metrics | grep -E 'healthcheck_(reference_height|target_height|height_difference)'

On a brand-new full node, eth_blockNumber can stay at 0x0 for a while. That is expected. During that window it is also normal for healthcheck_target_height to stay at 0. Use optimism_syncStatus and the healthcheck metrics to confirm the node is moving forward during early sync.

Open Grafana

Grafana is available at http://localhost:3000.

• Username: admin
• Password: ink

The preloaded dashboard is Simple Node Dashboard.

Operating The Node

View logs

docker compose logs -f --tail 50

Or for a single service:

docker compose logs -f --tail 50 op-node

Stop

docker compose down

This stops the stack without removing data volumes.

Restart

docker compose restart

Upgrade

git pull
docker compose pull
docker compose up -d --build

Wipe All Data

docker compose down -v

This removes all local chain and monitoring data.

Monitoring

Estimate remaining sync time

progress.sh uses Foundry's cast on the host machine.

The bedrock-init container installs Foundry for its own image build, but that does not make cast available on your host shell. Install Foundry locally if you want to use progress.sh.

Install Foundry from https://getfoundry.sh/ and then run:

./progress.sh

On a brand-new full node, ./progress.sh can return Error: Not syncing while eth_blockNumber is still 0x0. In that phase, use optimism_syncStatus and the healthcheck metrics from the validation section, then retry the script after the local block height starts moving.

If you do not want to install cast, use the RPC and metrics checks above instead.

Troubleshooting

bedrock-init exits quickly on a full node

That is expected. full nodes do not download a snapshot. If you want a snapshot restore path, switch to NODE_TYPE=archive.

bedrock-init says Bedrock node already initialized

That means the stack is reusing existing Docker volumes. This is expected on restarts. If you intentionally want a clean first-boot flow, wipe the volumes:

docker compose down -v

bedrock-init takes a long time on an archive node

That is expected while the snapshot is downloading and extracting. Check:

docker compose logs -f bedrock-init

If image pulls or snapshot downloads fail, make sure the host can reach:

• docker.io
• us-docker.pkg.dev
• ink.t.snapshots.gelato.cloud
• ink.snapshots.gelato.cloud

Archive geth snapshots for the current stack are resolved from these indexes:

• Sepolia: https://ink.t.snapshots.gelato.cloud/index.html
• Mainnet: https://ink.snapshots.gelato.cloud/index.html

bedrock-init downloads the matching .sha256 file and verifies the archive before extraction. This is still a geth datadir path, not an op-reth bootstrap flow.

At the time of this docs refresh, the Sepolia Ink Gelato index also exposes reth/full/datadir artifacts, but the checked mainnet Ink index does not yet show reth artifacts. This repository does not consume those reth snapshots yet.

If bedrock-init exits with Failed to resolve latest snapshot or Unexpected snapshot filename format, the index is unreachable or its format changed. Switch back to NODE_TYPE=full and retry, or pick a direct archive from the index page and update the script before retrying.

If bedrock-init exits with Unexpected checksum file format, Checksum file does not match downloaded archive, or SHA256 verification failed, do not reuse that download. Retry later or verify the checksum file from the index page before attempting another restore.

eth_blockNumber stays at 0x0 right after startup

That is normal for a fresh full node. Check the rollup node instead:

curl -fsS -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' http://127.0.0.1:9545

./progress.sh says Error: Not syncing

That is expected during the earliest part of a fresh full node bootstrap. The script samples eth_blockNumber twice over 10 seconds, so it cannot estimate sync speed until the local execution client starts importing blocks. Use optimism_syncStatus and the healthcheck metrics first, then retry later.

op-node cannot connect to L1

Double-check:

• OP_NODE__RPC_ENDPOINT
• OP_NODE__L1_BEACON
• OP_NODE__RPC_TYPE

Then restart the stack:

docker compose down
docker compose up -d --build

error dialing static peer appears in op-node logs

That can happen during early bootstrap if a configured static peer is temporarily unavailable. If optimism_syncStatus.current_l1 keeps advancing, the node is still making progress. If those errors continue and current_l1 stops moving, inspect envs/<network>/op-node.env and your outbound network access.

Walking back L1Block appears in the logs

A few reset lines during first startup are normal. If the node keeps printing them without any L1 progress, verify the L1 endpoints above and restart the stack.