Setup a Multichain Local Ecosystem - ZKsync Community Code

Introduction to ZKsync Gateway

ZKsync Gateway is an optional shared proof aggregation layer for ZKsync chains, including both rollups and validiums. It is purpose-built to enhance interoperability, provide proof aggregation, and offer cost efficiencies for chains that choose to operate on top of it.

To test out interoperability between ZKsync chains locally, you must also setup a local version of ZKsync Gateway.

You can learn more about ZKsync Gateway in the ZKsync protocol documentation.

Prerequisites

Install the dependencies for the zksync-era repo by following the instructions in the setup dev guide.

Setup

Install the latest version of `zkstack` CLI

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

zkstackup

Update `zksync-foundry`

Update foundry-zksync to use the version from commit 27360d4c8:

foundryup-zksync -C 27360d4c8

Create a new ecosystem

Before starting the containers, make sure Docker is already running.

zkstack ecosystem create

You will be prompted with a series of options to customize your ecosystem and generate a new chain within the ecosystem. For this tutorial, use the options shown below.

❯ zkstack ecosystem create

┌   ZK Stack CLI
│
◇  What do you want to name the ecosystem?
│  interop_ecosystem
│
◇  Select the origin of zksync-era repository
│  Clone for me (recommended)
│
◇  Select the L1 network
│  Localhost
│
◇  What do you want to name the chain?
│  zk_chain_1
│
◇  What's the chain id?
│  34234
│
◇  Select how do you want to create the wallet
│  Localhost
│
◇  Select the prover mode
│  NoProofs
│
◇  Select the commit data generator mode
│  Rollup
│
◇  Select the base token to use
│  Eth
│
◇  Enable EVM emulator?
│  Yes
│
◇  Do you want to start containers after creating the ecosystem?
│  Yes

Initialize the Ecosystem and Your First Chain

Move into your ecosystem folder and initialize the ecosystem and your first chain:

cd interop_ecosystem
zkstack ecosystem init --dev

This step can take several minutes to complete.

Create and Initialize ZKsync Gateway

Now that you have an ecosystem and chain setup for testing, use the commands below to add another chain to act as the ZKsync Gateway.

zkstack chain create \
    --chain-name gateway \
    --chain-id 506 \
    --prover-mode no-proofs \
    --wallet-creation localhost \
    --l1-batch-commit-data-generator-mode rollup \
    --base-token-address 0x0000000000000000000000000000000000000001 \
    --base-token-price-nominator 1 \
    --base-token-price-denominator 1 \
    --set-as-default false \
    --evm-emulator false \
    --ignore-prerequisites --update-submodules false

zkstack chain init \
  --deploy-paymaster \
  --l1-rpc-url=http://localhost:8545 \
  --server-db-url=postgres://postgres:notsecurepassword@localhost:5432 \
  --server-db-name=zksync_server_localhost_gateway \
  --chain gateway --update-submodules false

Setup the transaction filterer

Next, setup the transaction filterer for gateway:

zkstack chain gateway create-tx-filterer --chain gateway --ignore-prerequisites

Convert gateway chain to gateway mode

With the gateway chain setup, the next step is to convert the gateway chain to act as ZKsync gateway instead of a regular rollup.

zkstack chain gateway convert-to-gateway --chain gateway --ignore-prerequisites

Start the gateway server

Next, start the server for gateway and keep it running.

zkstack server --ignore-prerequisites --chain gateway

Create and Initialize Two More Chains

We will create two more chains. Open a new terminal in the same ecosystem folder, and use the commands below to create and initialize two more chains.

`zk_chain_2`

zkstack chain create \
    --chain-name zk_chain_2 \
    --chain-id 5328 \
    --prover-mode no-proofs \
    --wallet-creation localhost \
    --l1-batch-commit-data-generator-mode rollup \
    --base-token-address 0x0000000000000000000000000000000000000001 \
    --base-token-price-nominator 1 \
    --base-token-price-denominator 1 \
    --set-as-default false \
    --evm-emulator true \
    --ignore-prerequisites --update-submodules false

zkstack chain init \
    --deploy-paymaster \
    --l1-rpc-url=http://localhost:8545 \
    --server-db-url=postgres://postgres:notsecurepassword@localhost:5432 \
    --server-db-name=zksync_server_localhost_zk_chain_2 \
    --chain zk_chain_2 \
    --update-submodules false

`zk_chain_3`

zkstack chain create \
    --chain-name zk_chain_3 \
    --chain-id 37427 \
    --prover-mode no-proofs \
    --wallet-creation localhost \
    --l1-batch-commit-data-generator-mode rollup \
    --base-token-address 0x0000000000000000000000000000000000000001 \
    --base-token-price-nominator 1 \
    --base-token-price-denominator 1 \
    --set-as-default false \
    --evm-emulator true \
    --ignore-prerequisites --update-submodules false

zkstack chain init \
    --deploy-paymaster \
    --l1-rpc-url=http://localhost:8545 \
    --server-db-url=postgres://postgres:notsecurepassword@localhost:5432 \
    --server-db-name=zksync_server_localhost_zk_chain_3 \
    --chain zk_chain_3 \
    --update-submodules false

Migrate the Chains to Gateway

The next step is to migrate the three chains we have to settle via gateway. Without this step, these chains are unable to utilize interop. Run the commands below to do the migration.

zkstack chain gateway migrate-to-gateway --chain zk_chain_1 --gateway-chain-name gateway --ignore-prerequisites

zkstack chain gateway migrate-to-gateway --chain zk_chain_2 --gateway-chain-name gateway --ignore-prerequisites

zkstack chain gateway migrate-to-gateway --chain zk_chain_3 --gateway-chain-name gateway --ignore-prerequisites

Start the Other Chain Servers

Now that the chains are using gateway, you can start the rest of the servers. Start the first server for zk_chain_1 with:

zkstack server --ignore-prerequisites --chain zk_chain_1

Then, open another terminal in the ecosystem folder and start the second chain's server:

zkstack server --ignore-prerequisites --chain zk_chain_2

Open another terminal to start the last chain's server:

zkstack server --ignore-prerequisites --chain zk_chain_3

You should now have a local ecosystem with three interoperable ZKsync chains running in addition to a local ZKsync Gateway.

Bridge Funds

The last step needed to finish the ecosystem setup is to bridge some funds over to an account on each chain except Gateway. The command uses a pre-configured rich wallet to bridge 1 ETH to 0x36615cf349d7f6344891b1e7ca7c72883f5dc049. Open a new terminal in the ecosystem folder, and run:

zkstack dev rich-account --chain zk_chain_1

zkstack dev rich-account --chain zk_chain_2

zkstack dev rich-account --chain zk_chain_3

You can also send funds to an account of your choosing with the commands below:

zkstack dev rich-account --chain zk_chain_1 0x<YOUR_WALLET_ADDRESS>

zkstack dev rich-account --chain zk_chain_2 0x<YOUR_WALLET_ADDRESS>

zkstack dev rich-account --chain zk_chain_3 0x<YOUR_WALLET_ADDRESS>

How Max Gas Per Pubdata Works on ZKsync Era

Setup a Multichain Local Ecosystem

Setup a Local Multichain Ecosystem

What you'll learn:

Tools: