Run Local Roll-Up Node

Setting Up a Local zkNode on Lumia L2

This guide will walk you through the process of deploying a zkEVM rollup stack on your local machine for the Lumia L2 network. You will set up and run the following components:

  • Prover: lumia-prover

  • zkEVM node components: lumia-sync, lumia-eth-tx-manager, lumia-sequencer, lumia-sequence-sender, lumia-l2gaspricer, lumia-aggregator, lumia-json-rpc

  • L1 network: lumia-mock-l1-network

  • zkEVM node databases: lumia-event-db, lumia-pool-db, lumia-state-db

  • Explorer databases: lumia-explorer-l1-db, lumia-explorer-l2-db

  • Explorers: lumia-explorer-l1, lumia-explorer-l2, lumia-explorer-json-rpc

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



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

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

  • An AMD64 architecture system


  • Go version 1.21

  • Docker

  • Docker Compose

Step 1: Clone the Repository

git clone
cd zkevm-node

Step 2: Build the Docker Image

make build-docker

Note: Rerun this command every time there is a code change.

Step 3: Test the Environment

The test/ directory contains scripts and files for developing and debugging.

cd test/
make run

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 file in the test directory, 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):

platform: linux/amd64

You may find the explorer components affected similarly.


make run command spins up the containers that run the environment, but nothing else. This means that the L2 has no data yet.

Run the explorers:

make run-explorer-db run-explorer

To stop the environment:

make stop

To restart the environment:

make restart

Step 4: Test with Sample Data

This example builds and deploys contracts, funds accounts, and sends some transactions.

make deploy-sc

You should see output similar to this:

2024-04-17T10:05:17.729+0200    INFO    deploy_sc/main.go:42    connecting to Local L1: http://localhost:8545   {"pid": 16869, "version": "v0.1.0"}
2024-04-17T10:05:17.729+0200    INFO    deploy_sc/main.go:45    connected   {"pid": 16869, "version": "v0.1.0"}
2024-04-17T10:05:17.735+0200    DEBUG   deploy_sc/main.go:54    ETH Balance for 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266: 999899846763612022461   {"pid": 16869, "version": "v0.1.0"}
2024-04-17T10:05:17.735+0200    DEBUG   deploy_sc/main.go:57    Sending TX to deploy Counter SC {"pid": 16869, "version": "v0.1.0"}
2024-04-17T10:05:19.763+0200    DEBUG   operations/wait.go:101  Transaction successfully mined: 0xfac2ebc78eada5141cf3737fd5c6ad399d3d18ed7a026d60e87d00c2db0d6ed9  {"pid": 16869, "version": "v0.1.0"}

To deploy a full Uniswap environment:

make deploy-uniswap

You should see output similar to this:

2024-04-17T10:07:56.298+0200    DEBUG   pkg/swap.go:40  after first swap aCoin.balanceOf[0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266]: 989999999999999999950 {"pid": 17666, "version": "v0.1.0"}
2024-04-17T10:07:56.301+0200    DEBUG   pkg/swap.go:43  after first swap bCoin.balanceOf[0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266]: 980000000000000000009 {"pid": 17666, "version": "v0.1.0"}
2024-04-17T10:07:56.305+0200    DEBUG   pkg/swap.go:46  after first swap cCoin.balanceOf[0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266]: 990000000000000000032 {"pid": 17666, "version": "v0.1.0"}
2024-04-17T10:07:56.306+0200    DEBUG   pkg/swap.go:47  Swaping tokens from B <-> C {"pid": 17666, "version": "v0.1.0"}
2024-04-17T10:07:56.307+0200    DEBUG   pkg/swap.go:62  SwapExactTokensForTokens 0x70e0bA845a1A0F2DA3359C97E0285013525FFC49 <-> 0x4826533B4897376654Bb4d4AD88B7faFD0C98528 pair: 0x09dF250580cb3ba5D061f6dfcA783cDa4caa6461 {"pid": 17666, "version": "v0.1.0"}
2024-04-17T10:07:56.308+0200    DEBUG   pkg/swap.go:67  SwapExactTokensForTokens 0x70e0bA845a1A0F2DA3359C97E0285013525FFC49 <-> 0x4826533B4897376654Bb4d4AD88B7faFD0C98528 reserves 0: 9999999999999999968 1: 10000000000000000036 Block Timestamp: 1713341274  {"pid": 17666, "version": "v0.1.0"}
2024-04-17T10:07:56.309+0200    DEBUG   pkg/swap.go:70  SwapExactTokensForTokens 0x70e0bA845a1A0F2DA3359C97E0285013525FFC49 <-> 0x4826533B4897376654Bb4d4AD88B7faFD0C98528 exactAmountIn: 9 amountOut: 8    {"pid": 17666, "version": "v0.1.0"}
2024-04-17T10:07:58.338+0200    DEBUG   operations/wait.go:101  Transaction successfully mined: 0x5c0a2fdb27f6c681b898101883f278dee1ee78dcdacb8471872e5b00603643fe  {"pid": 17666, "version": "v0.1.0"}

To grant the Pol smart contract a set number of tokens:

make run-approve-pol

Step 5: Set Up MetaMask

To configure MetaMask to use your local environment, make sure the network is running and follow these steps:

  1. Log in to your MetaMask wallet and click on Settings.

  2. On the left menu, click Networks.

Add zkEVM L2 network

Click "Add Network" and entering the following details:

  • Network name: Lumia zkEVM - local

  • New RPC URL: http://localhost:8123

  • Chain ID: 1001

  • Block explorer URL: http://localhost:4000

Add Geth L1 network

Click "Add Network" and entering the following details:

  • Network name: Geth - local

  • New RPC URL: http://localhost:8545

  • Chain ID: 1337

  • Currency symbol: ETH

The environment also provides a set of pre-configured addresses for the deployer account, sequencer account, aggregator account, and test accounts with funds.

You can find the environment configurations, including database details, network information, explorer URLs, and prover settings, in the running logs or refer to the provided documentation.

By following this guide, you can easily set up a local zkNode environment for the Lumia L2 network, allowing you to develop, test, and deploy your zkEVM applications.

Last updated