Evento Transfer ERC-20: Struttura, Argomenti e Come Ascoltarlo

L’evento ERC-20 Transfer è il log che un contratto token emette ogni volta che i token si muovono. La sua firma è Transfer(address indexed from, address indexed to, uint256 value), ed è l’unico modo affidabile per un’app esterna alla catena di sapere che un pagamento è avvenuto. Per intercettarlo si filtrano i log tramite l’hash del topic dell’evento, si decodificano mittente, destinatario e importo, e si attende che il blocco sia sicuro da considerare definitivo. Questa guida illustra ogni passo, le trappole che costano denaro reale e quando ha senso smettere di interrogare i log da soli.

TL;DR

• Lo standard definisce Transfer(address indexed from, address indexed to, uint256 value). Deve scattare a ogni movimento di token, inclusi i trasferimenti a valore zero.
• Per filtrare i log, usare l’hash keccak256 di Transfer(address,address,uint256) come topic 0. I topic 1 e 2 sono gli indirizzi from e to con padding; l’importo si trova nel campo data.
• eth_getLogs su endpoint pubblici ha limiti e può restituire risultati incompleti per ampi intervalli di blocchi senza errori. Paginare, e usare infrastruttura dedicata per la produzione.
• ERC-20 non ha callback al destinatario, quindi ascoltare off-chain non è opzionale se si accredita i saldi utente.
• Se preferisce non gestire indexer di log, un servizio webhook può inviare notifiche di trasferimento decodificate al suo backend.

Indice

• What the Transfer event actually is
• Anatomy of a Transfer log
• Reading transfers with eth_getLogs
• Confirmations, reorgs and idempotency
• Why you cannot rely on the recipient to notice
• Edge cases that break naive listeners
• Build or buy: running your own listener
• Perspective: what we see when teams build deposit detection
• Getting transfer notifications without running indexers
• A minimal handler, step by step
• FAQ
• Sources

What the Transfer event actually is

Un contratto intelligente può emettere eventi, che sono segnali scritti nella ricevuta della transazione come log. Non sono memorizzati nello stato del contratto, quindi sono economici da scrivere e da leggere, ma un contratto non può leggerli in seguito. Il loro pubblico è il mondo esterno: portafogli, block explorer, indexer e il suo backend. Il tutorial di Ethereum sugli eventi li descrive come segnali che le dapp e qualsiasi cosa connessa all’API JSON-RPC possono ascoltare e su cui agire.

Per i token, la specifica ERC-20 definisce l’evento così:

event Transfer(address indexed _from, address indexed _to, uint256 _value)

Le regole che contano in pratica:

• DEVE essere emesso quando i token vengono trasferiti, e questo include i trasferimenti di valore zero.
• La funzione transfer deve emetterlo, e lo stesso vale per transferFrom, la funzione che uno spender utilizza dopo che è stata concessa un’allowance.
• Il minting dovrebbe emetterlo con l’indirizzo from impostato sull’indirizzo zero. Il burning fa il contrario, con l’indirizzo zero come destinatario (molte implementazioni seguono questa convenzione).

Quell’ultimo punto è una fonte comune di bug. Un listener che osserva solo i “trasferimenti verso il mio indirizzo” funzionerà correttamente, ma uno che tratta ogni Transfer come un pagamento da utente a utente interpreterà male mint e burn.

Il saldo del token è ciò che conta on-chain, e l’evento è un report su di esso. Se desidera lo sfondo sull’interfaccia completa, la trattiamo nel nostro post sullo standard token ERC-20.

Anatomia di un log Transfer

Quando l’evento viene emesso, il nodo memorizza un log con tre parti: l’indirizzo del contratto emittente, una lista di topic e un data blob. L’indicizzazione decide dove finisce ogni argomento.

I due indirizzi sono indicizzati, quindi sono ricercabili tramite il filtro log. Il valore non è indicizzato, quindi viene memorizzato nel campo data, il che mantiene bassi i costi on-chain e significa che non può filtrare per importo a livello di nodo. Se ha bisogno di “trasferimenti superiori a 1.000 token”, li recupera e filtra nel proprio codice.

L’hash del topic 0

Per interrogare tramite JSON-RPC le serve l’hash keccak256 della stringa di firma canonica Transfer(address,address,uint256). Niente spazi, niente nomi dei parametri, niente parola chiave indexed. Il risultato è:

