Introduction

Welcome to the anvil-zkSync documentation—your single stop for spinning up a local ZK chain node, forking mainnet or testnets, and debugging smart-contract workflows.

At a glance:
• Fast in-memory node for Elastic Network ZK chains • Drop-in anvil CLI parity (forking, snapshots, impersonation, …)
• Rich RPC surface for integration tests and L1↔L2 scenarios

Documentation map

• CLI Reference
• RPC Reference
• Guides

Getting started in 30 seconds

# 1. Install via Cargo (recommended)
brew tap matter-labs/anvil-zksync https://github.com/matter-labs/anvil-zksync.git 
brew install anvil-zksync

# 2. Launch a fresh local node
anvil-zksync run

# 3. Or fork Era mainnet at the latest block
anvil-zksync fork --fork-url mainnet

Once running, visit http://localhost:8011.

Where to next?

• New to zkSync? Start with Getting Started for a quick architectural primer.
• Deep dive into flags? Head over to the CLI Reference.
• Building an L1↔L2 bridge? Check the Guides section.
• Looking for Rust book? Head over to the Anzil-ZKsync Rust book.

Thank you for using anvil-zkSync —happy building!
If you spot an issue or have an idea for improvement, open an issue or pull request on GitHub.

Why anvil-zksync

Developers building on Elastic Network chains need a local node that understands EraVM, supports rapid iteration, and handles cross-chain workflows. anvil-zksync fills that gap.

Why not just use anvil?

Anvil is great but it is built to target Ethereum’s EVM but EraVM is not EVM-equivalent. EraVM is a custom virtual machine that powers ZKsync Era and other Elastic Network chains. It has its own opcodes, gas costs, and execution model. This means that anvil’s EVM-based execution environment is not compatible with EraVM bytecode.

anvil-zksync is a drop-in replacement for Anvil, delivering the same fast local development workflow—but with native EraVM support.

Rapid testing, debugging & prototyping

• Spin up a fresh network in milliseconds with anvil-zksync run.
• Fork any Elastic Network ZK chain at the latest block or a historic block number with fork.
• Auto-mine or mine on demand, so you can exercise blocks exactly when you need them.
• Verbose VM tracing helps you introspect failing txs, gas usage, and internal state.

Forking Elastic Network ZK chains

With --fork-url you can point at any supported network mainnet, sepolia-testnet, abstract, sophon, etc. and get a local fork that includes all state (accounts, contracts, balances). Perfect for:

• Integration tests
• Debugging live issues
• Prototyping
• dApp development
• Gas cost analysis

L2→L1 communication

anvil-zksync supports local L2-L1 communication:

• L1→L2 deposits and L2→L1 withdrawals
• L2→L1 messaging
• Priority queue transactions
• Upgrade and governance txs

Custom base-token support

Not every chain uses ETH for gas.

Configure a custom base token symbol and conversion ratio, and all gas estimations and balances will “just work” for non-ETH base tokens.

Protocol & system-contract development

For protocol engineers:

• Test system contracts and bootloader changes locally quickly and easily
• Experiment with new protocol versions (--protocol-version)
• Validate compression, pubdata costs, and bytecode overrides

EVM usage

Starting in the v27 protocol upgrade, anvil-zksync supports running the EVM interpreter on top of EraVM. This is useful if you need to:

• Test, debug, and prototype with EVM contracts on EraVM
• Compare EraVM vs EVM interpreter behavior

anvil-zksync --evm-interpreter

Replay and trace historical transactions

Replay any transaction:

anvil-zksync -vv replay_tx \
  --fork-url mainnet \
  0xe12b1924faa45881beb324adca1f8429d553d7ad56a2a030dcebea715e1ec1e4

Installation

You have the following ways to get up and running with anvil-zksync:

1. Homebrew (recommended)
2. Installation script (bundles forge, cast, and anvil-zksync from foundry-zksync)
3. Pre-built binaries (download & extract)
4. Docker
5. Build from source (requires Rust/Cargo)

1. Homebrew (recommended)

If you’re on macOS or Linux, the easiest and most up-to-date way is via Homebrew:

# Tap the official anvil-zksync formula
brew tap matter-labs/anvil-zksync https://github.com/matter-labs/anvil-zksync.git 
brew install anvil-zksync

# Install
brew install anvil-zksync

# To update later:
brew update
brew upgrade anvil-zksync

2. Installation script

The easiest path: grab and run the foundryup-zksync installer.

curl -L https://raw.githubusercontent.com/matter-labs/foundry-zksync/main/install-foundry-zksync \
  | bash

This installs forge, cast, and anvil-zksync into your PATH. Note: This will override existing foundry installations.

Then start your local ZK chain node:

anvil-zksync

3. Pre-built binaries

1. Download the latest release for your platform from
   GitHub Releases.

2. Extract and install:

   tar xzf anvil-zksync-<version>-<os>.tar.gz -C /usr/local/bin/
   chmod +x /usr/local/bin/anvil-zksync
   

3. Verify and run:

   anvil-zksync --version
   anvil-zksync
   

Convenience download links

These URLs always fetch the latest published build:

• anvil-zksync-aarch64-apple-darwin.tar.gz
• anvil-zksync-aarch64-unknown-linux-gnu.tar.gz
• anvil-zksync-x86_64-apple-darwin.tar.gz
• anvil-zksync-x86_64-unknown-linux-gnu.tar.gz

4. Docker

anvil-zksync is available as Docker image that supports Linux x64 and arm64.

docker pull ghcr.io/matter-labs/anvil-zksync:v0.6.0

Run it (interactive):

docker run --rm -it ghcr.io/matter-labs/anvil-zksync:v0.6.0 \
  anvil-zksync

5. Build from source

Requires Rust & Cargo installed.

gh repo clone matter-labs/anvil-zksync
cd anvil-zksync
cargo build --release

The anvil-zksync binary will be at target/release/. To make it globally available:

cp target/release/anvil-zksync /usr/local/bin/

Checking installation

After installation, verify that anvil-zksync is available:

anvil-zksync --version
# 0.5.1

With any method above, you can immediately begin:

# Launch default (equivalent to `run`)
anvil-zksync

# Or fork with tracing enabled:
anvil-zksync -vv fork --fork-url era

If you installed via script or binaries and see a “command not found” error, you may need to add the install directory to your PATH.

Adding to your PATH

First, determine what shell you’re using:

echo $SHELL

Then add these lines below to bottom of your shell’s configuration file.

export ANVIL_ZKSYNC_HOME="$HOME/.anvil-zksync"
export PATH="$ANVIL_ZKSYNC_HOME/bin:$PATH"

