World
Home
Mini Apps
World ID
World Chain

Technical Reference

How to set up a World Chain node

Follow this guide to set up your own World Chain node.

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.

Installation

First, download simple-worldchain-node and create your .env file.

Download simple-worldchain-node

git clone https://github.com/worldcoin/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.

  • Name
    NETWORK_NAME
    Type
    worldchain-mainnet | worldchain-sepolia
    Required
    REQUIRED
    Description

    Used to select which network the node connects to, either worldchain-mainnet or worldchain-sepolia.

  • Name
    COMPOSE_PROFILES
    Type
    geth | reth
    Required
    REQUIRED
    Description

    Used to select your execution client, either geth (default) or reth (experimental).

  • Name
    NODE_TYPE
    Type
    full | archive
    Required
    REQUIRED
    Description

    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).

  • Name
    OP_NODE__RPC_ENDPOINT
    Type
    URL
    Required
    REQUIRED
    Description

    An L1 (Ethereum) RPC endpoint. We recommend using Alchemy, but any Ethereum RPC provider or archive node will work.

  • Name
    OP_NODE__L1_BEACON
    Type
    URL
    Required
    REQUIRED
    Description

    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.

  • Name
    OP_NODE__RPC_TYPE
    Type
    string
    Required
    REQUIRED
    Description

    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.

For details on optional 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