ZKsync Era

https://matter-labs.github.io/zksync-era/core/latest/
Admin
ZKsync Era is a Layer 2 scaling solution for Ethereum that uses zero-knowledge proofs to enable...
Tokens:93,873
Snippets:772
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Linux VM Setup for ZKsync Era

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

This script configures Git for HTTPS access, installs Rust, NVM, Node.js, essential build tools, Docker, and then clones the ZKsync Era repository. It's designed for Linux VMs, particularly on Ubuntu, and includes steps for managing Docker group membership and starting the Docker service.

```shell
git config --global url."https://github.com/.insteadOf git@github.com:
git config --global url."https".insteadOf git://

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

# All necessary stuff
sudo apt-get update
sudo apt-get install -y build-essential pkg-config cmake clang lldb lld libssl-dev libpq-dev apt-transport-https ca-certificates curl software-properties-common

# Install docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"
sudo apt install docker-ce
sudo usermod -aG docker ${USER}

# Start docker.
sudo systemctl start docker

# Node & yarn
nvm install 20
# Important: there will be a note in the output to load
# new paths in your local session, either run it or reload the terminal.
npm install -g yarn
yarn set version 1.22.19

# For running unit tests
cargo install cargo-nextest
# SQL tools
cargo install sqlx-cli --version 0.8.1

# Foundry ZKsync
curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash
foundryup-zksync

# Non CUDA (GPU) setup, can be skipped if the machine has a CUDA installed for provers
# Don't do that if you intend to run provers on your machine. Check the prover docs for a setup instead.
echo "export ZKSYNC_USE_CUDA_STUBS=true" >> ~/.bashrc
# You will need to reload your `*rc` file here

# Clone the repo to the desired location
git clone git@github.com:matter-labs/zksync-era.git
cd zksync-era
git submodule update --init --recursive

```

--------------------------------

### Install PostgreSQL Client Library on macOS

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Installs the PostgreSQL client library on macOS using Homebrew. This allows the project to connect to PostgreSQL databases without requiring a full server installation.

```bash
brew install libpq
```

--------------------------------

### Start ZKsync Era Mainnet Node

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/external-node/00_quick_start

Starts a ZKsync Era mainnet node using Docker Compose. Ensure Docker and Docker Compose are installed. This command assumes you are in the 'docker-compose-examples' directory.

```bash
cd docker-compose-examples
sudo docker compose --file mainnet-external-node-docker-compose.yml up
```

--------------------------------

### Start ZKsync Era Testnet Node

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/external-node/00_quick_start

Starts a ZKsync Era testnet node using Docker Compose. This command requires Docker and Docker Compose to be installed and should be executed from the 'docker-compose-examples' directory.

```bash
cd docker-compose-examples
sudo docker compose --file testnet-external-node-docker-compose.yml up
```

--------------------------------

### Verify Rust Installation

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Verifies the installed Rust compiler version and displays its details. This command is used to confirm that the Rust toolchain is set up correctly.

```bash
rustc --version
```

--------------------------------

### Install Yarn Version 1.22.19

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Installs a specific version of Yarn (1.22.19) globally using npm. This ensures compatibility with project requirements.

```bash
npm install -g yarn
yarn set version 1.22.19
```

--------------------------------

### Convert Chain to Gateway and Start Server

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Commands to transform an existing chain into a gateway settlement layer and start its server process. This includes converting the chain type and running the server in the background, redirecting logs.

```bash
mkdir zruns
zkstack chain gateway convert-to-gateway --chain gateway --ignore-prerequisiteszkstack server --ignore-prerequisites --chain gateway &> ./zruns/gateway.log &zkstack server wait --ignore-prerequisites --verbose --chain gateway
```

--------------------------------

### Install SQLx CLI

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Installs the SQLx Command Line Interface (CLI) with a specific locked version (0.8.1). The SQLx CLI is used for managing database migrations and supporting features of the SQLx Rust library.

```bash
cargo install --locked sqlx-cli --version 0.8.1
```

--------------------------------

### Migrate Era Chain and Start Server

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Commands to migrate the 'era' chain to settle on the 'gateway' chain and start the 'era' chain's server process. This ensures that deposits and withdrawals to 'era' are routed through 'gateway'.

