Sviluppatori

Riferimento completo

Ogni route, i suoi parametri e la struttura della risposta:

Apri il riferimento API →  ·  vista alternativa

Entrambi gli indirizzi servono lo stesso documento.

Download

I file che un operatore ha pubblicato su questo gateway sono serviti su /dl/<name>. I nomi sono un singolo segmento di [A-Za-z0-9._-], e tutto viene inviato come allegato e mai visualizzato: questa origine serve anche il wallet, e una pagina visualizzata qui erediterebbe l'origine del wallet.

I pacchetti di rilascio si trovano sotto /releases/<version>/<arch>/, con /releases/latest che indica quello attuale. L'installer del nodo si trova su /install.

Questo gateway è in buona salute? verifica in corso…

/gateway/status riporta ciò che questo gateway sa di sé e dei nodi che può raggiungere: modalità, dominio, quanti nodi sono nella sua allowlist, quali rispondono.

/gateway/system-stats riporta i dati della macchina: CPU, memoria, disco, uptime. È da qui che provengono i valori nella pagina del gateway.

curl https://this-gateway/gateway/status
curl https://this-gateway/gateway/system-stats

Nessuno dei due richiede una chiave. Nessuno dei due espone dati della catena: per quelli usa /api/v1/… qui sopra.

Raggiungere un nodo specifico

Le route della catena rispondono da qualsiasi nodo di archivio scelto da questo gateway. Per interrogare un nodo specifico, inserisci il suo IP nel nome host, sostituendo i punti con trattini; un -p<port> facoltativo sceglie la porta dell'API:

curl https://ip-192-168-1-100.this-gateway/api/v1/node/info
curl https://ip-192-168-1-100-p8080.this-gateway/api/v1/node/info

Rispondono solo i nodi presenti nell'allowlist di questo gateway. Qualsiasi altra richiesta viene rifiutata anziché inoltrata, quindi il nome host non può essere usato per raggiungere host arbitrari tramite il gateway.

Relay

Voce, video e condivisione dello schermo viaggiano peer-to-peer; quando un firewall blocca un collegamento diretto, un relay trasporta il traffico in cambio di credito. /relay/info riporta il suo indirizzo, la sua tariffa e l'hash di genesi della catena su cui regola i pagamenti: un wallet lo confronta con quello del proprio nodo prima di pagare, perché un relay su un'altra catena non può accreditare ciò che riceve.

curl https://this-gateway/relay/info

Pannello di amministrazione

I controlli del gateway si trovano su zoobc.network/admin. Il pannello è protetto dalla chiave admin_api_key definita in /etc/zoobc/gateway.json, che l'installer genera per ogni macchina: non esiste una chiave predefinita.

L'allowlist

Un gateway inoltra le richieste solo ai nodi che gli sono stati indicati. È questo elenco a impedire che la forma di nome host ip-… trasformi il gateway in un proxy aperto.

Tutte e tre le scritture richiedono la chiave di amministrazione. In modalità pubblica il gateway scopre i nodi anche dal registro della catena stessa; in modalità privata usa solo static_nodes.

Strumenti per i rilasci

Il calcolatore di hash dei file calcola uno SHA-256 nel browser per qualsiasi cosa tu voglia controllare a mano, e /verify confronta un pacchetto scaricato con gli hash pubblicati dalla catena.

I due documenti

Tutto ciò di cui un team di hardware wallet ha bisogno è specificato qui, e per intero nei due PDF qui sotto. Entrambi sono stati verificati sul nodo ZooBC v0.4.0 (zoobc-main al commit 7ad161a4) e su vettori di transazione accettati da un nodo v0.4.0 attivo.

La versione 2.1 sostituisce la bozza 1 in un aspetto sostanziale: le firme delle transazioni sono ora vincolate alla catena. Due modifiche rompono la compatibilità per chi ha sviluppato sulla bozza 1: il digest di firma e il corpo di ApprovalEscrow. Nulla implementa la vecchia costruzione v0.3.2, quindi sviluppa solo sul documento attuale.

Riepilogo in una pagina

Leggi prima questi quattro

Quattro punti che influenzano un'implementazione più di tutto il resto.

Derivazione delle chiavi e indirizzi

Riferimento: zoobc-signer/extension/lib/zoobc-crypto.js, identico byte per byte al wallet di riferimento; equivalenti lato nodo in src/crypto/slip10.cpp.

