Polygon zkEVM

Instructions to set up your Polygon ZkEVM node.

ℹ️

Note: Currently ARM-based CPUs are not supported

Requirements

Setup your Axelar validator
Minimum hardware requirements: 4 cores, 32G RAM, 128G Disk with high IOPS.
Ubuntu 22.04, Docker(tested on 22.04)
Official Documentation
Official Documentation

Prerequisites

This is the most straightforward path to run a zkEVM node, and it’s perfectly fine for most use cases, This is quite opinionated, feel free to run this software in a different way, for instance it’s not needed to use Docker, you could use the Go and C++ binaries directly. Some instructions to install Prerequisites are give here however be sure to check the official documentation to install docker compose in case this doesn’t work

sudo apt-get install jq -y
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

Create necessary directories

You can modify the paths as per your requirements

# ZKEVM CONFIG DIR
mkdir -p ~/.zkevm/config
# ZKEVM NODE STATEDB DATA DIR
mkdir -p ~/.zkevm/data/statedb
# ZKEVM NODE POOLDB DATA_ DIR
mkdir -p ~/.zkevm/data/pooldb

Get network configurations

Storing directory paths to variables to reuse

ZKEVM_NET=mainnet

ZKEVM_NET=testnet

ZKEVM_DIR=~/.zkevm
ZKEVM_CONFIG_DIR=~/.zkevm/config

Fetch network configuration files

# get zip and unzip into $ZKEVM_DIR
curl -L https://github.com/0xPolygonHermez/zkevm-node/releases/latest/download/$ZKEVM_NET.zip > $ZKEVM_NET.zip && unzip -o $ZKEVM_NET.zip -d $ZKEVM_DIR && rm $ZKEVM_NET.zip
# create .env file from example.env
cp $ZKEVM_DIR/$ZKEVM_NET/example.env $ZKEVM_CONFIG_DIR/.env

Set node config

Update the variables in $ZKEVM_CONFIG_DIR/.env

# your network could be either mainnet or testnet, we defined this earlier
ZKEVM_NETWORK=$ZKEVM_NET
# L1 node rpc
ZKEVM_NODE_ETHERMAN_URL="your_ETH_rpc"
# ZKEVM NODE STATEDB DATA DIR, we created this earlier
ZKEVM_NODE_STATEDB_DATA_DIR="$HOME/.zkevm/data/statedb"
# ZKEVM NODE POOLDB DATA_ DIR, we created this earlier
ZKEVM_NODE_POOLDB_DATA_DIR="$HOME/.zkevm/data/pooldb"

ℹ️

Note: ZKEVM_NODE_ETHERMAN_URL must point to the validator’s ethereum rpc node for security

Optional

We will need to use directories defined earlier when we want to pass config and env file to docker-compose, it would be nice to persist them across sessions Add them to your shell file of your choice

ZKEVM_NET=testnet
ZKEVM_DIR=~/.zkevm
ZKEVM_CONFIG_DIR=~/.zkevm/config

Start the node

sudo docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml up -d

This should show an output like this:

   ⠿ b08a0a826235 Pull complete                                                                                                                             90.5s
   ⠦ d71d159599c3 Downloading [>                                                  ]  
   ...

After it is done, verify by listing the services and their status

docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml ps

You should see the following containers running

docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml ps

NAME                IMAGE                                      COMMAND                  SERVICE             CREATED             STATUS                    PORTS
zkevm-pool-db       postgres                                   "docker-entrypoint.s…"   zkevm-pool-db       12 minutes ago      Up 12 minutes (healthy)   0.0.0.0:5433->5432/tcp, :::5433->5432/tcp
zkevm-prover        hermeznetwork/zkevm-prover:v1.1.4-fork.4   "zkProver -c /usr/sr…"   zkevm-prover        12 minutes ago      Up 12 minutes             0.0.0.0:50061->50061/tcp, :::50061->50061/tcp, 0.0.0.0:50071->50071/tcp, :::50071->50071/tcp
zkevm-rpc           hermeznetwork/zkevm-node:v0.1.2            "/bin/sh -c '/app/zk…"   zkevm-rpc           12 minutes ago      Up 12 minutes             0.0.0.0:8545->8545/tcp, :::8545->8545/tcp, 8123/tcp, 0.0.0.0:9091->9091/tcp, :::9091->9091/tcp
zkevm-state-db      postgres                                   "docker-entrypoint.s…"   zkevm-state-db      12 minutes ago      Up 12 minutes (healthy)   0.0.0.0:5432->5432/tcp, :::5432->5432/tcp
zkevm-sync          hermeznetwork/zkevm-node:v0.1.2            "/bin/sh -c '/app/zk…"   zkevm-sync          12 minutes ago      Up 12 minutes             8123/tcp

