API d'événements de smart contract : lire, filtrer
Comment fonctionne une API d'événements de smart contract : logs, topics, décodage ABI, événements passés et en direct, webhooks, WebSockets ou polling.
Relu par Maurice Sobiera

Une API d’événements de smart contract est une interface qui donne à votre application un accès structuré aux logs qu’un contrat écrit, sans que vous scanniez vous-même chaque transaction. Vous interrogez les logs passés par adresse de contrat et signature d’événement, puis vous vous abonnez aux nouveaux au fil des blocs. Vous pouvez utiliser le RPC brut d’un nœud, une bibliothèque comme ethers.js ou une API hébergée avec des webhooks.
Ce guide présente le fonctionnement de chaque voie, ses points de rupture et la façon de choisir.
TL;DR
- Un événement de contrat est une entrée de log écrite quand une transaction est minée. Votre application la lit ensuite. Le contrat lui-même ne peut pas la lire.
- Les événements passés viennent d’une requête de logs (
eth_getLogsouqueryFilter). Les événements en direct viennent d’un abonnement ou d’un webhook. Les abonnements de nœud ne rejouent pas l’historique. - Seuls les paramètres indexés peuvent servir de filtres. Le décodage exige l’ABI du contrat.
- Les abonnements WebSocket meurent avec la connexion et peuvent être coupés quand vous traitez trop lentement. Les webhooks avec une file d’attente et des gestionnaires idempotents résistent mieux aux redémarrages.
- Une API hébergée supprime le travail lié au nœud, à l’ABI et à la reconnexion. C’est ce que fait Chaingateway pour les paiements et les événements de jetons.
Qu’est-ce qu’un événement de smart contract ?
Les événements sont la façon dont un contrat parle au monde extérieur. Selon ethereum.org, les événements permettent à un contrat de communiquer avec un frontend ou d’autres applications abonnées, qui peuvent traiter l’information enregistrée une fois la transaction validée et ajoutée à un bloc.
Trois conséquences en découlent, et elles expliquent l’essentiel de la confusion dans les résultats de recherche :
- Les événements sont une sortie, pas un stockage que vous pouvez interroger depuis Solidity. Le code du contrat écrit des logs mais ne peut pas les relire. C’est pourquoi les fils de discussion qui demandent comment un contrat peut accéder aux événements passés finissent toujours par « faites-le hors chaîne ».
- Les événements n’apparaissent qu’après l’inclusion. Il n’existe pas de log pour une transaction encore dans le mempool.
- Les événements sont peu coûteux à émettre et à rechercher, ce qui explique que les événements
TransferetApprovald’ERC-20, les créations de NFT et les échanges sur les DEX soient tous suivis par les logs et non par des lectures d’état.
Une API d’événements de smart contract est tout ce qui donne à votre backend un accès structuré à ces logs : le JSON-RPC d’un nœud, une bibliothèque qui l’encapsule, un indexeur ou un service hébergé qui vous envoie des webhooks.
Que contient un log d’événement ?
Pour filtrer ou décoder correctement les logs, il faut connaître leur forme. D’après la spécification ABI de Solidity, un log contient l’adresse du contrat, jusqu’à quatre topics et un segment de données. Les événements anonymes omettent le hachage de la signature de l’événement.
Pour un événement normal :
- Le topic 0 est le hachage Keccak-256 de la signature de l’événement, par exemple
Transfer(address,address,uint256). - Les topics 1 à 3 contiennent les paramètres indexés.
- Les données contiennent les paramètres non indexés, encodés en ABI.
L’ABI sépare les paramètres en paramètres indexés, stockés comme topics hachés pour un filtrage efficace, et en paramètres non indexés, stockés comme données binaires dans le log.
Il existe un piège à connaître. La même spécification (dans l’édition v0.8.3) note que les paramètres indexés de longueur dynamique, comme les chaînes et les tableaux d’octets, sont stockés sous forme d’un hachage Keccak d’un encodage spécial et non sous forme de valeur. Vous ne pouvez pas retrouver la chaîne d’origine à partir du log. Vous pouvez seulement tester si une valeur candidate correspond.
Un exemple concret : le Transfer d’ERC-20
Un log de transfert de jeton a le topic 0 pour la signature Transfer, l’adresse de l’expéditeur dans le topic 1, celle du destinataire dans le topic 2 et le montant dans le champ de données. Pour obtenir tous les dépôts vers l’adresse d’un client, vous filtrez sur le topic 0 et le topic 2. Nous le détaillons dans notre guide de l’événement Transfer d’ERC-20.