seed = PBKDF2-HMAC-SHA512(NFKD(mnemonic), "mnemonic" + passphrase, 2048, 64)
I    = HMAC-SHA512("ed25519 seed", seed);  k = I[0..32], c = I[32..64]

for index in [44, 883, account]:                       # all hardened
    data = 0x00 || k || u32be(index + 0x80000000)
    I    = HMAC-SHA512(c, data);  k = I[0..32], c = I[32..64]

pubkey = Ed25519.publicKeyFromSeed(k)                  # k is the 32-byte seed

L'account 0 è m/44'/883'/0', l'account 1 è m/44'/883'/1' e così via. La derivazione delle chiavi non è influenzata dal vincolo alla catena: un unico insieme di chiavi serve ogni catena ZooBC, cambia solo la firma.

L'indirizzo visualizzato è costruito a partire dalla chiave pubblica, non dall'account da 36 byte:

buf[35] = pubkey(32) || "ZBC"
h       = SHA3-256(buf);  buf[32..35] = h[0..3]        # 3-byte checksum
s       = base32(buf)                                   # RFC 4648 A-Z2-7, no padding, 56 chars
address = "ZBC_" + s[0..8] + "_" + s[8..16] + ...       # 7 groups, canonical length 66

La decodifica accetta trattini bassi, trattini, spazi o nessun separatore, in maiuscolo o minuscolo, e il checksum deve essere ricalcolato e confrontato. Il checksum SHA3 da 3 byte qui sopra è la definizione usata dal codice e dalla catena, quindi implementa a partire da quella e dall'implementazione di riferimento nella specifica, che riproduce gli indirizzi di esempio.

Formato di trasmissione della transazione non firmata

Fonte di verità: src/util/transaction_util.cpp:144-270. Il formato di trasmissione non è cambiato nella v0.4.0. Nessuna lunghezza o offset qui sotto è influenzato dal vincolo alla catena.

Il byte finale multi_party del blocco escrow è obbligatorio. Ometterlo, o scrivere il marcatore di assenza di escrow con un valore diverso, produce sul nodo soltanto «Invalid transaction signature», senza ulteriori diagnostiche.

Esempio svolto, convalidato sulla catena

SendZBC di 1 ZBC a se stessi, commissione 0.05 ZBC, timestamp 1700000000, senza escrow, senza messaggio. È il vettore 0 dei sette presenti nella specifica.

01000000                 type = 1 (SendZBC)
01                       version
00f1536500000000         timestamp 1700000000
00000000 5e8eb28d...2152 sender    (type 0 + pubkey)
00000000 5e8eb28d...2152 recipient (type 0 + pubkey)
404b4c0000000000         fee 5 000 000
08000000                 body length 8
00e1f50500000000         body: amount 100 000 000
02000000                 no-escrow marker
00000000                 message length 0

Sono 113 byte. La preimmagine di firma ne antepone altri 38:

5a42432d5458              tag "ZBC-TX"          6 bytes
090ab3c7...a61878         genesis hash         32 bytes
0100000001...00000000     the 113 bytes above 113 bytes
                                              ---------
                                              151 bytes

digest = SHA3-256(preimage) = f37e5340...4644fc, firma 9a3b044d...03bb07, tx_hash = f00a6692...ce78b0. Un nodo v0.4.0 attivo ha restituito HTTP 202 ed esattamente quell'hash.

Procedura di firma, lato dispositivo

input : account_index, genesis_hash(32), unsigned_bytes