```bash
zkstack chain gateway migrate-to-gateway --chain era --gateway-chain-name gateway
zkstack server --ignore-prerequisites --chain era &> ./zruns/era.log &
```

--------------------------------

### Manage ZKsync Containers

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Commands to manage Docker containers for the ZKsync stack. This includes starting required services and cleaning up the environment.

```bash
zkstack containers
zkstack dev clean all
zkstack containers --observability
```

--------------------------------

### Install PostgreSQL Development Libraries on Debian-based Linux

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Installs the development libraries for PostgreSQL on Debian-based Linux systems. These are required for compiling applications that interact with PostgreSQL.

```bash
sudo apt-get install libpq-dev
```

--------------------------------

### Install Build Tools on Debian-based Linux

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Installs essential build tools including a compiler (clang), debugger (lldb), and linker (lld) on Debian-based Linux systems. These are required for compiling dependencies like RocksDB.

```bash
sudo apt-get install build-essential pkg-config cmake clang lldb lld
```

--------------------------------

### Prepare for ZKsync Era Integration Tests

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

A sequence of commands to prepare the ZKsync Era environment for running integration tests. It involves cleaning previous states, starting necessary Docker containers, and initializing the blockchain and contracts.

```bash
zkstack dev clean all zkstack containers zkstack ecosystem init
```

--------------------------------

### Install OpenSSL Development Libraries on Debian-based Linux

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Installs the development libraries for OpenSSL on Debian-based Linux systems. These are necessary for compiling software that relies on OpenSSL.

```bash
sudo apt-get install libssl-dev
```

--------------------------------

### Install OpenSSL on macOS

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Installs the OpenSSL library on macOS using the Homebrew package manager. This is a dependency for certain cryptographic operations within the project.

```bash
brew install openssl
```

--------------------------------

### Install cargo-nextest

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Installs cargo-nextest, a next-generation test runner for Rust projects. This tool is used by the ZKSync project for running Rust tests.

```bash
cargo install cargo-nextest
```

--------------------------------

### Start ZKsync Era Docker Containers

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Initiates the Docker containers required for the ZKsync Era ecosystem. This is a prerequisite for initializing the local development environment.

```bash
zkstack containers
```

--------------------------------

### Display ZK Stack CLI Help

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Prints the help information for the ZK Stack CLI, providing an overview of available commands and their usage.

```bash
zkstack --help
```

--------------------------------

### Start zk Server Command

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/advanced/02_deposits

This command is used to start the zk server, which listens for events emitted from the contract and adds them to the postgres database.

```bash
zk server
```

--------------------------------

### Initialize ZKsync Ecosystem

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Command to initialize the ZKsync ecosystem, setting up the default 'era' chain with specified configurations like paymaster and ERC20 deployment, database URLs, and disabling prerequisites and observability.

```bash
zkstack ecosystem init --deploy-paymaster --deploy-erc20 \
  --deploy-ecosystem --l1-rpc-url=http://localhost:8545 \
  --server-db-url=postgres://postgres:notsecurepassword@localhost:5432 \
  --server-db-name=zksync_server_localhost_era \
  --ignore-prerequisites --observability=false \
  --chain era \
  --update-submodules false
```

--------------------------------

### Install ZK Stack CLI Locally

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Installs the ZK Stack CLI tool locally. This command should be run from the project's root directory. It places the executable in your user binaries directory and adds it to your PATH.

```bash
cd ./zkstack_cli/zkstackup
./install --local
```

--------------------------------

### Install Development Environment for ZKsync Era (Ubuntu)

Source: https://matter-labs.github.io/zksync-era/core/latest/print

This script installs necessary tools for ZKsync development on Ubuntu, including Rust, NVM, Docker, Node.js, Yarn, and Rust-based CLI tools. It also configures Git to use HTTPS instead of SSH for GitHub access and installs the Foundry ZKsync toolchain. This setup is suitable for VMs or systems without existing SSH keys.

