快速了解兼容 Ethereum 的 JSON-RPC 接口

最新推荐文章于 2026-06-29 09:57:50 发布

原创最新推荐文章于 2026-06-29 09:57:50 发布 · 913 阅读

14 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#json #智能合约 #polkadot #开发语言 #区块链

原文作者：PaperMoon团队

前言

随着区块链生态的发展，越来越多的开发者希望在不同公链之间实现技术复用与平滑迁移。为了降低以太坊开发者进入 Polkadot 生态的门槛，Polkadot Hub 提供了兼容 Ethereum 的 JSON-RPC 接口，使开发者可以继续使用熟悉的以太坊工具链进行交互。

通过这些接口，开发者可以：
   •   查询账户信息
   •   获取区块和交易数据
   •   调用智能合约
   •   发送交易
   •   调试执行过程

本文将系统介绍 Polkadot Hub 当前支持的 JSON-RPC 方法，并配合示例进行说明，帮助开发者快速上手。

测试网络 RPC 入口

本文示例使用 Polkadot Hub 测试网的 RPC 节点：

https://services.polkadothub-rpc.com/testnet

所有请求均通过 HTTP POST 的方式发送，遵循 JSON-RPC 2.0 标准格式。

JSON-RPC 基础说明

JSON-RPC 是一种基于 JSON 的远程过程调用协议，Ethereum 节点普遍采用该协议作为标准接口。

基本请求格式如下：

{
  "jsonrpc": "2.0",
  "method": "方法名",
  "params": [],
  "id": 1
}

   •   jsonrpc：协议版本
   •   method：调用的方法名称
   •   params：参数数组
   •   id：请求标识符

账户与链信息接口

1. eth_accounts

功能：返回当前客户端管理的地址列表。

参数：无

用途：查询节点钱包账户（通常用于本地节点）

2. eth_blockNumber

功能：返回最新区块高度

参数：无

用途：获取当前链的同步进度

3. eth_chainId

功能：返回当前链 ID

用途：用于交易签名防止重放攻击

4. net_version

功能：返回网络 ID

5. web3_clientVersion

功能：返回客户端版本信息

合约调用与 Gas 相关接口

1. eth_call

功能：执行一次“只读”合约调用，不会上链

常见用途：
   •   查询余额
   •   调用 view / pure 函数
   •   读取状态变量

特点：
• 不消耗 Gas
• 不改变状态

2. eth_estimateGas

功能：估算交易所需 Gas

用途：
• 发送交易前进行成本预估
• 防止 Gas 不足导致失败

3. eth_gasPrice

功能：返回当前 Gas 单价（Wei）

4. eth_maxPriorityFeePerGas

功能：返回建议的小费 Gas 价格（EIP-1559）

账户与合约状态查询

1. eth_getBalance

功能：查询账户余额

单位： Wei

2. eth_getCode

功能：获取地址上的合约字节码

用途：
• 判断是否为合约账户
• 调试部署问题

3. eth_getStorageAt

功能：读取合约指定存储槽数据

用途：
• 底层调试
• 状态分析

4. eth_getTransactionCount

功能：获取账户 nonce（交易序号）

用途：
• 构造交易时使用
• 防止重复交易

区块与交易查询接口

1. eth_getBlockByHash

通过区块 Hash 查询区块信息

2. eth_getBlockByNumber

通过区块高度查询区块

3. eth_getBlockTransactionCountByNumber

获取某个区块中的交易数量

4. eth_getBlockTransactionCountByHash

通过 Hash 查询交易数量

5. eth_getTransactionByHash

查询单笔交易详情

6. eth_getTransactionByBlockNumberAndIndex

按区块号和索引查询交易

7. eth_getTransactionByBlockHashAndIndex

按区块 Hash 和索引查询交易

8. eth_getTransactionReceipt

查询交易回执（是否成功、Gas 消耗、日志等）

这是判断交易状态的关键接口。

日志与事件查询

eth_getLogs

功能：按条件查询合约事件日志

支持过滤条件：
   •   区块范围
   •   合约地址
   •   Topics
   •   BlockHash

用途：
   •   监听合约事件
   •   构建区块浏览器
   •   数据分析

交易发送接口

1. eth_sendRawTransaction

功能：发送已签名交易

特点：
   •   本地签名
   •   最安全
   •   推荐方式

2. eth_sendTransaction

功能：由节点代签交易

说明：

通常只适用于本地节点环境，生产环境较少使用。

节点状态接口

1. eth_syncing

查看节点是否同步中

2. net_listening

节点是否监听网络连接

3. net_peerCount

当前连接的节点数量

4. system_health

系统健康状态

调试与执行追踪接口（Debug API）

Polkadot Hub 还支持部分以太坊调试接口，方便开发者排查问题。

1. debug_traceBlockByNumber

追踪整个区块的执行过程

支持 tracer：
• callTracer
• opTracer

2. debug_traceTransaction

追踪单笔交易执行路径

常用于：
• 分析失败原因
• 调试复杂合约调用

3. debug_traceCall

对 eth_call 进行完整执行追踪

特点：
• 不上链
• 返回详细执行信息

返回结果格式说明

所有正常返回遵循 JSON-RPC 2.0 规范：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": ...
}

错误处理机制

当发生错误时，返回格式如下：

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "错误信息"
  }
}

开发者应在代码中正确处理 error 字段，避免程序异常。

技术意义与实践价值

通过这些 JSON-RPC 接口，Polkadot Hub 实现了与以太坊生态的高度兼容，带来以下优势：

1. 工具链复用

开发者可直接使用：
   •   MetaMask
   •   Ethers.js
   •   Web3.js
   •   Hardhat
   •   Foundry

等成熟工具。

2. 降低迁移成本

无需重写大量基础代码，即可部署和调试合约。

3. 方便调试与运维

Debug API 为复杂应用提供了完善的排查能力。

4. 支持多层生态建设

这些接口是：
   •   区块浏览器
   •   钱包
   •   数据平台
   •   分析系统

的基础设施。

总结

Polkadot Hub 通过完整实现 Ethereum JSON-RPC 接口体系，为以太坊开发者提供了一条低成本进入 Polkadot 生态的路径。

本文系统介绍了：
   •   基础查询接口
   •   合约调用接口
   •   交易发送接口
   •   日志查询接口
   •   调试接口
   •   错误处理机制

对于希望在 Polkadot 上部署 EVM 合约的开发者来说，理解这些接口是必备基础能力。

未来，随着 Polkadot EVM 生态的不断完善，这套接口体系将成为连接多链应用的重要桥梁。

原文链接：https://docs.polkadot.com/smart-contracts/for-eth-devs/json-rpc-apis/