Check logs

Verify zkevm-rpc logs

sudo docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml logs zkevm-rpc -f

You should see logs like

zkevm-rpc  | 2023-06-25T05:53:07.044Z   INFO    state/l2block.go:104    new l2 blocks detected, Number 9294, Hash 0x1395cd706d44cff77f895b499c6edb12ab2590d5bada01c0e281813ed059e9fa        {"pid": 1, "version": "v0.1.2"}
zkevm-rpc  | 2023-06-25T05:53:07.045Z   INFO    state/l2block.go:104    new l2 blocks detected, Number 9295, Hash 0x9e60cef2b322bc0452b74f0ac29ce147e24765251de09b03c4bf949358fce789        {"pid": 1, "version": "v0.1.2"}
zkevm-rpc  | 2023-06-25T05:53:24.062Z   INFO    state/l2block.go:104    new l2 blocks detected, Number 9296, Hash 0x3d74c8d35b1a60a9c345dcb70239635e69a3579361ee6d11d81c942e626e8ccf        {"pid": 1, "version": "v0.1.2"}
zkevm-rpc  | 2023-06-25T05:53:24.062Z   INFO    state/l2block.go:104    new l2 blocks detected, Number 9297, Hash 0x21c3a1ef7098e26dca1d9f77525e2ecd2d5e7ca8e7f9a070d92725ee3071bc47        {"pid": 1, "version": "v0.1.2"}
zkevm-rpc  | 2023-06-25T05:53:24.063Z   INFO    state/l2block.go:104    new l2 blocks detected, Number 9298, Hash 0x951d2aac1a0fb068b3cb34cb5bc7608b845108ffda4e8f8d54d56a051d6e60b4        {"pid": 1, "version": "v0.1.2"}
zkevm-rpc  | 2023-06-25T05:53:24.063Z   INFO    state/l2block.go:104    new l2 blocks detected, Number 9299, Hash 0x824b0fae2fdfefb67bd5840700eb91e4dc435e5e9bb26353e6c2cbf09f45da19        {"pid": 1, "version": "v0.1.2"}
zkevm-rpc  | 2023-06-25T05:53:24.063Z   INFO    state/l2block.go:104    new l2 blocks detected, Number 9300, Hash 0x7596608aae585568e2c3be91ffa21c898508cb3d39aa6f7cb94533bb0da87db5        {"pid": 1, "version": "v0.1.2"}
zkevm-rpc  | 2023-06-25T05:53:24.064Z   INFO    state/l2block.go:104    new l2 blocks detected, Number 9301, Hash 0x6f3bf5c0c1a60a277db53a65b1b6c1885d99d7365880d328f25db1525bdf8952        {"pid": 1, "version": "v0.1.2"}
zkevm-rpc  | 2023-06-25T05:53:24.064Z   INFO    state/l2block.go:104    new l2 blocks detected, Number 9302, Hash 0x54540dd02f16197734fa4597fe691d37fb3f0dd4386734795ccab853eb78c87d        {"pid": 1, "version": "v0.1.2"}

Similarly, you can check logs for other containers too

#check logs
sudo docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml logs zkevm-pool-db -f
sudo docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml logs zkevm-prover -f
sudo docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml logs zkevm-rpc -f
sudo docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml logs zkevm-state-db -f
sudo docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml logs zkevm-sync -f

curl -H "Content-Type: application/json" -X POST --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":83}' http://localhost:8545 | jq
{
  "jsonrpc": "2.0",
  "id": 83,
  "result": "0x802"
}

Verify node sync status

RPC Endpoint

echo "$(curl -4 ifconfig.co):8545"

Method 1:

curl -X POST [rpc] -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | jq

If you get something like this in response to the above rpc call, your node is setup correctly

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

You can use a hex to number convertor to get the block height

You can compare the block height on your node with explorer (mainnet or testnet), use your RPC node only when it has caught up with the latest block height.

Configure vald

In order for vald to connect to your Zk EVM node, your rpc_addr should be exposed in vald’s config.toml

[[axelar_bridge_evm]]
name = "polygon-zkevm"
rpc_addr = "http://IP:PORT"
start-with-bridge = true

[[axelar_bridge_evm]]
name = "polygon-zkevm"
rpc_addr = "http://IP:PORT"
start-with-bridge = true

Common Node Operations

To start

sudo docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml up -d

To stop

sudo docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml down

To update

To update the zkNode software, repeat the setup steps, being careful not to overwrite the configuration files that you have modified.

To stop and wipe out everything

sudo docker-compose --env-file $ZKEVM_CONFIG_DIR/.env -f $ZKEVM_DIR/$ZKEVM_NET/docker-compose.yml down -v

Edit this page