Save the file. You’ll need to open a new shell/terminal window for the changes to take effect.

Upgrading

• Homebrew: brew upgrade anvil-zksync
• Installation script: re-run the install script to pull the latest
• Docker: docker pull ghcr.io/matter-labs/anvil-zksync:latest
• Source build: pull latest, cargo build --release, then replace the binary

Uninstall

Homebrew

brew uninstall anvil-zksync

Script

rm -f ~/.foundry/bin/anvil-zksync

Docker

docker rmi ghcr.io/matter-labs/anvil-zksync

Binaries

rm /usr/local/bin/anvil-zksync

Getting Started

Get up and running in four steps: start your node, interact via RPC, deploy a contract, and replay a transaction.

1. Start your local node

By default, run is the active command:

anvil-zksync

• RPC endpoint: http://localhost:8011
• Dev accounts: 10 pre-funded wallets

To see VM traces and call stacks, add -vv (increase verbosity level for more detail):

anvil-zksync -vv

2. Send an RPC call

Use curl or Foundry’s cast against your local node:

curl -s -X POST http://localhost:8011 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

cast block-number --rpc-url http://localhost:8011

3. Deploy a contract

Compile with zkSync support, then deploy via forge:

forge build --zksync
forge create \
  contracts/Greeter.sol:Greeter \
  --constructor-args "Hello, zkSync!" \
  --rpc-url http://localhost:8011 \
  --chain 260 \
  --zksync

4. Replay a historical transaction

Fork and replay any on-chain tx locally, with verbose tracing:

anvil-zksync -vv replay_tx \
  --fork-url mainnet \
  0xe12b1924faa45881beb324adca1f8429d553d7ad56a2a030dcebea715e1ec1e4

Next steps

• CLI commands
• RPC methods
• Guides

anvil-zksync

A single binary local ZK chain node that can impersonate any ZKsync powered or Elastic Network ZK chain. Ideal for integration tests, fork based debugging, quick prototyping, and offline experiments.

Installation

brew tap matter-labs/anvil-zksync https://github.com/matter-labs/anvil-zksync.git 
brew install anvil-zksync

Usage

anvil-zksync [OPTIONS] [COMMAND]

Quick start

# 1. Fresh network that auto‑mines
anvil-zksync run -vv

# 2. Fork mainnet at the latest block
anvil-zksync fork mainnet

# 3. Replay tx from Abstract mainnet with user vm traces
anvil-zksync -vv replay_tx --fork-url abstract \
0xea5a45976f8013fd937ac267211fa575bc5968350a0ae3d8932bad75651d933c

Commands

Global options

Chain initialization

Mining & mempool

General

Network

Debugging

Gas configuration

System

Logging

Cache

Accounts

Block sealing

Server

L1 (unstable)

Custom base token

Next steps

• Start a local chain → run
• Fork Elastic Network chains → fork
• Replay transaction → replay_tx

run

Launch an Elastic Network ZK chain for integration tests, debugging, or rapid prototyping.

Synopsis

anvil-zksync [OPTIONS]

Key options

All global flags (network, gas, logging, cache, etc.) are also accepted.

Experimental L1 mode 🚧

Enable a companion Layer 1 Anvil while running your L2 node.
Useful for testing bridge flows and deposit/withdraw paths.

⚠️ L1 support is marked UNSTABLE; interfaces and behavior may change between releases.

L1 quick start

anvil-zksync --spawn-l1 --auto-execute-l1 -vv

Connect to an existing L1 node

anvil-zksync --external-l1 http://127.0.0.1:8545

When running the L1 node (anvil) alongside anvil-zksync, make sure to start it with the --no-request-size-limit flag to avoid data payload issues:

anvil --no-request-size-limit

Behavior

• Starts with a clean L2 state (no contracts, no history).
• Auto-mines each submitted transaction unless you pass --no-mining or set a fixed --block-time.
• Generates deterministic dev accounts unless you provide a custom mnemonic.
• When --spawn-l1 or --external-l1 is enabled, cross-chain calls target that L1 endpoint and deposit logs are emitted as usual.

Examples

1. Quick start with verbose traces

anvil-zksync -vv

2. Manual mining workflow

anvil-zksync --no-mining
# elsewhere:
cast rpc evm_mine

3. Pre-load a snapshot & dump on exit

anvil-zksync --state ./snapshot.json

See also

• fork — fork an existing network
• replay_tx — fork & replay a transaction
• CLI overview — all global flags and usage

fork

Create a local anvil-zksync node pre-loaded with live state from a remote network. All subsequent transactions are mined locally, so you can experiment freely without touching the real chain.

Synopsis

anvil-zksync fork --fork-url <FORK_URL> [OPTIONS]

--fork-url is required. It accepts either an HTTP/S endpoint or a short-hand alias such as: mainnet, sepolia-testnet, abstract, etc.

Named chain aliases

Options

Behavior

• The forked state is loaded once at startup; changes made locally never propagate back to the remote network.
• If neither --fork-block-number nor --fork-transaction-hash is supplied, anvil-zksync fetches the latest block.
• All global flags (logging, gas, cache, etc.) still apply.

Examples

1. Fork Era mainnet at the latest block

anvil-zksync fork --fork-url mainnet

2. Fork a local node over HTTP

anvil-zksync fork --fork-url http://127.0.0.1:3050

3. Fork mainnet at block 59,473,098

anvil-zksync fork --fork-url mainnet --fork-block-number 59473098

4. Fork Abstract

anvil-zksync fork --fork-url abstract

See also

• run — start a clean chain
• replay_tx — fork & replay a specific transaction
• CLI Overview — global flags and usage

replay_tx

Spin up an anvil-zksync node that forks a remote network and immediately re-executes a chosen L2 transaction.

Perfect for step-through debugging or gas cost inspection of real world transactions and contract interactions.

Synopsis

anvil-zksync replay_tx --fork-url <FORK_URL> <TX>

Both parameters are required:

• --fork-url <FORK_URL> - remote endpoint or chain alias
• <TX> - L2 transaction hash to replay

Named chain aliases

Arguments

Options

All global flags (verbosity, cache, gas tuning, etc.) are also available.

Behavior

1. Downloads block state up to (but not including) <TX>.
2. Replays the transaction locally, reproducing calldata & timestamp.
3. Provides full VM traces, logs, and storage-diff when -vv or higher is enabled.

Examples

1. Replay a swap transaction from Era mainnet

anvil-zksync replay_tx \
  --fork-url mainnet \
  0xe56fd585309971c7c68b19c6c75a39c4b450731f9884c7b73e13276bb6db9b5b

2. Replay a tx from a local node

anvil-zksync replay_tx \
  --fork-url http://127.0.0.1:3050 \
  0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef

