node Documentation

1. Project Overview & Quickstart (inkonchain/node) Copy Chapter

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 Copy Chapter

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 Copy Chapter

Mainnet Copy Section

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

Testnet Copy Section

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

Prerequisites Copy Chapter

• 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 Copy Section

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 Copy Chapter

1. Clone the repo Copy Section

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

2. Copy the env template Copy Section

cp .env.example .env

3. Edit `.env` Copy Section

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 Copy Section

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 Copy Chapter

Check service status Copy Section

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 Copy Section

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 Copy Section

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 Copy Section

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

• Username: admin
• Password: ink

The preloaded dashboard is Simple Node Dashboard.

Operating The Node Copy Chapter

View logs Copy Section

docker compose logs -f --tail 50

Or for a single service:

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

Stop Copy Section

docker compose down

This stops the stack without removing data volumes.

Restart Copy Section

docker compose restart

Upgrade Copy Section

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

Wipe All Data Copy Section

docker compose down -v

This removes all local chain and monitoring data.

Monitoring Copy Chapter

Estimate remaining sync time Copy Section

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.

P2P endpoints Copy Chapter

The op-node bootstrap and static peers for each network are already set in
envs/<network>/op-node.env, so a clean checkout needs no manual peering setup.

The values below are execution-layer peers and are not used by the current
stack: op-geth runs with --maxpeers=0 --nodiscover, because op-node runs
--syncmode=consensus-layer and payloads arrive over the Engine API. They are
recorded here as the reference for the op-reth migration described in
Current Status.

op-reth --bootnodes, both networks:

enode://ca2774c3c401325850b2477fd7d0f27911efbf79b1e8b335066516e2bd8c4c9e0ba9696a94b1cb030a88eac582305ff55e905e64fb77fe0edcd70a4e5296d3ec@34.65.175.185:30305?discport=30305
enode://dd751a9ef8912be1bfa7a5e34e2c3785cc5253110bd929f385e07ba7ac19929fb0e0c5d93f77827291f4da02b2232240fbc47ea7ce04c46e333e452f8656b667@34.65.107.0:30305?discport=30305
enode://c5d289b56a77b6a2342ca29956dfd07aadf45364dde8ab20d1dc4efd4d1bc6b4655d902501daea308f4d8950737a4e93a4dfedd17b49cd5760ffd127837ca965@34.65.202.239:30305?discport=30305

op-reth --trusted-peers, mainnet:

enode://61164c944eba34a2d4f50682fd71fa966df42ffcf32bd962810c004acf47f574efd6d0d293bd7c6ffe964524468a98f1cd9427dca2bf54dcfa375d34e5a25fc7@34.178.90.179:30304?discport=30303
enode://3812d9e130a2f45761431935f0e2ad4a12e9389772a96e4e83e48a38722b44f02af7df32204a7a6f6fa91c38f7ba12a03178a7c6d5624dc45f87a79d076a95cb@34.6.15.128:30304?discport=30303
enode://b708474c6db25e99320daebd2d9a8b29139a676fad976e134eb6ca6271d7525510a361efe1b0828e9288b3d33cb8edcb602d8aea335fab086ad6e38251775f91@34.178.42.30:30304?discport=30303

op-reth --trusted-peers, sepolia:

enode://9978a50acf8f7c30c8cbd657a653c2faaf4033c62c9f288a2ae88b31ac121cf5c419788d4f0b45cc5fd75d05e29bd05f59c0c5339b6726c9ea41bca4108f4bcc@34.6.8.218:30304?discport=30303
enode://8e23c7c584b7b0808269dc74f825d68daa0df2a331c92b0c4c638b951607affa4ea614098f98791b68c73922ebbe146a5ae1e40a8d158babb372e11433091499@34.141.131.99:30304?discport=30303
enode://c2dd4ad2f3f5dd2e3d6c77acbb4f96a73d692f3172181caf457863bd9ac0645c4b709b98e8c2fa6e6d218135268635d85224b2623480290ac4dad22f0cb31b4b@35.204.224.2:30304?discport=30303

Troubleshooting Copy Chapter

`bedrock-init` exits quickly on a full node Copy Section

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` Copy Section

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 Copy Section

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 Copy Section

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` Copy Section

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 Copy Section

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 Copy Section

That can happen during early bootstrap if a configured static peer is
temporarily unavailable. If those errors continue against every configured peer,
inspect envs/<network>/op-node.env and your outbound network access; stale peer
endpoints are the usual cause. Note that current_l1 can keep advancing with
zero peers, since the node still derives the safe chain from L1 — check
opp2p_peerStats.connected to confirm P2P health.