0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef

La documentazione sugli eventi di ethers.js usa lo stesso meccanismo: topic 0 è l’hash della firma, e topic 1 e 2 corrispondono agli indirizzi from e to indicizzati, ciascuno padded a 32 byte.

Due dettagli le faranno risparmiare tempo nel debugging:

1. I decimali sono compito suo. Il value è un intero grezzo. Un token con 6 decimali e un valore di 2500000 equivale a 2,5 token. Legga decimals() dal contratto (o lo metta in cache per token) prima di mostrare gli importi.
2. Stesso hash, standard diversi. ERC-721 usa lo stesso nome evento e gli stessi tipi di argomento, quindi il suo topic 0 è identico. La differenza è che il token ID è indicizzato, quindi un log di trasferimento NFT ha quattro topic e un campo data vuoto, mentre un trasferimento fungibile ne ha tre. Controlli il numero di topic prima di decodificare, altrimenti interpreterà i movimenti NFT come pagamenti token. Il nostro post sullo standard ERC-721 copre quel lato.

Lettura dei trasferimenti con eth_getLogs

L’approccio classico è una chiamata JSON-RPC diretta. Un filtro che trova tutti i trasferimenti di un token verso un wallet appare così:

{
  "method": "eth_getLogs",
  "params": [{
    "fromBlock": "0x10d4f00",
    "toBlock": "0x10d4f64",
    "address": "0xTokenContractAddress",
    "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      null,
      "0x000000000000000000000000YourDepositAddressWithoutThe0x"
    ]
  }]
}

Un valore null in una posizione di topic significa “qualsiasi valore”. Qui accettiamo qualsiasi mittente e fissiamo il destinatario. Si noti che il destinatario è riempito con zeri fino a 32 byte.

Se preferisce una libreria, una breve procedura come questo gist web3.py per i log di trasferimento ERC-20 mostra la stessa chiamata avvolta in Python. Per aggiornamenti in tempo reale invece che per lo storico, eth_subscribe con il tipo logs invia i nuovi match tramite WebSocket.

Dove eth_getLogs la tradisce

Sembra semplice e funziona in un tutorial. La produzione è diversa. L’articolo di SQD sui limiti di eth_getLogs osserva che i provider di nodi standard spesso limitano il numero di log restituiti, e che l’interrogazione di un ampio intervallo di blocchi può produrre dati incompleti senza alcun errore. Il loro consiglio: paginare le richieste e usare nodi d’archivio per i dati storici. Lo stesso articolo avverte che fare affidamento su endpoint pubblici per un uso intensivo in produzione è inaffidabile, a causa delle limitazioni dei bloom filter e delle lacune nell’indicizzazione che variano da nodo a nodo.

Le regole pratiche:

• Interroghi finestre di blocchi piccole e proceda in avanti, invece di chiedere un unico grande intervallo.
• Confronti il conteggio dei risultati con ciò che si aspetta. Un troncamento silenzioso appare esattamente come un giorno tranquillo.
• Memorizzi l’ultimo numero di blocco processato, così un riavvio riprende da dove si era fermato invece di saltare blocchi.
• Mantenga una sovrapposizione di alcuni blocchi a ogni passaggio e deduplichi in base all’hash della transazione più l’indice del log.

Conferme, riorganizzazioni e idempotenza

Un log che appare nell’ultimo blocco non è definitivo. La catena può riorganizzarsi, e un blocco che conteneva il suo trasferimento può essere sostituito da uno che non lo contiene. Una pipeline di deposito solida tratta l’evento come una rivendicazione, non come un fatto, finché un numero sufficiente di blocchi non si è accumulato sopra di esso.

Una semplice macchina a stati funziona bene:

1. Visto. Il log viene rilevato. Lo registri, mostri “in attesa” all’utente e non accrediti nulla.
2. Confermato. Il blocco è più vecchio della soglia scelta. Accrediti il saldo una sola volta.
3. Orfano. Il log è scomparso dopo una riorganizzazione. Marchi il record come non valido e avvisi chi di dovere.

La soglia è una decisione aziendale. Un piccolo acquisto tollera meno conferme di un grande deposito che abilita i prelievi. La scelga per catena e per importo, e la documenti.