3. Replay a failed transaction with user VM tracing

anvil-zksync -vv replay_tx \
  --fork-url mainnet \
  0x9419f4eb8d553dd4f4d254badfd28efb0b2416c4b0eb26076f90e1226501a3e0

See also

• fork — fork without replay
• run — fresh, empty chain
• CLI overview — global flags and usage

anvil-zksync Action 🚀

A lightweight GitHub Action that starts an anvil-zksync node inside your workflow, so you can run tests or scripts against a local ZK chain.

Quickstart

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start anvil-zksync
        uses: dutterbutter/anvil-zksync-action@v1.1
        with:
          mode: run

      - name: Run tests
        run: |
          # e.g. point your tests at http://localhost:8011
          yarn test:contracts

Example: Forking Mainnet

- name: Start anvil-zksync in fork mode
  uses: dutterbutter/anvil-zksync-action@v1.1
  with:
    mode: fork
    forkUrl: mainnet
    forkBlockNumber: 59_485_781
    port: 8015

Inputs

For an exhausted list of available inputs, see the anvil-zksync-action readme.

Uploading Logs

- name: Upload anvil logs
  uses: actions/upload-artifact@v4
  with:
    name: anvil-zksync-log
    path: anvil-zksync.log

For more options and detailed CLI flags, see the anvil-zksync CLI reference.

Testing with anvil-zksync

Use Hardhat, Mocha & Chai to write and run tests against a live anvil-zksync node.

1. Scaffold a Hardhat project

npm init -y
npm install --save-dev hardhat
npx hardhat

2. Install ZKsync & test libraries

Install the ZKsync Hardhat plugin, ethers provider, and test tools:

yarn add -D @matterlabs/hardhat-zksync zksync-ethers ethers mocha chai @types/mocha @types/chai

3. Configure Hardhat

Edit hardhat.config.ts (or .js) to point tests at your local node:

import '@matterlabs/hardhat-zksync';

export default {
  zksolc: { version: '1.5.13', settings: {} },
  defaultNetwork: 'anvil_zksync',
  networks: {
    hardhat: { zksync: true },
    anvil_zksync: {
      url: 'http://localhost:8011',
      ethNetwork: 'http://localhost:8545',
      zksync: true,
    },
  },
  solidity: { version: '0.8.17' },
};

4. Add a test script

In your package.json, add:

"scripts": {
  "test": "mocha --recursive --exit"
}

5. Write a sample test

Create test/Greeter.test.ts:

import { expect } from 'chai';
import { Wallet, Provider } from 'zksync-ethers';
import * as hre from 'hardhat';
import { Deployer } from '@matterlabs/hardhat-zksync';

const RICH_PK = '0x7726827caac94a7f9e1b160f7ea819f172f7b6f9d2a97f992c38edeab82d4110';

describe('Greeter', function () {
  it('deploys and greets', async function () {
    const provider = Provider.getDefaultProvider();
    const wallet = new Wallet(RICH_PK, provider);
    const deployer = new Deployer(hre, wallet);

    // compile & deploy
    const artifact = await deployer.loadArtifact('Greeter');
    const greeter = await deployer.deploy(artifact, ['Hello, zkSync!']);

    // call and assert
    expect(await greeter.greet()).to.equal('Hello, zkSync!');
  });
});

6. Run your node & tests

1. Terminal A:

   anvil-zksync
   

2. Terminal B:

   npm test
   

Your tests will connect to http://localhost:8011 and run against your local ZK chain node.

anvil-zksync Action 🚀

A lightweight GitHub Action that starts an anvil-zksync node inside your workflow, so you can run tests or scripts against a local ZK chain.

Quickstart

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start anvil-zksync
        uses: dutterbutter/anvil-zksync-action@v1.1
        with:
          mode: run

      - name: Run tests
        run: |
          # e.g. point your tests at http://localhost:8011
          yarn test:contracts

Example: Forking Mainnet

- name: Start anvil-zksync in fork mode
  uses: dutterbutter/anvil-zksync-action@v1.1
  with:
    mode: fork
    forkUrl: mainnet
    forkBlockNumber: 59_485_781
    port: 8015

Inputs

For an exhausted list of available inputs, see the anvil-zksync-action readme.

Uploading Logs

- name: Upload anvil logs
  uses: actions/upload-artifact@v4
  with:
    name: anvil-zksync-log
    path: anvil-zksync.log

For more options and detailed CLI flags, see the anvil-zksync CLI reference.

Bootloader Debugging

Let’s assume you have a mainnet transaction that you would like to investigate in-depth. It could be halting, reverting without apparent reason, taking too much gas etc. You have tried looking at the trace, but it is not enough to figure out what the problem is. With anvil-zksync you can replay that transaction locally and reliably* reproduce the execution flow.

* with some caveats, like slight mismatch in gas consumption due to the difference in touched slots

Replaying a transaction locally means we have access to low-level ZK EVM and hence can in theory debug it step by step. That being said, this is a time-consuming process and is overkill for most scenarios. Instead, you can debug bootloader by observing (and adding your own) debug prints. Bootloader exposes a system hook that allows to log arbitrary strings:

/// @dev This method accepts the message and some 1-word data associated with it
/// It triggers a VM hook that allows the server to observe the behavior of the system.
function debugLog(msg, data) {
    storeVmHookParam(0, msg)
    storeVmHookParam(1, data)
    setHook(VM_HOOK_DEBUG_LOG())
}

This hook is used by zksync_multivm crate to propagate the logs into tracing:

#![allow(unused)]
fn main() {
/// Accepts a vm hook and, if it requires to output some debug log, outputs it.
pub(crate) fn print_debug_if_needed<H: HistoryMode>(
    hook: &VmHook,
    state: &VmLocalStateData<'_>,
    memory: &SimpleMemory<H>,
) {
    let log = match hook {
        VmHook::DebugLog => get_debug_log(state, memory),
        VmHook::DebugReturnData => get_debug_returndata(memory),
        _ => return,
    };

    tracing::trace!("{}", log);
}
}

If you run anvil-zksync with RUST_LOG=zksync_multivm=trace you will see these logs being printed to your console:

$ RUST_LOG=zksync_multivm=trace anvil-zksync -vv replay_tx --fork-url https://genlayer-testnet.rpc.caldera.xyz/http 0x3ef55f45c8ad0580604aaff5371fc669aaef3b518b4b70599bf4c4222fd86aa6
...
TRACE Bootloader transaction 0: txPtr: 52056224
TRACE Bootloader transaction 0: execute: 1
TRACE Bootloader transaction 0: ethCall: 0
TRACE Bootloader transaction 0: Setting new L2 block: : 20520
TRACE Bootloader transaction 0: Setting new L2 block: : 1743956487
TRACE Bootloader transaction 0: Setting new L2 block: : 0x9f60ca85c6a78283453674a4809f59d40c4bd6584cf54c91e80b1cfe8e7f039a
TRACE Bootloader transaction 0: Setting new L2 block: : 1
...

