Getting Started with ZK Stack

ZK Stack is still under development. We advise you to only use for local and testnet deployments.

Development dependencies

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

This guide is for setting up an Elastic Chain ecosystem and for spinning up your own ZK chains using ZK Stack. If you just want play around with a pre-built ZKsync chain, you can use zksync-cli dev to run docker containers. Learn more on zksync-cli.

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.

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. If you have previously installed zksync-foundry and have issues with this quickstart, try installing the standard latest version of foundry.

You can find a full reference for the zk_inception CLI in the zksync-era repo.

Setup ecosystem

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

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 ZK Chain", and next click enter to choose the default chain id as 271.
- To use the default wallet for making transactions, select "Localhost".
This option will use known mnemonic phrases to generate the wallets.yaml configuration files for the ecosystem and chain. You can also choose random to randomly generate the wallets, empty to generate a config file with empty values for the wallets, or in-file to set the location of the config to an existing file.
- 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

All subsequent commands should be executed from within the ecosystem folder you created:

cd  <YOUR_ECOSYSTEM_DIRECTORY> # if you followed the guide above, and used same ecosystem name, run `cd zksync_elastic_chain`

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.

To create additional chains:
```
zk_inception chain create
```
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.
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

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 <YOUR_ECOSYSTEM_DIRECTORY>/ZkStack.yaml.
ZK chain(s): Each chain has its own folder and configuration files can be found at <YOUR_ECOSYSTEM_DIRECTORY>/chains/<YOUR_CHAIN_NAME>/.
Wallets, ERC20 test tokens, contracts, initial deployments, and more can be found in the ecosystem config folder at <YOUR_ECOSYSTEM_DIRECTORY>/configs

Helpful Notes

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

Transaction filtering

Learn how to filter transactions on the ZK chain, including L1→L2 and L2 transactions.

Using a Local ZK chain