```bash
git config --global url."https://github.com/".insteadOf git@github.com:
git config --global url."https://".insteadOf git://

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

# All necessary stuff
sudo apt-get update
sudo apt-get install -y build-essential pkg-config cmake clang lldb lld libssl-dev libpq-dev apt-transport-https ca-certificates curl software-properties-common

# Install docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"
sudo apt install docker-ce
sudo usermod -aG docker ${USER}

# Start docker.
sudo systemctl start docker

# Node & yarn
nvm install 20
# Important: there will be a note in the output to load
# new paths in your local session, either run it or reload the terminal.
npm install -g yarn
yarn set version 1.22.19

# For running unit tests
cargo install cargo-nextest
# SQL tools
cargo install sqlx-cli --version 0.8.1

# Foundry ZKsync
curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync | bash
foundryup-zksync

# Non CUDA (GPU) setup, can be skipped if the machine has a CUDA installed for provers
# Don't do that if you intend to run provers on your machine. Check the prover docs for a setup instead.
echo "export ZKSYNC_USE_CUDA_STUBS=true" >> ~/.bashrc
# You will need to reload your `*rc` file here

# Clone the repo to the desired location
git clone git@github.com:matter-labs/zksync-era.git
cd zksync-era
git submodule update --init --recursive

```

--------------------------------

### Optimize Rust Build with Mold Linker

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Exports environment variables to use the 'mold' linker for Rust builds, significantly speeding up build times. This command specifies the path to the mold executable and configures Cargo to use it.

```bash
export RUSTFLAGS='-C link-arg=-fuse-ld=/usr/local/bin/mold'
export CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER="clang"
```

--------------------------------

### Set RocksDB and Snappy Library Directories

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Exports environment variables to specify the locations of precompiled RocksDB and Snappy libraries. This avoids recompiling C++ sources from scratch, significantly improving build times. Ensure the compiled libraries match the current RocksDB version.

```shell
export ROCKSDB_LIB_DIR=<library location>
export SNAPPY_LIB_DIR=<library location>
```

--------------------------------

### Check Rust Toolchain Configuration on macOS ARM

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Displays the current Rust toolchain configuration, including the default host and installed toolchains. This is particularly useful on macOS with ARM processors to ensure the correct architecture (aarch64) is active.

```bash
rustup show
```

--------------------------------

### Troubleshoot Connection Refused Error

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