Now, lets assume this is not enough, and you want to instrument some part of bootloader yourself. To do this you can open contracts/system-contracts/bootloader/bootloader.yul and modify it as you see fit. For the purposes of this demonstration I will add a new log at the very start of the transaction processing:

////////////////////////////////////////////////////////////////////////////
//                      Main Transaction Processing
////////////////////////////////////////////////////////////////////////////

debugLog("hello world")

Now rebuild bootloader:

$ cd contracts/system-contracts
$ yarn install --frozen-lockfile
$ yarn build:foundry

Finally, run anvil-zksync with your local version of contracts:

$ RUST_LOG=zksync_multivm=trace anvil-zksync --dev-system-contracts local --system-contracts-path $YOUR_PATH/contracts/system-contracts -vv replay_tx --fork-url https://genlayer-testnet.rpc.caldera.xyz/http 0x3ef55f45c8ad0580604aaff5371fc669aaef3b518b4b70599bf4c4222fd86aa6
...
TRACE Bootloader transaction 0: hello world
...

Updating anvil-zksync to Support a New Protocol Version

This guide describes the step-by-step process for adding support for a new protocol version in anvil-zksync, using the v28 support PR (#637) as a reference.

1. Prepare a Versioned Contract Branch with Anvil-ZKsync Debug Support

anvil-zksync relies on a customized version of the era-contracts repository to enable debugging, impersonation, and other test-specific features. This requires:

• Inserting special debug markers,
• Adding a no-security default account contract,
• Adjusting the preprocessing pipeline.

You can use the following diff as a reference: anvil-zksync-0.4.x-release-v28 vs release-v28

Required Customizations

The following markers and blocks are used to encapsulate anvil-zksync-specific changes:

• DEBUG SUPPORT START / DEBUG SUPPORT END
• FOUNDRY SUPPORT START / FOUNDRY SUPPORT END
• <!-- @ifndef ACCOUNT_IMPERSONATING --> (Yul preprocessing)
• For impersonating block start / For impersonating block end in bootloader preprocessing

You must also include a special test contract:

• system-contracts/contracts/DefaultAccountNoSecurity.sol

Files to Modify

Apply the above debug customizations to the following files in your era-contracts release branch:

• l1-contracts/contracts/state-transition/chain-deps/facets/Executor.sol
• system-contracts/bootloader/bootloader.yul
• system-contracts/contracts/DefaultAccount.sol
• system-contracts/contracts/interfaces/IAccount.sol
• system-contracts/contracts/DefaultAccountNoSecurity.sol (new)
• system-contracts/scripts/preprocess-bootloader.ts

Branch Naming Convention

Create a new branch from the official release branch (e.g. release-v29) using the format:

anvil-zksync-<anvil-version>-release-<protocol-version>

For example:

anvil-zksync-0.6.x-release-v29

This branch will contain the upstream contracts from the specified protocol version, augmented with the anvil-zksync debug and testing support described above.

Once the debug-ready contracts are prepared in this custom branch, they can be integrated into the anvil-zksync repository as part of the protocol support update.

2. Determine the Target Version and Affected Crates

Identify the new protocol version to support, such as v29, and locate the corresponding tag or commit in the zksync-era repository. This is typically a tag like core-v29.0.0.

Next, identify all crates in anvil-zksync that rely on upstream zksync-era components. The crates to be updated include:

• zksync_mini_merkle_tree
• zksync_multivm
• zksync_contracts
• zksync_basic_types
• zksync_types
• zksync_vm_interface
• zksync_web3_decl

2.1. Patch zksync-era Dependencies in Cargo

Update the zksync-era related dependencies section of the workspace Cargo.toml to pin all required crates to the appropriate tag. This ensures all crates across the workspace resolve to a consistent and correct version.

Example update for protocol version v29:

zksync_mini_merkle_tree = { git = "https://github.com/matter-labs/zksync-era", rev = "core-v29.0.0" }
zksync_multivm          = { git = "https://github.com/matter-labs/zksync-era", rev = "core-v29.0.0" }
zksync_contracts        = { git = "https://github.com/matter-labs/zksync-era", rev = "core-v29.0.0" }
zksync_basic_types      = { git = "https://github.com/matter-labs/zksync-era", rev = "core-v29.0.0" }
zksync_types            = { git = "https://github.com/matter-labs/zksync-era", rev = "core-v29.0.0" }
zksync_vm_interface     = { git = "https://github.com/matter-labs/zksync-era", rev = "core-v29.0.0" }
zksync_web3_decl        = { git = "https://github.com/matter-labs/zksync-era", rev = "core-v29.0.0" }

Note: Although the protocol version is typically aligned with the crate tags (e.g. core-v29.0.0), this is not guaranteed. Always verify the correct tag by inspecting the upstream changelog or repository releases.

Once dependencies are patched, run:

cargo check --workspace

to confirm that all crates resolve successfully and that no incompatible API changes were introduced. Resolve breaking changes incrementally as needed.

4. Add the New Protocol Version and Contract Artifacts

Once your versioned contracts branch is prepared, the next step is to integrate it into anvil-zksync by updating the contract refresh pipeline and accounting for any new contracts introduced in the protocol upgrade.

4.1 Update the refresh_contracts.sh Script

Modify the scripts/refresh_contracts.sh script to register the new protocol version. This script downloads, compiles, and bundles contract artifacts for use by anvil-zksync.

1. Add a new v29 entry to the case statement and set the corresponding ERA_CONTRACTS_GIT_COMMIT. This should point to the HEAD commit of your custom anvil-zksync-<version>-release-v29 branch:

PROTOCOL_VERSION=${1:-v29}
case $PROTOCOL_VERSION in
  v26)
    ERA_CONTRACTS_GIT_COMMIT=50dc0669213366f5d3084a7a29a83541cf3c6435
    ;;
  v27)
    ERA_CONTRACTS_GIT_COMMIT=f0e17d700929e25292be971ea5196368bf120cea
    ;;
  v28)
    ERA_CONTRACTS_GIT_COMMIT=054a4745385119e7275dad801a2e830105f21e3e
    ;;
  v29)
    ERA_CONTRACTS_GIT_COMMIT=<COMMIT-HASH> # HEAD of anvil-zksync-0.6.x-release-v29
    ;;
  *)
    echo "Unrecognized/unsupported protocol version: $PROTOCOL_VERSION"
    exit 1
    ;;
