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.
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:
| Membro | Significato |
|---|---|
jsonrpc | La stringa "2.0" |
method | Il nome del metodo da chiamare, per esempio eth_blockNumber |
params | Un array o un oggetto con gli argomenti. Può essere omesso se il metodo non ne richiede |
id | Una 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 integerPython, 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 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 integerCome 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:
| Codice | Nome | Causa tipica |
|---|---|---|
| -32700 | Parse error | Il corpo non è JSON valido |
| -32600 | Invalid Request | Il JSON non è un oggetto di richiesta valido |
| -32601 | Method not found | Nome del metodo errato, oppure il nodo non espone quel namespace |
| -32602 | Invalid params | Numero o tipo di parametri errato |
| -32603 | Internal error | Il 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.