Cronos zkEVM Mainnet

This guide covers running a node for Cronos zkEVM mainnet (Chain ID: 388) with external-node v24.23.0 on docker.

Pre-requisites

• Docker and Docker-compose

Prepare your machine

This configuration is approximate and should be considered as minimal requirements for:

Full Node

Full Node - is configured to build and store the last 7 days of data for Cronos zkEVM mainnet by default. Check here for details on the pruning setting.

Minimal requirements:

• 4-core of CPU

• 16GB of RAM

• 100G of SSD storage

Archive Node

Archive Node - is configured to build an archive of all historical data of Cronos zkEVM mainnet;

Minimal requirements:

• 4-core of CPU

• 32GB of RAM

• 500G of SSD storage

Step 1: Download the DB Dump

1.1 - Download the pgdump

Create a new folder and download the dump file into it:

wget https://storage.googleapis.com/cronos-zkevm-mainnet-en-pgdump/external_node.tar.gz

1.2 - Extract the data from dump

After extracting the file, locate the dump folder and the pg_restore.list file. Put both to the main directory, instead of default under “external_node”.

Step 2: Docker Preparations

2.1 - Pull Docker Image

Under the same directory, pull docker image from Github Container Registry:

docker pull ghcr.io/cronos-labs/external-node:mainnet-v24.23.0

2.2 - Create Docker Compose Configuration

Inside that directory, create and edit docker-compose.yml :

nano docker-compose.yml

Add the following configuration to docker-compose.yml:

Full Node

services: 
  cronoszk:
    image: "ghcr.io/cronos-labs/external-node:mainnet-v24.23.0"
    network_mode: host
    restart: unless-stopped
    stop_grace_period: "120s"
    user: 0:0  
    volumes:
      - "${PWD}:/db"  
    environment:
      DATABASE_POOL_SIZE: 10
      DATABASE_URL: "postgresql://zksync:password@localhost:5432/zksync"
      EN_ETH_CLIENT_URL: "https://ethereum-rpc.publicnode.com"
      EN_HEALTHCHECK_PORT: 3081
      EN_HTTP_PORT: 3060
      EN_L1_BATCH_COMMIT_DATA_GENERATOR_MODE: "Validium"
      EN_L1_CHAIN_ID: 1
      EN_L2_CHAIN_ID: 388
      EN_MAIN_NODE_URL: "https://seed.zkevm.cronos.org"    
      EN_MERKLE_TREE_PATH: "./db/ext-node/lightweight"
      EN_PROMETHEUS_PORT: 3312
      EN_PRUNING_ENABLED: "true"  #Note: Default value is false, i.e. no purning
      EN_REQ_ENTITIES_LIMIT: 1000
      EN_SNAPSHOTS_RECOVERY_ENABLED: "true"
      EN_SNAPSHOTS_OBJECT_STORE_BUCKET_BASE_URL: "cronos-zkevm-mainnet-en-snapshot"
      EN_SNAPSHOTS_OBJECT_STORE_MODE: 'GCSAnonymousReadOnly'
      EN_STATE_CACHE_PATH: "./db/ext-node/state_keeper"
      EN_WS_PORT: 3061
      RUST_LOG: "warn,zksync=info,zksync_core::metadata_calculator=debug,zksync_state=debug,zksync_utils=debug,zksync_web3_decl::client=error"
  postgres:
    image: postgres:16
    restart: unless-stopped
    stop_grace_period: "120s"
    network_mode: host
    environment:
      POSTGRES_DB: zksync
      POSTGRES_USER: zksync
      POSTGRES_PASSWORD: password
    ulimits:
      nofile: 60000
      nproc: 60000
      memlock: -1
    volumes:
      - "${PWD}/pgsql_data:/var/lib/postgresql/data/"
      - "${PWD}:/dump"

Archive Node