esac

Replace <COMMIT-HASH> with the actual commit hash of the latest commit in your anvil-zksync-0.6.x-release-v29 branch.

4.2 Add New Contracts

If the protocol upgrade introduced any new contracts, append them to the relevant contract groups in the script.

For example, to include a new L1 contract named ChainAssetHandler added in v29:

if [[ $PROTOCOL_VERSION == v29 ]]; then
  l1_artifacts+=("ChainAssetHandler")
fi

Apply the same approach for L2 contracts, system contracts, or bootloader components.

For reference, see how this was handled for v28 here.

4.3 Generate the Contract Bundle

Run the updated script to fetch, compile, and package the contract artifacts for the new version:

./scripts/refresh_contracts.sh v29

This will produce a compressed archive at:

crates/core/src/deps/contracts/builtin-contracts-v29.tar.gz

This archive includes all compiled artifacts required for bootstrapping and executing system contracts under --protocol-version 29.

4.4 Refresh Other Artifacts

Depending on what changed in the protocol upgrade, you may also need to refresh:

• End-to-end contracts: scripts/refresh_e2e_contracts.sh
• L1 sidecar artifacts: scripts/refresh_l1_sidecar_contracts.sh
• Test contracts: scripts/refresh_test_contracts.sh

Each script behaves similarly—updating contracts for its respective domain.

Tip: There is a make command to run the scripts: make build-contracts.

4.5 Add Protocol Version Support for l1-setup

In addition to refreshing contracts, you must also update the l1-setup/setup.sh script to support the new protocol version. This step generates the genesis state, upgrade transaction, and configuration files required for bootstrapping an L1 sidecar instance tied to a specific protocol version.

1. Register the New Protocol in setup.sh

Locate the case block in l1-setup/setup.sh and add a new entry for the protocol version, pointing to the HEAD commit of your custom anvil-zksync-<version>-release-<protocol-version> branch and its matching core-vXX.Y.Z tag:

PROTOCOL_VERSION=${1:-v29}
case $PROTOCOL_VERSION in
  v26)
    ERA_CONTRACTS_GIT_COMMIT=50dc0669213366f5d3084a7a29a83541cf3c6435
    ERA_TAG=core-v26.8.1
    ;;
  v27)
    ERA_CONTRACTS_GIT_COMMIT=f0e17d700929e25292be971ea5196368bf120cea
    ERA_TAG=core-v27.0.0
    ;;
  v28)
    ERA_CONTRACTS_GIT_COMMIT=054a4745385119e7275dad801a2e830105f21e3e
    ERA_TAG=core-v28.0.0
    ;;
  v29)
    ERA_CONTRACTS_GIT_COMMIT=<COMMIT-HASH> # HEAD of anvil-zksync-0.6.x-release-v29
    ERA_TAG=core-v29.0.0
    ;;
  *)
    echo "Unrecognized/unsupported protocol version: $PROTOCOL_VERSION"
    exit 1
    ;;
esac

Be sure to replace <COMMIT-HASH> with the actual commit hash of your branch and ensure the matching ERA_TAG exists upstream.

2. Run the Setup Script

From the l1-setup/ directory, invoke the setup script to generate the artifacts:

./setup.sh v29

This will:

• Spin up a temporary anvil instance
• Deploy and configure L1 contracts and L2 upgrade transaction
• Clone and patch the correct version of zksync-era
• Generate and persist the following:

Output Artifacts

All outputs are stored under l1-setup/:

• configs/v29-genesis.yaml: L2 genesis metadata
• configs/v29-contracts.yaml: Deployed contract addresses
• state/v29-l2-upgrade-tx.json: L1 upgrade transaction payload
• state/v29-l1-state-payload.txt: Compressed anvil state loadable via anvil_loadState
• state/v29-l1-state.json: Full uncompressed state JSON

Caveats

• The process uses a randomized salt when deploying via CREATE2, so running it multiple times will produce non-deterministic results.
• Do not commit changes to the contracts submodule that may appear after running the script.

2. Register Protocol Version in l1-sidecar

After generating the files, register the new version in the following locations within the l1-sidecar and l1-setup crate.

crates/l1_sidecar/src/zkstack_config/mod.rs

Add a new mapping for the v29 configuration:

#![allow(unused)]
fn main() {
(
    ProtocolVersionId::Version29,
    ZkstackConfig {
        contracts: serde_yaml::from_slice(include_bytes!(
            "../../../../l1-setup/configs/v29-contracts.yaml"
        ))
        .unwrap(),
        genesis: serde_yaml::from_slice(include_bytes!(
            "../../../../l1-setup/configs/v29-genesis.yaml"
        ))
        .unwrap(),
        wallets,
    },
),
}

crates/l1_sidecar/src/upgrade_tx.rs

Include the upgrade transaction for v29:

#![allow(unused)]
fn main() {
(
    ProtocolVersionId::Version29,
    serde_json::from_slice::<UpgradeTx>(include_bytes!(
        "../../../l1-setup/state/v29-l2-upgrade-tx.json"
    ))
    .unwrap(),
),
}

crates/l1_sidecar/src/anvil.rs

Add the L1 state and payload for v29:

#![allow(unused)]
fn main() {
(
    ProtocolVersionId::Version29,
    include_bytes!("../../../l1-setup/state/v29-l1-state.json").as_slice(),
),
}

#![allow(unused)]
fn main() {
(
    ProtocolVersionId::Version29,
    include_str!("../../../l1-setup/state/v29-l1-state-payload.txt"),
),
}

5. Register the Protocol Version and New Contracts in system_contracts.rs

Once contract artifacts have been bundled via the refresh scripts, you must register the new protocol version and any newly introduced contracts in crates/deps/system_contracts.rs. This ensures anvil-zksync can load and deploy the correct system contracts when bootstrapping a chain at this protocol version.

5.1 Import New Addresses from zksync_types

Start by importing the relevant contract address constant from zksync_types. For example, if the protocol introduces a new ChainAssetHandler contract:

#![allow(unused)]
fn main() {
use zksync_types::L2_CHAIN_ASSET_HANDLER_ADDRESS;
}

5.2 Extend the BUILTIN_CONTRACT_ARCHIVES Array

Add the v29 contract archive to the BUILTIN_CONTRACT_ARCHIVES:

