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.

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