用 JSON-RPC 与区块链节点交互:PHP、Python 与 JS 指南
JSON-RPC 2.0 如何与区块链节点协作:说明请求与响应的格式、错误码和批量调用。PHP、Python 与 JavaScript 三种语言的示例都发送同一个 eth_blockNumber 请求,并在本地节点上打印区块号。
审核: Maurice Sobiera
JSON-RPC 是一种以 JSON 编码请求与响应的远程过程调用协议。以太坊节点通过 HTTP 或 WebSocket 提供该接口,客户端只需发送一个小型 JSON 对象,就能读取区块和余额,或提交已签名的交易。该协议有版本号且有规范定义,因此大多数 EVM 节点都能用相同的代码结构调用。
本文介绍请求与响应格式、错误码和批量调用,并分别给出 PHP、Python 与 JavaScript 的可运行示例。
什么是 JSON-RPC?
JSON-RPC 2.0 是一种无状态协议,定义于 JSON-RPC 2.0 规范。客户端发送一个请求对象,服务器返回一个响应对象,其 id 与请求相同。
请求包含四个成员:
| 成员 | 含义 |
|---|---|
jsonrpc | 字符串 "2.0" |
method | 要调用的方法名,例如 eth_blockNumber |
params | 包含参数的数组或对象。若方法不需要参数,可省略 |
id | 字符串、数字或 null。响应中带有相同的值 |
响应要么包含 result 成员,要么包含 error 成员,两者不会同时出现。不带 id 的请求是通知,服务器不得回复。
如何向节点发送 JSON-RPC 请求?
发送 HTTP POST 请求,请求头为 Content-Type: application/json,请求体为该请求对象。对于 Geth 等以太坊客户端,节点的 HTTP 端点通常是 8545 端口。WebSocket 连接的方式相同,但需要保持一个连接处于打开状态。
方法名和参数由区块链本身定义,而非 JSON-RPC。以太坊的方法列表见 ethereum.org 上的 JSON-RPC API 参考。eth_blockNumber 不需要参数,返回以十六进制编码的当前区块号。
请求:
{"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}响应:
{"jsonrpc": "2.0", "id": 1, "result": "0x4b7"}数量以带 0x 前缀、无前导零的十六进制字符串表示。结果 0x4b7 即区块 1207。
PHP、Python 与 JavaScript 示例代码
三个示例都会把上面的请求发送到本地节点并打印响应。它们使用 POST,因为基于 HTTP 的 JSON-RPC 不使用 GET。
PHP,使用 curl 扩展:
<?php$request = json_encode([ 'jsonrpc' => '2.0', 'method' => 'eth_blockNumber', 'params' => [], 'id' => 1,]);
$curl = curl_init('http://localhost:8545');curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);curl_setopt($curl, CURLOPT_POST, true);curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);curl_setopt($curl, CURLOPT_POSTFIELDS, $request);
$response = json_decode(curl_exec($curl), true);curl_close($curl);
echo hexdec($response['result']); // block number as an integerPython,使用 requests 库:
import requests
payload = {"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}response = requests.post("http://localhost:8545", json=payload, timeout=10)body = response.json()
print(int(body["result"], 16)) # block number as an integerJavaScript,使用 fetch:
const response = await fetch('http://localhost:8545', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', method: 'eth_blockNumber', params: [], id: 1, }),});const body = await response.json();console.log(parseInt(body.result, 16)); // block number as an integer如何读取余额?
调用 eth_getBalance,传入地址和区块参数。区块参数可以是十六进制区块号,也可以是 "latest"、"safe" 或 "finalized" 等标签。结果是以十六进制数量表示的余额,单位为 wei。
{ "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0x407d73d8a49eeb85d32cf465507dd71d507100c1", "latest"], "id": 2}对支付系统而言,标签很重要。"latest" 仍可能被重组,而 "finalized" 不会。入账存款时应使用 "finalized","latest" 仅用于显示。
错误码是什么意思?
调用失败时,响应中会有一个 error 对象,包含数字类型的 code 和 message。规范保留了以下错误码:
| 错误码 | 名称 | 典型原因 |
|---|---|---|
| -32700 | 解析错误 | 请求体不是有效的 JSON |
| -32600 | 无效请求 | JSON 不是有效的请求对象 |
| -32601 | 找不到方法 | 方法名错误,或节点未开放该命名空间 |
| -32602 | 无效参数 | 参数数量或类型错误 |
| -32603 | 内部错误 | 节点在处理调用时失败 |
读取 result 之前,务必先检查是否有 error。JSON-RPC 将错误放在响应体中,因此无论 HTTP 状态码为何,都应检查响应体。
能否在一个请求中发送多个调用?
可以。批量请求是由多个请求对象组成的 JSON 数组,服务器会返回一个响应数组。响应的顺序可能与请求不同,因此应通过 id 进行匹配。
[ {"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}, {"jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 2}]批量调用可以减少往返次数。节点运营方可能限制批量大小,因此请查看所用端点的限制。
何时应使用 API 而不是自建节点?
自建节点可以直接使用 JSON-RPC 接口,但节点需要自行维护。对于钱包创建、代币转账和存款通知,Chaingateway 提供 REST API,端点列于 OpenAPI 文件 中。关于运行节点需要做什么,请参阅如何搭建 Tron 节点。
准备好自己动手构建了吗? 获取你的 API key — 7 天试用,无需信用卡 — 或查看 区块链 API 获取完整的 endpoint 参考。