#![allow(unused)]
fn main() {
static BUILTIN_CONTRACT_ARCHIVES: [(ProtocolVersionId, &[u8]); 4] = [
    (
        ProtocolVersionId::Version26,
        include_bytes!("contracts/builtin-contracts-v26.tar.gz"),
    ),
    (
        ProtocolVersionId::Version27,
        include_bytes!("contracts/builtin-contracts-v27.tar.gz"),
    ),
    (
        ProtocolVersionId::Version28,
        include_bytes!("contracts/builtin-contracts-v28.tar.gz"),
    ),
    (
        ProtocolVersionId::Version29,
        include_bytes!("contracts/builtin-contracts-v29.tar.gz"),
    ),
];
}

5.3 Add a Constant for V29

Declare a constant identifier for use in contract registration:

#![allow(unused)]
fn main() {
const V29: ProtocolVersionId = ProtocolVersionId::Version29;
}

5.4 Register the New Contract in NON_KERNEL_CONTRACT_LOCATIONS (or BUILTIN_CONTRACT_LOCATIONS)

If the new contract is a non-kernel system contract, add it to NON_KERNEL_CONTRACT_LOCATIONS:

#![allow(unused)]
fn main() {
pub static NON_KERNEL_CONTRACT_LOCATIONS: [(&str, Address, ProtocolVersionId); 9] = [
    // ... existing entries ...
    ("L2WrappedBaseToken", L2_WRAPPED_BASE_TOKEN_IMPL, V26),
    ("ChainAssetHandler", L2_CHAIN_ASSET_HANDLER_ADDRESS, V29),
];
}

If the contract is kernel-level or categorized differently (e.g. a precompile), place it in the corresponding section within BUILTIN_CONTRACT_LOCATIONS.

5.5 Verify get_deployed_contracts Loads the Correct Contracts

The static BUILTIN_CONTRACTS map is automatically constructed from the entries in BUILTIN_CONTRACT_LOCATIONS and NON_KERNEL_CONTRACT_LOCATIONS. If the mappings above are correct, the logic will automatically pick up your new contract when bootstrapping a chain with --protocol-version 29.

5.6 Add a Unit Test

Consider duplicating an existing protocol-specific test to ensure the correct number of contracts are loaded for v29:

#![allow(unused)]
fn main() {
#[test]
fn load_v29_contracts() {
    let contracts = get_deployed_contracts(
        SystemContractsOptions::BuiltIn,
        ProtocolVersionId::Version29,
        None,
    );
    assert_eq!(
        contracts.len(),
        count_protocol_contracts(ProtocolVersionId::Version29)
    );
}
}

6 Register the New Protocol Version in fork.rs

To enable forking against chains using the new protocol version, update the list of supported protocol versions in crates/core/src/node/inner/fork.rs.

Extend SUPPORTED_VERSIONS

Locate the SUPPORTED_VERSIONS constant inside the SupportedProtocolVersions implementation and add your new entry:

#![allow(unused)]
fn main() {
impl SupportedProtocolVersions {
    const SUPPORTED_VERSIONS: [ProtocolVersionId; 4] = [
        ProtocolVersionId::Version26,
        ProtocolVersionId::Version27,
        ProtocolVersionId::Version28,
        ProtocolVersionId::Version29,
    ];
}
}

Update the array length (4 in this case) accordingly to reflect the number of supported versions.

7. Update Tests

With support for the new protocol version in place, add test coverage to ensure it is fully integrated and behaves as expected.

7.1 Add Protocol Version Test in protocol.rs

Navigate to e2e-tests-rust/tests/protocol.rs and add a dedicated test to verify that a node launched with the new protocol version (e.g. v29) reports it correctly via eth_getBlockByNumber or zks_getBlockDetails.

Example:

#![allow(unused)]
fn main() {
#[tokio::test]
async fn protocol_v29_on_demand() -> anyhow::Result<()> {
    let tester = AnvilZksyncTesterBuilder::default()
        .with_node_fn(&|node| node.args(["--protocol-version", "29"]))
        .build()
        .await?;

    let receipt = tester.tx().finalize().await?;
    let block_number = receipt.block_number().unwrap();

    let block_details = tester
        .l2_provider()
        .get_block_details(block_number)
        .await?
        .unwrap();

    assert_eq!(
        block_details.protocol_version,
        Some("Version29".to_string())
    );

    Ok(())
}
}

7.2 Update L1 Compatibility Test in l1.rs

In e2e-tests-rust/tests/l1.rs, bump the #[test_casing] macro to reflect the updated set of supported protocol versions:

#![allow(unused)]
fn main() {
#[test_casing(4, SUPPORTED_PROTOCOL_VERSIONS)]
#[tokio::test]
async fn l1_priority_tx(protocol_version: u16) -> anyhow::Result<()> {
    // ...
}
}

Adjust the first argument (4 in this case) to match the current number of supported versions.

This ensures your tests automatically run against all supported protocol configurations.

7.3 Run and Validate the Full Test Suite

After all test updates are complete, validate your changes across both unit and end-to-end tests.

# Run all Rust unit tests
make test

# Run Rust-based e2e tests (requires a running anvil-zksync instance)
cd e2e-tests-rust && cargo test

# Run full e2e suite (requires a running anvil-zksync instance)
make test-e2e

Confirm that all test suites pass successfully under the new protocol version to ensure correctness and regression safety.

8. Final Checklist

Use the following checklist to ensure all steps for adding a new protocol version (e.g. v29) have been completed:

• era-contracts fork updated with debug support
• Upstream dependencies patched
• New protocol feature added
• refresh_contracts.sh updated
• L1 setup (l1-setup/setup.sh) updated
• l1-sidecar integration completed
• system_contracts.rs updated
• Forking logic updated
• Tests written and updated
• Test suites executed and passing
• Documentation & Lint

JSON-RPC Reference

anvil-zksync exposes several JSON-RPC namespaces. Click a namespace to view available methods:

eth_* namespace

Standard Ethereum JSON-RPC calls supported by anvil-zksync.
Unless marked ✗, behavior matches the same call on an actual ZK chain endpoint.

curl -X POST http://localhost:8011 \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Method index

Accounts & keys

Blocks & chain

Transactions

Logs & filters

Gas & fees

Misc & sync

Method reference

We keep this section lightweight — for full parameter and return definitions see the official Ethereum JSON-RPC spec ↗︎.

eth_accounts

Returns a list of addresses owned by the local node (e.g. dev accounts).

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_accounts","params":[]}'

eth_getTransactionCount

Returns the nonce (transaction count) for an address.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_getTransactionCount",
        "params":["0x6fC1E2F6c7381BF9b7205F3a14e0ccabe9d9a8F8", "latest"]
      }'

Replace the address with one from eth_accounts if you’re running dev mode.

eth_blockNumber

Returns the latest block height.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

eth_chainId

Returns the chain ID of the node (default: 260 / 0x104).

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

eth_getBlockByNumber

