← Blog
10 min di lettura
|
Pubblicato
|
Aggiornato

Nodi blockchain via JSON-RPC: guida PHP, Python e JS

Come funziona JSON-RPC 2.0 con i nodi blockchain: formato di richiesta e risposta, codici d'errore e batch, con esempi funzionanti in PHP, Python e JavaScript.

Capitoli
C
Chaingateway Team
Esperti di blockchain

Verificato da Maurice Sobiera

JSON-RPC è un protocollo di remote procedure call che codifica richieste e risposte in JSON. Un nodo Ethereum lo espone tramite HTTP o WebSocket, quindi un client può leggere blocchi e saldi oppure inviare transazioni firmate pubblicando un piccolo oggetto JSON. Il protocollo è versionato e specificato, per questo la stessa forma di codice funziona con la maggior parte dei nodi EVM.

Questo articolo mostra il formato di richiesta e risposta, i codici d’errore, i batch e un esempio funzionante ciascuno in PHP, Python e JavaScript.

Che cos’è JSON-RPC?

JSON-RPC 2.0 è un protocollo senza stato definito nella specifica JSON-RPC 2.0. Il client invia un oggetto di richiesta. Il server risponde con un oggetto di risposta che ha lo stesso id.

Una richiesta ha quattro membri:

MembroSignificato
jsonrpcLa stringa "2.0"
methodIl nome del metodo da chiamare, per esempio eth_blockNumber
paramsUn array o un oggetto con gli argomenti. Può essere omesso se il metodo non ne richiede
idUna stringa, un numero o null. La risposta riporta lo stesso valore

Una risposta contiene il membro result oppure il membro error, mai entrambi. Una richiesta senza id è una notifica, e il server non deve rispondere.

Come si invia una richiesta JSON-RPC a un nodo?

Si invia una richiesta HTTP POST con l’header Content-Type: application/json e l’oggetto di richiesta nel corpo. L’endpoint HTTP di un nodo usa di solito la porta 8545 per i client Ethereum come Geth. Le connessioni WebSocket funzionano allo stesso modo, ma mantengono aperta una sola connessione.

I nomi dei metodi e i parametri sono definiti dalla blockchain, non da JSON-RPC. Per Ethereum, la documentazione di riferimento dell’API JSON-RPC su ethereum.org li elenca. eth_blockNumber non richiede parametri e restituisce il numero del blocco corrente come quantità codificata in esadecimale.

Richiesta:

{"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}

Risposta:

{"jsonrpc": "2.0", "id": 1, "result": "0x4b7"}

Le quantità sono stringhe esadecimali con prefisso 0x e senza zeri iniziali. Il risultato 0x4b7 corrisponde al blocco 1207.

Codice di esempio in PHP, Python e JavaScript

Tutti e tre gli esempi inviano la richiesta sopra a un nodo locale e stampano la risposta. Usano POST, perché JSON-RPC su HTTP non usa GET.

PHP, con l’estensione 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 libreria 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

Come si legge un saldo?

Si chiama eth_getBalance con un indirizzo e un parametro di blocco. Il parametro di blocco può essere un numero di blocco esadecimale oppure un tag come "latest", "safe" o "finalized". Il risultato è il saldo in wei, come quantità esadecimale.

{
"jsonrpc": "2.0",
"method": "eth_getBalance",
"params": ["0x407d73d8a49eeb85d32cf465507dd71d507100c1", "latest"],
"id": 2
}

Per i sistemi di pagamento il tag conta. "latest" può ancora essere riorganizzato, mentre "finalized" no. Si usa "finalized" quando si accredita un deposito e "latest" solo per la visualizzazione.

Che cosa significano i codici d’errore?

Quando una chiamata fallisce, la risposta contiene un oggetto error con un code numerico e un message. La specifica riserva questi codici:

CodiceNomeCausa tipica
-32700Parse errorIl corpo non è JSON valido
-32600Invalid RequestIl JSON non è un oggetto di richiesta valido
-32601Method not foundNome del metodo errato, oppure il nodo non espone quel namespace
-32602Invalid paramsNumero o tipo di parametri errato
-32603Internal errorIl nodo ha fallito durante l’elaborazione della chiamata

Controllate sempre la presenza di error prima di leggere result. JSON-RPC riporta gli errori nel corpo della risposta, quindi controllate il corpo indipendentemente dallo stato HTTP.

Si possono inviare più chiamate in una sola richiesta?

Sì. Un batch è un array JSON di oggetti di richiesta, e il server risponde con un array di risposte. Le risposte possono arrivare in qualsiasi ordine, quindi le abbinate tramite id.

[
{"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1},
{"jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 2}
]

I batch riducono i viaggi di andata e ritorno. Gli operatori dei nodi possono limitare la dimensione del batch, quindi verificate il limite dell’endpoint che usate.

Quando conviene un’API invece di un nodo?

Un nodo proprio offre accesso JSON-RPC diretto, ma il nodo va mantenuto da voi. Per la creazione di wallet, i trasferimenti di token e le notifiche di deposito, Chaingateway offre invece un’API REST; i suoi endpoint sono elencati nel file OpenAPI. Per capire che cosa comporta gestire un nodo, consultate come configurare un nodo Tron.

Come scriviamo questi articoli

Pronto a costruirlo da solo? Ottieni la tua API key — prova di 7 giorni, senza carta — oppure consulta Blockchain API per il riferimento completo degli endpoint.

C
Chaingateway Team
Esperti di blockchain

Il team di Chaingateway si impegna a semplificare l'integrazione blockchain per sviluppatori di tutto il mondo.