services: 
  cronoszk:
    image: "ghcr.io/cronos-labs/external-node:mainnet-v24.23.0"
    network_mode: host
    restart: unless-stopped
    stop_grace_period: "120s"
    user: 0:0  
    volumes:
      - "${PWD}:/db"  
    environment:
      DATABASE_POOL_SIZE: 10
      DATABASE_URL: "postgresql://zksync:password@localhost:5432/zksync"
      EN_ETH_CLIENT_URL: "https://ethereum-rpc.publicnode.com"
      EN_HEALTHCHECK_PORT: 3081
      EN_HTTP_PORT: 3060
      EN_L1_BATCH_COMMIT_DATA_GENERATOR_MODE: "Validium"
      EN_L1_CHAIN_ID: 1
      EN_L2_CHAIN_ID: 388
      EN_MAIN_NODE_URL: "https://seed.zkevm.cronos.org"    
      EN_MERKLE_TREE_PATH: "./db/ext-node/lightweight"
      EN_PROMETHEUS_PORT: 3312
      EN_PRUNING_ENABLED: "false"  #Note: Default value is false, i.e. no purning
      EN_REQ_ENTITIES_LIMIT: 1000
      EN_SNAPSHOTS_RECOVERY_ENABLED: "false"
      EN_STATE_CACHE_PATH: "./db/ext-node/state_keeper"
      EN_WS_PORT: 3061
      RUST_LOG: "warn,zksync=info,zksync_core::metadata_calculator=debug,zksync_state=debug,zksync_utils=debug,zksync_web3_decl::client=error"
  postgres:
    image: postgres:16
    restart: unless-stopped
    stop_grace_period: "120s"
    network_mode: host
    environment:
      POSTGRES_DB: zksync
      POSTGRES_USER: zksync
      POSTGRES_PASSWORD: password
    ulimits:
      nofile: 60000
      nproc: 60000
      memlock: -1
    volumes:
      - "${PWD}/pgsql_data:/var/lib/postgresql/data/"
      - "${PWD}:/dump"

Important

Make sure you have the correct vars, volume attachment under the correct path.

Note

• EN_PRUNING_ENABLED: Determines whether the node is set to pruning mode. When enabled, the node retains only recent chain data and discards older data to conserve storage space.

• EN_SNAPSHOTS_RECOVERY_ENABLED, EN_SNAPSHOTS_OBJECT_STORE_BUCKET_BASE_URL, and EN_SNAPSHOTS_OBJECT_STORE_MODE: Enable snapshots recovery (similar to state-sync) and allows the node to recover from the latest batch without containing the full historical data.

• Add debug to namespaces: Enables debug tracing and saves debug data.EN_API_NAMESPACES:Defines the enabled API namespaces, including eth, net, web3, zks, pubsub, and debug.

• Read more on Snapshots Recovery here.

Step 3: Database Restoration

3.1 - Start PostgreSQL Container:

docker compose up -d postgres

Please note postgres was named in docker-compose.

When container is running, list containers to find the container ID:

docker ps

Below is the example output:

CONTAINER ID   IMAGE         COMMAND                  CREATED          STATUS          PORTS     NAMES
e29741123132   postgres:16   "docker-entrypoint.s…"   31 seconds ago   Up 30 seconds             zkevm_mainnet-postgres-1

3.2 - Restore Database from Dump

Run the following and docker retrieve and manipulate the data from data dump:

docker exec -it <container_ID> pg_restore -x -O -j2 -L <pg_restore.list_location>  -d <database_name> -U <username>  <path_to_dump_you_attached_in_volumes_docker_compose>

Example:

docker exec -it e29741123132 pg_restore -x -O -j2 -L /dump/pg_restore.list  -d zksync -U zksync  /dump/dump

NOTE

The username and database names were defined in thedocker-compose; in this example, they are zksync and zksync, respectively.

During the process, on the docker side, you should see:

The duration of the process may vary depending on the specifications, potentially taking several hours.

Step 4: Run Everything

Once the pg restore completed, start the cronoszk node service:

docker compose up -d 

Example output should be like:

[+] Running 2/2
 ✔ Container zkevm_mainnet-cronoszk-1  Started                                                                                                                        0.1s 
 ✔ Container zkevm_mainnet-postgres-1  Running  

You should see in the Docker logs that the node is fetching block data from the RPCs.

For example:

Once the node is synchronized, you may use EN_HTTP_PORT: 3060 as defined for ETH-JSON RPC calls.