Getting Started with ZK Stack


Getting Started with ZK Stack

Note

A new and improved ZK Stack CLI is coming very soon. The current version is deprecated and may not function as expected.

Development dependencies

Ensure you have followed these instructionsopen in new window to set up dependencies on your machine (don't worry about the Environment section for now).

Deploying locally

  1. Clone the zksync-era repo (or pull the latest if you've already cloned it) and go to the root of it:
git clone https://github.com/matter-labs/zksync-era
  1. Add ZKSYNC_HOME to your path (e.g. ~/.bash_profile, ~/.zshrc ) - don't forget to source your profile file again (or restart your terminal):
export ZKSYNC_HOME=/path/to/zksync/repo/you/cloned
export PATH=$ZKSYNC_HOME/bin:$PATH
  1. Build latest version of zk tools by just running zk on the root of the project.
zk
  1. Last, start the wizard and follow instructions to set up and deploy your new ZK Chain by running zk stack init

    • Initially you want to Configure new chain

    • Give it a name and chain id.

    • Select localhost (default matterlabs/geth) and follow the wizard.

      • If you are doing this for the first time, several components need to be compiled/built, so do not worry if it takes a few minutes. The console will show what is going on anyways.
    • If you don't want to configure any values for now and just want check the build process for a ZK Chain, try out the zk stack demo command.

Note

The commands above are not just running docker containers, but are actually building the code from the repo to spin up your ZK Chain. For this reason the process might take some time. If you just want to run docker containers to play around with a zkSync chain, you can use npx zksync-cli dev. Learn more here.

Your ZK Chain is now deployed

Your ZK Chain is now deployed to the base chain (most likely a local geth docker container) and configured. You can find all configuration in a new .env file created on <project root>/etc/env/<your_chain_name_slug>.env, and if you deployed test tokens, their addresses will be available at <project root>/etc/tokens/<the_l1_identifier>.json

  1. The wizard allows you to run the server in the end. If you chose not to, you’re still able to run it by executing
zk server --components "http_api,eth,state_keeper,housekeeper"
  1. You can now run transactions and start playing with your ZK Chain by using the RPC available at http://localhost:3050open in new window.

    • Don't forget to deposit some ETH and fund your accounts on your ZK Chain. To do so follow the instructions for Funding accounts.

Using your ZK Chain

Funding accounts

During the zk stack init configurator, you have a choice of what base layer to deploy the ZK Chain onto: the local geth node, or an Ethereum network (e.g., Sepolia). The first step to start interacting with your ZK Chain is to fund an account (or a few). This means you need some funds on the base layer.

Base layer is the local geth node (@matterlabs/geth:latestopen in new window)

  • If you chose to deploy on local geth node, you will have a set of addresses that have 100 ETH each. You can find the list hereopen in new window and use these addresses to deposit into your ZK Chain via the bridge.

Base layer is an Ethereum network (e.g., Sepolia)

  • If you chose to deploy on an Ethereum network (e.g., Sepolia), you need to have an account on the base layer with ETH. You can use the deployer, governor, or operator wallets setup during the the deployment process, or any other one you have funds, to deposit into your ZK Chain via the bridge.

Once you have the accounts with funds on the L1 base layer, you can do a deposit via the bridge to your ZK Chain, and any further interactions with your ZK Chain.

Using your ZK Chain RPC

Your server contains both HTTPS as well as WebSocket (WS) services that are fully web3 compatible (and contain some extra ZK Stack functionalities). Learn more about it here.

Using zksync-cliopen in new window

zkSync CLI allows you to easily interact and develop applications on your ZK Chain. When executing any command with zksync-cli, you can specify RPC urls for both L1 and L2. Your local server contains RPCs for both. An example deposit command via the bridge would look like:

npx zksync-cli bridge deposit --rpc=http://localhost:3050 --l1-rpc=http://localhost:8545 --zeek

Using Portalopen in new window

The dApp Portal module allows you to:

  • View balances, transfer and bridge tokens to your ZK Chain.
  • Add contacts for quick and easy access.

You can run the Portal module locally, and point it to your ZK Chain configuration. It comes with scripts that help pulling the ZK Chain configuration from your zksync-era repo and adapting to portal needs. Learn more hereopen in new window. An example command would look like:

npm run hyperchain:configure ../zksync-era
npm run dev:node:hyperchain

You can now navigate to the displayed Portal URL (typically http://localhost:3000open in new window).

Using Block Exploreropen in new window

A free open source block explorer is available for your ZK Chain. Block explorer contains three components Workeropen in new window, APIopen in new window, and Appopen in new window, which you can run all together locally and connect to your ZK Chain.

Make sure you have your zksync-eraopen in new window repo set up locally and the zk server is running. The wizard in this guide allows you to run the server in the end. If you chose not to, you’re still able to run it by executing:

zk server --components "http_api,eth,state_keeper,housekeeper"

Running block explorer locally

Install block explorer

Clone & install the block explorer repository:

cd /path/to/where/you/clone/repos
git clone https://github.com/matter-labs/block-explorer.git
cd block-explorer
npm install

Setting up env variables

Next you need to set up all the necessary environment and configuration files with your ZK Chain settings. You can use a script to set them up:

npm run hyperchain:configure

Run block explorer

Afterwards you can run the block explorer:

# if you are running block explorer for the first time
npm run db:create
npm run dev

Verify block explorer is up and running

By default, you can access front-end App at http://localhost:3010open in new window in your browser. API should be available at http://localhost:3020open in new window, Worker at http://localhost:3001open in new window and Data Fetcher at http://localhost:3040open in new window.

Enabling Boojum prover

With the default configuration, your ZK Chain is not running a prover, and has a DummyExecutor contract, which mainly “accepts” that a batch is executed without proof. This enables you to test it with much lower hardware requirements.

To enable the prover, run the zk stack prover-setup command. It will guide through the necessary configuration.

There are two options for running the Boojum prover: in GPU, or in CPU.

Note

Running a prover is not required for deploying a testnet. The requirements below are only necessary if you want to enable the prover.

Requirements for GPU Prover

The docker compose file assumes you will be running all components in the same machine. The current minimum requirements for a low TPS scenario are:

  • 6 GB VRAM NVIDIA GPU
  • 16 Core CPU
  • 64 GB of RAM
  • 300 GB of Disk Space (SSD preferred)

Requirements for CPU Prover

The docker compose file assumes you will be running all components in the same machine. The current minimum requirements for a low TPS scenario are:

  • 32 Core CPU
  • 128 GB of RAM
  • 700 of Disk Space (SSD preferred)

Addendum

  • If you make changes to any contract, you can always deploy a new ZK Chain to easily test those changes.

  • If you configure your ZK Chain once, you don't need to do it again as the wizard allows you to use an existing config file.

  • For now, it is only possible to deploy a ZK Chain as an L2, but soon it will also work as L3s.

  • When running the default matterlabs/geth, you have a set of rich wallets available to you. You can check them hereopen in new window.

  • If you face an issue compiling rust code (example <jemalloc>: Error allocating TSD) try removing the rust-toolchain file from the repo.

  • If you want to have a custom local base chain, you must ensure you have a database for your ZK Chain, as well as the local RPC for your L1.

    • To run a Postgres 14 database for your ZK Chain, execute the following:
docker-compose -f docker-compose-zkstack-common.yml up -d postgres

In case you don't want to use the docker Postgres database above but another one you already have locally, make sure its version is 14 and it is running and accepts connections at postgres://postgres@localhost/zksync_local. You can test with:

psql -h localhost -U postgres -d postgres -c 'SELECT 1;'