API per Eventi Smart Contract: Lettura, Filtraggio e Sottoscrizione

Un’API per eventi di smart contract consente alla Sua applicazione di scoprire cosa ha fatto un contratto senza dover scansionare ogni transazione da sé. Interroga i log passati tramite indirizzo del contratto e firma dell’evento, quindi si iscrive ai nuovi man mano che arrivano i blocchi. Può fare entrambe le cose tramite RPC del nodo raw, tramite una libreria come ethers.js, o tramite un’API ospitata che decodifica i log e li invia come webhook. Questa guida spiega come funziona ogni percorso, dove ognuno fallisce e come scegliere.

TL;DR

• Un evento di contratto è una voce di log scritta quando una transazione viene minata. La Sua app la legge in seguito. Il contratto stesso non può leggerla.
• Gli eventi passati provengono da una query di log (eth_getLogs o queryFilter). Gli eventi live provengono da una sottoscrizione o un webhook. Le sottoscrizioni del nodo non riproducono la cronologia.
• Solo i parametri indicizzati possono essere usati come filtri. La decodifica richiede l’ABI del contratto.
• Le sottoscrizioni WebSocket muoiono con la connessione e possono essere interrotte se elabora troppo lentamente. I webhook con coda e gestori idempotenti sopravvivono meglio ai riavvii.
• Un’API ospitata rimuove il lavoro su nodo, ABI e riconnessione. È ciò che fa Chaingateway per eventi di pagamenti e token.

Indice

• What a smart contract event is
• What is inside an event log
• Reading past events
• Subscribing to new events
• Reorgs and confirmations
• Webhooks, WebSockets or polling
• Setting up event monitoring step by step
• Events across chains
• Build it yourself or use a hosted API
• Our perspective
• Getting events without running nodes
• FAQ
• Sources

What a smart contract event is

Gli eventi sono il modo in cui un contratto parla con il mondo esterno. Secondo ethereum.org, gli eventi permettono a un contratto di comunicare con un frontend o altre applicazioni sottoscritte, che possono elaborare le informazioni registrate dopo che la transazione è stata validata e aggiunta a un blocco.

Ne derivano tre conseguenze, che spianano la maggior parte della confusione nei risultati di ricerca:

1. Gli eventi sono output, non storage interrogabile da Solidity. Il codice del contratto scrive i log ma non può rileggerli. È per questo che i thread che chiedono come un contratto possa accedere agli eventi passati finiscono sempre con “fallo off-chain”.
2. Gli eventi appaiono solo dopo l’inclusione. Non esiste alcun log per una transazione ancora nella mempool.
3. Gli eventi sono economici da emettere e da cercare, ed è per questo che gli eventi ERC-20 Transfer e Approval, i mint di NFT e gli swap DEX sono tutti tracciati tramite log e non tramite letture di stato.

Un’API per eventi di smart contract è qualsiasi cosa dia al Suo backend accesso strutturato a quei log: JSON-RPC di un nodo, una libreria che lo avvolge, un indexer, o un servizio ospitato che Le invia webhook.

What is inside an event log

Per filtrare o decodificare correttamente i log è necessario conoscerne la struttura. Secondo la specifica ABI di Solidity, un log contiene l’indirizzo del contratto, fino a quattro topic e un segmento dati. Gli eventi anonimi omettono l’hash della firma dell’evento.

Per un evento normale:

• Topic 0 è l’hash Keccak-256 della firma dell’evento, ad esempio Transfer(address,address,uint256).
• Topic da 1 a 3 contengono i parametri indicizzati.
• Data contiene i parametri non indicizzati, codificati in ABI.

L’ABI separa i parametri in indicizzati, memorizzati come hash topic per un filtraggio efficiente, e non indicizzati, memorizzati come dati binari nel log.

C’è una trappola che vale la pena conoscere. La stessa specifica (nell’edizione v0.8.3) nota che i parametri indicizzati a lunghezza dinamica, come stringhe e array di byte, vengono memorizzati come hash Keccak di una codifica speciale piuttosto che come valore. Non è possibile recuperare la stringa originale dal log. È possibile solo verificare se un valore candidato corrisponde.

