Ethereum JSON-RPC API for ZKsync Era

·

ZKsync Era is a high-performance Layer 2 scaling solution that maintains full compatibility with the Ethereum ecosystem. It supports the standard Ethereum JSON-RPC API, enabling developers to interact with the network using familiar tools and workflows. However, due to its unique architecture as a zkRollup, there are important distinctions and considerations when working with ZKsync-specific implementations.

This guide provides a comprehensive overview of supported JSON-RPC methods, key differences from Ethereum L1, and practical usage examples to help developers build efficiently on ZKsync Era.

Key Differences from Ethereum L1

While ZKsync Era aligns closely with Ethereum's interface, certain structural differences impact how some RPC methods behave:

Block Data Retrieval Methods

Methods such as eth_getBlockByHash, eth_getBlockByNumber, and Geth’s pubsub API eth_subscribe with the newHeads parameter do not return actual values for receiptsRoot, transactionsRoot, or stateRoot. Instead, these fields contain zero values.

👉 Discover how ZKsync’s architecture enhances scalability while preserving security.

This behavior occurs because ZKsync’s Layer 2 blocks don’t include a state root—only L1 batches have this concept. Developers should account for this when validating block integrity or building explorers and analytics tools.

Unsupported Method: eth_sendTransaction

The eth_sendTransaction method is intentionally not supported in ZKsync. To send transactions, use eth_sendRawTransaction with a pre-signed transaction payload. This design enforces security best practices and aligns with non-interactive transaction submission models used in modern wallets and dApps.

Core JSON-RPC Methods Overview

Below is a detailed breakdown of essential JSON-RPC methods available on ZKsync Era, including parameters, return types, and usage examples.

eth_chainId

Retrieves the current chain ID of the ZKsync network.

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_chainId",
  "params": []
}

Example Response:

{
  "jsonrpc": "2.0",
  "result": "0x144",
  "id": 1
}
Chain ID 0x144 corresponds to ZKsync Era Mainnet.

eth_call

Executes a read-only message call immediately without creating a transaction.

Useful for querying contract state without gas costs.

eth_estimateGas

Estimates the gas required to execute a transaction.

Note: The from field cannot reference a smart contract unless it's a SmartAccount.

eth_gasPrice

Returns the current average gas price in gwei.

This value helps optimize transaction costs based on real-time network demand.

👉 Learn how to optimize gas efficiency across Layer 2 networks.

eth_newFilter, eth_newBlockFilter, eth_newPendingTransactionFilter

These methods create filters to monitor events, new blocks, or pending transactions respectively.

Filters enable real-time monitoring of blockchain activity and are essential for event-driven applications like decentralized exchanges or alert systems.

eth_uninstallFilter

Removes an existing filter by ID.

Use this method to clean up unused filters and free node resources.

eth_getLogs, eth_getFilterLogs, eth_getFilterChanges

Retrieve logs matching filter criteria:

Each log includes details like address, topics, transaction hash, and removal status (due to reorgs).

eth_getBalance

Gets the balance of an account at a specific block.

Critical for wallet interfaces and balance tracking services.

eth_getBlockByNumber, eth_getBlockByHash

Fetches block data by number or hash.

Despite zeroed-out roots (stateRoot, etc.), these methods remain vital for block exploration.

eth_getBlockTransactionCountByNumber, ByHash

Returns the number of transactions in a given block.

Useful in dashboards and statistical analysis tools.

eth_getBlockReceipts

Fetches receipts for all transactions in a specified block.

eth_getCode, eth_getStorageAt

Both support optional block parameters for historical analysis.

eth_getTransactionCount

Gets the number of transactions sent from an address (nonce).

Used to construct valid transactions and prevent replay attacks.

Transaction Retrieval Methods

ZKsync supports standard Ethereum methods:

All return detailed metadata including L1 batch association, crucial for cross-layer tracking.

Network & Client Information

Frequently Asked Questions

Why are stateRoot and receiptsRoot zero in block responses?

ZKsync uses zkRollup architecture where state commitments occur at the L1 batch level, not per L2 block. Hence, per-block roots are not applicable and return zero.

Can I use MetaMask with ZKsync Era?

Yes. Configure MetaMask with the correct chain ID (0x144) and RPC URL (https://mainnet.era.zksync.io). Most dApps work seamlessly after configuration.

Is EIP-1559 supported?

Yes. ZKsync Era supports dynamic fee markets via EIP-1559. Use maxFeePerGas and maxPriorityFeePerGas in your transactions.

How do I handle transaction finality?

Finality is determined through L1 confirmation of batch proofs. Monitor L1 contracts like the zkSync contract on Ethereum for proof submission and verification events.

What tools can I use to interact with ZKsync?

You can use standard tools like ethers.js, web3.js, Hardhat, and Foundry. Ensure you're connecting to a ZKsync-compatible RPC endpoint.

Why is eth_sendTransaction not supported?

It's disabled to prevent insecure transaction signing patterns. Always use eth_sendRawTransaction with pre-signed payloads for better control and security.

Keyword Integration Summary

Core keywords naturally integrated throughout:

These terms reflect common developer search intents and ensure strong SEO performance while maintaining technical accuracy.

👉 Start building on one of the fastest-growing Layer 2 ecosystems today.