Qualunque sia la sua scelta, renda l’accredito idempotente. La chiave univoca per un log è l’hash della transazione più l’indice del log, non il solo hash della transazione, perché una transazione può emettere diversi eventi Transfer (uno swap, ad esempio, ne emette almeno due). Se il suo gestore riceve lo stesso evento due volte, da un retry o da una seconda fonte, non deve fare nulla la seconda volta.

Perché non può fare affidamento sul destinatario che se ne accorge

I trasferimenti ERC-20 sono silenziosi dal lato ricevente. Un indirizzo wallet non esegue codice e un contratto ricevente non viene informato di nulla. La pagina ERC-20 di ethereum.org sottolinea che i token vanno persi quando inviati a contratti che non riconoscono il trasferimento in entrata, poiché lo standard non prevede un callback nativo, e afferma che oltre 83.656.418 dollari di token ERC-20 erano andati persi in questo modo al 20 giugno 2024. Una mitigazione comune è un controllo require nel token che blocca l’invio al contratto del token stesso.

Due punti chiave per gli sviluppatori:

• Se gestisce un contratto che dovrebbe ricevere token, ha bisogno di una propria contabilità. Standard come gli hook in stile ERC-1363 esistono per questo, ma non può presumere che il token del mittente li supporti.
• Se gestisce un backend, il log Transfer è l’unico trigger. Ne manca uno significa che un cliente ha pagato e Lei non lo ha mai saputo.

Esiste un secondo divario: l’evento non trasporta alcun riferimento di pagamento. Nulla lega un trasferimento alla fattura 4471. La maggior parte delle aziende lo risolve assegnando a ogni fattura o utente un indirizzo di deposito univoco. Una proposta più recente, ERC-7699, estenderebbe ERC-20 con un riferimento di trasferimento in modo che un messaggio per il destinatario viaggi con il pagamento, ma è una proposta e i token popolari di oggi non la implementano.

Casi limite che rompono listener ingenui

Token in stile nativo. Su alcune catene una stablecoin è integrata nel protocollo piuttosto che essere un normale contratto. La documentazione di Arc sul rilevamento dei depositi spiega che i movimenti nativi di USDC lì emettono un log Transfer ERC-20 standard da un indirizzo di sistema, quindi gli sviluppatori filtrano su quell’emittente piuttosto che sul singolo contratto token. L’insegnamento è generale: legga la documentazione sui depositi di ogni catena prima di presumere che un filtro sull’indirizzo del contratto sia sufficiente.

Token con fee-on-transfer e rebasing. L’ammontare nell’evento può differire da ciò di cui cambia il saldo del destinatario, o i saldi possono spostarsi senza alcun Transfer. Se accetta token sconosciuti, riconcili con balanceOf invece di fidarsi solo dell’evento.

Trasferimenti a valore zero. Lo standard richiede che emettano l’evento. Gli aggressori lo usano per l’avvelenamento degli indirizzi, inviando trasferimenti a valore zero che inseriscono un indirizzo simile nella cronologia della vittima. Ignori i log a valore zero in qualsiasi flusso di deposito.

Token contraffatti. Chiunque può distribuire un contratto che emette un evento Transfer con qualsiasi nome di token. Filtrisugli indirizzi dei contratti che riconosce, non solo sul topic 0.

Altre catene. La stessa forma di evento appare su reti compatibili EVM come Polygon, BNB Chain (BEP-20) e Arbitrum. I token TRC-20 di TRON seguono la stessa idea con i propri strumenti; veda il nostro confronto tra TRC10 e TRC20 per capire come differiscono.

Costruire o comprare: eseguire il proprio listener

Un listener fatto in casa è un buon progetto e una scelta giusta quando i dati blockchain sono il Suo prodotto principale. Per la maggior parte dei team che accettano pagamenti, è una missione secondaria con una lunga coda di manutenzione. Lei possiede il nodo o il contratto con il provider, il cursore del blocco, la gestione delle riorganizzazioni, i tentativi, la decodifica per ogni token, e lo stesso stack di nuovo per ogni catena in più.

Un modo approssimativo per decidere:

Se si colloca nella colonna di destra, un’API gestita che invia eventi decodificati rimuove l’intero livello di indicizzazione.

Prospettiva: cosa vediamo quando i team costruiscono il rilevamento dei depositi

