Smart Contract Events API: Lesen, Filtern und Abonnieren

Eine Smart-Contract-Events-API ermöglicht es Ihrer Anwendung herauszufinden, was ein Vertrag getan hat, ohne jede Transaktion selbst scannen zu müssen. Sie fragen vergangene Logs per Vertragsadresse und Event-Signatur ab und abonnieren dann neue, sobald Blöcke eintreffen. Beides können Sie über rohes Node-RPC, über eine Bibliothek wie ethers.js oder über eine gehostete API tun, die die Logs decodiert und Ihnen als Webhooks zusendet. Dieser Leitfaden behandelt, wie jeder Pfad funktioniert, wo jeder scheitert und wie Sie wählen.

TL;DR

• Ein Contract-Event ist ein Log-Eintrag, der geschrieben wird, wenn eine Transaktion gemined wird. Ihre App liest ihn danach. Der Vertrag selbst kann ihn nicht lesen.
• Vergangene Events stammen aus einer Log-Abfrage (eth_getLogs oder queryFilter). Live-Events stammen aus einem Abonnement oder einem Webhook. Node-Abonnements spielen die Historie nicht nach.
• Nur indizierte Parameter können als Filter verwendet werden. Das Decodieren erfordert das Vertrags-ABI.
• WebSocket-Abonnements sterben mit der Verbindung und können verworfen werden, wenn Sie zu langsam verarbeiten. Webhooks mit einer Warteschlange und idempotenten Handlern überstehen Neustarts besser.
• Eine gehostete API entfernt die Node-, ABI- und Reconnect-Arbeit. Das ist das, was Chaingateway für Zahlungs- und Token-Events tut.

Inhaltsverzeichnis

• Was ein Smart-Contract-Event ist
• Was in einem Event-Log steckt
• Vergangene Events lesen
• Neue Events abonnieren
• Reorgs und Bestätigungen
• Webhooks, WebSockets oder Polling
• Event-Monitoring Schritt für Schritt einrichten
• Events über Ketten hinweg
• Selbst bauen oder gehostete API nutzen
• Unsere Perspektive
• Events erhalten, ohne Nodes zu betreiben
• FAQ
• Quellen

Was ein Smart-Contract-Event ist

Events sind der Weg, wie ein Vertrag mit der Außenwelt spricht. Laut ethereum.org ermöglichen Events einem Vertrag, mit einem Frontend oder anderen abonnierenden Anwendungen zu kommunizieren, die die geloggten Informationen verarbeiten können, nachdem die Transaktion validiert und einem Block hinzugefügt wurde.

Daraus folgen drei Konsequenzen, die den Großteil der Verwirrung in den Suchergebnissen erklären:

1. Events sind Output, kein Speicher, den Sie aus Solidity abfragen können. Vertragscode schreibt Logs, kann sie aber nicht zurücklesen. Deshalb enden Threads, die fragen, wie ein Vertrag auf vergangene Events zugreifen kann, immer mit „machen Sie es off-chain“.
2. Events erscheinen erst nach der Inklusion. Es gibt kein Log für eine Transaktion, die noch im Mempool ist.
3. Events sind günstig zu emittieren und günstig zu durchsuchen, weshalb ERC-20 Transfer- und Approval-Events, NFT-Mints und DEX-Swaps alle über Logs und nicht über State-Reads getrackt werden.

Eine Smart-Contract-Events-API ist alles, was Ihrem Backend strukturierten Zugriff auf diese Logs gibt: das JSON-RPC eines Nodes, eine es umschließende Bibliothek, ein Indexer oder ein gehosteter Dienst, der Ihnen Webhooks sendet.

Was in einem Event-Log steckt

Um Logs korrekt zu filtern oder zu decodieren, müssen Sie deren Struktur kennen. Gemäß der Solidity ABI-Spezifikation enthält ein Log die Vertragsadresse, bis zu vier Topics und einen Datensegment. Anonyme Events lassen den Event-Signatur-Hash weg.

Bei einem normalen Event:

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

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

Es gibt eine Falle, die Sie kennen sollten. Dieselbe Spezifikation (in der v0.8.3-Ausgabe) merkt an, dass dynamisch lange indizierte Parameter, wie Strings und Byte-Arrays, als Keccak-Hash einer speziellen Kodierung gespeichert werden, statt als der Wert. Sie können den ursprünglichen String nicht aus dem Log wiederherstellen. Sie können nur testen, ob ein Kandidatwert übereinstimmt.

Ein konkretes Beispiel: ERC-20 Transfer

