Run Local Validium Node

Setting Up a Validium on Lumia L2

This quick start guide will walk you through the process of setting up a CDK validium on your local machine for the Lumia L2 network. The setup includes the following components:

  • Lumia zkEVM databases: data node, event, explorer L1 and L2, pool, state, and bridge service

  • Lumia zkEVM node components: aggregator, approve service, sequencer and sequence sender, synchronizer

  • L1 network (mock)

  • Prover

  • Explorers L1, L2

  • JSON RPC explorer

  • L2 gas pricer

  • DAC: data availability service, DAC setup committee

  • Lumia zkEVM bridge service and UI

Note: The documentation describes standard deployments. You can edit the configuration files to implement your own custom setups.

Prerequisites Hardware Requirements:

  • A Linux-based OS (e.g., Ubuntu Server 22.04 LTS)

  • At least 16GB RAM with a 4-core CPU

  • An AMD64 architecture system

Note: CDK does not support ARM-based Macs.

Software Requirements:

  • Go

  • Docker and Docker Compose

Note: This document uses Docker Compose v2.

Installing Make on Ubuntu:

sudo apt install make

Cloning the Repository:

git clone https://github.com/orionprotocol/zkValidium-quickstart.git
cd zkValidium-quickstart

Testnet and Mainnet zkNode Config files required can be downloaded using IPFS links below.

Testnet: ipfs://QmNMnawxoSo7N1xFB73Ygw571T3Cj67Rqg2edsUCNob9h3/lumia-testnet-node-config.zip

Mainnet: ipfs://QmfNFzWVJxiu9JHHAS7rFnnUVCvdVTfrtF6TtmVKkcf1xA/prism-mainnet-node-config.zip

Create the .env file by copying the example:

cp .env.example .env

Launching Validium Locally

Pull the required Docker images from Docker Hub:

sudo docker compose pull

Start your local CDK validium:

sudo make run

Check the status of each container:

sudo docker compose ps

You may see errors related to amd64 such as:

zkevm-prover no matching manifest for linux/arm64/v8 in the manifest list entries

make: *** [run] Error 18

If so, go to the docker-compose.yml, search for the component details - in this case zkevm-prover, and add the platform: linux/amd64 environment variable under the environment variable (which you should also add if it is not there):

environment:
  - EXPERIMENTAL_DOCKER_DESKTOP_FORCE_QEMU=1
platform: linux/amd64

You may find the explorer components affected similarly.

If you receive any errors such as below, make sure your Docker has SUDO rights.

error getting credentials - err: exit status 1

You should see an output similar to the provided container status details.