This error message indicates that no containers are currently running, preventing a connection to the expected service (e.g., http://127.0.0.1:8545/). To resolve this, ensure all necessary ZKstack containers are started and operational.

```bash
error sending request for url (http://127.0.0.1:8545/): error trying to connect: tcp connect error: Connection refused (os error 61)
```

```bash
zkstack containers
```

--------------------------------

### Install PostgreSQL Client Library (macOS and Linux)

Source: https://matter-labs.github.io/zksync-era/core/latest/print

Installs the PostgreSQL client library, necessary for interacting with PostgreSQL databases. Homebrew is used on macOS, and apt-get on Debian-based Linux systems.

```bash
brew install libpq
```

```bash
sudo apt-get install libpq-dev
```

--------------------------------

### Execute ZKsync Era Integration Tests

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Runs the integration tests for the ZKsync Era project after the server has been started and the ecosystem initialized. This command verifies the system's behavior in integrated scenarios.

```bash
zkstack dev test integration
```

--------------------------------

### Install dependencies for the contracts module

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Navigates into the 'contracts' directory and installs its specific npm dependencies using yarn. This is a common step to ensure the contract development environment is correctly set up, but it can sometimes lead to dependency conflicts with the core project.

```bash
cd contracts && yarn install
```

--------------------------------

### Snapshot Recovery Log Example

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/external-node/07_snapshots_recovery

An example log output demonstrating the snapshot recovery process during the initial startup of a zkSync Era node. This log illustrates the sequence of events from node initialization to Merkle tree recovery.

```log
2024-06-20T07:25:32.466926Z  INFO zksync_external_node::init: Node has neither genesis L1 batch, nor snapshot recovery info
2024-06-20T07:25:32.466946Z  INFO zksync_external_node::init: Chosen node initialization strategy: SnapshotRecovery
2024-06-20T07:25:32.466951Z  WARN zksync_external_node::init: Proceeding with snapshot recovery. This is an experimental feature; use at your own risk
2024-06-20T07:25:32.475547Z  INFO zksync_snapshots_applier: Found snapshot with data up to L1 batch #7, L2 block #27, version 0, storage logs are divided into 10 chunk(s)
2024-06-20T07:25:32.516142Z  INFO zksync_snapshots_applier: Applied factory dependencies in 27.768291ms
2024-06-20T07:25:32.527363Z  INFO zksync_snapshots_applier: Recovering storage log chunks with 10 max concurrency
2024-06-20T07:25:32.608539Z  INFO zksync_snapshots_applier: Recovered 3007 storage logs in total; checking overall consistency...
2024-06-20T07:25:32.612967Z  INFO zksync_snapshots_applier: Retrieved 2 tokens from main node
2024-06-20T07:25:32.616142Z  INFO zksync_external_node::init: Recovered Postgres from snapshot in 148.523709ms
2024-06-20T07:25:32.645399Z  INFO zksync_metadata_calculator::recovery: Recovering Merkle tree from Postgres snapshot in 1 chunks with max concurrency 10
2024-06-20T07:25:32.650478Z  INFO zksync_metadata_calculator::recovery: Filtered recovered key chunks; 1 / 1 chunks remaining
2024-06-20T07:25:32.681327Z  INFO zksync_metadata_calculator::recovery: Recovered 1/1 Merkle tree chunks, there are 0 left to process
2024-06-20T07:25:32.784597Z  INFO zksync_metadata_calculator::recovery: Recovered Merkle tree from snapshot in 144.040125ms
```

--------------------------------

### Start ZKsync Server

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/advanced/01_initialization

Starts the ZKsync server, which is a Rust cargo binary. It listens for new transactions via JSON RPC and L1 contract logs to generate blocks.

```Shell
zkstack server
```

--------------------------------

### Display Help for zkstack dev contracts

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Shows all available options and subcommands for interacting with smart contracts using the `zkstack dev contracts` command. This is useful for exploring contract-related functionalities.

```bash
zkstack dev contracts --help
```

--------------------------------

### Generate ZKSync Verification Keys

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Compiles and runs the `zksync_verification_key_generator` binary in release mode. This tool is used to generate all necessary verification keys for ZKSync, requiring a `setup_2^26.key` file in the current directory.

```bash
# ensure that the setup_2^26.key in the current directory, the file can be download from  https://storage.googleapis.com/matterlabs-setup-keys-us/setup-keys/setup_2\^26.key

# To generate all verification keys
cargo run --release --bin zksync_verification_key_generator
```

--------------------------------

### Enable CUDA Stubs for Builds

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

Sets an environment variable to enable CUDA stubs, allowing the project to build even on systems without a CUDA-enabled GPU. This is a workaround for the Circuit Prover's CUDA dependency.

```bash
export ZKSYNC_USE_CUDA_STUBS=true
```

--------------------------------

### Start ZK Stack Era Chain Servers

Source: https://matter-labs.github.io/zksync-era/core/latest/print

Starts the server processes for the 'era' chain in the background, directing their logs to './zruns/era.log'.

```shell
zkstack server --ignore-prerequisites --chain era &> ./zruns/era.log &
```

--------------------------------

### Create and Initialize Gateway Chain

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Commands to create a new 'gateway' chain as a rollup, configure its parameters, and then initialize it. This includes setting chain ID, prover mode, base token details, and database configurations.

```bash
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
```

--------------------------------

### Initialize ZKstack Prover with Credentials

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Initializes the ZKstack prover, requiring a bucket base URL and a path to a credentials file (e.g., `service_account.json` for GCP). This command is used to set up the prover with necessary access information.

```bash
zkstack prover init --bucket-base-url={url} --credentials-file={path/to/service_account.json}
```

--------------------------------

### Create and Initialize Chain with Legacy Bridge

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Commands to create a new blockchain environment that supports a legacy bridge, followed by initialization. This setup is required for running load tests with the legacy bridge.

```bash
zkstack chain create --legacy-bridge zkstack chain init
```

--------------------------------

### Examples of eth_call Gas Cap Configuration

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/external-node/02_configuration

Demonstrates various configurations for the `eth_call_gas_cap` setting. Examples include setting a conservative 10M gas cap, a permissive 100M gas cap, disabling the cap (setting to 0, not recommended), and omitting the setting to use the protocol default.

```yaml
# Example 1: 10M gas cap (conservative)
api:
  web3_json_rpc:
    eth_call_gas_cap: 10000000

# Example 2: 100M gas cap (permissive)
api:
  web3_json_rpc:
    eth_call_gas_cap: 100000000

# Example 3: No gas cap (unlimited, not recommended for public nodes)
api:
  web3_json_rpc:
    eth_call_gas_cap: 0

# Example 4: Use protocol default (recommended)
api:
  web3_json_rpc:
    # eth_call_gas_cap not specified - uses protocol default
```

--------------------------------

### Run ZKstack Contract Verifier

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Executes the ZKstack contract verifier service. This service is responsible for verifying smart contracts within the ZKstack ecosystem.

```bash
zkstack contract-verifier run
```

--------------------------------

### Start ZK Stack Gateway Chain Server

Source: https://matter-labs.github.io/zksync-era/core/latest/print

Initiates the server process for the 'gateway' chain in the background and logs its output to './zruns/gateway.log'. It then waits for the server to become available, with verbose output enabled.

```shell
mkdir zruns zkstack server --ignore-prerequisites --chain gateway &> ./zruns/gateway.log & zkstack server wait --ignore-prerequisites --verbose --chain gateway
```

--------------------------------

### VSCode Launch Configuration for ZKSync Server Debugging

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/advanced/90_advanced_debugging

This configuration snippet is for VSCode's launch.json file. It sets up a debugging session for the 'zksync_server' binary within the ZKsync core project using LLDB. It specifies how to build the binary using Cargo, defines the working directory, and importantly, includes a 'preRunCommands' entry to import the 'prelaunch.py' script for environment variable setup before execution.

```json
{
    "type": "lldb",
    "request": "launch",
    "name": "Debug executable 'zksync_server' DEV ENV",
    "cargo": {
        "args": [
            "build",
            "--bin=zksync_server",
            "--package=zksync_core"
        ],
        "filter": {
            "name": "zksync_server",
            "kind": "bin"
        }
    },
    "args": [],
    "cwd": "${workspaceFolder}",
    "preRunCommands": [
        "command script import ${workspaceFolder}/.vscode/prelaunch.py"
    ]
}
```

--------------------------------

### Troubleshooting Docker Connection Issues

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/setup-dev

This section addresses a common Docker error on Linux where the user cannot connect to the Docker daemon. It provides commands to verify the issue and instructs on how to add the current user to the 'docker' group to resolve permission problems. A logout/login or system restart is recommended after the group modification.

```shell
docker-compose up # Should raise the same error.
sudo docker-compose up # Should start doing things.

sudo usermod -a -G docker your_user_name
```

--------------------------------

### Run ZK Stack CLI Locally

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Executes the ZK Stack CLI from the current source directory after local installation. This command is used to manage local ZKsync Era development environments.

```bash
zkstackup --local
```

--------------------------------

### Install OpenSSL on macOS and Linux

Source: https://matter-labs.github.io/zksync-era/core/latest/print

Installs the OpenSSL library, a crucial dependency for various cryptographic operations. Uses Homebrew on macOS and apt-get on Debian-based Linux distributions.

```bash
brew install openssl
```

```bash
sudo apt-get install libssl-dev
```

--------------------------------

### Run ZKstack Prover Component

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Executes the ZKstack prover component. This command is intended for running on machines with a GPU, as running without one is currently not supported.

```bash
zkstack prover run --component=prover
```

--------------------------------

### Run ZK Stack CLI Test Commands

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Displays help information for the `zkstack dev test` command, outlining the various subcommands available for running different types of tests within the ZKsync Era project.

```bash
zkstack dev test --help
```

--------------------------------

### Create2AndTransfer Deployment Example

Source: https://matter-labs.github.io/zksync-era/core/latest/specs/upgrade_history/gateway_upgrade/upgrade_process_no_gateway_chain

Shows a conceptual usage of a Create2AndTransfer contract to deploy a new contract at a predictable address using CREATE2 and immediately transfer its ownership to governance.

```Solidity
pragma solidity ^0.8.0;

import "@openzeppelin/contracts/utils/CREATE2.sol";
import "@openzeppelin/contracts/access/Ownable.sol";

contract Create2AndTransfer is Ownable {
    address public governance;

    constructor(address _governance) {
        governance = _governance;
    }

    function deployAndTransfer(bytes memory _creationCode, bytes32 _salt) public onlyOwner {
        // Deploy the contract using CREATE2
        address deployedContract = CREATE2.deploy(payable(address(this)), _salt, _creationCode);
        
        // Assuming the deployed contract is Ownable and we have a way to call its transferOwnership function
        // This requires the _creationCode to include initialization that sets the initial owner or allows for immediate transfer.
        // A more robust implementation would involve a factory pattern or specific interfaces.
        
        // Example: If deployedContract is an Ownable contract and its constructor doesn't set the owner, 
        // or if we need to override it. This part is highly dependent on the contract being deployed.
        // For instance, if the deployed contract's init code sets owner to address(0) or deployer, 
        // we'd call transferOwnership here.
        
        // Pseudocode for transferring ownership after deployment:
        // I_Ownable(deployedContract).transferOwnership(governance);
    }
}

```

--------------------------------

### Rich Account Setup for Era

Source: https://matter-labs.github.io/zksync-era/core/latest/print

This snippet demonstrates how to set up a rich account on a local Era chain for testing purposes. It involves using a development command to generate an account and its associated private key, which can then be used for funding or other operations.

```shell
zkstack dev rich-account
ACCOUNT="0x36615Cf349d7F6344891B1e7CA7C72883F5dc049"
PRIVATE_KEY="0x7726827caac94a7f9e1b160f7ea819f172f7b6f9d2a97f992c38edeab82d4110"
```

--------------------------------

### Convert ZKSync JSON Verification Key to Binary

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Executes the `zksync_json_to_binary_vk_converter` binary in release mode, converting a JSON verification key to a binary format. An output path for the binary file must be specified.

```bash
cargo run --release --bin zksync_json_to_binary_vk_converter -- -o /path/to/output-binary-vk
```

--------------------------------

### Example Pruning Log Output

Source: https://matter-labs.github.io/zksync-era/core/latest/print

Provides example log messages indicating successful soft and hard pruning of L1 batches and L2 blocks. These logs help verify that the pruning mechanism is functioning correctly.

```log
2024-06-20T07:26:03.415382Z  INFO zksync_node_db_pruner: Soft pruned db l1_batches up to 8 and L2 blocks up to 29, operation took 14.850042ms
2024-06-20T07:26:04.433574Z  INFO zksync_node_db_pruner::metrics: Performed pruning of database, deleted 1 L1 batches, 2 L2 blocks, 68 storage logs, 383 events, 27 call traces, 12 L2-to-L1 logs
2024-06-20T07:26:04.436516Z  INFO zksync_node_db_pruner: Hard pruned db l1_batches up to 8 and L2 blocks up to 29, operation took 18.653083ms
```

--------------------------------

### Run Upgrade Tests with zkstack

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Executes the upgrade tests for the zksync-era project. This command assumes the zksync-era environment is set up and the zkstack tool is built.

```bash
ZKSYNC_HOME=<path_to_zksync_era> zkstack dev test upgrade
```

--------------------------------

### Example L2 to L1 Log Proof Response

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/advanced/19_interop_basics

This is an example of the JSON response when requesting an L2 to L1 log proof. The 'proof' field contains an array of hexadecimal strings representing the proof elements, and 'root' is the state root associated with the proof.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "proof": [
      "0x010f050000000000000000000000000000000000000000000000000000000000",
      "0x72abee45b59e344af8a6e520241c4744aff26ed411f4c4b00f8af09adada43ba",
      "0xc3d03eebfd83049991ea3d3e358b6712e7aa2e2e63dc2d4b438987cec28ac8d0",
      "0xe3697c7f33c31a9b0f0aeb8542287d0d21e8c4cf82163d0c44c7a98aa11aa111",
      "0x199cc5812543ddceeddd0fc82807646a4899444240db2c0d2f20c3cceb5f51fa",
      "0xe4733f281f18ba3ea8775dd62d2fcd84011c8c938f16ea5790fd29a03bf8db89",
      "0x1798a1fd9c8fbb818c98cff190daa7cc10b6e5ac9716b4a2649f7c2ebcef2272",
      "0x66d7c5983afe44cf15ea8cf565b34c6c31ff0cb4dd744524f7842b942d08770d",
      "0xb04e5ee349086985f74b73971ce9dfe76bbed95c84906c5dffd96504e1e5396c",
      "0xac506ecb5465659b3a927143f6d724f91d8d9c4bdb2463aee111d9aa869874db",
      "0x124b05ec272cecd7538fdafe53b6628d31188ffb6f345139aac3c3c1fd2e470f",
      "0xc3be9cbd19304d84cca3d045e06b8db3acd68c304fc9cd4cbffe6d18036cb13f",
      "0xfef7bd9f889811e59e4076a0174087135f080177302763019adaf531257e3a87",
      "0xa707d1c62d8be699d34cb74804fdd7b4c568b6c1a821066f126c680d4b83e00b",
      "0xf6e093070e0389d2e529d60fadb855fdded54976ec50ac709e3a36ceaa64c291",
      "0xe4ed1ec13a28c40715db6399f6f99ce04e5f19d60ad3ff6831f098cb6cf75944",
      "0x0000000000000000000000000000000000000000000000000000000000000015",
      "0x156467afe10e8eb1dcac04cca213c53d4bade9d73edfe9410ea45c86ebd9804e",
      "0xcc4c41edb0c2031348b292b768e9bac1ee8c92c09ef8a3277c2ece409c12d86a",
      "0x183a40fea23b03351928919261dfc02e45b94b564e263d339a601b9740112ccc",
      "0x4cd95f8962e2e3b5f525a0f4fdfbbf0667990c7159528a008057f3592bcb2c06",
      "0x112038ecbdf21c5fc2ef97d9ec047402bba05d6ff2aa1b304dcfac974ebaa109",
      "0x0000000000000000000000000000001900000000000000000000000000000003",
      "0x00000000000000000000000000000000000000000000000000000000000001fa",
      "0x0102000100000000000000000000000000000000000000000000000000000000",
      "0xf84927dc03d95cc652990ba75874891ccc5a4d79a0e10a2ffdd238a34a39f828",
      "0x2c21d37d09509f7ccb3d7d93c86ff4d7b29246113b0032dec9688c9e119d6872"
    ],
    "id": 0,
    "root": "0xeb6861fa2f2fd60c93dba1343bf85e2312811fd23549b3df2b8017102430f086"
  }
}
```

--------------------------------

### Nix Development Shell

Source: https://matter-labs.github.io/zksync-era/core/latest/print

Enters a Nix development shell that provides all necessary dependencies for the ZKSync project. This command assumes Nix, Docker, and Rustup are already installed and configured.

```bash
nix develop
```

--------------------------------

### Generate ZKSync Commitment

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/launch

Compiles and runs the `zksync_commitment_generator` binary in release mode. This tool is responsible for generating commitments required by the ZKSync protocol.

```bash
cargo run --release --bin zksync_commitment_generator
```

--------------------------------

### Starting a ZKsync Era Debug Environment Container

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/advanced/91_docker_and_ci

This command starts a new Docker container using the 'matterlabs/zk-environment' image in interactive mode, providing a bash shell. This is useful for debugging as it allows direct interaction with the container's environment, bypassing the default binary execution.

```docker
docker run  -it matterlabs/zk-environment:latest2.0-lightweight-nightly /bin/bash
```

--------------------------------

### Postgres Pruning Log Example

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/external-node/08_pruning

This snippet shows example log output for successful Postgres database pruning. It indicates the number of L1 batches and L2 blocks pruned, along with the time taken for soft and hard pruning operations. This is useful for verifying the functionality of the `zksync_node_db_pruner`.

```log
__
2024-06-20T07:26:03.415382Z  INFO zksync_node_db_pruner: Soft pruned db l1_batches up to 8 and L2 blocks up to 29, operation took 14.850042ms
2024-06-20T07:26:04.433574Z  INFO zksync_node_db_pruner::metrics: Performed pruning of database, deleted 1 L1 batches, 2 L2 blocks, 68 storage logs, 383 events, 27 call traces, 12 L2-to-L1 logs
2024-06-20T07:26:04.436516Z  INFO zksync_node_db_pruner: Hard pruned db l1_batches up to 8 and L2 blocks up to 29, operation took 18.653083ms
```

--------------------------------

### Generate Genesis File with zkstack

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Generates the `genesis.yaml` file for the zksync-era network. This involves building `zkstack` from the desired branch and configuring the ecosystem beforehand.

```bash
zkstack dev generate-genesis
```

--------------------------------

### Bootloader Contract Structure Example (Solidity)

Source: https://matter-labs.github.io/zksync-era/core/latest/specs/era_vm_specification/zkSync_era_virtual_machine_primer

This snippet illustrates the conceptual structure of the Bootloader contract, outlining its primary functions for block execution. It's not the actual implementation but demonstrates responsibilities like transaction validation, fee charging, and execution.

```Solidity
contract Bootloader {
  function executeBlock(address operatorAddress, Transaction[2] memory transactions) {
    for (uint256 i = 0; i < transactions.length; i++) {
      validateTransaction(transactions[i]);
      chargeFee(operatorAddress, transactions[i]);
      executeTransaction(transactions[i]);
    }
  }

  function validateTransaction(Transaction memory tx) {
    // validation logic
  }

  function chargeFee(address operatorAddress, Transaction memory tx) {
    // charge fee
  }

  function executeTransaction(Transaction memory tx) {
    // execution logic
  }
}

