okx
Build on X Layer
X Layer overview
Network information
Deploying contract
Verifying contract
X Layer bridge overview
Setup nodes
Setup local ZKNodeSetup production ZKNode
RPC endpointsWebsocket endpointsGas station
Architecture
Architecture overview
Tooling and infrastructure
Tooling and infrastructure
Build on X Layer

Setup local ZKNode#

It’s crucial that developers can thoroughly test the network for a developing blockchain technology like X Layer ZKEVM without putting users or themselves at unnecessary risk. Developers should be able to test their smart contracts, experiment with new code, and play around with the network on their local machines. X Layer ZKEVM has a local development environment setup for this reason. This tutorial will help you create a local single-node ZKEVM blockchain with no connections to external peers. It only exists on your local machine.

CAUTION
Currently the ZKProver does not run on ARM-powered Macs. For Windows users, using WSL/WSL2 is not recommended. Unfortunately, Apple M1 chips are not supported for now - since some optimizations on the ZKProver require specific Intel instructions. This means some non-M1 computers won’t work regardless of the OS, for example: AMD.

After completing this tutorial, you will have the following components running:

  • ZKEVM node databases
  • Explorer databases
  • Layer 1 network
  • Prover
  • ZKEVM node components
  • Explorers

Prerequisites#

The tutorial for current version of the environment requires Foundryup, go, docker and docker-compose to be previously installed on your machine. If you don’t have these installed, check out the links provided below:

System requirements#

  • ZKEVM node: 16GB RAM with 4-core CPU
  • Mock ZKProver (Default): 16GB RAM with 4-core CPU
  • Full ZKProver: 1TB RAM with 128-core CPU

If you want to run a full-fledged ZKProver on your own, you’ll need at least 1TB of RAM. If you are unable to meet the Prover requirements, you can still run the zkNode.

Setup ZKNode#

Before starting the ZKEVM node setup, we need to clone the official ZKNode repository from xlayer-node Github.

# latest_version refers to https://github.com/okx/xlayer-node/releases
git clone -b latest_version https://github.com/okx/xlayer-node
cd xlayer-node

The xlayer-node docker image must be built at least once and whenever the code is changed. If you haven’t already built the xlayer-node image, you must run:

make build-docker

Certain commands on the xlayer-node can interact with smart contracts, run specific components, create encryption files, and print debug information. To interact with the binary program, we provide docker-compose files and a Makefile to spin up/down the various services and components, ensuring smooth local deployment and a better command line interface for developers.

Note
All the data is stored inside of each docker container. This means once you remove the container, the data will be lost.

The test/ directory contains scripts and files for developing and debugging. Change the working directory to test/ on your local machine.

cd test/

Now, run the ZKNode environment:

make run

To stop the ZKNode:

make stop

To restart the whole ZKNode environment:

make restart

Configuration parameters#

The Synchronizer regularly pulls for network updates, mainly from Ethereum but also via the Trusted Sequencer’s broadcasting mechanism, in order to stay up-to-date. Unless otherwise specified in the setup, the Synchronizer’s default syncing rate is every 2 seconds. The Keystore file, used to store private keys, is normally required for running the Sequencer & Aggregator but not for a Synchronizer/RPC-setup.

Note
We have the inconvenient situation where the Keystore file is required to run the node when it shouldn’t be, for example, if no transactions are sent to layer 1. Keystore is not required in the Mango Testnet as it uses a trusted sequencer and aggregator. This will be reviewed when a decentralised ZKEVM network is implemented.

Sample data#

It’s important to populate your local ZKEVM node with some data before you start testing out the network. The make run command will execute the containers required to run the environment, but it will not execute anything else. Your local layer 2 network will be essentially empty. The following scripts are available if you require sample data that has already been deployed to the network.

cast send --legacy --from 0x2ECF31eCe36ccaC2d3222A303b1409233ECBB225 --private-key 0xde3ca643a52f5543e84ba984c4419ff40dbabd0e483c31c1d09fee8168d68e38 --rpc-url http://127.0.0.1:8123 0xC949254d682D8c9ad5682521675b8F43b102aec4 --value 10ether

# To add some examples of transactions and smart contracts:
make deploy-sc

# To deploy a full Uniswap environment:
make deploy-uniswap

# To grant the OKB smart contract a set amount of tokens:
make run-approve-matic

Connecting to Metamask#

Note
Metamask requires the network to be running while configuring it, so make sure your network is up.

To configure your MetaMask to use your local ZKEVM environment, follow these steps:

  1. Log in to your MetaMask wallet.
  2. Click on your account picture and then on Settings.
  3. On the left menu, click on Networks.
  4. Click on Add Network button.
  5. Fill in the layer 2 network information:
  6. Click on Save.
  7. Click on Add Network button.
  8. Fill in the layer 1 network information:
  9. Click on Save.

You can now interact with your local ZKEVM network and sign transactions from your MetaMask wallet.

Table of contents