Comment lire les événements passés ?
Une lecture de l’historique est une requête, pas un abonnement. La méthode JSON-RPC standard est eth_getLogs. Elle prend un objet de filtre avec une plage de blocs, une adresse de contrat facultative et un tableau de topics facultatif. La référence d’eth_getLogs dans la documentation développeur de Coinbase montre la forme : fromBlock, toBlock et topics, et indique qu’un hachage de bloc peut remplacer la plage.
Les bibliothèques encapsulent cet appel. Dans ethers.js, contract.queryFilter(event, fromBlock, toBlock) renvoie les événements correspondants, et la documentation des contrats d’ethers v5 précise que seuls les paramètres indexés peuvent être filtrés. Un paramètre laissé à null correspond à n’importe quelle valeur.
Règles pratiques pour les requêtes historiques :
- Bornez toujours la plage. De nombreux fournisseurs limitent l’étendue en blocs ou le nombre de résultats par appel. Parcourez les plages par tranches (par exemple quelques milliers de blocs à la fois) et divisez la tranche par deux en cas d’erreur.
- Filtrez au minimum par adresse et par topic 0. Les requêtes de logs sans filtre sont le moyen le plus rapide d’atteindre une limite de débit.
- Stockez le dernier bloc traité. Ce point de reprise vous permet de repartir après un plantage sans trous ni doublons.
- Décodez avec la bonne ABI. Si vous n’avez que le topic 0, vous pouvez rechercher la signature de l’événement, mais un contrat proxy peut émettre des événements définis dans son implémentation : utilisez donc l’ABI de l’implémentation.
Pour un rappel sur la communication directe avec les nœuds, notre guide JSON-RPC avec des exemples en PHP, Python et JavaScript présente le format des requêtes.
Comment s’abonner aux nouveaux événements ?
Le côté en direct fonctionne autrement, et c’est là que beaucoup de premières implémentations échouent.
La documentation des événements en temps réel de go-ethereum explique que les abonnements utilisent des connexions WebSocket ou IPC persistantes, en général via eth_subscribe, et diffusent les événements au fur et à mesure que le nœud les traite. Deux limites comptent :
- Pas de relecture. Les notifications d’abonnement couvrent les événements courants, pas les passés. Si votre processus était arrêté pendant dix minutes, l’abonnement ne vous rend pas ce que vous avez manqué. Vous comblez le trou avec une requête de logs.
- Couplage à la connexion. Les abonnements sont liés à une seule connexion. Quand elle se ferme, tous ses abonnements se ferment.
La même page ajoute que les nœuds mettent les notifications en mémoire tampon, et que si votre client ne peut pas les traiter assez vite, la connexion peut être fermée une fois la limite du tampon atteinte (l’exemple de Geth est 10 000). Un gestionnaire lent, qui écrit directement en base de données, est exactement ce qui provoque cela.
Le schéma qui tient la route
Combinez les deux mécanismes :
- Au démarrage, lisez votre bloc de reprise.
- Comblez l’écart entre ce point de reprise et la tête actuelle avec
eth_getLogs, par tranches. - Ouvrez l’abonnement et dédupliquez par hachage de transaction plus index du log.
- Passez chaque événement à une file d’attente et accusez réception immédiatement. Traitez-le dans un worker.
- En cas de déconnexion, revenez à l’étape 1.
Cela reste correct même quand la connexion tombe, ce qui arrivera.
Que se passe-t-il lors d’une réorganisation ?
Un log vu dans le dernier bloc peut disparaître si la chaîne se réorganise. Dès qu’il s’agit d’argent, ne créditez pas un utilisateur à la première observation. Attendez une profondeur de confirmation adaptée à la chaîne et au montant, et gérez l’indicateur « removed » que les nœuds de type Ethereum attachent aux logs des blocs orphelins. Conservez l’identifiant de l’événement traité et rendez votre gestionnaire idempotent, pour qu’un événement rejoué ou corrigé ne puisse pas créditer deux fois.

