← Blog
10 min de lectura
|
Publicado
|
Actualizado

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.

Capítulos
C
Chaingateway Team
Expertos en blockchain

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:

MiembroSignificado
jsonrpcLa cadena "2.0"
methodEl nombre del método que se llama, por ejemplo eth_blockNumber
paramsUn array u objeto con los argumentos. Puede omitirse si el método no tiene ninguno
idUna 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 integer

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

JavaScript, 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ódigoNombreCausa habitual
-32700Parse errorEl cuerpo no es JSON válido
-32600Invalid RequestEl JSON no es un objeto de petición válido
-32601Method not foundNombre de método incorrecto, o el nodo no expone ese espacio de nombres
-32602Invalid paramsNúmero o tipo de parámetros incorrecto
-32603Internal errorEl 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.

C
Chaingateway Team
Expertos en blockchain

El equipo de Chaingateway se dedica a simplificar la integración blockchain para desarrolladores de todo el mundo.