Skip to content
Taiko Hekla will be sunsetting with the deprecation of the Holesky Testnet on September 30th, 2025. In it's place, we are deploying the Taiko Hoodi testnet with Ethereum Hoodi as L1. Please find network details here.

Run a Taiko Alethia node with Docker

This guide will help you start up a Taiko Alethia RPC node using simple-taiko-node.

Software Dependencies

DependencyVersionVersion Check Command
git^2git --version
Docker^24.0docker --version

Prerequisites

  • If using Windows, you should install Git BASH or WSL to use as your terminal.
  • Meet the Geth minimum hardware requirements except for the storage requirement because Taiko nodes will require less storage (at the time of writing).

Run a Taiko Alethia node with simple-taiko-node

  1. Clone simple-taiko-node

    Terminal window
    git clone https://github.com/taikoxyz/simple-taiko-node.git
    cd simple-taiko-node

  2. Copy the sample .env files

    Terminal window
    cp .env.sample .env

  3. Set the L1 node endpoint

    First, open the .env in your preferred text editor:

    Terminal window
    nano .env

    Next, you will set the L1 node endpoints. If you are running a local L1 node, you cannot reference the L1 endpoints as ws://127.0.0.1:8546 and http://127.0.0.1:5052 because that is local to inside the simple-taiko-node Docker networking. Instead you can try:

    • Using host.docker.internal (see: stack overflow).
    • Using the private ip address of your machine (use something like ip addr show to get this ip address).

    After getting the address of the L1 node, set the following L1 node endpoints in your .env file. Here is an example:

    • L1_ENDPOINT_WS=ws://192.168.1.15:8546
    • L1_BEACON_HTTP=http://192.168.1.15:5052

  4. Remove old testnet volumes

    If you ran a testnet node previously, make sure to first remove the old volumes:

    Terminal window
    docker compose down -v

  5. Set the profiles you want to run

    In your .env, please set COMPOSE_PROFILES to whichever set of services you’d like to run in a comma separated list (i.e., l2_execution_engine,prover or any combination of the three).

    Note that if you include prover, the service will still be disabled if you do not set ENABLE_PROVER=true in your .env file.

  6. Set your node’s external IP for p2p discovery

    This is an important config for based preconfirmations. Find your machine’s external IP and set PUBLIC_IP={EXTERNAL_IP} in your .env file. You may choose to leave it blank, in which case our scripts will enable p2p.nat in your driver; this means that you will automatically enable NAT traversal with PMP/UPNP devices to learn external IP. This is not preferred, and we highly recommend you manually set the PUBLIC_IP for discovery.

  7. Ensure that the relevant ports are open on your machine at the external IP you set.

    Whether you are running the node on a personal machine or a cloud provider’s machine, you should ensure your the following ports on your machine are open and visible to the internet at your external IP:

    • TCP 4001 OR whichever port you set P2P_TCP_PORT to in your .env.
    • UDP 30303 OR whichever port you set P2P_UDP_PORT to in your .env.

    These ports are required for p2p gossiping preconfirmed blocks, so if it is not set you will only subscribe to the events that are emitted on chain. You may need to add additional port-forwarding rules in your firewall/router to enable discovery from the internet.

  8. Set a private key for your P2P id

    Another important config for based preconfirmations, your node needs a private key set to acquire a stable peer ID. This private key should be unique to each node: if you are running multiple, please use different ones for each node. This private key does not need to hold eth or any valuables, it is simply to persist an identity.

    You may either set PRIV_RAW in your .env, or PRIV_FILE:

    • PRIV_RAW is the hexstring private key in plaintext
    • PRIV_FILE is the name of your txt file that consists entirely of a private key with no newlines IN YOUR /script/ DIRECTORY.

  9. Start the node

    Terminal window
    docker compose up -d

  10. Verify that your node has joined the P2P network

    To ensure that your node is actually configured correctly and has joined the P2P network for preconfirmations, please use grep to find logs regarding peer tick. You should find something that resembles the following:

    INFO [07-30|18:37:38.168] Peer tick                                peersLen=6 peers="[...]" addrInfo="[...]" id=... advertisedUDP=52700 advertisedTCP=4001 advertisedIP=...

    As long as connected=X is greater than or equal to 6, your node should have joined the P2P network correctly! If it is below that, please reach out to us on Discord for troubleshooting help.

  11. Verify node is running

    Option 1: Check with the node dashboard

    A node dashboard will be running on localhost on the GRAFANA_PORT you set in your .env file, which defaults to 3001: http://localhost:3001/d/L2ExecutionEngine/l2-execution-engine-overview.

    You can verify that your node is syncing by checking that the chain head on the dashboard is increasing. Once the chain head matches what’s on the block explorer, you are fully synced.

    Option 2: Check with curl commands

    1. Check if the Execution Layer client is connected to Taiko L2:

      Terminal window
      curl http://localhost:8547 \
        -X POST \
        -H "Content-Type: application/json" \
        --data '{"method":"eth_chainId","params":[],"id":1,"jsonrpc":"2.0"}'

      which should return the chainId as 0x28c61 (167009):

      { "jsonrpc": "2.0", "id": 1, "result": "0x28c61" }

    2. Check if the Execution Layer client is synced by requesting the latest Taiko L2 / L3 block from the Execution Layer client:

      Terminal window
      curl http://localhost:8547 \
        -X POST \
        -H "Content-Type: application/json" \
        --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}'

    3. If the blockNumber response value is 0 or not growing, check the Taiko L2 logs here:

      Terminal window
      docker compose logs -f

      Note: You may need to use sudo docker compose logs -f if you are not in the docker group.

Video tutorial

See the video tutorial Run a Taiko L2 node (YouTube). It’s for a previous testnet but the overall steps are the same!

Full simple-taiko-node CLI reference

Make sure you are in the simple-taiko-node folder. If you are not:

Terminal window
cd simple-taiko-node

Start node

Terminal window
docker compose up -d

Stop node

Terminal window
docker compose down

Restart node

Terminal window
docker compose down && docker compose up -d

Update node

Terminal window
git pull origin main && docker compose pull

Remove node

Terminal window
docker compose down -v

Start and remove orphan containers

This command will start and remove containers that are not part of the current docker compose file.

Terminal window
docker compose up -d --remove-orphans

View grafana dashboard

Terminal window
open http://localhost:3001/d/L2ExecutionEngine/l2-execution-engine-overview

View logs

Terminal window
docker compose logs -f

View execution logs

Terminal window
docker compose logs -f l2_execution_engine

View client driver logs

Terminal window
docker compose logs -f taiko_client_driver

View client proposer logs

Terminal window
docker compose logs -f taiko_client_proposer

View system resource usage stats

Terminal window
docker stats

Compare .env and .env.sample

Terminal window
sdiff .env .env.sample

Troubleshooting

  • Visit the Discord for help on any common error codes / issues.
  • View the logs of the node (see above).