Open-source project
inkonchain/node avatar
inkonchain/node

inkonchain/node: running an Ink node on op-reth after op-geth was retired

How to run an Ink Node

36,381 stars652 forksShellMIT

At a glance

What is it?
inkonchain/node is a Docker Compose stack for running an Ink Mainnet or Ink Sepolia node with op-reth, op-node and monitoring sidecars. The setup is short, but the op-geth migration discards old data and the L1 endpoint requirements rule out free public RPCs.
Who is it for?
Use inkonchain/node if you want a self-hosted Ink Mainnet or Ink Sepolia RPC and can pay for an L1 provider with receipts for week-old blocks and high rate limits. Skip it if you only have free public endpoints or less than 2 TB of SSD for mainnet.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 31 days ago.
What is it written in?
Mainly Shell, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • inkonchain/node36,381 ★ · -96
Star history
Repository2026-08-182026-11-15
inkonchain/node36.5k36.4k

-96 Stars in the last 89 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

op-reth is the only execution client after Karst

op-geth reached end of support on May 31, 2026, and the Karst hardfork activated on Ink Mainnet on July 8, 2026 without op-geth support. This repository, forked from smartcontracts/simple-optimism-node, now runs op-reth v2.6.0 as the execution client alongside op-node v1.19.8. Both version floors matter if you pin your own images: post-Karst op-reth needs op-node v1.19.1 or later because of the new getPayloadV5 engine API method, and op-reth must be v2.3.3 or later, since v2.3.2 shipped an eth_estimateGas bug after Karst activation. The newest tagged release is v2.0.0 from May 15, 2025, which is older than the op-geth end-of-support date, so do not assume a release tag carries the op-reth stack. The quick start clones the default branch, main, which was last pushed on October 15, 2026.

Migrating from op-geth throws away your existing chain data

Operators coming from the old stack cannot reuse op-geth data. op-reth starts from an op-reth snapshot, so the old volume is dead weight, and you reclaim the disk by running this once or by deleting the op_geth volume yourself:

sh
docker compose down -v

The consequence is a full re-download: the snapshot is hundreds of GB, and the first start after migrating takes as long as a fresh install. Configuration breaks too. Port variables moved from PORT__OP_GETH_* to PORT__OP_RETH_*, and envs/<network>/op-geth.env became envs/<network>/op-reth.env, so an old .env silently stops mapping the ports you expect until you rename the keys. InfluxDB and its opgeth database are gone, with the dashboard now reading op-reth metrics from Prometheus. The op-node flags --rollup.halt and --rollup.load-protocol-versions were removed upstream and are no longer passed, so scripts that relied on them need rework.

Free public L1 endpoints cannot carry the derivation from a snapshot

After the snapshot restore, op-node derives the chain from Ethereum L1 starting from the point the snapshot was taken, up to about a week back. That requires an L1 execution RPC that serves receipts for old blocks through eth_getBlockReceipts, a matching L1 beacon API, and high rate limits. The comments in .env.example name the free Sepolia endpoints that failed against Ink Sepolia: ethereum-sepolia-rpc.publicnode.com returns no receipts for older blocks, sepolia.gateway.tenderly.co returns 429 Too Many Requests, and sepolia.drpc.org only allows batches of 3 and still catches up slower than the chain advances. OP_NODE_L1_RPC_MAX_BATCH_SIZE (default 20) can be lowered to 3 for such providers, but that does not fix the throughput. The practical result is that running this node costs a paid or self-hosted L1 provider on top of the hardware: 16GB+ RAM, 100 Mbps+ download, and a 2 TB SSD for mainnet or 500 GB for testnet, NVMe recommended.

A Sepolia full node needs six .env values

The lowest-friction first run is ink-sepolia with a full node. Clone the repository and copy the template:

sh
git clone https://github.com/inkonchain/node
cd node
sh
cp .env.example .env

Then set these values in .env:

sh
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

