Nœuds blockchain en JSON-RPC : guide PHP, Python et JS
JSON-RPC 2.0 avec les nœuds blockchain : format des requêtes et réponses, codes d'erreur et lots, avec exemples PHP, Python et JavaScript.
Relu par Maurice Sobiera
JSON-RPC est un protocole d’appel de procédure à distance qui encode requêtes et réponses en JSON. Un nœud Ethereum l’expose en HTTP ou WebSocket : un client lit des blocs et des soldes, ou soumet des transactions signées, avec un petit objet JSON. Le protocole étant spécifié, la même forme de code fonctionne sur la plupart des nœuds EVM.
Cet article présente le format des requêtes et des réponses, les codes d’erreur, les lots, et un exemple fonctionnel en PHP, Python et JavaScript.
Qu’est-ce que JSON-RPC ?
JSON-RPC 2.0 est un protocole sans état défini dans la spécification JSON-RPC 2.0. Le client envoie un objet de requête. Le serveur répond par un objet de réponse qui porte le même id.
Une requête comporte quatre membres :
| Membre | Signification |
|---|---|
jsonrpc | La chaîne "2.0" |
method | Le nom de la méthode à appeler, par exemple eth_blockNumber |
params | Un tableau ou un objet avec les arguments. Peut être omis si la méthode n’en prend aucun |
id | Une chaîne, un nombre ou null. La réponse porte la même valeur |
Une réponse contient soit un membre result, soit un membre error, jamais les deux. Une requête sans id est une notification, et le serveur ne doit pas y répondre.
Comment envoyer une requête JSON-RPC à un nœud ?
Envoyez une requête HTTP POST avec l’en-tête Content-Type: application/json et l’objet de requête comme corps. Le point d’accès HTTP du nœud se trouve généralement sur le port 8545 pour les clients Ethereum comme Geth. Les connexions WebSocket fonctionnent de la même façon, mais gardent une connexion ouverte.
Les noms de méthodes et les paramètres sont définis par la blockchain, et non par JSON-RPC. Pour Ethereum, la référence de l’API JSON-RPC sur ethereum.org les liste. eth_blockNumber ne prend aucun paramètre et renvoie le numéro du bloc courant sous forme de quantité encodée en hexadécimal.
Requête :
{"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}Réponse :
{"jsonrpc": "2.0", "id": 1, "result": "0x4b7"}Les quantités sont des chaînes hexadécimales préfixées par 0x, sans zéros de tête. Le résultat 0x4b7 correspond au bloc 1207.
Exemples de code en PHP, Python et JavaScript
Les trois exemples envoient la requête ci-dessus à un nœud local et affichent la réponse. Ils utilisent POST, car JSON-RPC sur HTTP n’utilise pas GET.
PHP, avec l’extension 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, avec la bibliothèque 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, avec 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 integerComment lire un solde ?
Appelez eth_getBalance avec une adresse et un paramètre de bloc. Le paramètre de bloc peut être un numéro de bloc hexadécimal ou une étiquette comme "latest", "safe" ou "finalized". Le résultat est le solde en wei, sous forme de quantité hexadécimale.
{ "jsonrpc": "2.0", "method": "eth_getBalance", "params": ["0x407d73d8a49eeb85d32cf465507dd71d507100c1", "latest"], "id": 2}Pour les systèmes de paiement, l’étiquette compte. "latest" peut encore être réorganisée, alors que "finalized" ne le peut pas. Utilisez "finalized" lorsque vous créditez un dépôt, et "latest" seulement pour l’affichage.
Que signifient les codes d’erreur ?
Lorsqu’un appel échoue, la réponse contient un objet error avec un code numérique et un message. La spécification réserve les codes suivants :
| Code | Nom | Cause typique |
|---|---|---|
| -32700 | Parse error | Le corps n’est pas du JSON valide |
| -32600 | Invalid Request | Le JSON n’est pas un objet de requête valide |
| -32601 | Method not found | Nom de méthode erroné, ou le nœud n’expose pas cet espace de noms |
| -32602 | Invalid params | Nombre ou type de paramètres incorrect |
| -32603 | Internal error | Le nœud a échoué pendant le traitement de l’appel |
Vérifiez toujours la présence de error avant de lire result. JSON-RPC transporte les erreurs dans le corps de la réponse : vérifiez donc le corps, quel que soit le statut HTTP.
Peut-on envoyer plusieurs appels dans une seule requête ?
Oui. Un lot est un tableau JSON d’objets de requête, et le serveur répond par un tableau de réponses. Les réponses peuvent arriver dans n’importe quel ordre : faites donc la correspondance par id.
[ {"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id": 1}, {"jsonrpc": "2.0", "method": "eth_chainId", "params": [], "id": 2}]Le regroupement économise des allers-retours. Les opérateurs de nœuds peuvent limiter la taille des lots : vérifiez donc la limite du endpoint que vous utilisez.
Quand utiliser une API plutôt qu’un nœud ?
Faire tourner votre propre nœud vous donne un accès JSON-RPC brut, mais c’est vous qui le maintenez. Pour la création de portefeuilles, les transferts de tokens et les notifications de dépôt, Chaingateway propose une API REST à la place. Ses endpoints sont listés dans le fichier OpenAPI. Voir comment installer un nœud Tron pour ce que suppose l’exploitation d’un nœud.
Comment nous rédigeons ces articles
Prêt à le construire vous-même ? Obtenir votre clé API — essai de 7 jours, sans carte bancaire — ou consultez API Blockchain pour la référence complète des endpoints.