Un esempio concreto: Transfer ERC-20

Un log di trasferimento token ha il topic 0 per la firma Transfer, l’indirizzo del mittente nel topic 1, quello del destinatario nel topic 2 e l’importo nel campo data. Se si desidera ogni deposito verso un indirizzo cliente, si filtra sul topic 0 e sul topic 2. Ne parliamo in dettaglio nella nostra guida all’evento Transfer ERC-20.

Lettura degli eventi passati

Le letture storiche sono una query, non una sottoscrizione. Il metodo JSON-RPC standard è eth_getLogs. Accetta un oggetto filtro con un intervallo di blocchi, un indirizzo contratto opzionale e un array opzionale di topic. Il riferimento della documentazione sviluppatori Coinbase per eth_getLogs ne mostra la struttura: fromBlock, toBlock e topics, e nota che un hash di blocco può sostituire l’intervallo.

Le librerie incapsulano questo metodo. In ethers.js, contract.queryFilter(event, fromBlock, toBlock) restituisce gli eventi corrispondenti, e la documentazione ethers v5 sui contratti afferma che solo i parametri indicizzati possono essere filtrati. Un parametro lasciato null corrisponde a qualsiasi valore.

Regole pratiche per le query storiche:

• Limitare sempre l’intervallo. Molti provider limitano l’estensione dei blocchi o il numero di risultati per chiamata. Scorrere gli intervalli a blocchi (ad esempio qualche migliaio di blocchi alla volta) e dimezzare il blocco quando si riceve un errore.
• Filtrare almeno per indirizzo e topic 0. Le query log non filtrate sono il modo più veloce per raggiungere un rate limit.
• Memorizzare l’ultimo blocco elaborato. Questo checkpoint è ciò che permette di riprendere dopo un crash senza lacune o duplicati.
• Decodificare con l’ABI corretto. Se si ha solo il topic 0, si può cercare la firma dell’evento, ma un contratto proxy potrebbe emettere eventi definiti nella sua implementazione, quindi usare l’ABI dell’implementazione.

Se desidera un ripasso su come parlare direttamente con i nodi, la nostra guida JSON-RPC con esempi in PHP, Python e JavaScript copre il formato della richiesta.

Sottoscrizione ai nuovi eventi

La parte live funziona in modo diverso, ed è qui che molte prime implementazioni falliscono.

La documentazione sugli eventi in tempo reale di go-ethereum spiega che le sottoscrizioni utilizzano connessioni WebSocket o IPC persistenti, tipicamente tramite eth_subscribe, e trasmettono gli eventi mentre il nodo li elabora. Due limiti sono rilevanti:

• Nessun replay. Le notifiche di sottoscrizione coprono gli eventi correnti, non quelli passati. Se il suo processo era inattivo da dieci minuti, la sottoscrizione non le fornirà ciò che ha perso. Esegue il backfill con una query sui log.
• Accoppiamento alla connessione. Le sottoscrizioni sono legate a una singola connessione. Quando questa si chiude, tutte le sue sottoscrizioni si chiudono.

La stessa pagina aggiunge che i nodi mettono in buffer le notifiche e, se il suo client non riesce a elaborarle abbastanza velocemente, la connessione potrebbe essere chiusa una volta raggiunto il limite del buffer (l’esempio di Geth è 10.000). Un gestore lento che esegue scritture sul database in linea è esattamente il modo in cui ciò accade.

Il pattern che regge

Combinare entrambi i meccanismi:

1. All’avvio, legga il suo blocco di checkpoint.
2. Esegua il backfill dal checkpoint alla testa corrente con eth_getLogs, a blocchi.
3. Apra la sottoscrizione e deduplichi per hash della transazione più indice del log.
4. Invii ogni evento a una coda e confermi immediatamente. Lo elabori in un worker.
5. In caso di disconnessione, torni al punto 1.