Costruiamo un’API unificata per i pagamenti in criptovaluta, quindi vediamo ripetutamente lo stesso schema. Un team inizia con un ciclo eth_getLogs per un token su una catena. Funziona. Poi aggiungono una seconda catena, un secondo standard di token, un job di retry e una patch per le riorganizzazioni, e la funzionalità di pagamento è silenziosamente diventata un progetto infrastrutturale.

La nostra opinione è che l’evento Transfer sia la primitiva giusta ma il posto sbagliato in cui spendere il tempo dei Suoi ingegneri. Ciò di cui la Sua applicazione ha bisogno è un’affermazione pulita: questo indirizzo ha ricevuto questo importo di questo token in questa transazione. È per questo che forniamo dati pre-decodificati invece di topic grezzi, e per questo le notifiche arrivano tramite webhook firmati con HMAC, così il Suo server può verificare che un messaggio provenga davvero da noi prima di accreditare qualcuno. Riteniamo anche che non dovrebbe dover gestire i propri nodi o destreggiarsi tra endpoint specifici per catena per arrivarci.

Il consiglio che diamo indipendentemente dagli strumenti: usi un indirizzo di deposito per pagatore o fattura, accrediti in modo idempotente, attenda conferme proporzionate all’importo in gioco e verifichi l’indirizzo del contratto del token. Queste quattro abitudini prevengono la maggior parte degli incidenti di cui sentiamo parlare.

— Bitblade

Ricevere notifiche di trasferimento senza gestire indexer

Chaingateway offre agli sviluppatori un’unica API REST per portafogli, trasferimenti di token e dati di transazione decodificati su Ethereum, Bitcoin, Tron, Solana, Polyggon, BNB Chain e Arbitrum. Per questo argomento, il pezzo rilevante sono i Chaingateway Webhooks: Lei sottoscrive un indirizzo e, quando un trasferimento di token lo tocca, una notifica in tempo reale raggiunge il Suo endpoint con i dati già decodificati, così salta l’hashing e il padding dei topic. La nostra pagina Ethereum API mostra come inviare token ERC-20 via REST senza web3.js, e la guida agli indirizzi ERC-20 copre il formato degli indirizzi e i controlli dei saldi.

I piani sono pubblicati sulla pagina dei prezzi: Plus a 49 € al mese, Pro 99 €, Premium 249 € ed Enterprise 499 € al mese, con fatturazione annuale a 490 €, 990 €, 2.490 € e 4.990 € rispettivamente. L’accesso alla Blockchain API inizia con una prova gratuita.

Un handler minimo, passo dopo passo

Che Lei usi log grezzi o webhook, la logica lato server è la stessa.

1. Verificare la fonte. Per i webhook, controllare la firma HMAC sul corpo della richiesta grezza prima di analizzarlo. Per il proprio lettore di log, ci si fida già del proprio nodo.
2. Controllare il token. Confrontare l’indirizzo del contratto con la propria allowlist.
3. Controllare il destinatario. Cercare l’indirizzo to nel proprio database degli indirizzi di deposito. Ignorare tutto ciò che è sconosciuto.
4. Eliminare il rumore. Scartare i trasferimenti a valore zero e i mint o burn di cui non ci si preoccupa.
5. Deduplicare. Inserire l’hash della transazione e l’indice del log sotto un vincolo univoco. Se l’inserimento fallisce, fermarsi.
6. Convertire l’importo. Dividere il valore grezzo per 10 elevato alla potenza dei decimali del token, usando tipi interi o decimali, mai a virgola mobile.
7. Registrare come in sospeso, poi confermato. Accreditare solo dopo che la soglia di conferma è stata superata.
8. Rispondere rapidamente. Confermare un webhook con uno stato di successo immediatamente ed eseguire il lavoro pesante in una coda.

Fonti

• ERC-20: Token Standard (EIP-20)
• ERC-20 Token Standard | ethereum.org
• Logging data from smart contracts with events | ethereum.org
• Events | ethers.js documentation
• eth_getLogs: Limits, Pagination, and the Logs It Leaves Out | SQD
• ERC-7699: ERC-20 Transfer Reference Extension
• Detect and process deposits | Arc Docs
• Use web3.py to get ERC-20 transfer logs for a specific account

Consigliati

• Ethereum API – Send ERC-20 Tokens via REST, No web3.js
• The ERC20 Token Standard