Container Status
$ sudo docker ps --format "table {{.Names}}\t{{.Command}}\t{{.Status}}\t{{.Ports}}"
NAMES                              COMMAND                  STATUS                    PORTS
explorer-sig-provider              "./sig-provider-serv…"   Up 11 minutes             0.0.0.0:8151->8050/tcp, :::8151->8050/tcp
visualizer-proxy                   "/docker-entrypoint.…"   Up 11 minutes             80/tcp, 0.0.0.0:8083->8081/tcp, :::8083->8081/tcp
explorer-visualizer                "./visualizer-server"    Up 11 minutes             0.0.0.0:8152->8050/tcp, :::8152->8050/tcp
explorer-smart-contract-verifier   "./smart-contract-ve…"   Up 11 minutes             0.0.0.0:8150->8050/tcp, :::8150->8050/tcp
explorer-proxy-l2                  "/docker-entrypoint.…"   Up 11 minutes             0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:8084->8080/tcp, :::8084->8080/tcp
explorer-stats-l2                  "./stats-server"         Up 11 minutes             0.0.0.0:8154->8050/tcp, :::8154->8050/tcp
explorer-stats-db-l2               "docker-entrypoint.s…"   Up 11 minutes             0.0.0.0:7434->5432/tcp, :::7434->5432/tcp
explorer-frontend-l2               "./entrypoint.sh nod…"   Up 11 minutes             0.0.0.0:3001->3000/tcp, :::3001->3000/tcp
explorer-backend-l2                "sh -c 'bin/blocksco…"   Up 11 minutes             0.0.0.0:4001->4000/tcp, :::4001->4000/tcp
zkevm-explorer-json-rpc            "/bin/sh -c '/app/zk…"   Up 11 minutes             0.0.0.0:8124->8124/tcp, :::8124->8124/tcp, 8123/tcp, 0.0.0.0:8134->8134/tcp, :::8134->8134/tcp
explorer-backend-l2-db             "docker-entrypoint.s…"   Up 11 minutes             0.0.0.0:5437->5432/tcp, :::5437->5432/tcp
explorer-proxy-l1                  "/docker-entrypoint.…"   Up 11 minutes             0.0.0.0:81->80/tcp, :::81->80/tcp, 0.0.0.0:8082->8080/tcp, :::8082->8080/tcp
explorer-stats-l1                  "./stats-server"         Up 12 minutes             0.0.0.0:8153->8050/tcp, :::8153->8050/tcp
explorer-stats-db-l1               "docker-entrypoint.s…"   Up 12 minutes             0.0.0.0:7433->5432/tcp, :::7433->5432/tcp
explorer-frontend-l1               "./entrypoint.sh nod…"   Up 12 minutes             0.0.0.0:3000->3000/tcp, :::3000->3000/tcp
explorer-backend-l1                "sh -c 'bin/blocksco…"   Up 12 minutes             0.0.0.0:4000->4000/tcp, :::4000->4000/tcp
explorer-backend-l1-db             "docker-entrypoint.s…"   Up 12 minutes             0.0.0.0:5436->5432/tcp, :::5436->5432/tcp
zkevm-bridge-ui                    "/bin/sh /app/script…"   Up 12 minutes             0.0.0.0:8088->80/tcp, :::8088->80/tcp
zkevm-bridge-service               "/bin/sh -c '/app/zk…"   Up 12 minutes             0.0.0.0:8080->8080/tcp, :::8080->8080/tcp, 0.0.0.0:9090->9090/tcp, :::9090->9090/tcp
zkevm-bridge-db                    "docker-entrypoint.s…"   Up 12 minutes             5438/tcp, 0.0.0.0:5438->5432/tcp, :::5438->5432/tcp
zkevm-json-rpc                     "/bin/sh -c '/app/zk…"   Up 12 minutes             0.0.0.0:8123->8123/tcp, :::8123->8123/tcp, 0.0.0.0:8133->8133/tcp, :::8133->8133/tcp, 0.0.0.0:9091->9091/tcp, :::9091->9091/tcp
zkevm-aggregator                   "/bin/sh -c '/app/zk…"   Up 12 minutes             8123/tcp, 0.0.0.0:50081->50081/tcp, :::50081->50081/tcp, 0.0.0.0:9093->9091/tcp, :::9093->9091/tcp
zkevm-l2gaspricer                  "/bin/sh -c '/app/zk…"   Up 12 minutes             8123/tcp
zkevm-sequence-sender              "/bin/sh -c '/app/zk…"   Up 12 minutes             8123/tcp
zkevm-sequencer                    "/bin/sh -c '/app/zk…"   Up 12 minutes             0.0.0.0:6060->6060/tcp, :::6060->6060/tcp, 0.0.0.0:6900->6900/tcp, :::6900->6900/tcp, 8123/tcp, 0.0.0.0:9092->9091/tcp, :::9092->9091/tcp
zkevm-eth-tx-manager               "/bin/sh -c '/app/zk…"   Up 12 minutes             8123/tcp, 0.0.0.0:9094->9091/tcp, :::9094->9091/tcp
zkevm-sync                         "/bin/sh -c '/app/zk…"   Up 12 minutes             8123/tcp, 0.0.0.0:9095->9091/tcp, :::9095->9091/tcp
zkevm-prover                       "zkProver -c /usr/sr…"   Up 12 minutes             0.0.0.0:50061->50061/tcp, :::50061->50061/tcp, 0.0.0.0:50071->50071/tcp, :::50071->50071/tcp
zkevm-data-availability            "/bin/sh -c '/app/cd…"   Up 12 minutes             0.0.0.0:8444->8444/tcp, :::8444->8444/tcp
zkevm-data-node-db                 "docker-entrypoint.s…"   Up 12 minutes (healthy)   0.0.0.0:5444->5432/tcp, :::5444->5432/tcp
zkevm-mock-l1-network              "geth --http --http.…"   Up 12 minutes             0.0.0.0:8545-8546->8545-8546/tcp, :::8545-8546->8545-8546/tcp, 30303/tcp, 30303/udp
zkevm-event-db                     "docker-entrypoint.s…"   Up 12 minutes             0.0.0.0:5435->5432/tcp, :::5435->5432/tcp
zkevm-pool-db                      "docker-entrypoint.s…"   Up 12 minutes             0.0.0.0:5433->5432/tcp, :::5433->5432/tcp
zkevm-state-db                     "docker-entrypoint.s…"   Up 12 minutes             0.0.0.0:5432->5432/tcp, :::5432->5432/tcp