Ein Token-Transfer-Log hat Topic 0 für die Transfer-Signatur, die Absenderadresse in Topic 1, die Empfängeradresse in Topic 2 und den Betrag im Datenfeld. Wenn Sie jede Einzahlung auf eine Kundenadresse erfassen möchten, filtern Sie nach Topic 0 und Topic 2. Wir gehen dies detailliert in unserem ERC-20 Transfer Event Guide durch.

Vergangene Events lesen

Historische Abfragen sind eine Query, kein Abonnement. Die Standard-JSON-RPC-Methode ist eth_getLogs. Sie nimmt ein Filterobjekt mit einem Blockbereich, einer optionalen Vertragsadresse und einem optionalen Array von Topics entgegen. Die Coinbase Developer Documentation-Referenz für eth_getLogs zeigt die Struktur: fromBlock, toBlock und topics, und sie merkt an, dass ein Block-Hash den Bereich ersetzen kann.

Bibliotheken kapseln dies. In ethers.js gibt contract.queryFilter(event, fromBlock, toBlock) passende Events zurück, und die ethers v5 Vertragsdokumentation besagt, dass nur indizierte Parameter gefiltert werden können. Ein auf null gesetzter Parameter stimmt mit jedem Wert überein.

Praktische Regeln für historische Abfragen:

• Begrenzen Sie den Bereich immer. Viele Provider begrenzen den Blockumfang oder die Anzahl der Ergebnisse pro Aufruf. Blättern Sie in Blöcken (beispielsweise einige tausend Blöcke auf einmal) durch die Bereiche und halbieren Sie den Block, wenn Sie einen Fehler erhalten.
• Filtern Sie mindestens nach Adresse und Topic 0. Ungefilterte Log-Abfragen sind der schnellste Weg, ein Rate-Limit zu erreichen.
• Speichern Sie den letzten verarbeiteten Block. Dieser Checkpoint ermöglicht es Ihnen, nach einem Absturz ohne Lücken oder Duplikate fortzufahren.
• Decodieren Sie mit dem richtigen ABI. Wenn Sie nur Topic 0 haben, können Sie die Event-Signatur nachschlagen, aber ein Proxy-Vertrag kann Events emittieren, die in seiner Implementierung definiert sind, daher verwenden Sie das Implementierungs-ABI.

Wenn Sie eine Auffrischung zur direkten Kommunikation mit Nodes wünschen, deckt unser JSON-RPC-Guide mit PHP-, Python- und JavaScript-Beispielen das Anfrageformat ab.

Neue Events abonnieren

Die Live-Seite funktioniert anders, und genau hier scheitern viele erste Implementierungen.

Die go-ethereum Dokumentation zu Echtzeit-Events erklärt, dass Subscriptions persistente WebSocket- oder IPC-Verbindungen verwenden, typischerweise über eth_subscribe, und Events streamen, während der Knoten sie verarbeitet. Zwei Limits sind entscheidend:

• Kein Replay. Subscriptions-Benachrichtigungen decken aktuelle Events ab, keine vergangenen. War Ihr Prozess zehn Minuten lang down, liefert die Subscription nicht das, was Sie verpasst haben. Sie füllen die Lücke mit einer Log-Abfrage auf.
• Verbindungskopplung. Subscriptions sind an eine Verbindung gebunden. Wenn diese schließt, schließen alle ihre Subscriptions.

Auf derselben Seite heißt es zudem, dass Knoten Benachrichtigungen puffern, und wenn Ihr Client sie nicht schnell genug verarbeiten kann, die Verbindung geschlossen werden kann, sobald der Puffer ein Limit erreicht (Geths Beispiel sind 10.000). Ein langsamer Handler, der Datenbank-Schreibvorgänge inline ausführt, ist genau der Weg, wie das passiert.

Das Muster, das hält

Kombinieren Sie beide Mechanismen:

1. Beim Start lesen Sie Ihren Checkpoint-Block.
2. Backfill vom Checkpoint bis zum aktuellen Head mit eth_getLogs, in Chunks.
3. Öffnen Sie die Subscription und deduplizieren Sie anhand von Transaktions-Hash plus Log-Index.
4. Übergeben Sie jedes Event an eine Queue und bestätigen Sie sofort. Verarbeiten Sie es in einem Worker.
5. Bei Trennung gehen Sie zurück zu Schritt 1.

Das bleibt korrekt, selbst wenn die Verbindung abreißt – was passieren wird.

Reorgs und Bestätigungen

