## Run a Node \[Run a Taiko mainnet or Hoodi testnet node with Docker or from source. Hardware, sync modes, RPC exposure, and taiko-client setup.] ### Architecture Taiko nodes still follow Ethereum's execution/consensus split, but under the Shasta protocol architecture (which the current Unzen fork runs on) the consensus side is driven by Taiko's L1 inbox, proposal derivation rules, and L2 anchoring logic instead of an Ethereum beacon chain. The main components are: * [`alethia-reth`](https://github.com/taikoxyz/alethia-reth) — the default Reth-based **execution client** in `simple-taiko-node` for Unzen. It executes L2 blocks, maintains chain state, and exposes the JSON-RPC, WebSocket, metrics, and Engine API surfaces that `taiko-client` expects. * [`taiko-geth`](https://github.com/taikoxyz/taiko-geth) — a minimally modified fork of `go-ethereum` that remains available as the geth-based execution client. * [`taiko-client`](https://github.com/taikoxyz/taiko-mono/tree/main/packages/taiko-client) — the **consensus and rollup driver**. It watches the `Inbox` on L1, derives L2 blocks from proposal data, tracks finalization, and drives the selected execution client through the Engine API. Since the Shasta fork, the protocol no longer upgrades the old Pacaya inbox in place. It uses a separate **Inbox** contract on L1 for proposing, proving, forced inclusion, and finalization, while the L2 side uses the **TaikoAnchor** plus fork-router contracts to keep pre-fork and post-fork behavior compatible during the transition. #### taiko-client roles | Component | Responsibility | | ---------- | ----------------------------------------------------------------------------------------------------------------------- | | `driver` | Tracks L1 proposals and finalized proposal ranges, derives L2 blocks, and feeds them into the execution engine | | `proposer` | Collects transactions and submits proposals to the L1 inbox, including lookahead data when preconfirmations are enabled | | `prover` | Generates and submits validity proofs that finalize consecutive proposal ranges | #### Chain synchronization At a high level, sync works like this: 1. Read the latest finalized proposal state from the L1 inbox 2. Attempt to catch up to the network tip via P2P preconfirmation peers 3. If needed, replay finalized L2 blocks through the Engine API 4. Listen for new `Proposed` events on L1 5. Reconstruct and execute the corresponding L2 blocks from proposal data and forced inclusions 6. Keep the L2 head anchored to the L1 checkpoints exposed through the anchor path If a proposed tx list is invalid, the protocol still advances by constructing an empty anchor-only block rather than halting execution. #### APIs Taiko nodes expose standard Ethereum-style interfaces: * **JSON-RPC API** for standard execution-layer workflows * **Engine API** for communication between `taiko-client` and execution client This is what allows most Ethereum tooling to work against Taiko with minimal changes. ### Prerequisites #### Hardware | Resource | Minimum | | -------- | -------- | | CPU | 4 cores | | RAM | 16 GB | | Storage | 2 TB SSD | Storage requirements grow over time. Plan accordingly. #### Software | Dependency | Version | Check | | ------------------------------------------------- | ----------------------------------------- | ------------------ | | [Git](https://git-scm.com/) | 2+ | `git --version` | | [Docker](https://docs.docker.com/engine/install/) | 24+ (Docker method) | `docker --version` | | [Go](https://go.dev/) | 1.21+ (source method) | `go version` | | [Make](https://www.gnu.org/software/make/) | 4+ (source method) | `make --version` | | [Rust](https://www.rust-lang.org/tools/install) | stable (source method for `alethia-reth`) | `cargo --version` | #### L1 Endpoint You need access to an Ethereum L1 node (execution + beacon). * **Mainnet nodes** require an Ethereum mainnet L1 endpoint. * **Hoodi testnet nodes** require an Ethereum Hoodi testnet L1 endpoint. :::warning Third-party RPC providers will eventually rate-limit your node and stop syncing. Run your own L1 node for a reliable setup. ::: :::info To prove blocks older than 128 blocks, your L1 node must be an archive node. ::: ### Docker Method ::::steps #### Clone simple-taiko-node ```bash git clone https://github.com/taikoxyz/simple-taiko-node.git cd simple-taiko-node git checkout ``` On Windows, also run `git config core.autocrlf false` after cloning. #### Copy the sample environment file :::code-group ```bash [Mainnet] cp .env.sample .env ``` ```bash [Hoodi Testnet] cp .env.sample.hoodi .env ``` ::: #### Configure L1 endpoints Open `.env` in a text editor and set: ```bash L1_ENDPOINT_WS=ws://:8546 L1_BEACON_HTTP=http://:5052 ``` :::warning If your L1 node runs on the same machine, do not use `127.0.0.1`. Docker cannot reach the host loopback. Use `host.docker.internal` or your machine's private IP (find it with `ip addr show` or `ifconfig`). ::: #### Choose an execution client In `.env`, set `COMPOSE_PROFILES` to the execution client profile you wish to use. :::code-group ```bash [Mainnet] COMPOSE_PROFILES=reth_execution_engine ``` ```bash [Mainnet - taiko-geth] COMPOSE_PROFILES=geth_execution_engine ``` ```bash [Hoodi Testnet - alethia-reth] COMPOSE_PROFILES=reth_execution_engine ``` ```bash [Hoodi Testnet - taiko-geth] COMPOSE_PROFILES=geth_execution_engine ``` ::: In `simple-taiko-node`, `reth_execution_engine` runs `alethia-reth` and is the default profile for both mainnet and Hoodi. Use `geth_execution_engine` only if you want to run `taiko-geth` instead. Choose exactly one execution client profile; both profiles expose the same internal `l2_execution_engine` alias for `taiko-client`. If you run `alethia-reth`, you can set `L2_RETH_DATA_DIR` in `.env` to point at an extracted snapshot directory. If unset, Docker uses the `l2_execution_engine_data` volume. You may download the most recent publicly hosted snapshot for `alethia-reth` at [https://snapshots.taiko.xyz/](https://snapshots.taiko.xyz/). #### Configure preconfirmations (recommended) To receive preconfirmed blocks and keep your node at the tip of the chain, configure these settings in `.env`: 1. Set `ENABLE_PRECONFS_P2P=true`. 2. Set `PUBLIC_IP` to your machine's external IP. If left blank, NAT traversal (PMP/UPnP) is used automatically, but manual configuration is preferred. 3. Open these ports on your firewall/router so they are reachable from the internet: * TCP `4001` (or your custom `P2P_TCP_PORT`) * UDP `30303` (or your custom `P2P_UDP_PORT`) 4. Set a private key for your P2P peer identity. Use either: * `PRIV_RAW` — hex-encoded private key in plaintext * `PRIV_FILE` — filename of a key file in the `script/` directory :::info The P2P private key does not need to hold ETH or any assets. It exists only to give your node a stable peer identity. Use a unique key for each node. ::: :::warning `PUBLIC_IP` must be publicly reachable from the internet at the advertised TCP and UDP ports. If it is not, your node will not join the P2P network. ::: #### Start the node :::code-group ```bash [Mainnet] docker compose up -d ``` ```bash [Hoodi Testnet] docker compose -f docker-compose-hoodi.yml up -d ``` ::: You may need `sudo` if your user is not in the `docker` group. #### Verify the node is running Check that the execution engine is connected: ```bash curl http://localhost:8547 \ -X POST \ -H "Content-Type: application/json" \ --data '{"method":"eth_chainId","params":[],"id":1,"jsonrpc":"2.0"}' ``` Expected response for mainnet: `"result":"0x28c58"` (chain ID 167000). Check sync progress: ```bash curl http://localhost:8547 \ -X POST \ -H "Content-Type: application/json" \ --data '{"method":"eth_blockNumber","params":[],"id":1,"jsonrpc":"2.0"}' ``` If the block number is `0` or not growing, inspect the logs: ```bash docker compose logs -f ``` #### Verify P2P connectivity Search for `peer tick` in the logs: ```bash docker compose logs -f | grep "peer tick" ``` Look for output like: ``` INFO [07-30|18:37:38.168] Peer tick peersLen=2 peers="[...]" ... ``` If `peersLen` is greater than 0 and your L2 block number keeps increasing, P2P connectivity is working. :::: ### From Source Method A Taiko node has two components: * **Execution engine** — use `alethia-reth` by default on mainnet and Hoodi testnet, or `taiko-geth` if you need the geth-based client. It executes block payloads, holds chain state, and exposes the standard Ethereum JSON-RPC API. * **taiko-client** (consensus client) — decodes L2 blocks from L1 calldata/blobspace and passes payloads to the execution engine. ::::steps #### Build an execution engine Choose the execution engine you want to run. Check out the matching release from the relevant releases page before building. :::code-group ```bash [alethia-reth] git clone https://github.com/taikoxyz/alethia-reth.git cd alethia-reth git checkout cargo build --release ``` ```bash [taiko-geth] git clone https://github.com/taikoxyz/taiko-geth.git cd taiko-geth git checkout make geth ``` ::: #### Build taiko-client Clone the monorepo and check out the release branch from the [releases page](https://github.com/taikoxyz/taiko-mono/releases) (search for `taiko-client`): ```bash git clone https://github.com/taikoxyz/taiko-mono.git cd taiko-mono/packages/taiko-client git checkout make build ``` #### Create a JWT secret The execution engine and taiko-client communicate over the Engine API, secured by a shared secret: ```bash openssl rand -hex 32 > jwt.txt ``` Copy `jwt.txt` into both the execution engine and `taiko-client` directories, or pass the same absolute path to both commands. #### Start execution engine :::code-group ```bash [Mainnet - alethia-reth] mkdir -p ./data/alethia-reth ./target/release/alethia-reth node \ --chain mainnet \ --datadir ./data/alethia-reth \ --http \ --http.addr 0.0.0.0 \ --http.port 8545 \ --http.api eth,net,debug,trace,rpc \ --ws \ --ws.addr 0.0.0.0 \ --ws.port 8546 \ --metrics 0.0.0.0:6060 \ --color never \ --enable-discv5-discovery \ --engine.persistence-threshold 128 \ --engine.memory-block-buffer-target 128 \ --rpc.eth-proof-window 1209600 \ --authrpc.addr 0.0.0.0 \ --authrpc.port 8551 \ --authrpc.jwtsecret ./jwt.txt \ --ipcpath ./data/alethia-reth/reth.ipc \ --bootnodes "enode://266a8e3b5e44201eca9c368d58aa59a7750295397e77d5b32aea2644f9962cbc4e1cb0543aab0480995a209408174413f65e5ce253d60bb83d22d3b8ab12eb89@34.142.239.251:30303,enode://d94d78fa9c3be00d403788bcbcbfe7f99efb8db26b04b38100f520a38ee40a29b5f6b7ab01e4f8908e0683d3153fa840264500bc72c114c08b0eb770b6ce52f5@34.126.181.0:30303,enode://27384375dbbfd8af5df71392fceb01b93cef1f674e4884fb481be145426f9ce5706941fd93928101a3079a52e621d8a42d266ab9165f4f960233adce22e905f8@34.21.195.34:30303" ``` ```bash [Mainnet - taiko-geth] ./build/bin/geth \ --taiko \ --networkid 167000 \ --gcmode archive \ --datadir ./data/taiko-geth \ --metrics \ --metrics.expensive \ --metrics.addr "0.0.0.0" \ --bootnodes enode://266a8e3b5e44201eca9c368d58aa59a7750295397e77d5b32aea2644f9962cbc4e1cb0543aab0480995a209408174413f65e5ce253d60bb83d22d3b8ab12eb89@34.142.239.251:30303,enode://d94d78fa9c3be00d403788bcbcbfe7f99efb8db26b04b38100f520a38ee40a29b5f6b7ab01e4f8908e0683d3153fa840264500bc72c114c08b0eb770b6ce52f5@34.126.181.0:30303,enode://27384375dbbfd8af5df71392fceb01b93cef1f674e4884fb481be145426f9ce5706941fd93928101a3079a52e621d8a42d266ab9165f4f960233adce22e905f8@34.21.195.34:30303 \ --authrpc.addr "0.0.0.0" \ --authrpc.port 8551 \ --authrpc.vhosts "*" \ --authrpc.jwtsecret ./jwt.txt \ --http \ --http.api debug,eth,net,web3,txpool,taiko \ --http.addr "0.0.0.0" \ --http.port 8545 \ --http.vhosts "*" \ --ws \ --ws.api debug,eth,net,web3,txpool,taiko \ --ws.addr "0.0.0.0" \ --ws.port 8546 \ --ws.origins "*" \ --gpo.ignoreprice "25000000" \ --port 30306 \ --discovery.port 30306 \ --syncmode full \ --state.scheme=path ``` ```bash [Hoodi Testnet - taiko-geth] ./build/bin/geth \ --taiko \ --networkid 167013 \ --gcmode archive \ --datadir ./data/taiko-geth \ --metrics \ --metrics.expensive \ --metrics.addr "0.0.0.0" \ --bootnodes enode://eb5079aae185d5d8afa01bfd2d349da5b476609aced2b57c90142556cf0ee4a152bcdd724627a7de97adfc2a68af5742a8f58781366e6a857d4bde98de6fe986@34.44.53.195:30303,enode://dc1adc9fe0b23bcafb4a3929e14df0f020e0168886991ec26e6ca2fd8b86541f70edde6f0933b186f6e675b6ef5a7e0c7e9a96ffa3337c6afa28c10727b8a868@34.58.49.30:30303,enode://44503022a2ba9d554dc25530917a887686174e100b02a988b8e79cc35d8f174140ae1e4809c3a4c8ee64a3dc51e8c57967f5ed6d9bf661c233e40a00657e121d@104.197.222.109:30303 \ --authrpc.addr "0.0.0.0" \ --authrpc.port 8551 \ --authrpc.vhosts "*" \ --authrpc.jwtsecret ./jwt.txt \ --http \ --http.api admin,debug,eth,net,web3,txpool,miner,taiko \ --http.addr "0.0.0.0" \ --http.port 8545 \ --http.vhosts "*" \ --ws \ --ws.api admin,debug,eth,net,web3,txpool,miner,taiko \ --ws.addr "0.0.0.0" \ --ws.port 8546 \ --ws.origins "*" \ --gpo.ignoreprice "25000000" \ --port 30306 \ --discovery.port 30306 \ --syncmode full \ --state.scheme=path ``` ```bash [Hoodi Testnet - alethia-reth] mkdir -p ./data/alethia-reth ./target/release/alethia-reth node \ --chain taiko-hoodi \ --datadir ./data/alethia-reth \ --http \ --http.addr 0.0.0.0 \ --http.port 8545 \ --http.api eth,net,debug,trace,rpc \ --ws \ --ws.addr 0.0.0.0 \ --ws.port 8546 \ --metrics 0.0.0.0:6060 \ --color never \ --enable-discv5-discovery \ --engine.persistence-threshold 128 \ --engine.memory-block-buffer-target 128 \ --rpc.eth-proof-window 1209600 \ --authrpc.addr 0.0.0.0 \ --authrpc.port 8551 \ --authrpc.jwtsecret ./jwt.txt \ --ipcpath ./data/alethia-reth/reth.ipc \ --bootnodes "enode://eb5079aae185d5d8afa01bfd2d349da5b476609aced2b57c90142556cf0ee4a152bcdd724627a7de97adfc2a68af5742a8f58781366e6a857d4bde98de6fe986@34.44.53.195:30303,enode://dc1adc9fe0b23bcafb4a3929e14df0f020e0168886991ec26e6ca2fd8b86541f70edde6f0933b186f6e675b6ef5a7e0c7e9a96ffa3337c6afa28c10727b8a868@34.58.49.30:30303,enode://44503022a2ba9d554dc25530917a887686174e100b02a988b8e79cc35d8f174140ae1e4809c3a4c8ee64a3dc51e8c57967f5ed6d9bf661c233e40a00657e121d@104.197.222.109:30303" ``` ::: Start the execution engine first. It will wait for taiko-client to connect. #### Start taiko-client Set your L1 endpoint environment variables: ```bash export L1_ENDPOINT_WS= export L1_BEACON_HTTP= export PUBLIC_IP= export PRIV_RAW= ``` :::code-group ```bash [Mainnet] ./bin/taiko-client driver \ --l1.ws "${L1_ENDPOINT_WS}" \ --l2.ws ws://localhost:8546 \ --l1.beacon "${L1_BEACON_HTTP}" \ --l2.auth http://localhost:8551 \ --inbox 0x6f21C543a4aF5189eBdb0723827577e1EF57ef1f \ --taikoAnchor 0x1670000000000000000000000000000000010001 \ --verbosity 3 \ --jwtSecret ./jwt.txt \ --p2p.sync \ --p2p.checkPointSyncUrl https://rpc.mainnet.taiko.xyz \ --p2p.bootnodes enode://c263741b17759f3850d24d67d6c3cbc307c73e17d80c6b12a63a4792a10529d1125d00ecf7ef4c9b0dc51d28b94dfc1b8798fb524f61a1f93946748649f73b23@34.142.239.251:4001?discport=30304,enode://67c739e00a9b6476fce8f9d3cf0ae12589c325c51520da75c2dbfe5094d5c9ef72abf0e368316b10e8332b96e1886869164113a86b66f7f8b989ed0d8dee8895@34.126.181.0:4001?discport=30304,enode://a31855cd5c4138327617bde2e87418774d03c40cd7217344e24f6d906a8ca72c777d65ed9bd38b20e03fa5f91302ae690b00963cd490011c549189ac24e0d1b9@34.21.195.34:4001?discport=30304 \ --p2p.listen.ip 0.0.0.0 \ --p2p.advertise.ip ${PUBLIC_IP} \ --p2p.listen.tcp 4001 \ --p2p.advertise.tcp 4001 \ --p2p.listen.udp 30303 \ --p2p.advertise.udp 30303 \ --p2p.peerstore.path /node-keys/peerstore \ --p2p.discovery.path /node-keys/discv5 \ --preconfirmation.serverPort 9871 \ --preconfirmation.jwtSecret ./jwt.txt \ --p2p.useragent taiko \ --p2p.priv.raw "${PRIV_RAW}" ``` ```bash [Hoodi Testnet] ./bin/taiko-client driver \ --l1.ws "${L1_ENDPOINT_WS}" \ --l2.ws ws://localhost:8546 \ --l1.beacon "${L1_BEACON_HTTP}" \ --l2.auth http://localhost:8551 \ --inbox 0xeF4bB7A442Bd68150A3aa61A6a097B86b91700BF \ --taikoAnchor 0x1670130000000000000000000000000000010001 \ --verbosity 3 \ --jwtSecret ./jwt.txt \ --p2p.sync \ --p2p.checkPointSyncUrl https://rpc.hoodi.taiko.xyz \ --p2p.peerstore.path ./peerstore \ --p2p.discovery.path ./discv5 \ --preconfirmation.serverPort 9871 \ --preconfirmation.jwtSecret ./jwt.txt \ --p2p.listen.ip 0.0.0.0 \ --p2p.useragent taiko \ --p2p.bootnodes enode://b2d094ade1ce68990878b197bf818bd41d5b32e4019d42dc63d91d7020f531532f063833e44e84f78792969f69fd5553370216703c40fcc0cb835f17177fbe07@34.63.52.157:4001?discport=30304,enode://4f075635abd45a468e2fffeac97dad6e275d5728449054fbf265478b26db848092631c8e3cc287e5ab49cfa4e5ad4a53c2f0f4369d17c948fb0e08a6ceabc448@34.58.49.30:4001?discport=30304 \ --p2p.listen.tcp 4001 \ --p2p.advertise.tcp 4001 \ --p2p.listen.udp 30303 \ --p2p.advertise.udp 30303 \ --p2p.advertise.ip ${PUBLIC_IP} \ --p2p.priv.raw "${PRIV_RAW}" ``` ::: :::info To run without P2P preconfirmations, remove all `--p2p.*` and `--preconfirmation.*` flags except `--p2p.sync` and `--p2p.checkPointSyncUrl`. Your node will only update when events are emitted on-chain. ::: :::warning For Hoodi testnet, if you run an Ethereum Hoodi beacon client, configure it for data column sampling (Fusaka upgrade). Required flags by client: * **Lighthouse:** `--semi-supernode` or `--supernode` * **Teku:** `--p2p-subscribe-all-custody-subnets-enabled` * **Grandine:** `--subscribe-all-data-column-subnets` * **Lodestar:** `--supernode` * **Nimbus:** `--debug-peerdas-supernode` Alternatively, set a `--blob.server` URL pointing to a blob indexer service. ::: :::: ### Monitoring #### Grafana Dashboard (Docker) A Grafana dashboard runs at `http://localhost:3001` (or your custom `GRAFANA_PORT`): ``` http://localhost:3001/d/L2ExecutionEngine/l2-execution-engine-overview ``` #### Docker CLI Reference | Action | Command | | -------------------------------- | --------------------------------------------------- | | Start | `docker compose up -d` | | Stop | `docker compose down` | | Restart | `docker compose down && docker compose up -d` | | Update | `git checkout && docker compose pull` | | Remove (with data) | `docker compose down -v` | | View all logs | `docker compose logs -f` | | View alethia-reth execution logs | `docker compose logs -f reth_execution_engine` | | View taiko-geth execution logs | `docker compose logs -f geth_execution_engine` | | View driver logs | `docker compose logs -f taiko_client_driver` | | Resource usage | `docker stats` | For Hoodi testnet, add `-f docker-compose-hoodi.yml` to the Docker Compose commands. ### Troubleshooting | Problem | Cause | Fix | | ------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `Caught SIGILL in blst_cgo_init` | Older CPU incompatible with blst | Set `CGO_CFLAGS="-O -D__BLST_PORTABLE__"` and `CGO_CFLAGS_ALLOW="-O -D__BLST_PORTABLE__"` | | `beacon client not found` | Missing or incorrect `--l1.beacon` flag | Set `L1_BEACON_HTTP` in `.env` or pass `--l1.beacon` with a valid beacon endpoint | | `Dial tcp: lookup l2_execution_engine ... server misbehaving` | L1 node out of sync or rate-limited | Verify L1 sync status; run your own L1 node instead of a rate-limited provider | | `no service selected` | Outdated simple-taiko-node | Pull the latest version and set `COMPOSE_PROFILES` in `.env` | | `failed to check whether L1 chain has been reorged` | BlockPi archive mode disabled | Enable the Archive feature on BlockPi, or use your own L1 node | | `Looking for peers` (stuck) | P2P sync issue | Set `DISABLE_P2P_SYNC=true` in `.env` and restart | | `Bind for 0.0.0.0:6060 failed: port is already allocated` | Port conflict | Stop the conflicting service or change the port in `.env` | | `Required flag "l2.suggestedFeeRecipient" not set` | Spaces in `.env` values | Remove all trailing spaces from `.env` fields | | `Unknown shorthand flag: 'd' in -d` | Docker Compose v1 | Upgrade to [Docker Compose v2](https://docs.docker.com/compose/install/linux/) or use `docker-compose up -d` (hyphenated) | | `/bin/sh: ... not found` (Windows) | Windows line endings (CRLF) | Delete the repo, run `git config --global core.autocrlf false`, and re-clone | | `Dial tcp: connect: connection refused` | Firewall blocking ports | Check firewall rules with `sudo ufw status` and allow the required ports | | `No contract code at given address` | Node not synced or wrong network | Wait for L1 to fully sync; verify you are on the correct network | | `Database contains incompatible genesis` | Old testnet data | Run `docker compose down -v` to remove old volumes | | `genesis header hash mismatch` | Wrong docker-compose file | Use the correct file for your network (e.g., `docker-compose-hoodi.yml` for Hoodi) |