← Blog
10 min de lecture
|
Publié le
|
Mis à jour le

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.

Chapitres
C
Chaingateway Team
Experts blockchain

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 :

MembreSignification
jsonrpcLa chaîne "2.0"
methodLe nom de la méthode à appeler, par exemple eth_blockNumber
paramsUn tableau ou un objet avec les arguments. Peut être omis si la méthode n’en prend aucun
idUne 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 integer

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

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

Comment 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 :

CodeNomCause typique
-32700Parse errorLe corps n’est pas du JSON valide
-32600Invalid RequestLe JSON n’est pas un objet de requête valide
-32601Method not foundNom de méthode erroné, ou le nœud n’expose pas cet espace de noms
-32602Invalid paramsNombre ou type de paramètres incorrect
-32603Internal errorLe 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.

C
Chaingateway Team
Experts blockchain

L'équipe Chaingateway s'attache à simplifier l'intégration blockchain pour les développeurs du monde entier.