ZKsync Era 以太坊 JSON-RPC API 完全指南

·

ZKsync Era 全面支持标准的以太坊 JSON-RPC API，使开发者能够使用熟悉的以太坊工具和库与 ZKsync 网络进行交互。本文将详细介绍 ZKsync Era 的 API 特性、使用方法和注意事项。

ZKsync Era 与标准以太坊 API 的差异

尽管 ZKsync Era 兼容以太坊 JSON-RPC API，但在某些方面存在重要差异，开发者需要特别注意：

区块数据检索方法

eth_getBlockByHash、eth_getBlockByNumber 和 Geth 的 pubsub API eth_subscribe（使用 newHeads 参数）等方法在返回区块数据时，不会提供实际的 receiptsRoot、transactionsRoot 和 stateRoot 值。

这些字段包含零值，因为 ZKsync 的 L2 区块不包含状态根的概念，只有 L1 批次才有此概念。

不支持的方法

eth_sendTransaction 方法在 ZKsync Era 中 intentionally 不被支持。开发者应使用 eth_sendRawTransaction 来发送已签名的交易。

核心 API 方法详解

eth_chainId：获取当前链 ID

获取当前区块链网络的链 ID。

参数：无

返回：QUANTITY - 当前区块链网络链 ID 的十六进制表示

示例请求：

curl --request POST \
  --url https://mainnet.era.zksync.io/ \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_chainId",
    "params": []
  }'

示例响应：

{
  "jsonrpc": "2.0",
  "result": "0x144",
  "id": 1
}

eth_call：执行消息调用

立即执行新的消息调用，而不在区块链上创建交易。

参数：

  1. 交易对象
  2. BlockIdVariant - 可选，区块编号或标签

返回：DATA - 智能合约函数返回的数据，以十六进制格式编码

eth_estimateGas：估算 gas 用量

估算执行调用所需的 gas 量。如果 from 字段不是 SmartAccount 的智能合约，则会触发异常。

参数：

  1. 交易对象
  2. uint32 - 可选区块号

返回：QUANTITY - 估算的 gas 量，十六进制格式

eth_gasPrice：获取当前 gas 价格

检索网络中当前的平均 gas 价格，以 gwei 表示。此值提供了查询时网络上每个 gas 单位成本的估计，对于根据当前网络状况动态调整交易费用特别有用。

参数：无

返回：QUANTITY - 网络上当前的平均 gas 价格，以 gwei 表示并编码为十六进制字符串

事件监听与过滤器

eth_newFilter：创建新事件过滤器

启动新过滤器以监听智能合约或其他区块链操作发出的特定事件。此功能使应用程序能够通过设置感兴趣事件的标准来实时响应事件和更新。

参数：

  1. Filter - 包含各种字段的对象，用于指定过滤事件的标准

返回：QUANTITY - 新创建过滤器的唯一标识符，编码为十六进制字符串

eth_newBlockFilter：创建新区块过滤器

创建过滤器以在新区块到达时通知。

参数：无

返回：QUANTITY - 新创建的区块过滤器的唯一标识符，编码为十六进制字符串

eth_newPendingTransactionFilter：创建待处理交易过滤器

设置新过滤器以提供进入待处理状态交易的通知，这意味着它们已广播到网络但尚未包含在区块中。此过滤器可用于跟踪等待确认的交易。

参数：无

返回：QUANTITY, 32 字节 - 新待处理交易过滤器的唯一标识符，编码为十六进制字符串

eth_uninstallFilter：卸载过滤器

移除先前使用 eth_newFilter、eth_newBlockFilter 或 eth_newPendingTransactionFilter 创建的过滤器。此方法用于停止接收指定过滤器的更新，并清理节点上与其关联的资源。

参数：

  1. QUANTITY, 32 字节 - 要移除的过滤器的唯一标识符，最初由过滤器创建方法返回

返回：Boolean - 如果过滤器成功卸载则为 true；否则为 false

数据检索方法

eth_getLogs：检索匹配的日志

检索与过滤器对象匹配的日志。

参数：

  1. Filter - 包含各种字段的对象，用于指定过滤事件的标准

返回：匹配过滤器条件的日志对象数组

eth_getBalance：获取账户余额

获取特定区块处账户的余额。

参数：

  1. DATA, 20 字节 - 要查询余额的账户地址
  2. QUANTITY | TAG - 整数区块号，或字符串 "latest"、"earliest"、"pending"、"safe" 或 "finalized"

返回：QUANTITY - 指定区块处账户的余额，编码为表示 gwei 值的十六进制字符串

