Skip to main content
Follow this guide to set up your own World Chain node.
Anyone running a World Chain node is encouraged to join this Telegram channel for notifications of required software updates or other relevant information: World Chain Node Updates Telegram Channel

​
Overview

World Chain mainnet and testnet run on the OP Stack as part of the Superchain. We provide a simple Docker Compose configuration for running World Chain nodes, simple-worldchain-node. If you’re interested in building a node from source, see the documentation from Optimism.

​
Using simple-worldchain-node

simple-worldchain-node supports World Chain Mainnet and Sepolia, full nodes and archive nodes, and two execution clients: op-geth and op-reth.
World Chain archive node snapshots for op-geth are available from Bware Labs here.

​
Installation

First, download simple-worldchain-node and create your .env file. 
git clone https://github.com/worldcoin-foundation/simple-worldchain-node.git
cd simple-worldchain-node
cp .env.example .env
Ensure you have installed Docker and Docker Compose by following this guide.

​
Configuration

Open your .env file in an editor of your choice. The following values must be configured before starting your node.
​
NETWORK_NAME
worldchain-mainnet | worldchain-sepolia
required
Used to select which network the node connects to, either worldchain-mainnet or worldchain-sepolia.
​
COMPOSE_PROFILES
geth | reth
required
Used to select your execution client, either geth (default) or reth (recommended for archive nodes).
​
GETH_NODE_TYPE
full | archive
required
When using op-geth, determines which type of node to run. Either full (less storage, but only recent history) or archive (more storage, all history).
​
L1_RPC_ENDPOINT
URL
required
An L1 (Ethereum) RPC endpoint. We recommend using Alchemy or QuickNode, but any Ethereum RPC provider or archive node will work.
​
L1_BEACON_RPC_ENDPOINT
URL
required
An L1 Beacon Archive RPC endpoint. Note that this is not the same as a standard RPC endpoint, as this is used to retrieve Blobs from the Ethereum Beacon Chain. We recommend using QuickNode.
​
L1_RPC_TYPE
string
required
Selects which RPC provider is set in OP_NODE__RPC_ENDPOINT. This allows for more efficient syncing given different RPC capabilities. Choose from alchemy, quicknode, erigon, or basic for other RPC providers.
​
GETH_SYNCMODE
string
Selects whether op-geth will use snap sync or full sync. Defaults to snap for non-archival nodes and full for archive nodes.
​
GETH_STATE_SCHEME
string
required
Selects whether op-geth uses hash-based or path-based storage. As of op-geth v1.101602.0, path-based storage is supported for archive nodes and is enabled by default, leading to lower disk usage. The eth_getProof RPC method is not supported when using path-based storage.
For details on additional settings, see the simple-worldchain-node README.

​
Running your node

To start your node in the background, run the following command from the simple-worldchain-node folder: 
docker compose up -d --build
To view logs for your node, run the following command: 
docker compose logs -f --tail 10
To shut down your node: 
docker compose down

​
Monitoring your node

A Grafana dashboard is included to monitor your node. Access it by visiting http://localhost:3000 and logging in with these credentials:
  • Username: admin
  • Password: worldchain

​
Upgrading your Node

When new versions of op-geth, op-reth, or op-node are released, we will update the simple-worldchain-node repository to use these new versions. You can then update your node to use these versions with the following commands: 
git pull
docker compose pull
docker compose up -d --build