Nodos blockchain con JSON-RPC: guía con PHP, Python y JS
Cómo funciona JSON-RPC 2.0 con nodos blockchain: peticiones, respuestas, códigos de error y lotes, con ejemplos en PHP, Python y JavaScript.
Revisado por Maurice Sobiera
JSON-RPC es un protocolo de llamada a procedimientos remotos que codifica peticiones y respuestas como JSON. Un nodo de Ethereum lo expone por HTTP o WebSocket, así que un cliente puede leer bloques y saldos, o enviar transacciones firmadas, enviando un pequeño objeto JSON. El protocolo está versionado y especificado, por eso la misma forma de código funciona en la mayoría de nodos EVM.
Este artículo muestra el formato de las peticiones y las respuestas, los códigos de error y los lotes, con un ejemplo funcional en PHP, Python y JavaScript.
¿Qué es JSON-RPC?
JSON-RPC 2.0 es un protocolo sin estado definido en la especificación JSON-RPC 2.0. El cliente envía un objeto de petición. El servidor responde con un objeto de respuesta que tiene el mismo id.
Una petición tiene cuatro miembros:
| Miembro | Significado |
|---|---|
jsonrpc | La cadena "2.0" |
method | El nombre del método que se llama, por ejemplo eth_blockNumber |
params | Un array u objeto con los argumentos. Puede omitirse si el método no tiene ninguno |
id | Una cadena, un número o null. La respuesta lleva el mismo valor |
Una respuesta contiene un miembro result o un miembro error, nunca los dos. Una petición sin id es una notificación, y el servidor no debe responderla.
¿Cómo se envía una petición JSON-RPC a un nodo?
Envíe una petición HTTP POST con la cabecera Content-Type: application/json y el objeto de petición como cuerpo. El endpoint HTTP del nodo suele ser el puerto 8545 en clientes de Ethereum como Geth. Las conexiones WebSocket funcionan igual, pero mantienen una conexión abierta.
Los nombres de los métodos y sus parámetros los define la blockchain, no JSON-RPC. Para Ethereum, la referencia de la API JSON-RPC en ethereum.org los enumera. eth_blockNumber no recibe parámetros y devuelve el número del bloque actual como cantidad codificada en hexadecimal.
Petición:
{"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}Respuesta:
{"jsonrpc": "2.0", "id": 1, "result": "0x4b7"}Las cantidades son cadenas hexadecimales con el prefijo 0x y sin ceros a la izquierda. El resultado 0x4b7 corresponde al bloque 1207.
Ejemplos de código en PHP, Python y JavaScript
Los tres ejemplos envían la petición anterior a un nodo local e imprimen la respuesta. Usan POST, porque JSON-RPC sobre HTTP no usa GET.
PHP, con la extensión 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, con la biblioteca 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, con 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¿Cómo se lee un saldo?
Llame a eth_getBalance con una dirección y un parámetro de bloque. El parámetro de bloque puede ser un número de bloque en hexadecimal o una etiqueta como "latest", "safe" o "finalized". El resultado es el saldo en wei, como cantidad hexadecimal.
{ "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0x407d73d8a49eeb85d32cf465507dd71d507100c1", "latest"], "id": 2}En los sistemas de pago, la etiqueta importa. "latest" todavía puede ser reorganizado, mientras que "finalized" no. Use "finalized" cuando acredite un depósito y "latest" solo para mostrar información.
¿Qué significan los códigos de error?
Cuando una llamada falla, la respuesta tiene un objeto error con un code numérico y un message. La especificación reserva estos códigos:
| Código | Nombre | Causa habitual |
|---|---|---|
| -32700 | Parse error | El cuerpo no es JSON válido |
| -32600 | Invalid Request | El JSON no es un objeto de petición válido |
| -32601 | Method not found | Nombre de método incorrecto, o el nodo no expone ese espacio de nombres |
| -32602 | Invalid params | Número o tipo de parámetros incorrecto |
| -32603 | Internal error | El nodo falló al procesar la llamada |
Compruebe siempre si hay error antes de leer result. JSON-RPC lleva los errores en el cuerpo de la respuesta, así que revise el cuerpo sea cual sea el estado HTTP.
¿Se pueden enviar varias llamadas en una sola petición?
Sí. Un lote es un array JSON de objetos de petición, y el servidor responde con un array de respuestas. Las respuestas pueden llegar en cualquier orden, así que empareje las por id.
[ {"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}, {"jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 2}]Los lotes ahorran viajes de ida y vuelta. Los operadores de nodos pueden limitar el tamaño del lote, así que compruebe el límite del endpoint que usa.
¿Cuándo conviene usar una API en lugar de un nodo?
Ejecutar un nodo propio le da acceso JSON-RPC en bruto, pero el mantenimiento del nodo corre de su cuenta. Para crear wallets, transferir tokens y recibir notificaciones de depósitos, Chaingateway ofrece en su lugar una API REST; sus endpoints figuran en el archivo OpenAPI. Consulte cómo montar un nodo TRON para ver lo que implica operar uno.
Cómo escribimos estos artículos
¿Listo para construirlo tú mismo? Obtenga su clave de API — prueba de 7 días, sin tarjeta — o consulte API Blockchain para la referencia completa de los endpoints.