eth_getBlockByNumber：按区块号检索区块

按区块号检索区块。

参数：

  1. QUANTITY | TAG - 整数区块号，或字符串 "latest"、"earliest"、"pending"、"safe" 或 "finalized"
  2. Boolean - 布尔标志，指示是返回完整交易对象（true）还是仅返回其哈希值（false）

返回：表示请求的区块的对象

eth_getBlockByHash：按区块哈希检索区块

按区块哈希检索区块。

参数：

  1. DATA, 32 字节 - 表示区块哈希的十六进制字符串
  2. Boolean - 布尔标志，指示是返回完整交易对象（true）还是仅返回其哈希值（false）

返回：包含有关区块及其交易的详细信息对象

👉 查看实时区块链数据工具

交易相关方法

eth_getTransactionCount：获取交易数量

获取从地址发送的交易数量。

参数：

  1. DATA, 20 字节 - 地址
  2. QUANTITY | TAG - 整数区块号，或字符串 "latest"、"earliest"、"pending"、"safe" 或 "finalized"

返回：QUANTITY - 从此地址发送的交易数量的整数

eth_getTransactionByHash：按哈希检索交易

按哈希检索交易。

参数：

  1. DATA, 32 字节 - 交易的哈希

返回：交易对象或 null（未找到交易时）

eth_getTransactionReceipt：获取交易收据

按交易哈希检索交易收据。

参数：

  1. DATA, 32 字节 - 交易的唯一哈希

返回：交易收据对象或 null（未找到收据时）

eth_sendRawTransaction：发送原始交易

将预签名的交易提交到网络进行广播。

参数：

  1. DATA - 完整的签名交易数据

返回：DATA, 32 字节 - 如果交易已成功提交到网络，则为交易哈希的单个字符串

网络状态方法

eth_protocolVersion：获取协议版本

返回当前协议版本。

参数：无

返回：String - 指示协议版本的单个字符串

web3_clientVersion：获取客户端版本

检索客户端软件的版本。

参数：无

返回：String - 节点支持的客户端版本

eth_feeHistory：获取费用历史记录

检索请求区块的费用历史记录。

参数：

  1. uint64 - 要检查的区块数量
  2. QUANTITY - 最新区块号
  3. Array of float32 - 要返回的交易费用百分位数

返回：包含以下字段的对象

常见问题

ZKsync Era 与标准以太坊 API 有何不同？

ZKsync Era 支持大多数标准以太坊 JSON-RPC API，但在区块数据检索方面存在关键差异。特别是 receiptsRoot、transactionsRoot 和 stateRoot 字段包含零值，因为 ZKsync 的 L2 区块不包含状态根的概念。此外，eth_sendTransaction 方法不被支持，开发者应使用 eth_sendRawTransaction。

如何在 ZKsync Era 上发送交易？

在 ZKsync Era 上发送交易，需要使用 eth_sendRawTransaction 方法而不是 eth_sendTransaction。您需要先在客户端签署交易，然后将已签名的原始交易数据提交到网络。这种方法提高了安全性并确保了交易的完整性。

ZKsync Era 支持哪些事件监听方法？

ZKsync Era 支持完整的事件监听功能，包括 eth_newFilter（创建事件过滤器）、eth_newBlockFilter（创建区块过滤器）和 eth_newPendingTransactionFilter（创建待处理交易过滤器）。这些过滤器可以使用 eth_uninstallFilter 方法移除，并使用 eth_getFilterChanges 或 eth_getFilterLogs 检索数据。

如何获取 ZKsync Era 的 gas 价格信息？

可以使用 eth_gasPrice 方法获取当前网络的平均 gas 价格，或以 gwei 表示。此外，eth_feeHistory 方法可以提供历史费用数据，帮助开发者了解网络费用趋势并优化交易成本。

👉 探索更多区块链开发策略

ZKsync Era 的区块结构有什么特点？

ZKsync Era 的区块结构包含一些特有的字段，如 l1BatchNumber（关联的 L1 批次号）和 l1BatchTimestamp（L1 批次时间戳）。这些字段反映了 ZKsync 作为 Layer 2 解决方案与以太坊主网的特殊集成方式，为开发者提供了更多维度的区块链数据。

如何处理 ZKsync Era 上的智能合约交互？

在 ZKsync Era 上与智能合约交互与以太坊主网类似，可以使用 eth_call 执行只读操作，使用 eth_estimateGas 估算 gas 消耗，以及使用 eth_sendRawTransaction 执行状态改变操作。合约地址和 ABI 的使用方式与以太坊完全相同，确保了开发体验的一致性。