If a service isn't running (i.e., it is in Exit1 state), investigate further using the logs:

sudo docker compose logs <container_name>
Useful Commands:

  • To stop CDK validium:

    sudo make stop

  • To restart all services:

    sudo make restart

Note: This local deployment runs on an L1 Geth instance.

Testing Validium

  1. Verify the block explorer is running by navigating to localhost.

  2. Add the network to a Web3 wallet (e.g., MetaMask) by following the instructions on how to set up a network manually.

  3. Set the chain ID to 1001 and use "POL" as the currency symbol. The RPC node and block explorer containers can be found at ports 8123 and 80, respectively.

  4. Switch to the new network in MetaMask.

Important: An account with test funds is available with the private key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80.

NEVER transfer real assets to the address associated with this private key.

Import the account to MetaMask. The balance should show up as 100000 POL

  1. Transfer some tokens to another account and confirm the transaction. Check the updated balances.

  2. View the transaction details in the block explorer by clicking on the transaction details in MetaMask.

Troubleshooting Stuck Transactions with MetaMask: If you encounter a stuck transaction, it is likely due to an incorrect nonce setting. To resolve this issue:

  1. Open MetaMask and navigate to your account.

  2. Click on Settings > Advanced.

  3. Locate the option "Clear activity and nonce data" and click on it. This resets the nonce data associated with the account, which often resolves transaction-related issues.

Testing the Bridge

Lumia L2 has a native bridge portal with UI that allows you to transfer funds between the L1 and the L2 validium.

L1 to L2:

  1. Add the L1 RPC to MetaMask and switch to the L1 network. You will see the previously imported account with ~999 POL on the L1 chain.

  2. Verify the bridge UI by navigating to localhost:8088. Click on "Connect a wallet" > "MetaMask" and select the previously imported account.

  3. Enter the amount to bridge (e.g., 5) and click "Continue". After confirming that you understand what you're doing, you will see the "Confirm Bridge" page.

  4. Click "Bridge" and approve the transaction on the MetaMask pop-up. Once bridging is complete, you should see the "Activity" page.

L2 to L1:

  1. Switch the network on MetaMask to your validium chain and navigate back to localhost:8088. You should see both the updated L1 and L2 balances.

  2. Enter an amount and follow the same process to bridge the funds back to L1.

    Note: You cannot bridge back funds more than what you have previously bridged from L1 to L2.

  3. The L2->L1 bridging process is slightly different from L1->L2. After the transaction is executed, you will see the "Activity" page.

  4. Click "Finalise" and approve the transaction. MetaMask will pop up a window asking you to switch to the L1 network first. Once the bridging is complete, you will see the confirmation page.

PreviouszkNodeNextRun an RPC

Last updated