`Walking back L1Block` appears in the logs Copy Section

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.

2. Official Technical Reference & Guides (inkonchain/docs) Copy Chapter

File: README.md Copy Chapter

InkChain Documentation App

An advanced, streamlined documentation platform built with Next.js and Nextra for InkChain.

🚀 Build & Run Copy Chapter

1. Build Docker image:

   bash Copy

   docker build -t docs .

2. Run Docker container:

   bash Copy

   docker run -p 3000:3000 docs

📋 Requirements Copy Chapter

• Node.js: v20.11.0 or higher

📖 Overview Copy Chapter

This is a documentation application powered by Nextra and built on Next.js. Nextra simplifies the creation of documentation sites, allowing us to leverage the Pages Router for efficient navigation and routing. Currently, due to compatibility limitations, we have not yet upgraded to the App Router.

🏁 Getting Started Copy Chapter

To get started with local development:

1. Clone the repository
2. Install dependencies:
   bash Copy

   pnpm install

3. Start development server:
   bash Copy

   pnpm run dev

🛠 Tooling Copy Chapter

Our development setup includes multiple tools to maintain high-quality code and documentation:

• CSpell: Real-time spell checking to maintain documentation accuracy.
• Remark: Processes and renders Markdown content with added plugins.
• ESLint: Ensures code quality by catching potential issues.
• Prettier: Enforces consistent code formatting.
• Tailwind CSS: Utility-first CSS framework for fast, responsive UI development.

🚦 CI/CD Pipeline Copy Chapter

Our CI/CD setup utilizes GitHub Actions to run automated checks on every pull request (PR):

• js-lint: Ensures proper JavaScript code formatting with ESLint.
• md-lint: Checks Markdown code formatting with Remark.
• format: Enforces consistent code style with Prettier.
• spell-check: Uses CSpell to verify correct spelling in the documentation. For any unique terms (e.g., "InkChain"), add them to the ./cspell/project-words.txt file to whitelist.

🌐 Feature Branch Deployment Copy Chapter

For every new PR, our CI/CD pipeline deploys a temporary environment via AWS Amplify. This real-time deployment enables live testing and review of changes before merging, ensuring a smoother workflow. The deployment URL is automatically provided within the PR checks, allowing team members to interact with new features.

🚀 Production Deployment Copy Chapter

The main branch is configured for automatic continuous deployment via AWS Amplify. Every merge triggers a new build and deployment, ensuring that the latest version of the documentation is available to users without manual intervention.

File: src/content/shared/_badges.mdx Copy Chapter

Badges

Welcome To Ink Copy Chapter

Awarded for bridging Ethereum to Ink.

To bridge Ethereum, you can use the L1StandardBridge on the sepolia network crafted for Ink.

There are two ways to do it:

Gelato Bridge app Copy Section

The app provides a very simple UI to deposit or withdraw SepoliaETH from and to Sepolia Ink.

Here is the app: https://testnet-bridge.gelato.network/bridge/ink-sepolia

Connect your wallet, select the amount to transfer, and that's it!

Directly calling the contract Copy Section

You can call the bridgeETH method in the contract here: https://sepolia.etherscan.io/address/0xC0d337f71aD19a8f17a1b297cDb3a86c5EEf9Eec#writeProxyContract

For instance, if you want to bridge 1 Sepolia ETH into 1 Sepolia "Ink" ETH:

1. Connect your Wallet using the "Connect to Wallet" button
2. Expand the bridgeETH method and enter bridgeETH: 1
3. Enter _minGasLimit: 1000 (or whatever suits you)
4. Enter _extraData: 0x00
5. Click "Write", then validate the transaction in MetaMask, then sign it to complete the transaction.

Wrapped ETH Copy Chapter

Awarded for wrapping Ethereum into WETH.

To create Wrapped ETH tokens (WETH), you can interact with the deposit method in the contract here: https://explorer-sepolia.inkonchain.com/token/0x47d1f931eaff721549cc0ad57da81729baa8b4b2?tab=write_contract

1. Connect your Wallet using the button
2. Expand the deposit method and enter Send native ETH: 10 000 000 000 000 000.

• This is equivalent to 0.01 ETH, adjust as needed

3. Click "Write", then validate the transaction in MetaMask, then sign it to complete the transaction.

If you want the token to appear in MetaMask, click on the MetaMask button at the top of the page

ERC20 Interactions Copy Chapter