Ein Log, den Sie im neuesten Block gesehen haben, kann verschwinden, wenn die Kette reorganisiert wird. Bei allem, was Geld betrifft, schreiben Sie einem Nutzer nicht beim ersten Sighting gut. Warten Sie auf eine Bestätigungstiefe, die zur Kette und zum Betrag passt, und behandeln Sie das “removed”-Flag, das Ethereum-ähnliche Knoten Logs aus verwaisten Blöcken anhängen. Behalten Sie die verarbeitete Event-ID bei, und machen Sie Ihren Handler idempotent, damit ein wiederholtes oder korrigiertes Event nicht zweimal gutschreibt.

Webhooks, WebSockets oder Polling

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

Ansatz	Funktionsweise	Stärke	Schwäche
Polling	Ihr Code ruft eth_getLogs timerbasiert vom letzten Checkpoint auf	Einfach, zustandslos, leicht fortzusetzen	Latenz entspricht Ihrem Intervall, und kostet Requests
WebSocket-Subscription	Persistente Verbindung streamt Logs von einem Knoten	Geringste Latenz	Stirbt mit der Verbindung, kein Replay, Puffer-Limits
Webhook	Ein Dienst überwacht die Kette und sendet einen HTTP POST an Ihren Endpunkt	Keine langlebige Verbindung zu warten, funktioniert mit Serverless	Sie brauchen einen öffentlichen Endpunkt, Signatur-Prüfungen und Duplicate-Handling

Polling eignet sich für Low-Volume-Backoffice-Jobs. WebSockets passen zu Dashboards oder Bots, die innerhalb eines Blocks reagieren müssen und Lücken tolerieren können. Webhooks passen zu Zahlungsflüssen, wo Sie einen zuverlässigen Push pro Event und eine Worker-Queue dahinter wollen. Unser Artikel zum Ingest, Queue, Fan-out-Muster für Webhooks versus WebSockets geht tiefer auf die Trade-offs ein.

Webhook-Zustellung richtig handhaben

Was auch immer den Webhook sendet, bauen Sie den Empfänger gleich:

• Überprüfen Sie die Signatur, bevor Sie den Body parsen.
• Geben Sie schnell einen 2xx-Status zurück und verarbeiten Sie asynchron.
• Gestalten Sie Handler idempotent, basierend auf Transaktions-Hash und Log-Index.
• Rechnen Sie mit Wiederholungsversuchen und Out-of-Order-Zustellung.
• Protokollieren Sie Fehler, damit Sie diese später mit einer Log-Abfrage abgleichen können.

Das Wiederholungsverhalten ist ein eigenes Designthema. Für einen tieferen Einblick in das Design rund um Wiederholungsversuche und verpasste Benachrichtigungen lesen Sie diesen Artikel zur Behandlung von Zahlungs-Webhook-Wiederholungen.

Einrichtung der Ereignisüberwachung Schritt für Schritt

Hier ist ein minimaler Pfad für einen einzelnen EVM-Vertrag, unabhängig vom verwendeten Tool.

1. ABI beschaffen. Aus dem verifizierten Vertrags-Quellcode oder Ihrem eigenen Build-Output. Ohne ihn sehen Sie nur rohe Topics und Hex-Daten.
2. Ereignisse auswählen. Listen Sie die Signaturen auf, die Sie interessieren, wie Transfer, Approval oder Ihr eigenes OrderPaid.
3. Filter festlegen. Vertragsadresse, Topic 0 und ggf. indizierte Parameter wie den Empfänger. Beachten Sie, dass nur indizierte Werte gefiltert werden können.
4. Nachladen (Backfill). Ab dem Bereitstellungsblock oder Ihrem Geschäftsstartdatum in Blöcken abfragen.
5. Live gehen. Über WebSocket abonnieren oder einen Webhook registrieren.
6. Dekodieren und normalisieren. Hex-Beträge mithilfe der Token-Dezimalstellen umwandeln und Blocknummer, Transaktions-Hash, Log-Index und Vertragsadresse speichern.
7. Auf Finalität warten. Ereignisse als ausstehend markieren, dann als bestätigt.
8. Den Monitor überwachen. Alarmieren, wenn kein Ereignis länger eintrifft als die normale Lücke der Kette, oder wenn Ihr Checkpoint hinter dem Head zurückbleibt.

Ereignisse über Ketten hinweg

Das EVM-Modell aus Topics und ABI-dekodierten Daten gilt für Ethereum, Polygon, BNB Chain und Arbitrum, sodass ein Decoder mit unterschiedlichen RPC-Endpunkten und Bestätigungsregeln übergreifend funktioniert. Andere Netzwerke teilen dieses Modell nicht. Bitcoin hat gar keine Vertrags-Logs, daher überwachen Sie Adressen und Transaktionen. Tron und Solana haben eigene Formate und APIs. Einige Cosmos-ähnliche Stacks unterscheiden sich erneut: Tendermint v0.36 hat seine Legacy-Streaming-API zugunsten einer Event-Log-API abgeschafft, die Clients per Long-Polling mit Cursorn abfragen.

