← 博客
10 分钟阅读
|
发布于
|
更新于

用 JSON-RPC 与区块链节点交互:PHP、Python 与 JS 指南

JSON-RPC 2.0 如何与区块链节点协作:说明请求与响应的格式、错误码和批量调用。PHP、Python 与 JavaScript 三种语言的示例都发送同一个 eth_blockNumber 请求,并在本地节点上打印区块号。

章节
C
Chaingateway Team
区块链专家

审核: 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 integer

Python,使用 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 integer

JavaScript,使用 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 参考。

C
Chaingateway Team
区块链专家

Chaingateway 团队致力于为全球开发者简化区块链集成。