← Blog
10 Min. Lesezeit
|
Veröffentlicht
|
Aktualisiert

JSON-RPC-Blockchain-Nodes: Leitfaden für PHP, Python & JS

So funktioniert JSON-RPC 2.0 mit Blockchain-Nodes: Anfrage- und Antwortformat, Fehlercodes und Batching, mit Beispielen in PHP, Python und JavaScript.

Kapitel
C
Chaingateway Team
Blockchain-Experten

Geprüft von Maurice Sobiera

JSON-RPC ist ein Protokoll für Remote Procedure Calls, das Anfragen und Antworten als JSON kodiert. Ein Ethereum-Node stellt es über HTTP oder WebSocket bereit. Ein Client kann so Blöcke und Salden lesen oder signierte Transaktionen senden, indem er ein kleines JSON-Objekt schickt. Das Protokoll ist versioniert und spezifiziert. Deshalb funktioniert dieselbe Code-Form mit den meisten EVM-Nodes.

Dieser Artikel zeigt das Anfrage- und Antwortformat, die Fehlercodes, Batching und je ein funktionierendes Beispiel in PHP, Python und JavaScript.

Was ist JSON-RPC?

JSON-RPC 2.0 ist ein zustandsloses Protokoll, das in der JSON-RPC-2.0-Spezifikation definiert ist. Der Client sendet ein Anfrageobjekt. Der Server antwortet mit einem Antwortobjekt mit derselben id.

Eine Anfrage hat vier Bestandteile:

BestandteilBedeutung
jsonrpcDer String "2.0"
methodDer Name der aufzurufenden Methode, zum Beispiel eth_blockNumber
paramsEin Array oder Objekt mit den Argumenten. Kann entfallen, wenn die Methode keine nimmt
idEin String, eine Zahl oder null. Die Antwort trägt denselben Wert

Eine Antwort enthält entweder ein result- oder ein error-Feld, nie beides. Eine Anfrage ohne id ist eine Benachrichtigung (Notification). Der Server darf darauf nicht antworten.

Wie senden Sie eine JSON-RPC-Anfrage an einen Node?

Senden Sie eine HTTP-POST-Anfrage mit dem Header Content-Type: application/json und dem Anfrageobjekt als Body. Der HTTP-Endpunkt eines Nodes liegt bei Ethereum-Clients wie Geth meist auf Port 8545. WebSocket-Verbindungen funktionieren genauso, halten aber eine Verbindung dauerhaft offen.

Die Methodennamen und Parameter legt die Blockchain fest, nicht JSON-RPC. Für Ethereum listet sie die JSON-RPC-API-Referenz auf ethereum.org. eth_blockNumber nimmt keine Parameter und gibt die aktuelle Blocknummer als hexadezimal kodierte Größe zurück.

Anfrage:

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

Antwort:

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

Mengenangaben sind Hex-Strings mit dem Präfix 0x und ohne führende Nullen. Das Ergebnis 0x4b7 ist Block 1207.

Beispielcode in PHP, Python und JavaScript

Alle drei Beispiele senden die Anfrage von oben an einen lokalen Node und geben die Antwort aus. Sie verwenden POST, weil JSON-RPC über HTTP kein GET nutzt.

PHP mit der curl-Erweiterung:

<?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 mit der Bibliothek 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 mit 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

Wie lesen Sie einen Saldo aus?

Rufen Sie eth_getBalance mit einer Adresse und einem Block-Parameter auf. Der Block-Parameter kann eine hexadezimale Blocknummer oder ein Tag wie "latest", "safe" oder "finalized" sein. Das Ergebnis ist der Saldo in Wei als Hex-Größe.

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

Bei Zahlungssystemen ist das Tag wichtig. "latest" kann noch reorganisiert werden, "finalized" nicht. Verwenden Sie "finalized", wenn Sie eine Einzahlung gutschreiben, und "latest" nur zur Anzeige.

Was bedeuten die Fehlercodes?

Schlägt ein Aufruf fehl, enthält die Antwort ein error-Objekt mit einem numerischen code und einer message. Die Spezifikation reserviert diese Codes:

CodeNameTypische Ursache
-32700Parse-FehlerDer Body ist kein gültiges JSON
-32600Ungültige AnfrageDas JSON ist kein gültiges Anfrageobjekt
-32601Methode nicht gefundenFalscher Methodenname, oder der Node stellt diesen Namensraum nicht bereit
-32602Ungültige ParameterFalsche Anzahl oder falscher Typ der Parameter
-32603Interner FehlerDer Node ist bei der Verarbeitung des Aufrufs fehlgeschlagen

Prüfen Sie immer auf error, bevor Sie result lesen. JSON-RPC transportiert Fehler im Antwort-Body. Prüfen Sie den Body deshalb unabhängig vom HTTP-Statuscode.

Können Sie mehrere Aufrufe in einer Anfrage senden?

Ja. Ein Batch ist ein JSON-Array aus Anfrageobjekten. Der Server antwortet mit einem Array aus Antworten. Die Antworten können in beliebiger Reihenfolge kommen. Ordnen Sie sie deshalb über die id zu.

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

Batching spart Netzwerkumläufe. Node-Betreiber können die Batch-Größe begrenzen. Prüfen Sie deshalb das Limit des Endpunkts, den Sie nutzen.

Wann sollten Sie eine API statt eines Nodes nutzen?

Ein eigener Node gibt Ihnen direkten JSON-RPC-Zugriff, aber Sie müssen ihn pflegen. Für Wallet-Erstellung, Token-Transfers und Einzahlungsbenachrichtigungen bietet Chaingateway stattdessen eine REST-API. Ihre Endpunkte listet die OpenAPI-Datei. Was der Betrieb eines Nodes umfasst, zeigt So richten Sie einen Tron-Node ein.

So entstehen diese Artikel

Möchten Sie das selbst umsetzen? API-Key erhalten — 7 Tage kostenlos testen, keine Karte nötig — oder werfen Sie einen Blick auf Blockchain-API für die vollständige Endpoint-Referenz.

C
Chaingateway Team
Blockchain-Experten

Das Chaingateway-Team hat es sich zur Aufgabe gemacht, die Blockchain-Integration für Entwickler weltweit zu vereinfachen.