Questo rimane corretto anche quando la connessione cade, cosa che accadrà.

Riorganizzazioni e conferme

Un log visto nell’ultimo blocco può sparire se la catena si riorganizza. Per qualsiasi cosa che coinvolga denaro, non accrediti un utente al primo avvistamento. Attenda una profondità di conferma adatta alla catena e all’importo, e gestisca il flag “removed” che i nodi in stile Ethereum allegano ai log provenienti da blocchi orfani. Conservi l’ID dell’evento elaborato e renda il suo gestore idempotente in modo che un evento riprodotto o corretto non possa accreditare due volte.

Webhook, WebSocket o polling

Tutti e tre possono consegnare eventi. Differiscono per chi detiene la connessione e chi gestisce le modalità di errore.

Approccio	Come funziona	Punto di forza	Punto debole
Polling	Il suo codice chiama eth_getLogs su un timer dall’ultimo checkpoint	Semplice, senza stato, facile da riprendere	La latenza è uguale al suo intervallo, e costa richieste
Sottoscrizione WebSocket	Connessione persistente che trasmette i log da un nodo	Latenza più bassa	Muore con la connessione, nessun replay, limiti di buffer
Webhook	Un servizio osserva la catena e invia un HTTP POST al suo endpoint	Nessuna connessione di lunga durata da mantenere, funziona con serverless	Le serve un endpoint pubblico, controlli di firma e gestione dei duplicati

Il polling va bene per lavori di back-office a basso volume. I WebSocket si adattano a una dashboard o a un bot che deve reagire entro un blocco e può tollerare lacune. I webhook si adattano ai flussi di pagamento, dove desidera una spinta affidabile per evento e una coda di worker dietro. Il nostro articolo sul pattern ingest, queue, fan out per webhook versus WebSocket approfondisce i compromessi.

Gestire correttamente la consegna dei webhook

Qualunque sia il mittente del webhook, costruisca il ricevitore nello stesso modo:

• Verifichi la firma prima di analizzare il corpo.
• Restituisca un 2xx rapidamente ed elabori in modo asincrono.
• Renda gli handler idempotenti, basati su hash della transazione e indice del log.
• Preveda tentativi ripetuti e consegna fuori ordine.
• Registri i fallimenti in modo da poterli riconciliare con una query sui log in seguito.

Il comportamento dei tentativi ripetuti è un argomento di progettazione a sé stante. Per un’analisi più approfondita sulla progettazione attorno a tentativi ripetuti e notifiche mancate, consulti questo articolo sulla gestione dei tentativi ripetuti dei webhook di pagamento.

Configurazione del monitoraggio degli eventi passo dopo passo

Ecco un percorso minimo per un singolo contratto EVM, qualunque strumento utilizzi.

1. Ottenga l’ABI. Dal codice sorgente del contratto verificato o dal proprio output di build. Senza di esso vede topic grezzi e dati esadecimali.
2. Scelga gli eventi. Elenchi le firme che le interessano, come Transfer, Approval o il proprio OrderPaid.
3. Decida i filtri. Indirizzo del contratto, topic 0 e qualsiasi parametro indicizzato come il destinatario. Ricordi che solo i valori indicizzati possono essere filtrati.
4. Esegua il backfill. Esegua query dal blocco di deployment, o dalla data di inizio dell’attività, a blocchi.
5. Vada in produzione. Si iscriva via WebSocket, o registri un webhook.
6. Decodifichi e normalizzi. Converta gli importi esadecimali usando i decimali del token, e memorizzi numero di blocco, hash della transazione, indice del log e indirizzo del contratto.
7. Attenda la finalità. Marchi gli eventi come in sospeso, poi confermati.
8. Monitori il monitor. Imposti allerte quando nessun evento arriva per un tempo superiore al gap normale della catena, o quando il suo checkpoint rimane indietro rispetto alla testa.

Eventi tra catene

