Locally

Quickstart - Getting Started with ZK Stack

Development dependencies

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

Deploying locally

Install ZK Inception

ZK Inception facilitates the creation and management of an Elastic Chain ecosystem and ZK chains using ZK Stack. All commands are interactive, but you can also pass all necessary arguments via the command line. See here for full instructions for ZK Inception.

1. Install zk_inception from git:

   cargo install --git https://github.com/matter-labs/zksync-era/ --locked zk_inception --force
   

Note: Foundry is utilized for deploying smart contracts with ZK Inception. For commands related to deployment, you can pass flags for Foundry integration.

Setup ecosystem

An Elastic Chain ecosystem includes the components that connects all ZK chains, like the BridgeHub, ZK Router, and state transition managers.

1. To create a ZK Stack project, you must first create the Elastic Chain ecosystem.

   zk_inception ecosystem create
   

   • Give the ecosystem a name, for example "ZKsync Elastic Chain".
   • For the origin of zksync-era repository, select "Clone for me".
   • For the L1 network select "Localhost" to use the local reth docker container.
   • Give your ZK chain a name like "My ZKchain", and next click enter to choose the default chain id as 271.
   • To use the default wallet for making transactions, select "Localhost".
   • Proofs are not required to run a testnet, so for now choose "NoProofs".
   • For data availability, you can choose normal on chain Rollup data mode or off chain Validium data mode.
   • ZK chains support using $ETH or a custom ERC20 as a gas token. For now choose "Eth".
   • To start the database & containers, make sure you have Docker running. At this point the Elastic Chain ecosystem will be created.
     • Note: If you chose to not start database & L1 containers after creating the ecosystem, you can later run zk_inception containers
2. All subsequent commands should be executed from within the ecosystem folder you created:

   cd `path/to/ecosystem/name` # if you followed the guide above, and used same ecosystem name, run `cd zksync_elastic_chain`
   

3. If the ecosystem has never been deployed before, initialization is required:

   zk_inception ecosystem init
   

   • Follow the wizard to choose options for your deployment. For default options, you can simply use --dev flag.
   • 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. To see a detailed breakdown you can run --verbose on ecosystem init.

Add more ZK chains (optional)

Upon ecosystem setup, the first ZK chain is automatically generated. However, ZK Stack supports many ZK chains running on the same Elastic Chain ecosystem. You can create additional chains and switch between them.

1. To create additional chains:

   zk_inception chain create
   

2. Once created, contracts for the ZK chain must be deployed:

   zk_inception chain init
   

   
   Initialization utilizes the ecosystem's governance to register it in the BridgeHub.
3. The first ZK chain created during ecosystem setup becomes the default chain, but you can override it with another one by using the --chain <name> flag. Or to change the default ZK chain, use:

   zk_inception ecosystem change-default-chain
   

Running the ZK chain

1. For running the ZK chain:

   zk_inception server
   

   
   If you setup multiple ZK chains, you can specify the chain you are running by providing --chain <chain_name> argument.

Your ZK chain is now deployed & running

Your Elastic Chain ecosystem and your ZK chain(s) are now deployed to the base chain (most likely a local reth docker container if you followed above guide) and are fully configured.

You can now run transactions and start playing with your ZK chain by using the RPC available at http://localhost:3050.

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

You can find all configurations:

• Ecosystem: At project root path/to/ecosystem/name/ZkStack.yaml.
• ZK chain(s): Each chain has its own folder and configuration files can be found at path/to/ecosystem/name/chains/<your_chain_name_slug>/.
• Wallets, ERC20 test tokens, contracts, initial deployments, and more: Can be found in the ecosystem config folder at path/to/ecosystem/name/configs/

Using your ZK chain

Funding accounts

During the zk_inception ecosystem create configurator, you have a choice of what base layer to deploy the ZK chain onto: the local reth 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 reth node

@paradigmxyz/reth

• If you chose to deploy on local reth node, you will have a set of addresses that have 100 ETH each. You can find the list here 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-cli

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

Using Portal

The dApp Portal module allows you to:

• Bridge & transfer tokens to your ZK chain.
• View balances.
• 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 here. 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:3000).

Using Block Explorer

A free open source block explorer is available for your ZK chain. Block explorer contains three components

• Worker
• API
• App

Which you can run all together locally and connect to your ZK chain.

Make sure you have your zksync-era repo set up locally and the zk_inception server is running.

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:3010 in your browser. API should be available at http://localhost:3020, Worker at http://localhost:3001 and Data Fetcher at http://localhost:3040.

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_inception prover init command. It will guide through the necessary configuration.

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

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 local reth node, you have a set of rich wallets available to you.
  Rich Wallets
• 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;'