JSON-RPC для блокчейн-нод: гайд на PHP, Python и JS
Как работает JSON-RPC 2.0 с нодами блокчейна: формат запроса и ответа, коды ошибок и батчи, с рабочими примерами на PHP, Python и JavaScript.
Проверил(а) Maurice Sobiera
JSON-RPC — протокол удалённого вызова процедур, который кодирует запросы и ответы в JSON. Нода Ethereum предоставляет его через 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 и объектом запроса в теле. HTTP-эндпоинт ноды обычно находится на порту 8545 у клиентов Ethereum, например Geth. Соединения WebSocket работают так же, но держат одно соединение открытым.
Имена методов и параметры задаёт блокчейн, а не JSON-RPC. Для Ethereum их перечисляет справочник JSON-RPC API на ethereum.org. 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, потому что JSON-RPC по HTTP не использует 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 | Внутренняя ошибка | Нода выдала сбой при обработке вызова |
Всегда проверяйте error до того, как читать result. 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-ключ — 7-дневный пробный период, без карты — или посмотрите API блокчейна для полного справочника по эндпоинтам.