Returns block details by block number.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_getBlockByNumber",
        "params":["latest", true]
      }'

true returns full transaction objects; false returns only tx hashes.

eth_getBlockByHash

Returns block details by hash.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_getBlockByHash",
        "params":["0xabc123...blockHash...", true]
      }'

Replace the hash with a real block hash from your node (e.g. via eth_getLogs or block explorer).

eth_sendRawTransaction

Broadcasts a raw signed transaction.
Use this with pre-signed transactions (e.g. from Foundry or viem).

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_sendRawTransaction",
        "params":["0x02f8..."]  // replace with actual signed tx
      }'

eth_sendTransaction

Broadcasts an unsigned transaction using dev accounts (in local mode only).
Automatically signs and sends the tx.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_sendTransaction",
        "params":[{
          "from": "0x6fC1E2F6c7381BF9b7205F3a14e0ccabe9d9a8F8",
          "to": "0x0000000000000000000000000000000000000000",
          "value": "0x2386F26FC10000"  // 0.01 ETH
        }]
      }'

eth_getTransactionByHash

Returns a transaction by its hash.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_getTransactionByHash",
        "params":["0x...transactionHash..."]
      }'

eth_getTransactionReceipt

Returns the receipt for a transaction hash (after it has been mined).

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_getTransactionReceipt",
        "params":["0x...transactionHash..."]
      }'

eth_estimateGas

Estimates how much gas a transaction will consume.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_estimateGas",
        "params":[{
          "from": "0x6fC1E2F6c7381BF9b7205F3a14e0ccabe9d9a8F8",
          "to": "0x0000000000000000000000000000000000000000",
          "data": "0x"
        }]
      }'

eth_call

Simulates a read-only call to a contract (does not submit a tx).

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_call",
        "params":[{
          "from": "0x6fC1E2F6c7381BF9b7205F3a14e0ccabe9d9a8F8",
          "to": "0x0000000000000000000000000000000000000000",
          "data": "0x..."
        }, "latest"]
      }'

Replace data with the ABI-encoded call data for the method you wish to simulate.

eth_getLogs

Returns logs matching the specified filter object.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_getLogs",
        "params":[{
          "fromBlock": "0x0",
          "toBlock": "latest",
          "address": "0x0000000000000000000000000000000000000000",
          "topics": []
        }]
      }'

eth_newFilter

Creates a new log filter on the node and returns its ID.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_newFilter",
        "params":[{
          "fromBlock": "0x0",
          "toBlock": "latest",
          "address": "0x0000000000000000000000000000000000000000",
          "topics": []
        }]
      }'

eth_getFilterChanges

Polls the filter for new changes (e.g. logs or block hashes since last call).

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_getFilterChanges",
        "params":["0x1"]
      }'

Replace 0x1 with the filter ID returned by eth_newFilter.

eth_uninstallFilter

Removes a previously created filter.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_uninstallFilter",
        "params":["0x1"]
      }'

After removal, the filter ID becomes invalid and cannot be polled.

eth_gasPrice

Returns the current gas price.
In anvil-zksync, this is hardcoded to 50_000_000 gwei (0x2FAF080).

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_gasPrice","params":[]}'

eth_feeHistory

Returns a stubbed gas fee history.
Parameters include block count, reference block, and optional reward percentiles.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"eth_feeHistory",
        "params":["0x5", "latest", [25, 50, 75]]
      }'

eth_syncing

Returns false — the node is always considered fully synced.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_syncing","params":[]}'

eth_protocolVersion

Returns the Ethereum protocol version as a hex string.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_protocolVersion","params":[]}'

Unimplemented stubs

The following methods currently return Method not found:

• eth_getCompilers
• eth_sign
• eth_subscribe
• eth_hashrate
• eth_maxPriorityFeePerGas
• eth_coinbase
• eth_signTypedData
• eth_getUncleByBlockNumberAndIndex
• eth_getUncleCountByBlockHash
• eth_getUncleByBlockHashAndIndex
• eth_getUncleCountByBlockNumber
• eth_getUncleByBlockNumberAndIndex

See also

• zks_* — ZKsync specific extensions
• debug_* — Execution traces & state inspection
• anvil_* — Node testing helpers

zks_* namespace

These calls expose Elastic Network specific data such as L1→L2 fees, bridge contract addresses, and batch details.

Unless marked ✗, they behave the same as on a public ZKsync endpoint.

curl -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zks_L1ChainId","params":[]}'

Method index

Fees & gas

Blocks & batches

Proofs

Accounts & tokens

Bridges & contracts

Misc & system

Method reference

Full schemas live in the official zkSync JSON-RPC docs ↗︎.

zks_estimateFee

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,"method":"zks_estimateFee",
        "params":[{
          "from":"0x…","to":"0x…","data":"0x…"
        }]
      }'

zks_estimateGasL1ToL2

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,"method":"zks_estimateGasL1ToL2",
        "params":[{
          "from":"0x…","to":"0x…","gasPerPubdata":"0x0"
        }]
      }'

zks_getAllAccountBalances

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,"method":"zks_getAllAccountBalances",
        "params":["0x…account…"]
      }'

zks_getBridgeContracts

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zks_getBridgeContracts","params":[]}'

zks_getBridgehubContract

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zks_getBridgehubContract","params":[]}'

zks_getBlockDetails

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zks_getBlockDetails","params":["0x1a"]}'

zks_getBytecodeByHash

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zks_getBytecodeByHash","params":["0x…hash…"]}'

zks_getConfirmedTokens

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zks_getConfirmedTokens","params":[0, 50]}'

zks_getBaseTokenL1Address

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zks_getBaseTokenL1Address","params":[]}'

zks_getL2ToL1LogProof

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,"method":"zks_getL2ToL1LogProof",
        "params":["0x…txHash…", 0]
      }'

zks_getRawBlockTransactions

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zks_getRawBlockTransactions","params":["0x1a"]}'

zks_getTransactionDetails

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zks_getTransactionDetails","params":["0x…txHash…"]}'

zks_L1ChainId

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"zks_L1ChainId","params":[]}'

Unimplemented stubs

The following methods are not yet implemented and will return Method not found:

• zks_getBatchFeeInput
• zks_getFeeParams
• zks_getL1BatchBlockRange
• zks_getL1BatchDetails
• zks_getL1GasPrice
• zks_getL2ToL1MsgProof
• zks_getMainContract
• zks_getProof
• zks_getProtocolVersion
• zks_getTestnetPaymaster
• zks_sendRawTransactionWithDetailedOutput
• zks_getTimestampAsserter
• zks_getL2Multicall3

See also