Die praktische Konsequenz ist, dass ein Multi-Chain-Produkt am Ende einen Adapter pro Netzwerkfamilie wartet, jeweils mit eigenem Reconnect-, Decoding- und Finalitätscode. Das ist der Teil, den die meisten Teams unterschätzen. Für eine Übersicht der Optionen sehen Sie sich unseren Vergleich von sechs Arten von Blockchain-APIs und den Erklärer zu Blockchain-API versus Betrieb eines Nodes an.

Selbst bauen oder gehostete API nutzen

Der Betrieb eines eigenen Stacks bedeutet einen Node (oder einen bezahlten RPC-Endpunkt), einen Log-Scanner, eine ABI-Registry, einen Reorg-Handler, eine Queue und ein Alerting-Setup. Das ist sinnvoll, wenn Ereignisse Ihr Kernprodukt sind oder Sie benutzerdefiniertes Indexing über Tausende von Verträgen benötigen.

Es ist weniger sinnvoll, wenn Ereignisse nur Mittel zum Zweck sind, etwa um eine Einzahlung gutzuschreiben oder eine Bestellung zu bestätigen. In diesem Fall möchten Sie dekodierte Ereignisse an einen von Ihnen kontrollierten Endpunkt geliefert bekommen und sonst nichts betreiben.

Unsere Perspektive

Die meisten Ereignisbehandlungs-Fehler, die wir sehen, betreffen nicht das Lesen von Logs. Sie betreffen das, was drumherum passiert: eine verpasste Benachrichtigung während eines Deployments, eine doppelte Gutschrift nach einem Wiederholungsversuch, eine Dezimalumrechnung, die für einen Token falsch war, eine Verbindung, die nachts stillschweigend starb.

Wir bauen auf drei Überzeugungen auf. Erstens sollte die Anwendung decodierte, strukturierte Daten erhalten, keine rohen Topics, die sie selbst interpretieren muss. Zweitens ist Push für Zahlungen besser als Polling, solange jede Nachricht signiert und verifizierbar ist. Drittens sollte ein Entwickler keine Nodes betreiben oder chain-spezifische Endpunkte synchron halten müssen, nur um zu erfahren, dass eine Zahlung eingegangen ist.

Deshalb stellt Chaingateway eine einzige REST-API für Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain und Arbitrum bereit, mit vor-decodierten Transaktionsdaten, automatischer Gas-Schätzung und HMAC-signierten Anfragen. Webhooks liegen darüber, sodass Ihr Handler das Event erhält und sich Ihr Team auf das Produkt konzentrieren kann. Was auch immer Sie wählen: Behalten Sie den Checkpoint, den Idempotenz-Key und die Bestätigungsregel bei. Diese drei entscheiden, ob Ihre Zahlen stimmen.

— Bitblade

Events erhalten, ohne Nodes zu betreiben

Wenn Ihr Ziel Zahlungs- und Token-Events in einer App sind, liefern unsere Chaingateway Webhooks Echtzeit-Blockchain-Benachrichtigungen an Ihren Endpunkt, und die Blockchain API stellt Ihnen decodierte Transaktionsdaten, Wallets, Transfers und Gebührenschätzungen über eine einzige Schnittstelle bereit. Die Pläne beginnen bei 49 € pro Monat für Plus, Pro bei 99 €, Premium bei 249 € und Enterprise bei 499 € pro Monat. Bei jährlicher Abrechnung betragen die Preise 490 €, 990 €, 2.490 € und 4.990 € entsprechend. Details zu den enthaltenen Leistungen finden Sie auf der Preisseite. Für ein chain-spezifisches Beispiel lesen Sie über Polygon Webhooks ohne Polling.

Quellen

• Anatomie von Smart Contracts, ethereum.org
• Contract ABI Specification, Solidity v0.8.22
• Contract ABI Specification, Solidity v0.8.3
• Echtzeit-Events, go-ethereum
• eth_getLogs, Coinbase Developer Documentation
• Contract, ethers v5 Dokumentation
• Events abonnieren, Tendermint Core

Empfohlen

• ERC-20 Transfer Event: Struktur, Topics und wie man zuhört
• Blockchain-Webhooks & Event-Benachrichtigungen
• Was ist ein Smart Contract