Faut-il utiliser des webhooks, des WebSockets ou du polling ?
Les trois peuvent livrer des événements. Ils diffèrent par celui qui tient la connexion et celui qui porte les modes de défaillance.
| Approche | Fonctionnement | Atout | Faiblesse |
|---|---|---|---|
| Polling | Votre code appelle eth_getLogs à intervalle régulier depuis le dernier point de reprise | Simple, sans état, facile à reprendre | Latence égale à votre intervalle, et coût en requêtes |
| Abonnement WebSocket | Une connexion persistante diffuse les logs d’un nœud | Latence la plus faible | Meurt avec la connexion, pas de relecture, limites de tampon |
| Webhook | Un service surveille la chaîne et envoie un POST HTTP à votre point d’accès | Pas de connexion durable à maintenir, compatible avec le serverless | Il faut un point d’accès public, des contrôles de signature et une gestion des doublons |
Le polling convient aux tâches d’arrière-bureau à faible volume. Les WebSockets conviennent à un tableau de bord ou à un robot qui doit réagir en un bloc et peut tolérer des trous. Les webhooks conviennent aux flux de paiement, où vous voulez un envoi fiable par événement et une file de workers derrière. Notre article sur le schéma réception, file d’attente et diffusion pour webhooks et WebSockets détaille ces compromis.
Bien gérer la livraison des webhooks
Quel que soit l’émetteur du webhook, construisez le récepteur de la même façon :
- Vérifiez la signature avant d’agir sur le payload.
- Renvoyez vite un code 2xx et traitez en asynchrone.
- Rendez les gestionnaires idempotents, avec pour clé le hachage de transaction et l’index du log.
- Attendez-vous à des doublons et à une livraison dans le désordre.
- Journalisez les échecs pour pouvoir rapprocher plus tard avec une requête de logs.
Le comportement de livraison est un sujet de conception à part entière. Notre article sur les garanties de livraison des webhooks traite les doublons, l’ordre et les notifications manquées.
Mettre en place la surveillance d’événements pas à pas
Voici un chemin minimal pour un contrat EVM unique, quel que soit l’outil.
- Obtenez l’ABI. À partir du code source vérifié du contrat ou de votre propre sortie de compilation. Sans elle, vous ne voyez que des topics bruts et des données hexadécimales.
- Choisissez les événements. Listez les signatures qui vous intéressent, comme
Transfer,Approvalou votre propreOrderPaid. - Décidez des filtres. Adresse du contrat, topic 0 et tout paramètre indexé comme le destinataire. N’oubliez pas que seules les valeurs indexées peuvent être filtrées.
- Comblez l’historique. Interrogez depuis le bloc de déploiement, ou depuis la date de début de votre activité, par tranches.
- Passez en direct. Abonnez-vous par WebSocket ou enregistrez un webhook.
- Décodez et normalisez. Convertissez les montants hexadécimaux avec les décimales du jeton, et stockez le numéro de bloc, le hachage de transaction, l’index du log et l’adresse du contrat.
- Attendez la finalité. Marquez les événements comme en attente, puis confirmés.
- Surveillez la surveillance. Déclenchez une alerte quand aucun événement n’arrive pendant plus que l’écart normal de la chaîne, ou quand votre point de reprise prend du retard sur la tête.
Les événements sur plusieurs chaînes
Le modèle EVM de topics et de données décodées par ABI s’applique à Ethereum, Polygon, BNB Chain et Arbitrum : un seul décodeur fonctionne donc sur toutes, avec des points d’accès RPC et des règles de confirmation différents. Les autres réseaux ne partagent pas ce modèle. Bitcoin n’a aucun log de contrat : vous surveillez donc les adresses et les transactions. Tron et Solana ont leurs propres formats et API.
En pratique, un produit multi-chaînes finit par maintenir un adaptateur par famille de réseaux, chacun avec son propre code de reconnexion, de décodage et de finalité. C’est la partie que la plupart des équipes sous-estiment. Pour une carte des options, consultez notre comparaison des six types d’API blockchain et l’explication sur l’API blockchain face à l’exploitation d’un nœud.
Faut-il le construire soi-même ou utiliser une API hébergée ?
Exploiter votre propre pile signifie un nœud (ou un point d’accès RPC payant), un scanner de logs, un registre d’ABI, un gestionnaire de réorganisation, une file d’attente et un dispositif d’alerte. C’est raisonnable si les événements sont votre produit principal ou si vous avez besoin d’une indexation sur mesure sur des milliers de contrats.
C’est moins raisonnable si les événements ne sont qu’un moyen, par exemple pour créditer un dépôt ou confirmer une commande. Dans ce cas, vous voulez des événements décodés livrés à un point d’accès que vous contrôlez, et rien d’autre à exploiter.
Notre point de vue
La plupart des bogues de traitement d’événements que nous voyons ne tiennent pas à la lecture des logs. Ils tiennent à ce qui se passe autour : une notification manquée pendant un déploiement, un crédit en double après une nouvelle tentative, une conversion de décimales fausse pour un jeton, une connexion morte sans bruit pendant la nuit.
Nous construisons donc autour de trois convictions. Première conviction : l’application doit recevoir des données décodées et structurées, pas des topics bruts qu’elle doit interpréter. Deuxième : pousser vaut mieux que tirer pour les paiements, tant que chaque message est signé et vérifiable. Troisième : un développeur ne devrait pas avoir à exploiter des nœuds ni à synchroniser des points d’accès propres à chaque chaîne juste pour apprendre qu’un paiement est arrivé.
C’est pourquoi Chaingateway expose une seule API REST pour Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain et Arbitrum, avec des transactions décodées et des prix du gaz. Les webhooks s’y ajoutent et sont signés en HMAC : votre gestionnaire reçoit l’événement et votre équipe garde son attention sur le produit. Quoi que vous choisissiez, gardez le point de reprise, la clé d’idempotence et la règle de confirmation. Ces trois éléments décident si vos chiffres sont justes.
Bitblade
Comment obtenir des événements sans exploiter de nœuds ?
Si votre objectif est de recevoir des événements de paiement et de jetons dans une application, nos webhooks Chaingateway livrent des notifications blockchain en temps réel à votre point d’accès, et l’API blockchain vous donne transactions décodées, portefeuilles, transferts et prix du gaz via une seule interface. Les offres démarrent à 49 € par mois pour Plus, avec Pro à 99 €, Premium à 249 € et Enterprise à 499 € par mois. La facturation annuelle est de 490 €, 990 €, 2 490 € et 4 990 € respectivement. Consultez la page des tarifs pour le contenu de chaque niveau. Pour un exemple propre à une chaîne, lisez l’article sur les webhooks Polygon sans polling.
Sources
- Anatomy of smart contracts, ethereum.org
- Contract ABI Specification, Solidity v0.8.22
- Contract ABI Specification, Solidity v0.8.3
- Real-time Events, go-ethereum
- eth_getLogs, Coinbase Developer Documentation
- Contract, ethers v5 documentation
Recommandé
Questions fréquentes
Non. Les contrats peuvent émettre des logs mais ne peuvent pas y accéder ensuite : les données d’événements sont destinées à des consommateurs hors chaîne. Si votre contrat a besoin de données historiques sur la chaîne, stockez plutôt la valeur dans l’état du contrat, à un coût de gaz plus élevé.
Lancez une requête de logs depuis votre dernier bloc traité jusqu’à la tête actuelle. Les abonnements de nœud n’envoient que les événements courants : se reconnecter ne rejoue donc rien. Stockez un point de reprise après chaque bloc traité et dédupliquez par hachage de transaction et index du log.
Seuls les paramètres indexés sont stockés comme topics, et seuls les topics peuvent être filtrés. Les valeurs non indexées se trouvent dans le champ de données : vous devez donc récupérer les logs et les filtrer dans votre propre code. Si vous contrôlez le contrat, marquez comme indexés les champs sur lesquels vous chercherez, jusqu’à trois par événement.
Pour les paiements, les webhooks avec une file d’attente sont généralement plus faciles à exploiter, car vous ne tenez pas une connexion qui peut tomber. Utilisez les WebSockets quand une réaction en moins d’une seconde compte et que vous pouvez combler les trous. Dans les deux cas, traitez les événements de façon idempotente et attendez assez de confirmations avant de créditer des fonds.
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.