Awarded for minting, sending, and receiving ERC20 tokens.

coming soon

NFT Interactions Copy Chapter

Awarded for minting, sending, and receiving NFTs.

coming soon

Faucet User Copy Chapter

Awarded for using the Ink faucet.

Get here: https://mystery-faucet.inkonchain.com/

Enter your address, enter the captcha, that's it!

Smart Contract Deployer Copy Chapter

Awarded for deploying a smart contract.

coming soon

File: src/content/shared/block-explorers-content.mdx Copy Chapter

Blockscout Copy Chapter

Blockscout is a universal block explorer providing detailed chain information and tools for debugging smart contracts and transactions. Visit the Blockscout Docs for details.

Supported Networks

• Ink Sepolia: https://explorer-sepolia.inkonchain.com/
  • API: https://explorer-sepolia.inkonchain.com/api

Verifying Smart Contract Code on Blockscout

• Please see this tutorial

Routescan Copy Chapter

Routescan is a unified explorer for over 54 blockchains.

Supported Networks

• Ink Sepolia: https://sepolia.inkonscan.xyz/
  • API: https://sepolia.inkonscan.xyz/documentation/api-swagger

File: src/content/shared/bridges-content.mdx Copy Chapter

import { Callout } from 'nextra/components'

Bridges

These bridges provide different interfaces to the canonical smart contracts that facilitate migrating ETH from one chain to another.

How to use

1. Visit the bridge and connect your wallet.
2. Choose Sepolia as your source and Ink as the destination.
3. Input the amount of assets you want to bridge.
4. Confirm and sign the transaction with your wallet.
5. Once the bridging is complete, the assets will appear in your wallet on Ink.

Gelato bridge Copy Chapter

Bridge: https://bridge-gel-sepolia.inkonchain.com/

Ink Bridge Copy Chapter

Bridge: https://inkonchain.com/bridge

Brid.gg Copy Chapter

Bridge: https://testnet.brid.gg/

Superbridge Copy Chapter

Bridge: https://superbridge.app/ (enable testnet in settings)

File: src/content/shared/community-content.mdx Copy Chapter

import { URLS } from "@/utils/urls";

Get Support

Join the Ink community, vibe with fellow developers and get support:

• Join the Ink Telegram for announcements: Join Telegram

File: src/content/shared/crosschain-content.mdx Copy Chapter

Crosschain Infrastructure

Wormhole Copy Chapter

Wormhole is an interoperability platform powering multichain apps and bridges.

• Wormhole currently supports Ink Mainnet and Ink Sepolia.

File: src/content/shared/faucets-content.mdx Copy Chapter

Faucets

Get Sepolia ETH on Ink from these faucets below! Alternatively, you can bridge testnet funds to Ink.

[Ink](https://inkonchain.com/faucet) Copy Chapter

Our in-house faucet provides a quick and easy way to acquire testnet ETH.

[Optimism Superchain Faucet](https://console.optimism.io/faucet) Copy Chapter

The Superchain Faucet provides testnet ETH for Ink and all other OP chains. Sign in to claim 0.10 test ETH on 1 network every 24 hours or verify your onchain identity for more tokens.

[QuickNode](https://faucet.quicknode.com/drip) Copy Chapter

Use QuickNode Faucet to claim Ink Sepolia for testnet ETH for free - one drip per network every 12 hours.

[Gelato](https://faucet-gel-sepolia.inkonchain.com) Copy Chapter

Gelato's Faucet uses Cloudflare authentication and drops up to 0.3 Ink Sepolia ETH every 12 hours.

[Tenderly](https://tenderly.co/?mtm_campaign=ext-docs&mtm_kwd=ink) Copy Chapter

Tenderly's Unlimited Faucet allows you to mint native and ERC20 tokens for development and testing on Virtual TestNets. The unlimited faucet is part of the Admin RPC, a collection of cheat-codes allowing full customization of the network.

File: src/content/shared/multisig-content.mdx Copy Chapter

Multisig

Safe Copy Chapter

Ink hosts Safe's technology to bring digital ownership of accounts to everyone by building universal and open contract standards for the custody of digital assets, data, and identity.

Using Safe you can:

• Manage customizable non-custodial wallets supporting multisignatures for individuals and teams
• Perform financial management of onchain assets incl. ERC20s, ERC721s and ETH
• Access your safe using Web, Mobile and Desktop apps.
• Safe also features access to DeFi, open source code, batch transactions, modular extensions, gasless signatures and more.

Supported Networks

• Ink Mainnet
• Ink Sepolia