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

Smart Contract Events API: Lesen, Filtern und Abonnieren

Wie eine Smart Contract Events API funktioniert: Logs, Topics, ABI-Dekodierung und die Wahl zwischen Webhooks, WebSockets und Polling.

Kapitel
C
Chaingateway Team
Blockchain-Experten

Geprüft von Maurice Sobiera

Ereignisdatensätze laufen durch einen Filter in zwei Pfade

Eine Smart Contract Events API ist eine Schnittstelle, die Ihrer Anwendung strukturierten Zugriff auf die Logs gibt, die ein Contract schreibt. Sie müssen dafür nicht jede Transaktion selbst durchsuchen. Vergangene Logs fragen Sie über Contract-Adresse und Event-Signatur ab. Neue Logs abonnieren Sie, sobald Blöcke eintreffen. Dafür nutzen Sie rohe Node-RPC, eine Bibliothek wie ethers.js oder eine gehostete API mit Webhooks.

Dieser Leitfaden zeigt, wie jeder Weg funktioniert, wo er jeweils bricht und wie Sie wählen.

TL;DR

  • Ein Contract-Event ist ein Log-Eintrag, der geschrieben wird, wenn eine Transaktion in einen Block aufgenommen wird. Ihre App liest ihn danach. Der Contract selbst kann ihn nicht lesen.
  • Vergangene Events stammen aus einer Log-Abfrage (eth_getLogs oder queryFilter). Live-Events kommen aus einem Abonnement oder einem Webhook. Node-Abonnements spielen die Historie nicht nach.
  • Nur indizierte Parameter lassen sich als Filter nutzen. Für die Dekodierung braucht man das ABI des Contracts.
  • WebSocket-Abonnements enden mit der Verbindung und können abbrechen, wenn Sie zu langsam verarbeiten. Webhooks mit Warteschlange und idempotenten Handlern überstehen Neustarts besser.
  • Eine gehostete API erspart Node-, ABI- und Reconnect-Arbeit. Genau das leistet Chaingateway für Zahlungs- und Token-Events.

Was ist ein Smart-Contract-Event?

Events sind die Art, wie ein Contract mit der Außenwelt spricht. Laut ethereum.org erlauben Events einem Contract, mit einem Frontend oder anderen abonnierenden Anwendungen zu kommunizieren. Diese können die protokollierten Informationen verarbeiten, nachdem die Transaktion validiert und in einen Block aufgenommen wurde.

Daraus folgen drei Dinge. Sie erklären den größten Teil der Verwirrung in den Suchergebnissen:

  1. Events sind Ausgabe, kein Speicher, den Sie aus Solidity abfragen können. Contract-Code schreibt Logs, kann sie aber nicht zurücklesen. Deshalb enden Threads, die fragen, wie ein Contract auf vergangene Events zugreift, immer mit „Das erledigen Sie off-chain.“
  2. Events erscheinen erst nach der Aufnahme in einen Block. Für eine Transaktion, die noch im Mempool liegt, gibt es noch kein Log.
  3. Events sind günstig zu emittieren und günstig zu durchsuchen. Deshalb werden ERC-20-Transfer- und Approval-Events, NFT-Mints und DEX-Swaps alle über Logs verfolgt und nicht über Zustandsabfragen.

Eine Smart Contract Events API ist alles, was Ihrem Backend strukturierten Zugriff auf diese Logs gibt. Das kann das JSON-RPC eines Nodes sein, eine Bibliothek darüber, ein Indexer oder ein gehosteter Dienst, der Ihnen Webhooks schickt.

Was steckt in einem Event-Log?

Um Logs richtig zu filtern oder zu dekodieren, müssen Sie ihre Struktur kennen. Laut der Solidity-ABI-Spezifikation enthält ein Log die Contract-Adresse, bis zu vier Topics und ein Datensegment. Anonyme Events lassen den Hash der Event-Signatur weg.