1. k      = SLIP10(m/44'/883'/account_index')
2. pub    = Ed25519.pub(k);  self = 00000000 || pub
3. parse unsigned_bytes; every length must land exactly at the end
4. require version == 1 and sender == self
5. decode body per type; render the approval screen; wait for the user
6. digest = SHA3-256("ZBC-TX" || genesis_hash || unsigned_bytes)
7. sig    = Ed25519.sign(k, digest)          # the digest IS the message
8. return sig(64), and tx_hash = SHA3-256(unsigned_bytes || sig) for the host to cross-check

Usa SHA3 in streaming, così il passaggio 6 non richiede l'intera transazione in RAM. Fornisci i 6 byte del tag, poi i 32 byte di genesi, poi la transazione.

Il tag è in assoluto l'errore di implementazione più probabile dell'intera specifica. "ZBC-TX" è composto da sei byte ASCII, 5a 42 43 2d 54 58, senza terminatore NUL e senza prefisso di lunghezza. Un firmware che termina la stringa, o che scrive sette byte, produce una firma dall'aspetto valido che fallisce sulla catena con un errore generico e senza diagnostica. Testalo sul vettore 0 prima di ogni altra cosa.

Cosa fa e cosa non fa il vincolo alla catena

L'host fornisce i 32 byte di genesi; il dispositivo non li cerca. La firma è quindi indipendente dalla catena, e un unico percorso di codice serve TestNet, devnet, MainNet e qualsiasi catena ZooBC privata o parallela.

Una tabella nel firmware con gli hash di genesi noti serve quindi ancora, ma per un solo scopo: mostrare sullo schermo un nome di rete affidabile, ripiegando su «UNKNOWN CHAIN» più i primi 8 caratteri esadecimali quando l'hash non è nella tabella.

Non rifiutare per impostazione predefinita le catene non riconosciute. L'hash della devnet cambia a ogni riavvio, e le catene private o parallele sono normali su ZooBC, quindi un rifiuto rigido rende il dispositivo inutilizzabile per l'integrazione e per le installazioni legittime. Se un produttore vuole quel blocco, ne faccia un'impostazione esplicita dell'utente, disattivata per impostazione predefinita.

Tipi di transazione: cosa dovrebbe supportare un firmware standard

Id del tipo = group + 256 × subtype. Esistono cinquantasei tipi. Questi tre coprono il pagamento in ZBC, il pagamento con qualsiasi token e il completamento di un escrow, e i loro corpi sono piccoli e fissi.

token_id è un valore con segno a 64 bit derivato da un hash, quindi può essere negativo. Le monete della Genesis hanno id da 1 a 14; ZBC stesso ha id 0 e non compare mai in TransferToken. Ogni token ha il proprio decimals (da 0 a 8), che il dispositivo non può verificare.

ApprovalEscrow è cambiato nella v0.4.0. Il corpo era approval più un id da 8 byte (12 byte); ora è approval più l'hash da 32 byte della transazione in escrow (36 byte), e il parser rifiuta qualsiasi altra lunghezza. Il motivo riguarda direttamente gli hardware wallet: un firmatario che vedeva solo un id da 8 byte non poteva controllare cosa stava sbloccando, e un id da 8 byte è individuabile con una ricerca su 2^64 per un falso escrow mostrato al dispositivo. Con l'hash completo il dispositivo può verificare ciò che approva.

Cosa verifica il dispositivo

Cosa approva l'utente sullo schermo

Schermata per schermata, in quest'ordine, adattato dal firmatario di riferimento convalidato sulla catena.

Non è necessario mostrare i timestamp. Non hanno significato per l'utente e il nodo impone la finestra.

Protocollo tra host e dispositivo

Il trasporto è il livello USB/HID del produttore, con la sua suddivisione in blocchi già esistente. Ciò che conta è il contenuto.

genesis_hash è essenziale, non un suggerimento di visualizzazione. Nella bozza 1 il parametro di rete poteva essere un enum, perché sceglieva solo un'etichetta. Ora è dentro il digest, quindi deve contenere i 32 byte effettivi, e un valore errato produce una firma che nessuna catena accetterà.

La regola della firma grezza. Un comando di firma grezza non deve mai firmare un input di esattamente 32 byte, e dovrebbe firmare solo input che può mostrare come testo. Un input grezzo di 32 byte potrebbe essere il digest SHA3 di una transazione che l'utente non ha mai visto, trasformando il comando dei messaggi in una firma di transazioni alla cieca. Rifiutare la lunghezza 32 chiude quella falla senza modifiche alla catena.

La sequenza completa

Website (page)         Companion / host           device                    Gateway / node
   |-- connect ---------->|                            |                          |
   |                      |-- GET_PUBLIC_KEY(0) ----->|  (shows ZBC_... address) |
   |<-- address ----------|<-- pubkey, address -------|                          |
   |-- GET /api/v1/node/info  (genesis_hash, signing_version, height) ---------->|
   |-- GET /api/v1/accounts/<addr>  (balances) --------------------------------->|
   |-- GET /api/v1/accounts/<addr>/tokens, /api/v1/tokens/<id> (decimals) ------>|
   |   user fills the form                             |                          |
   |-- GET /api/v1/blockchain/estimate-fee?type=1&body_length=8 ---------------->|
   |<-- {minimum_fee, timestamp} ------------------------------------------------|
   |-- fields {type, recipient, body, fee, message} -->|                          |
   |                      |  serialize the 11 fields   |                          |
   |                      |-- SIGN_TX(0, genesis, -->|  parse, verify, display,  |
   |                      |            bytes)         |  user approves            |
   |                      |<-- signature, tx_hash ---|                          |
   |<-- signature --------|                            |                          |
   |-- POST /api/v1/transactions {JSON} ---------------------------------------->|
   |<-- 202 {status:"success", transaction_hash} --------------------------------|
   |-- GET /api/v1/transactions/<hash>/status  (staging, mempool, confirmed) --->|

L'host confronta il transaction_hash del nodo con il tx_hash del dispositivo. Devono essere identici, altrimenti l'host ha alterato i byte dopo la firma.

Leggi genesis_hash e signing_version dall'endpoint a cui trasmetterai, perché è quella la catena che giudica la firma.

Identità della catena

L'unico identificatore di rete di ZooBC è l'hash del blocco genesi. I nodi lo confrontano prima di stabilire il peering; non esiste un byte di network-id. GET /api/v1/node/info lo restituisce insieme a due campi nuovi nella v0.4.0:

"genesis_hash": "090ab3c7...", "signing_version": 2, "signing_tag": "ZBC-TX"

signing_version assente significa che il nodo è precedente alla v0.4.0 e applica il vecchio digest non vincolato. Un host che supporta solo le catene attuali può interpretarne l'assenza come «non firmare qui». Un nodo stampa l'esadecimale in minuscolo e l'API di archivio in maiuscolo, quindi decodifica senza distinguere maiuscole e minuscole e rimuovi un eventuale 0x iniziale. I byte sono gli stessi in entrambi i casi.

Da dove leggerlo. Un gateway risponde a /api/v1/node/info dal servizio di archivio anziché da un nodo. L'archivio inoltra i due campi di firma dal nodo di cui è copia, emettendoli esattamente quando il nodo li riporta, a partire dalla build 7ad161a4. Leggi signing_version da un endpoint di nodo, o da un gateway con quella build o successiva, e interpretane l'assenza come «chiedi a un nodo» anziché come una risposta.

Trasmissione

POST /api/v1/transactions. Invariato nella v0.4.0, nessun nuovo campo. transaction_body_bytes è solo il corpo: il nodo ricostruisce la busta dai campi con nome, antepone il proprio hash di genesi e il tag, e ricalcola il digest, quindi ogni campo deve essere uguale a quanto è stato firmato.

{
  "version": 1,
  "timestamp": 1700000000,
  "transaction_type": 1,
  "fee": 5000000,
  "sender_account_address":    "00000000 5e8eb28d ... 2152",
  "recipient_account_address": "00000000 5e8eb28d ... 2152",
  "transaction_body_bytes": "00e1f50500000000",
  "signature": "9a3b044d ... 03bb07",
  "message_hex": "...optional...",
  "escrow": { "approver_address": "...", "commission": 0, "timeout": 1700003600 }
}

Il successo è HTTP 202 con {"status":"success","duplicate":false,"transaction_hash":"..."}. duplicate:true significa che il nodo la possiede già, quindi non inviarla di nuovo. Considera un successo anche 200. Il fallimento è 400 con un corpo di errore, o 503 sotto carico.

Un test di integrazione utile: il pool di staging controlla prima la firma, quindi una transazione che arriva a un errore successivo come «Sender account does not exist» ha già superato la verifica della firma. Puoi convalidare il tuo percorso di firma con una chiave senza fondi.

Quando una firma viene rifiutata

Oggi una mancata corrispondenza di catena non è distinguibile da qualsiasi altro errore di firma. Un digest legacy e un digest della catena sbagliata restituiscono entrambi lo stesso identico corpo:

{"success":false,"error":"Transaction validation failed: ValidationError: Invalid transaction signature","code":400}

Quindi verifica le cause in quest'ordine, partendo dalla più probabile:

Endpoint su cui sviluppare

Instrada le letture prima al nodo di archivio, poi al gateway, poi al nodo. Trasmetti a un gateway o a un nodo, mai a un endpoint di archivio.

Leggi l'hash genesis a runtime, non scriverlo nel codice. Quello della devnet cambia a ogni rilancio. Una tabella di hash nel firmware serve solo a mostrare un nome sullo schermo, quindi una voce obsoleta degrada a «UNKNOWN CHAIN» invece di bloccare la firma. Quando l'hash della devnet cambia, ogni firma fatta in precedenza perde validità: è la funzionalità che fa il suo lavoro.