L'API del nodo

Ogni nodo ZooBC offre un'API HTTP pubblica. È il modo in cui wallet, explorer, gli strumenti da riga di comando e qualsiasi pagina web leggono la catena e inviano transazioni. Per leggere non servono chiavi, account o chiavi API, e l'API risponde a pagine ospitate ovunque. Per scrivere serve solo una transazione firmata dal suo mittente.

Le basi

• Dove: HTTP/1.1 in chiaro sulla porta 8080 per impostazione predefinita, con più di cento route sotto /api/v1/. Il nodo serve anche il wallet web su / e /wallet.
• Nessun TLS sul nodo: i siti pubblici raggiungono l'API in HTTPS tramite un gateway, che mette anche davanti un servizio di archivio per la cronologia profonda.
• Aperta a ogni pagina: ogni risposta contiene Access-Control-Allow-Origin: *, e il controllo OPTIONS del browser riceve subito risposta, quindi una pagina su qualsiasi dominio può chiamare l'API (costruire un'app come singola pagina HTML).
• Soprattutto letture: tutte le route tranne otto sono letture che non richiedono autenticazione. Inviare una transazione non richiede una chiave API, perché la transazione porta con sé la propria firma.
• Limiti per indirizzo del client: 300 richieste di scrittura al minuto per impostazione predefinita (oltre questo limite il nodo risponde 429 con un'intestazione Retry-After); le letture sono illimitate a meno che l'operatore non fissi un limite.

Che cosa puoi leggere

Tutti i percorsi della seconda colonna si trovano sotto /api/v1/. /movements elenca ogni variazione del saldo di un account con la sua causa, compresi i canoni pagati e le ricompense vinte. /pubkey restituisce la chiave pubblica di un account nativo a partire dal solo indirizzo. Dalla versione 0.5.8, le route della catena riportano la finalized_height e ogni transazione un flag finalized, impostato quando un blocco spine co-firmato copre il suo blocco (finalità e rollback).

Chiunque può consultare in questo modo qualsiasi indirizzo. La catena registra chiavi, non nomi, quindi la privacy su ZooBC deriva da come si usano gli indirizzi, non da saldi nascosti (account e indirizzi).

Inviare una transazione

Un client costruisce i byte della transazione, firma il digest legato alla catena con la chiave del mittente, usando il genesis_hash letto da /api/v1/node/info (firmare una transazione), e invia il risultato a POST /api/v1/transactions. Non serve alcun SDK: bastano Ed25519, SHA3-256 e l'hash genesi.

Il nodo risponde HTTP 202, che significa «accettata», non «completata», e restituisce l'hash della transazione. Il client interroga poi /api/v1/transactions/<hash>/status, che passa per:

1. staging, poi mempool, mentre la transazione attende un blocco;
2. confirmed, con l'altezza del blocco, quando un blocco la include;
3. oppure rejected, con il motivo e la fase, se viene rifiutata; not_found (404) se il nodo non la conosce.

Con un blocco ogni 15 secondi, interrogare ogni paio di secondi è più che sufficiente. Prima di consegnare merce a fronte di un pagamento, attendi la conferma e, preferibilmente, il flag finalized.

Se una risposta va persa, reinvia gli stessi identici byte firmati. L'hash viene calcolato da quei byte, quindi un nodo che detiene già la transazione, anche se è già stata inclusa in un blocco, risponde di nuovo 202, segnandola come duplicato, e la transazione viene eseguita una sola volta. Firmare di nuovo con un nuovo timestamp crea una transazione diversa, ed è così che nascono i pagamenti doppi.

Richieste firmate e annullamento

Alcune richieste portano una propria firma: una firma Ed25519 su METHOD:PATH:TIMESTAMP:BODY, valida per 300 secondi. Un client che fallisce 20 autenticazioni firmate in 5 minuti viene bloccato per 300 secondi. Una transazione in sospeso può essere ritirata dal pool di un nodo con una richiesta DELETE firmata (messaggi firmati e cifrati).

Altre interfacce di un nodo

• Porta 8001: la rete peer-to-peer tra i nodi.
• Porta 8545: un adattatore JSON-RPC in stile Ethereum, per impostazione predefinita solo sulla macchina del nodo, usato da MetaMask.
• Porta 8332: un adattatore RPC in stile Bitcoin Core, disattivato per impostazione predefinita, che richiede credenziali proprie dell'operatore.

Vedi anche

• Costruire un'app come singola pagina HTML
• Strumenti da riga di comando
• Gateway
• Firmare una transazione
• L'explorer e i nodi di archivio