Bei einem normalen Event gilt:

  • Topic 0 ist der Keccak-256-Hash der Event-Signatur, zum Beispiel Transfer(address,address,uint256).
  • Topics 1 bis 3 enthalten die indizierten Parameter.
  • Data enthält die nicht indizierten Parameter, ABI-kodiert.

Das ABI trennt die Parameter in indizierte, die als Hash-Topics für effizientes Filtern gespeichert werden, und nicht indizierte, die als Binärdaten im Log liegen.

Eine Falle sollten Sie kennen. Dieselbe Spezifikation (in der Fassung v0.8.3) hält fest, dass dynamisch lange indizierte Parameter wie Strings und Byte-Arrays nicht als Wert gespeichert werden. Stattdessen landet ein Keccak-Hash einer speziellen Kodierung im Log. Den ursprünglichen String können Sie daraus nicht zurückgewinnen. Sie können nur prüfen, ob ein Kandidatenwert passt.

Ein konkretes Beispiel: ERC-20-Transfer

Ein Token-Transfer-Log hat in Topic 0 die Signatur Transfer, in Topic 1 die Absenderadresse, in Topic 2 die Empfängeradresse und im Datenfeld den Betrag. Wenn Sie jede Einzahlung auf eine Kundenadresse erfassen wollen, filtern Sie auf Topic 0 und Topic 2. Die Details beschreiben wir in unserem Leitfaden zum ERC-20-Transfer-Event.

Tabelle der ERC-20-Transfer-Logfelder: Topic 0 ist die Signatur und ein Einzahlungsfilter, Topic 1 der Absender, Topic 2 der Empfänger und ein Einzahlungsfilter, das Datenfeld enthält den Betrag

Wie lese ich vergangene Events aus?

Historische Daten lesen Sie per Abfrage, nicht per Abonnement. Die Standardmethode im JSON-RPC ist eth_getLogs. Sie nimmt ein Filterobjekt mit einem Blockbereich, optional einer Contract-Adresse und optional einem Array von Topics. Die Referenz der Coinbase Developer Documentation zu eth_getLogs zeigt die Form mit fromBlock, toBlock und topics. Sie nennt außerdem, dass ein Block-Hash den Bereich ersetzen kann.

Bibliotheken kapseln das. In ethers.js liefert contract.queryFilter(event, fromBlock, toBlock) passende Events. Die Dokumentation zu ethers v5 hält fest, dass nur indizierte Parameter gefiltert werden können. Ein nicht gesetzter Parameter passt auf jeden Wert.

Praktische Regeln für historische Abfragen:

  • Begrenzen Sie den Bereich immer. Viele Anbieter begrenzen die Blockspanne oder die Anzahl der Ergebnisse pro Aufruf. Blättern Sie den Bereich in Abschnitten durch, etwa einige tausend Blöcke auf einmal. Halbieren Sie den Abschnitt, wenn ein Fehler auftritt.
  • Filtern Sie mindestens nach Adresse und Topic 0. Ungefilterte Log-Abfragen sind der schnellste Weg, ein Rate-Limit zu erreichen.
  • Speichern Sie den zuletzt verarbeiteten Block. Dieser Checkpoint erlaubt es, nach einem Absturz ohne Lücken oder Duplikate weiterzumachen.
  • Dekodieren Sie mit dem richtigen ABI. Mit nur Topic 0 können Sie die Event-Signatur nachschlagen. Ein Proxy-Contract kann aber Events emittieren, die in seiner Implementierung definiert sind. Verwenden Sie deshalb das ABI der Implementierung.

Wenn Sie den direkten Umgang mit Nodes auffrischen möchten, behandelt unser JSON-RPC-Leitfaden mit Beispielen in PHP, Python und JavaScript das Anfrageformat.

Wie abonniere ich neue Events?

Der Live-Teil funktioniert anders, und genau hier scheitern viele erste Implementierungen.

