Setup local zkNode

This quick start guide shows you how to deploy a zkEVM rollup stack on your local machine.

It sets up and runs the following components:

• Prover: zkevm-prover
• zkEVM node components: zkevm-sync, zkevm-eth-tx-manager, zkevm-sequencer, zkevm-sequence-sender, zkevm-l2gaspricer, zkevm-aggregator, zkevm-json-rpc
• L1 network: zkevm-mock-l1-network
• zkEVM node databases: zkevm-event-db, zkevm-pool-db, zkevm-state-db
• Explorer databases: zkevm-explorer-l1-db, zkevm-explorer-l2-db
• Explorers: zkevm-explorer-l1, zkevm-explorer-l2, zkevm-explorer-json-rpc

Prerequisites

Hardware

• A Linux-based OS (e.g., Ubuntu Server 22.04 LTS).
• At least 16GB RAM with a 4-core CPU.
• An AMD64 architecture system.

⠇ zkevm-prover 
no matching manifest for linux/arm64/v8 in the manifest list entries
make: *** [run] Error 18

environment:
  - EXPERIMENTAL_DOCKER_DESKTOP_FORCE_QEMU=1
platform: linux/amd64

Software

• go _{version 1.21}
• Docker
• Docker Compose

1. Clone the repo

git clone https://github.com/0xPolygonHermez/zkevm-node.git
cd zkevm-node

2. Build the Docker image

make build-docker

3. Test the environment

zkevm-node provides commands that allow you to interact with smart contracts, run components, create encryption files, and print out debug information.

3.1 Run the environment

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

cd test/

Then:

make run

The 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

You need to bring up the explorer databases and networks separately:

make run-explorer-db run-explorer

3.2 Stop the environment

make stop

3.3 Restart the environment

make restart

4. Test with sample data

4.1 Add example transactions and smart contracts

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"}
...

4.2 Deploy a full Uniswap environment

This example builds out a Uniswap environment which creates token contracts and deploys them, mines tokens, and performs token swaps.

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"}

4.3 Grant the Pol smart contract a set amount of tokens

This sets up accounts with POL and is run as part of the previous examples.

make run-approve-pol

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.
2. Click your account picture and then on Settings.
3. On the left menu, click Networks.

Add zkEVM L2 network

• Click the Add Network button and Add a network manually.
• Enter the following L2 network information:
  1. Network name: Polygon zkEVM - local
  2. New RPC URL: http://localhost:8123
  3. Chain ID: 1001
  4. Currency symbol: (accept default)
  5. Block explorer URL: http://localhost:4000
• Click Save.

Add Geth L1 network

• Click the Add Network button and Add a network manually.
• Enter the following L1 network information:
  1. Network name: Geth - local
  2. New RPC URL: http://localhost:8545
  3. Chain ID: 1337
  4. Currency symbol: ETH
• Click Save.

Environment configurations

• Use the following details for the running components to set up your applications and tests.
• You can find these details in the running logs also.

Databases

zkEVM node state database

• Type: Postgres DB
• User: state_user
• Password: state_password
• Database: state-db
• Host: localhost
• Port: 5432
• URL: postgres://state_user:srare_password@localhost:5432/state-db

zkEVM node pool database

• Type: Postgres DB
• User: pool_user
• Password: pool_password
• Database: pool_db
• Host: localhost
• Port: 5433
• URL: postgres://pool_user:pool_password@localhost:5433/pool_db

zkEVM node JSON-RPC database

• Type: Postgres DB
• User: rpc_user
• Password: rpc_password
• Database: rpc_db
• Host: localhost
• Port: 5434
• URL: postgres://rpc_user:rpc_password@localhost:5434/rpc_db

Explorer L1 database

• Type: Postgres DB
• User: l1_explorer_user
• Password: l1_explorer_password
• Database: l1_explorer_db
• Host: localhost
• Port: 5435
• URL: postgres://l1_explorer_user:l1_explorer_password@localhost:5435/l1_explorer_db

Explorer L2 database

• Type: Postgres DB
• User: l2_explorer_user
• Password: l2_explorer_password
• Database: l2_explorer_db
• Host: localhost
• Port: 5436
• URL: postgres://l2_explorer_user:l2_explorer_password@localhost:5436/l2_explorer_db

Networks

L1 network

• Type: Geth
• Host: localhost
• Port: 8545
• URL: http://localhost:8545

zkEVM node

• Type: JSON RPC
• Host: localhost
• Port: 8123
• URL: http://localhost:8123

Explorers

Explorer L1

• Type: Web
• Host: localhost
• Port: 4000
• URL: http://localhost:4000

Explorer L2

• Type: Web
• Host: localhost
• Port: 4001
• URL: http://localhost:4001

Prover

• Type: Mock
• Host: localhost
• Port: Depending on the prover image, if it's mock or not:
  • Prod prover: 50052 for Prover, 50061 for Merkle Tree, 50071 for Executor
  • Mock prover: 43061 for MT, 43071 for Executor
• URL: http://localhost:50001

Environment addresses

The following addresses are configured into the running environment.

L1 addresses

Deployer account

Sequencer account

Aggregator account

Test accounts with funds

The environment also provides a bunch of test accounts that contain funds.