• eth_* — Ethereum compatible base methods
• debug_* — Execution traces & state inspection
• anvil_* — Node testing helpers

anvil_* namespace

Low level node controls that anvil-zksync exposes on top of the standard Ethereum RPC and zks RPC. They let devs mine blocks on demand, timetravel, impersonate accounts, edit balances/code, and tweak automine behaviour.

curl -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"anvil_mine","params":[]}'

Method index

Mining & mempool

Automine & intervals

State snapshots

Time travel

Accounts & impersonation

Chain parameters & logging

Method reference

Full schema lives in the Anvil docs ↗︎.

anvil_mine

Mine one or more blocks instantly.

# mine 1 block
curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"anvil_mine","params":[]}'

# mine 12 blocks
curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"anvil_mine","params":["0xc"]}'

anvil_mine_detailed

Same as anvil_mine but returns block hash, timestamp, gas used, etc.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"anvil_mine_detailed","params":[]}'

anvil_getAutomine

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"anvil_getAutomine","params":[]}'

anvil_setAutomine

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"anvil_setAutomine","params":[false]}'

anvil_snapshot

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"anvil_snapshot","params":[]}'

Stores the snapshot ID returned. Revert with anvil_revert.

anvil_revert

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"anvil_revert","params":["0x1"]}'

Snapshot IDs are hex strings ("0x1", "0x2"…).

anvil_impersonateAccount

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"anvil_impersonateAccount","params":["0x…addr…"]}'

anvil_setBalance

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,"method":"anvil_setBalance",
        "params":["0x…addr…", "0x8AC7230489E80000"]  // 10 ETH
      }'

anvil_setRpcUrl

Hot swap the upstream fork URL (must be same chain).

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"anvil_setRpcUrl","params":["https://mainnet.era.zksync.io"]}'

Unimplemented stubs

The following method is not yet implemented and will return Method not found:

• anvil_setMinGasPrice

See also

• eth_* — Ethereum compatible base methods
• hardhat_* — Hardhat style helpers
• zks_* — ZKsync specific extensions

hardhat_* namespace

Utility methods that mimic Hardhat Network behavior (impersonation, snapshot resets, on demand mining, etc.).
Perfect for Hardhat test suites, Foundry scripts, or any framework that expects the Hardhat JSON-RPC surface.

curl -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"hardhat_impersonateAccount","params":["0x…address…"]}'

Method index

Impersonation

Mining & automine

Chain reset

State modification

Method reference

Hardhat’s full spec is in the Hardhat Network docs ↗︎.

hardhat_impersonateAccount

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"hardhat_impersonateAccount",
        "params":["0x…targetAddress…"]
      }'

hardhat_stopImpersonatingAccount

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"hardhat_stopImpersonatingAccount",
        "params":["0x…targetAddress…"]
      }'

hardhat_getAutomine ▲

Returns true.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"hardhat_getAutomine","params":[]}'

hardhat_mine

Mine one block or N blocks instantly.

# mine 1 block
curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"hardhat_mine","params":[]}'

# mine 5 blocks
curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"hardhat_mine","params":["0x5"]}'

hardhat_reset ▲

Resets the chain state.
Blocknumber rewinds only work while running in fork mode.

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"hardhat_reset","params":[]}'

hardhat_setBalance

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"hardhat_setBalance",
        "params":["0x…targetAddress…", "0xDE0B6B3A7640000"]  // 1 ETH
      }'

hardhat_setCode

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"hardhat_setCode",
        "params":["0x…targetAddress…", "0x60006000…"]  // EVM bytecode
      }'

hardhat_setNonce

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"hardhat_setNonce",
        "params":["0x…targetAddress…", "0xA"]  // nonce = 10
      }'

hardhat_setStorageAt

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,
        "method":"hardhat_setStorageAt",
        "params":[
          "0x…targetAddress…",
          "0x0",                    // storage slot
          "0x0000000000000000000000000000000000000000000000000000000000000042"
        ]
      }'

Unimplemented stubs

The following methods are not yet implemented and will return Method not found:

• hardhat_addCompilationResult
• hardhat_dropTransaction
• hardhat_metadata
• hardhat_setCoinbase
• hardhat_setLoggingEnabled
• hardhat_setMinGasPrice
• hardhat_setNextBlockBaseFeePerGas
• hardhat_setPrevRandao

See also

• eth_* — Ethereum compatible base methods
• zks_* — ZKsync specific extensions
• anvil_* — node management helpers

evm_*, net_*, web3_*, and debug_* namespaces

These helper methods cover developer tooling (evm_*), network status (net_*), client metadata (web3_*), and execution tracing (debug_*).

Use them alongside the core eth_* and zks_* calls for full functionality.

curl -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"debug_traceCall","params":[{ "to":"0x…", "data":"0x…"}, "latest", {}]}'

Method index

evm_* — Developer utility calls

net_* — Network diagnostics

web3_* — Client metadata

debug_* — Execution tracing

Method reference

evm_snapshot

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"evm_snapshot","params":[]}'

evm_revert

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"evm_revert","params":["0x1"]}'

Use the snapshot ID returned by evm_snapshot.

evm_increaseTime

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"evm_increaseTime","params":[3600]}'

evm_mine

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"evm_mine","params":[]}'

evm_setNextBlockTimestamp

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"evm_setNextBlockTimestamp","params":[1700000000]}'

evm_setTime

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"evm_setTime","params":[1700000000]}'

evm_setAccountNonce

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"evm_setAccountNonce","params":["0x…addr…", "0xA"]}'

net_version

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"net_version","params":[]}'

net_peerCount

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"net_peerCount","params":[]}'

net_listening

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"net_listening","params":[]}'

web3_clientVersion

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"web3_clientVersion","params":[]}'

debug_traceCall

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,"method":"debug_traceCall",
        "params":[{ "to":"0x…","data":"0x…"}, "latest", {}]
      }'

debug_traceBlockByHash

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{
        "jsonrpc":"2.0","id":1,"method":"debug_traceBlockByHash",
        "params":["0x…blockHash…", {}]
      }'

debug_traceBlockByNumber

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"debug_traceBlockByNumber","params":["latest", {}]}'

debug_traceTransaction

curl -s -X POST http://localhost:8011 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"debug_traceTransaction","params":["0x…txHash…", {}]}'

Unimplemented stubs

• evm_addAccount
• evm_removeAccount
• evm_setAccountBalance
• evm_setAccountCode
• evm_setAccountStorageAt
• evm_setAutomine
• evm_setBlockGasLimit
• evm_setIntervalMining

See also

• eth_* — Ethereum compatible base methods
• zks_* — ZKsync specific extensions
• hardhat_* — Hardhat style helpers