Die Dokumentation zu Echtzeit-Events in go-ethereum erklärt, dass Abonnements dauerhafte WebSocket- oder IPC-Verbindungen nutzen, typischerweise über eth_subscribe. Sie liefern Events, sobald der Node sie verarbeitet. Zwei Grenzen sind wichtig:

  • Keine Wiedergabe. Abonnement-Benachrichtigungen betreffen aktuelle Events, keine vergangenen. War Ihr Prozess zehn Minuten offline, liefert das Abonnement nicht nach, was Sie verpasst haben. Das holen Sie mit einer Log-Abfrage nach.
  • Kopplung an die Verbindung. Abonnements hängen an einer Verbindung. Wenn sie schließt, enden alle ihre Abonnements.

Dieselbe Seite ergänzt, dass Nodes Benachrichtigungen puffern. Kann Ihr Client sie nicht schnell genug verarbeiten, kann die Verbindung geschlossen werden, sobald der Puffer ein Limit erreicht. Das Beispiel von Geth nennt 10.000. Ein langsamer Handler, der Datenbankschreibvorgänge inline ausführt, führt genau dazu.

Das Muster, das trägt

Kombinieren Sie beide Mechanismen:

  1. Lesen Sie beim Start Ihren Checkpoint-Block.
  2. Holen Sie mit eth_getLogs die Lücke vom Checkpoint bis zum aktuellen Head in Abschnitten nach.
  3. Öffnen Sie das Abonnement und entfernen Sie Duplikate anhand von Transaktions-Hash und Log-Index.
  4. Geben Sie jedes Event an eine Warteschlange weiter und bestätigen Sie es sofort. Verarbeitet wird es in einem Worker.
  5. Bei einem Verbindungsabbruch beginnen Sie wieder bei Schritt 1.

Das bleibt auch korrekt, wenn die Verbindung abbricht, was sie irgendwann tut.

Was passiert bei einem Reorg?

Ein Log aus dem neuesten Block kann verschwinden, wenn die Chain sich reorganisiert. Bei allem, was Geld betrifft, schreiben Sie einem Nutzer nicht bei der ersten Sichtung Guthaben gut. Warten Sie auf eine Bestätigungstiefe, die zu Chain und Betrag passt. Behandeln Sie außerdem das Flag „removed“, das Nodes im Ethereum-Stil an Logs aus verwaisten Blöcken anhängen. Speichern Sie die ID des verarbeiteten Events, und machen Sie Ihren Handler idempotent. So kann ein wiederholtes oder korrigiertes Event nicht doppelt gutschreiben.

Diagramm einer Chain-Gabelung: Ein verwaister Zweig mit einer Event-Markierung spaltet ab, während der längere bestätigte Zweig dasselbe Event weiterträgt

Soll ich Webhooks, WebSockets oder Polling nutzen?

Alle drei können Events zustellen. Sie unterscheiden sich darin, wer die Verbindung hält und wer die Fehlerfälle verantwortet.

AnsatzFunktionsweiseStärkeSchwäche
PollingIhr Code ruft eth_getLogs per Timer ab dem letzten Checkpoint aufEinfach, zustandslos, leicht fortzusetzenDie Latenz entspricht Ihrem Intervall, und jeder Aufruf kostet Requests
WebSocket-AbonnementEine dauerhafte Verbindung streamt Logs von einem NodeGeringste LatenzEndet mit der Verbindung, keine Wiedergabe, Puffergrenzen
WebhookEin Dienst überwacht die Chain und sendet einen HTTP-POST an Ihren EndpunktKeine dauerhafte Verbindung zu pflegen, funktioniert mit ServerlessSie brauchen einen öffentlichen Endpunkt, Signaturprüfung und Duplikatbehandlung

Polling eignet sich für Back-Office-Jobs mit geringem Volumen. WebSockets passen zu einem Dashboard oder Bot, der innerhalb eines Blocks reagieren muss und Lücken verkraftet. Webhooks passen zu Zahlungsabläufen, in denen Sie pro Event eine verlässliche Zustellung und eine Worker-Warteschlange dahinter wollen. Unser Beitrag zum Muster aus Erfassung, Warteschlange und Verteilung für Webhooks versus WebSockets behandelt die Abwägungen ausführlicher.

Webhook-Zustellung richtig umsetzen

