← Blog
10 min di lettura
|
Pubblicato
|
Aggiornato

API blockchain nelle applicazioni Web3

Che cosa fa un'API blockchain in un'app Web3: legge i dati della catena, invia transazioni e riceve notifiche, e perché i contratti hanno bisogno di oracoli.

Capitoli
C
Chaingateway Team
Esperti di blockchain

Verificato da Maurice Sobiera

Un’API blockchain è un’interfaccia web che permette a un’applicazione di leggere dati blockchain e inviare transazioni senza eseguire un proprio nodo. In un’applicazione Web3 si colloca tra l’interfaccia utente e la catena. Gli smart contract non possono chiamare direttamente API web, quindi i dati esterni alla catena li raggiungono tramite oracoli.

Questo articolo separa le due direzioni in cui API e blockchain si collegano e spiega dove si usa ciascuna.

Che cosa fa un’API blockchain in un’applicazione Web3?

Un’API blockchain offre tre funzioni: legge i dati della catena, invia transazioni e segnala eventi. Senza di essa, il backend dovrebbe eseguire un nodo, mantenerlo sincronizzato e analizzare i blocchi da solo.

FunzioneEsempioCome funziona
LetturaSaldo di un indirizzo, transazioni in un bloccoUna richiesta a un nodo o a un fornitore di API
ScritturaInvio di un trasferimento di tokenLa transazione viene firmata con una chiave privata, poi trasmessa alla rete
NotificaSegnalazione al backend dell’arrivo di un depositoUn webhook, oppure il polling del nodo

Chaingateway è una di queste API. Gli endpoint per wallet, trasferimenti e webhook sono elencati nel file OpenAPI. I webhook esistono per Bitcoin, Ethereum, BNB Smart Chain, Polygon, Arbitrum e Tron. Solana non ha webhook, quindi un’applicazione Solana deve fare polling.

Perché uno smart contract non può chiamare un’API web?

Uno smart contract non può chiamare un’API web perché ogni nodo deve eseguirlo e ottenere lo stesso risultato. La documentazione di Ethereum afferma che acquisire dati esterni renderebbe impossibile il determinismo: un’API dei prezzi potrebbe restituire valori diversi a nodi diversi, che non concorderebbero più sullo stato della catena (ethereum.org: oracoli).

Questa è una proprietà del modello. Non dipende dal linguaggio della catena né da una particolare API. La conseguenza è che i dati devono essere inseriti nella catena tramite una transazione prima che un contratto possa usarli.

Come arrivano i dati esterni a uno smart contract?

I dati esterni raggiungono un contratto tramite un oracolo. Un oracolo è un’applicazione che reperisce, verifica e trasmette informazioni esterne agli smart contract. Un protocollo di prestito che necessita del prezzo di un asset, o un contratto che dipende da dati meteorologici o sui voli, ne ha bisogno.

La documentazione di Ethereum descrive due modelli comuni:

  • Publish-subscribe: l’oracolo pubblica un flusso di dati e i contratti lo leggono. Questo modello si adatta a dati che cambiano spesso, come i prezzi dei token.
  • Request-response: un contratto richiede dati specifici e l’oracolo risponde con una callback. Questo modello si adatta a grandi insiemi di dati di cui il contratto usa solo una piccola parte. Chi richiede paga la ricerca e il gas della callback.

Un oracolo gestito da una sola parte è un singolo punto di guasto. Se quella parte si guasta, viene violata o mente, il contratto agisce su dati sbagliati. La stessa documentazione descrive i servizi di oracolo decentralizzati, in cui più partecipanti concordano i dati prima che raggiungano il contratto. La decentralizzazione è una scala graduale, e resta da decidere quanto si ripone fiducia nell’oracolo scelto.

Quale API serve per quale funzione?

La risposta dipende dalla direzione del flusso dei dati.

DirezioneProblemaStrumento
Dalla catena all’applicazioneLeggere saldi, inviare trasferimenti, ricevere notifiche di depositoAPI blockchain o un nodo proprio
Dal mondo esterno al contrattoFornire a un contratto un prezzo, un punteggio o un valore meteorologicoOracolo
Dal contratto al mondo esternoAttivare un’azione dopo un evento on-chainLog degli eventi letti da un servizio, oppure un oracolo

Un sistema di pagamento usa solo la prima riga. Un utente paga a un indirizzo, un webhook raggiunge il backend, e il backend accredita il conto nel proprio database. Non è coinvolto alcun oracolo. Per capire come ripartire il lavoro tra catena e database, consulti blockchain vs database.

Come un’applicazione legge gli eventi da un contratto?

Un’applicazione legge gli eventi del contratto tramite i log. Quando un contratto emette un evento, il nodo lo memorizza nella ricevuta della transazione, e il metodo eth_getLogs dell’API JSON-RPC di Ethereum, che segue la specifica JSON-RPC 2.0, restituisce i log che corrispondono a un filtro. È il modo abituale per trovare i trasferimenti di token.

Un filtro per gli eventi Transfer di un token ERC-20 in un intervallo di blocchi ha questo aspetto:

{
"jsonrpc": "2.0",
"method": "eth_getLogs",
"params": [{
"fromBlock": "0x10d4f00",
"toBlock": "0x10d4f0a",
"address": "0xTokenContract",
"topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
}],
"id": 1
}

Il primo topic è l’hash della firma dell’evento Transfer(address,address,uint256). Gli altri topic contengono gli argomenti indicizzati, qui il mittente e il destinatario. L’importo si trova nel campo data di ciascun log, come numero esadecimale.

Gli intervalli di blocchi sono importanti. Molti fornitori limitano l’intervallo o il numero di risultati di una singola chiamata eth_getLogs, quindi uno scanner deve scorrere i blocchi a pagine. Un’API blockchain che decodifica questi log o li invia come webhook elimina questo codice. Non cambia però il significato dei log: un log in un blocco che viene poi riorganizzato scompare insieme a quel blocco.

Quali sono i limiti delle API blockchain?

Un’API non cambia il funzionamento della catena. Una transazione è definitiva solo quando la catena lo dichiara, e un’API può riportarla come in attesa o confermata prima di quel momento. Un deposito va considerato saldato solo dopo che sono state superate le regole di finalità della catena.

Le consegne di webhook fallite non vengono ritentate automaticamente. Chaingateway le elenca nell’endpoint delle notifiche fallite di ogni catena, per esempio GET /api/v2/tron/webhooks/notifications/failed, e le si invia di nuovo con l’endpoint di retry. Un backend che elabora i webhook dovrebbe inoltre essere idempotente, così che una notifica inviata di nuovo non accrediti un conto due volte.

Un’API ospitata aggiunge anche una dipendenza dal fornitore. Se serve un accesso diretto al protocollo, si può comunque eseguire un nodo e comunicare con esso tramite JSON-RPC.

Come scriviamo questi articoli

Pronto a costruirlo da solo? Ottieni la tua API key — prova di 7 giorni, senza carta — oppure consulta Blockchain API per il riferimento completo degli endpoint.

C
Chaingateway Team
Esperti di blockchain

Il team di Chaingateway si impegna a semplificare l'integrazione blockchain per sviluppatori di tutto il mondo.