← Блог
10 мин чтения
|
Опубликовано
|
Обновлено

JSON-RPC для блокчейн-нод: гайд на PHP, Python и JS

Как работает JSON-RPC 2.0 с нодами блокчейна: формат запроса и ответа, коды ошибок и батчи, с рабочими примерами на PHP, Python и JavaScript.

Главы
C
Chaingateway Team
Эксперты по блокчейну

Проверил(а) 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 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Внутренняя ошибкаНода выдала сбой при обработке вызова

Всегда проверяйте 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 блокчейна для полного справочника по эндпоинтам.

C
Chaingateway Team
Эксперты по блокчейну

Команда Chaingateway стремится упростить интеграцию блокчейна для разработчиков по всему миру.