Unabhängig davon, wer den Webhook sendet, bauen Sie den Empfänger gleich auf:

  • Prüfen Sie die Signatur, bevor Sie auf den Payload reagieren.
  • Antworten Sie schnell mit 2xx und verarbeiten Sie asynchron.
  • Machen Sie Handler idempotent, mit Transaktions-Hash und Log-Index als Schlüssel.
  • Rechnen Sie mit Duplikaten und mit Zustellung außerhalb der Reihenfolge.
  • Protokollieren Sie Fehler, damit Sie später per Log-Abfrage abgleichen können.

Das Zustellverhalten ist ein eigenes Gestaltungsthema. Unser Artikel zu Zustellungsgarantien von Webhooks behandelt Duplikate, Reihenfolge und verpasste Benachrichtigungen.

Event-Monitoring Schritt für Schritt einrichten

Hier ist ein minimaler Weg für einen einzelnen EVM-Contract, egal welches Tool Sie nutzen.

  1. Holen Sie das ABI. Nehmen Sie es aus dem verifizierten Contract-Quelltext oder aus Ihrem eigenen Build-Output. Ohne ABI sehen Sie nur rohe Topics und Hex-Daten.
  2. Wählen Sie die Events aus. Listen Sie die Signaturen auf, die Sie interessieren, etwa Transfer, Approval oder Ihr eigenes OrderPaid.
  3. Legen Sie die Filter fest. Dazu gehören Contract-Adresse, Topic 0 und jeder indizierte Parameter, etwa der Empfänger. Denken Sie daran: Nur indizierte Werte lassen sich filtern.
  4. Holen Sie die Historie nach. Fragen Sie ab dem Deployment-Block oder ab Ihrem geschäftlichen Startdatum in Abschnitten ab.
  5. Gehen Sie live. Abonnieren Sie per WebSocket oder registrieren Sie einen Webhook.
  6. Dekodieren und normalisieren. Rechnen Sie Hex-Beträge mit den Dezimalstellen des Tokens um. Speichern Sie Blocknummer, Transaktions-Hash, Log-Index und Contract-Adresse.
  7. Warten Sie auf Finalität. Markieren Sie Events zuerst als ausstehend und danach als bestätigt.
  8. Überwachen Sie den Monitor selbst. Alarmieren Sie, wenn länger kein Event eintrifft als die übliche Lücke der Chain. Alarmieren Sie auch, wenn Ihr Checkpoint hinter den Head zurückfällt.

Events über mehrere Chains hinweg

Das EVM-Modell aus Topics und ABI-dekodierten Daten gilt für Ethereum, Polygon, BNB Chain und Arbitrum. Ein Dekodierer funktioniert deshalb über alle vier, mit unterschiedlichen RPC-Endpunkten und Bestätigungsregeln. Andere Netzwerke teilen dieses Modell nicht. Bitcoin hat überhaupt keine Contract-Logs, also überwachen Sie dort Adressen und Transaktionen. Tron und Solana haben eigene Formate und APIs.

Praktisch heißt das: Ein Produkt über mehrere Chains pflegt am Ende je Netzwerkfamilie einen eigenen Adapter. Jeder Adapter hat eigene Reconnect-, Dekodier- und Finalitätslogik. Genau diesen Teil unterschätzen die meisten Teams. Eine Übersicht der Optionen bieten unser Vergleich von sechs Typen von Blockchain-APIs und der Beitrag zu Blockchain-API versus eigenem Node.

Selbst bauen oder gehostete API nutzen?

Ein eigener Stack bedeutet einen Node (oder einen kostenpflichtigen RPC-Endpunkt), einen Log-Scanner, eine ABI-Registry, eine Reorg-Behandlung, eine Warteschlange und Alarmierung. Das ist sinnvoll, wenn Events Ihr Kernprodukt sind oder Sie eigenes Indexing über Tausende Contracts brauchen.

Weniger sinnvoll ist das, wenn Events nur Mittel zum Zweck sind, etwa um eine Einzahlung gutzuschreiben oder eine Bestellung zu bestätigen. Dann wollen Sie dekodierte Events an einen Endpunkt liefern, den Sie kontrollieren, und sonst nichts betreiben.