NETWORK_NAME accepts ink-sepolia or ink-mainnet. NODE_TYPE=full restores the latest op-reth full snapshot and runs op-reth --full, which prunes old state; NODE_TYPE=archive restores the archive snapshot and keeps all history. Snapshots come from snapshots.optimism.io on first run. OP_NODE__RPC_TYPE=basic suits generic providers, with alchemy, quicknode or erigon reserved for providers that need them. Network P2P defaults already sit in envs/<network>/op-node.env.

.env wins over the per-network files, and two mainnet URLs disagree

In docker-compose.yml each service loads its per-network env file first and .env last, so a value in .env overrides the same variable for op-reth, op-node, healthcheck and bedrock-init. Default host ports are 9993 and 9994 for op-reth HTTP and WebSocket, 39393 for op-reth P2P over UDP and TCP, 9003 for op-node P2P, 9545 for the op-node RPC and 7300 for healthcheck metrics. PORT__OP_NODE_P2P only changes the published host port; the in-container listener stays on 9003. EXTENDED_ARG is appended to both op-reth and op-node, while OVERRIDE_HOLOCENE goes to op-node only, so leave both empty unless the flag fits the process. One inconsistency to check: for ink-mainnet the README says to switch the healthcheck reference RPC to https://rpc-gel.inkonchain.com, while the comment in .env.example says https://rpc-gel.ink. Verify which one answers before trusting healthcheck comparisons.

bedrock-init gates the first start

Start the stack with:

sh
docker compose up -d --build

This pulls images, builds the local bedrock-init image, downloads and extracts the latest op-reth snapshot, creates a JWT, and starts bedrock-init, op-reth, op-node, healthcheck, prometheus and grafana. op-reth and op-node both wait for bedrock-init to create /shared/initialized.txt, so if the stack looks stuck, bedrock-init is the place to look. Because it is a one-time container, it disappears from plain docker compose ps once it exits; docker compose ps -a should show it exited with code 0. On Apple Silicon the healthcheck sidecar runs as linux/amd64, which Docker Desktop handles automatically, though the first startup can take longer. On Linux the stack needs Docker Engine with Compose v2.

Log lines and curl checks that confirm a healthy node

Check the three services that matter during startup:

sh
docker compose logs --tail 50 bedrock-init op-reth op-node

On first boot bedrock-init prints Creating JWT... and Creating Bedrock flag..., and on a restart with existing volumes it prints Bedrock node already initialized. op-reth reports RPC HTTP server started and op-node reports Rollup node started. Then query the execution RPC directly:

sh
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

The rollup node answers on port 9545, where an rpc_modules call on ink-sepolia should list the optimism, opp2p and health modules. If any of these fail, the L1 endpoint is the first suspect.

Editorial conclusion

Use inkonchain/node if you want a self-hosted Ink Mainnet or Ink Sepolia RPC and can pay for an L1 provider with receipts for week-old blocks and high rate limits. Skip it if you only have free public endpoints or less than 2 TB of SSD for mainnet. Before starting, confirm your op-geth volume can be discarded, check that your .env uses PORT__OP_RETH_* names, and verify the healthcheck reference RPC for mainnet.

Frequently asked questions

What does a crypto node like the inkonchain/node stack do?

In this stack, op-node derives the Ink chain from Ethereum L1 data and op-reth executes it and serves JSON-RPC, by default on host port 9993. Healthcheck, Prometheus and Grafana run beside them for monitoring.

Can inkonchain/node reuse my op-geth data?

No. op-geth data cannot be reused; op-reth starts from an op-reth snapshot, and you reclaim the space with docker compose down -v or by removing the op_geth volume.

What hardware does an inkonchain/node mainnet node need?

Mainnet calls for 16GB+ RAM, a 2 TB SSD with NVMe recommended, and 100 Mbps+ download. Testnet needs the same RAM and bandwidth with a 500 GB SSD.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/inkonchain-node.svg)](https://hysenlabs.com/projects/inkonchain-node)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/inkonchain-node.svg)](https://hysenlabs.com/projects/inkonchain-node)

Was this useful?