```

--------------------------------

### Solidity Test Case with Metadata

Source: https://matter-labs.github.io/zksync-era/core/latest/print

A Solidity smart contract example demonstrating a simple function returning a uint64. The accompanying metadata in the comment block defines test cases, inputs, and expected outputs for the compiler-tester.

```json
//! { "cases": [ { 
//!     "name": "first", 
//!     "inputs": [ 
//!         { 
//!             "method": "first", 
//!             "calldata": [ 
//!             ] 
//!         } 
//!     ], 
//!     "expected": [ 
//!         "42" 
//!     ] 
//! }, ] }
```

```solidity
// SPDX-License-Identifier: MIT

pragma solidity >=0.4.16;

contract Test {
  function first() public pure returns (uint64) {
    uint64 result = 42;
    return result;
  }
}
```

--------------------------------

### ZKstack CLI Implementation in Rust

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/advanced/01_initialization

The zkstack CLI tool is implemented in Rust. Changes to this code require recompilation and installation using `zkstackup --local` before running zkstack commands.

```Rust
// Code for zkstack CLI is located in the /zkstack_cli directory
```

--------------------------------

### Initialize ZKstack Ecosystem

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/advanced/01_initialization

Initializes the ZKsync ecosystem by configuring settings, building and deploying L1/L2 contracts, setting up chains, configuring observability, running the genesis process, and initializing the database.

```Shell
zkstack ecosystem init
```

--------------------------------

### Object Store Configuration Migration (YAML)

Source: https://matter-labs.github.io/zksync-era/core/latest/announcements/config_format_changes

Demonstrates the transformation of object store configurations from the old 'one-of' encoding to the new tagged representation in YAML. It shows an example before and after migration, along with a recommended configuration for compatibility with both old and new node versions.

```yaml
core_object_store:
  file_backed:
    file_backed_base_path: artifacts
  max_retries: 10