Il modello EVM di topic e dati decodificati con ABI si applica a Ethereum, Polygon, BNB Chain e Arbitrum, quindi un decoder funziona su di essi con endpoint RPC e regole di conferma diversi. Altre reti non condividono il modello. Bitcoin non ha log di contratto, quindi osserva indirizzi e transazioni. Tron e Solana hanno i propri formati e API. Alcuni stack in stile Cosmos differiscono di nuovo: Tendermint v0.36 ha deprecato la sua API di streaming legacy a favore di un’API di log eventi che i client interrogano tramite long-polling con cursori.

La conseguenza pratica è che un prodotto multi-catena finisce per mantenere un adapter per famiglia di rete, ognuno con il proprio codice di riconnessione, decodifica e finalità. È la parte che la maggior parte dei team sottostima. Per una mappa delle opzioni, veda il nostro confronto tra sei tipi di API blockchain e la spiegazione su API blockchain versus esecuzione di un nodo.

Costruirla da sé o usare un’API ospitata

Eseguire il proprio stack significa un nodo (o un endpoint RPC a pagamento), uno scanner di log, un registro ABI, un gestore di reorg, una coda e una configurazione di alerting. È ragionevole se gli eventi sono il suo prodotto principale o se ha bisogno di indicizzazione personalizzata su migliaia di contratti.

È meno ragionevole se gli eventi sono un mezzo per uno scopo, come l’accredito di un deposito o la conferma di un ordine. In quel caso vuole eventi decodificati consegnati a un endpoint che controlla, e nient’altro da gestire.

La nostra prospettiva

La maggior parte dei bug di gestione eventi che vediamo non riguardano la lettura dei log. Riguardano ciò che accade attorno a loro: una notifica mancata durante un deploy, un accredito duplicato dopo un tentativo ripetuto, una conversione decimale errata per un token, una connessione che è morta silenziosamente durante la notte.

Quindi costruiamo attorno a tre convinzioni. Primo, l’applicazione dovrebbe ricevere dati decodificati e strutturati, non argomenti grezzi che deve interpretare. Secondo, il push batte il poll per i pagamenti, a patto che ogni messaggio sia firmato e possa essere verificato. Terzo, uno sviluppatore non dovrebbe dover eseguire nodi o mantenere endpoint specifici per catena sincronizzati solo per scoprire che un pagamento è arrivato.

È per questo che Chaingateway espone un’unica API REST su Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain e Arbitrum, con dati di transazione pre-decodificati, stima automatica del gas e richieste firmate con HMAC. I webhook si trovano in cima, così il Suo gestore riceve l’evento e il Suo team mantiene l’attenzione sul prodotto. Qualunque cosa scelga, mantenga il checkpoint, la chiave di idempotenza e la regola di conferma. Quei tre elementi decidono se i Suoi numeri sono corretti.

— Bitblade

Ottenere eventi senza eseguire nodi

Se il Suo obiettivo sono gli eventi di pagamento e token in un’app, i nostri Chaingateway Webhooks consegnano notifiche blockchain in tempo reale al Suo endpoint, e la Blockchain API Le fornisce dati di transazione decodificati, portafogli, trasferimenti e stime delle commissioni attraverso un’unica interfaccia. I piani partono da 49 € al mese per Plus, con Pro a 99 €, Premium a 249 € e Enterprise a 499 € al mese. La fatturazione annuale è rispettivamente 490 €, 990 €, 2.490 € e 4.990 €. Veda la pagina dei prezzi per cosa include ogni livello. Per un esempio specifico per catena, legga sui webhook Polygon senza polling.

Fonti

• Anatomia degli smart contract, ethereum.org
• Specifica ABI dei contratti, Solidity v0.8.22
• Specifica ABI dei contratti, Solidity v0.8.3
• Eventi in tempo reale, go-ethereum
• eth_getLogs, Documentazione per sviluppatori Coinbase
• Contratto, documentazione ethers v5
• Sottoscrizione agli eventi, Tendermint Core

Consigliati

• Evento Transfer ERC-20: Struttura, Argomenti e Come Ascoltarlo
• Webhook Blockchain e Notifiche di Eventi
• Cos’è uno Smart Contract