🌋 Askja testnet is here! Learn more →
Docs
Guides
🌐 Run a node

This guide will walk you through the process of operating a Taiko node via simple-taiko-node (opens in a new tab). You will be able to:

  • Run a Taiko node easily from the command line on Windows, Mac, and Linux.
  • Run a Taiko node regularly or as a prover.
  • View a Grafana (opens in a new tab) dashboard which displays the node's status.

Prerequisites

Steps

Clone simple-taiko-node

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

Configure your node (required)

First, copy the .env.sample to a new file .env:

cp .env.sample .env

Next, open the .env file in your preferred text editor:

Finally, set the following environment variables:

  • L1_ENDPOINT_HTTP
  • L1_ENDPOINT_WS
💡

You can get a Sepolia L1 endpoint from a few places, Alchemy (opens in a new tab) is one popular example.

Enable your node as a prover (optional)

See enable a prover for more information.

Start a node

💡

If you ran an alpha-1 testnet node make sure to first run a docker compose down -v to remove the old volumes. Also, it may take some time to synchronize from the genesis block. You can monitor this progress through logs, or in the local grafana dashboard and see the latest L2 chain status in the Taiko alpha-2 block explorer (opens in a new tab).

Make sure Docker is running and then run the following command to start the node. If you want to run it in the background, please add the -d flag (docker compose up -d).

docker compose up

To run the node in the background (detached mode), use the -d flag:

docker compose up -d

Stop a node

This command shuts down the node, but will keep all volumes, so next time you restart the node, it won't need to synchronize from the genesis again.

docker compose down

Remove a node

These commands will completely remove the node by removing all volumes used by each container:

docker compose down -v
rm -f .env

Update a node

Update the simple-taiko-node Docker images:

docker compose pull

View the node's logs

To view the Docker logs, the following commands can be ran:

View all logs
docker compose logs -f
View the prover image's logs
docker compose logs -f taiko_client_prover_relayer
View the L2 execution engine logs
docker compose logs -f l2_execution_engine
View the live data streams of your running containers

This shows the CPU/MEM USAGE % and consumption of your machine's resources (add prefix "docker stats -a" to display all containers)

docker stats

View the node's status dashboard

A Grafana (opens in a new tab) dashboard with a Prometheus (opens in a new tab) datasource is also included to display the L2 execution engine's real time status. You can visit it at http://localhost:3000/d/L2ExecutionEngine/l2-execution-engine-overview?orgId=1&refresh=10s (opens in a new tab).

image

Troubleshooting

Node warning logs

You can ignore any WARN logs.

Node error logs

error: L1_ID

The block that you want to prove has already been verified, you can ignore this.

error: L1_ALREADY_PROVEN

This block has been proven by someone else, but its not verified yet, you can ignore it.

Fatal: Failed to register the Ethereum service: database contains incompatible genesis

Try to remove the node with docker compose down -v and then try again.

Unhandled trie error: missing trie node

You can ignore this error, it doesn't affect you and goes away after a while.

Block batch iterator callback error; error="failed to fetch L2 parent block: not found

You can ignore this error.

Error starting ...: listen tcp4 0.0.0.0:{port} bind: address already in use

The port is already in use by another service. You can either shut down the other program or change the port in the .env file.

error parsing HTTP 403 response body: invalid character '<' looking for beginning of value

Your IP address is being geo-blocked due to sanctions lists. If you're affected, try changing hosting locations or utilize a VPN to change your IP address.

ERROR: The Compose file './docker-compose.yml' is invalid because: Unsupported config option for some_serivce 'pull_policy'

Your docker installation is out of date. You need to update your docker compose installation: https://docs.docker.com/compose/install/ (opens in a new tab).

daemon docker is not running
Cannot connect to the Docker daemon

Need to start the Docker before running the commands.

database contains incompatible genesis

If you ran an alpha-1 testnet node make sure to first run a docker compose down -v to remove the old volumes.

🔀 Swap tokens🔐 Enable a prover