```

```yaml
core_object_store:
  mode: FileBacked
  file_backed_base_path: artifacts
  max_retries: 10
```

```yaml
core_object_store:
  # Read by old node versions
  file_backed:
    file_backed_base_path: artifacts
  # Read by new node versions
  mode: FileBacked
  file_backed_base_path: artifacts
  # Read by both
  max_retries: 10
```

--------------------------------

### Initializing Postgres and Reth Services with Docker Compose

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/advanced/91_docker_and_ci

This command initializes and starts the necessary PostgreSQL and Reth services in detached mode for ZKsync Era development. These services are often required by tests and are managed using Docker Compose.

```docker
docker compose up -d
```

--------------------------------

### Run Load Tests with Legacy Bridge

Source: https://matter-labs.github.io/zksync-era/core/latest/guides/development

Executes load tests against a previously initialized chain that has legacy bridge support enabled. Ensure the chain is properly set up before running this command.

```bash
zkstack dev test loadtest
```

--------------------------------

### Starting Governance Upgrade Timer - Governance Operation

Source: https://matter-labs.github.io/zksync-era/core/latest/print

This function initiates a timer for the protocol upgrade. It provides a fixed window for all ecosystem chains to upgrade their systems before the old protocol version becomes invalid.

```solidity
function startTimer() external {
    // Implementation details for starting the upgrade timer
}
```
Tokens:
Raw