Unsere Perspektive

Die meisten Fehler bei der Event-Verarbeitung, die wir sehen, betreffen nicht das Lesen von Logs. Sie betreffen das Drumherum: eine verpasste Benachrichtigung während eines Deployments, eine doppelte Gutschrift nach einem Retry, eine falsche Dezimalumrechnung bei einem Token oder eine Verbindung, die über Nacht still abgebrochen ist.

Deshalb bauen wir auf drei Überzeugungen. Erstens sollte die Anwendung dekodierte, strukturierte Daten erhalten und keine rohen Topics, die sie selbst interpretieren muss. Zweitens ist Push bei Zahlungen dem Polling überlegen, solange jede Nachricht signiert und prüfbar ist. Drittens sollte ein Entwickler keine Nodes betreiben oder chainspezifische Endpunkte synchron halten müssen, nur um zu erfahren, dass eine Zahlung eingegangen ist.

Chaingateway stellt deshalb eine REST-API für Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain und Arbitrum bereit, mit dekodierten Transaktionen und Gaspreisen. Webhooks setzen darauf auf und sind HMAC-signiert. So erhält Ihr Handler das Event, und Ihr Team bleibt bei seinem Produkt. Was Sie auch wählen: Behalten Sie den Checkpoint, den Idempotenzschlüssel und die Bestätigungsregel im Blick. Diese drei entscheiden, ob Ihre Zahlen stimmen.

— Bitblade

Wie bekomme ich Events ohne eigene Nodes?

Wenn Ihr Ziel Zahlungs- und Token-Events in einer App sind, liefern unsere Chaingateway Webhooks Echtzeit-Benachrichtigungen an Ihren Endpunkt. Die Blockchain-API gibt Ihnen dekodierte Transaktionen, Wallets, Transfers und Gaspreise über eine einzige Schnittstelle. Die Pläne beginnen bei 49 € pro Monat für Plus. Pro kostet 99 €, Premium 249 € und Enterprise 499 € pro Monat. Bei jährlicher Abrechnung kosten die Tarife 490 €, 990 €, 2.490 € und 4.990 €.

Was jeder Tarif enthält, steht auf der Preisseite. Ein Beispiel für eine bestimmte Chain finden Sie im Beitrag über Polygon-Webhooks ohne Polling.

Quellen

Empfohlen

Häufig gestellte Fragen

Nein. Contracts können Logs emittieren, aber danach nicht darauf zugreifen. Event-Daten sind daher für Off-Chain-Verbraucher gedacht. Braucht Ihr Contract historische Daten on-chain, speichern Sie den Wert stattdessen im Contract-Zustand. Das kostet mehr Gas.

Führen Sie eine Log-Abfrage vom letzten verarbeiteten Block bis zum aktuellen Head aus. Node-Abonnements senden nur aktuelle Events, ein erneutes Verbinden spielt also nichts nach. Speichern Sie nach jedem verarbeiteten Block einen Checkpoint und entfernen Sie Duplikate anhand von Transaktions-Hash und Log-Index.

Nur indizierte Parameter werden als Topics gespeichert, und nur Topics lassen sich filtern. Nicht indizierte Werte liegen im Datenfeld. Deshalb müssen Sie die Logs abrufen und in Ihrem eigenen Code filtern. Wenn Sie den Contract kontrollieren, markieren Sie die Felder, nach denen Sie suchen werden, als indiziert. Pro Event sind bis zu drei möglich.

Für Zahlungen sind Webhooks mit Warteschlange meist einfacher zu betreiben, weil Sie keine Verbindung halten, die abbrechen kann. Nutzen Sie WebSockets, wenn eine Reaktion unter einer Sekunde zählt und Sie Lücken nachholen können. In beiden Fällen verarbeiten Sie Events idempotent. Außerdem warten Sie auf genügend Bestätigungen, bevor Sie Guthaben gutschreiben.

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.