Cos'è un gateway Label 309?

Un gateway Label 309 è il servizio che pubblica i record di Proof of Existence su Cardano. Si occupa del lavoro operativo — pricing, upload, invio della transazione, tracciamento delle conferme, indicizzazione dei record, saldi, chiavi API e webhook — così che un client non debba farlo. Il client prepara la prova e tiene le chiavi private in locale; il gateway porta il record sulla rete.

Label 309 è lo standard aperto e neutrale rispetto al fornitore per ancorare un hash di contenuto su Cardano sotto la label dei metadati 309. Il gateway è la parte che fa la pubblicazione. Non è un backend privato utilizzabile da una sola azienda — è uno strato di servizio definito che qualunque prodotto può eseguire o con cui può integrarsi, e l'implementazione di riferimento è open source. CardanoWall fa girare il proprio prodotto commerciale esattamente su queste superfici, senza alcun percorso separato riservato a sé.

Perché la pubblicazione ha bisogno di un gateway?

La verifica è leggera. La pubblicazione è operativa.

Per verificare una prova, di solito parti da un riferimento di transazione Cardano, recuperi il record da un explorer pubblico e ricalcoli da solo gli hash o le firme. Non serve alcun servizio speciale — proprio questa indipendenza è il senso dello standard. (Vedi come verificare un record Label 309 per il percorso completo.)

La pubblicazione ha molte più parti in movimento:

costruire un record Label 309 valido;
stimare il costo della transazione Cardano;
caricare testo cifrato o contenuto quando ci sono file di mezzo;
pagare i costi di storage;
inviare la transazione Cardano;
attendere la conferma;
gestire errori e rimborsi;
indicizzare il risultato;
mostrare lo stato all'utente;
mantenere accurati i saldi dell'account.

Un gateway raccoglie tutti questi aspetti dietro un'API. Senza, ogni prodotto che volesse pubblicare dovrebbe ricostruire la stessa pipeline di catena e storage. Con uno, un team di prodotto può concentrarsi sulla propria esperienza utente e sul proprio flusso di lavoro, mentre il gateway si occupa di catena, storage e contabilità.

Cosa fa davvero il gateway?

Il gateway possiede la pipeline di pubblicazione e lo stato di denaro, catena e storage che la sostiene. In termini pratici può:

fare il preventivo di una prova prima che tu pubblichi (il prezzo regge per una breve finestra, circa 15 minuti);
accettare upload cifrati e upload di contenuto pubblico, restituendo URI indirizzati per contenuto;
accettare un record di prova già preparato;
costruire e inviare una transazione Cardano con commissioni esatte;
tracciare la conferma, gestione dei reorg inclusa;
rimborsare automaticamente l'addebito quando una pubblicazione fallisce in modo definitivo;
indicizzare ogni record Label 309 presente sulla rete in un feed condiviso e pubblico;
gestire i saldi prepagati degli account e applicare il pricing;
emettere chiavi API e token di account;
inviare webhook per gli eventi del ciclo di vita.

Questo lo rende il motore di pubblicazione dietro la web app di CardanoWall, l'app desktop, lo strumento da riga di comando, le integrazioni basate su SDK, i flussi CI/CD e, allo stesso modo, i prodotti di terze parti.

Cosa non fa di proposito il gateway?

Il gateway non è la radice della fiducia.

Non ha mai bisogno del tuo Identity Seed. Non ha mai bisogno delle chiavi private dei destinatari. Non decifra i file sigillati. E non è mai l'unico posto in cui una prova può essere controllata. Queste proprietà sono volute: tenerle fuori dal gateway è ciò che permette a una prova di reggersi da sola.

Una prova Label 309 valida poggia su dati pubblici, non sulla parola del gateway:

la transazione Cardano;
i metadati Label 309;
il contenuto originale o il testo cifrato, quando serve;
le firme dei record e le chiavi pubbliche;
le prove Merkle, per i record raggruppati;
le chiavi del destinatario, per il contenuto sigillato.

Se il gateway segnala che una prova esiste, un verificatore può comunque confermarla sulla catena — senza alcun coinvolgimento del gateway. Per ciò che un operatore di gateway può e non può osservare, vedi cosa può vedere CardanoWall.

Cos'è il data plane?

Il data plane è l'API rivolta all'utente. È ciò che un client chiama quando agisce per conto di un utente o di un account — una web app, l'app desktop, la CLI, un SDK o uno script di automazione che chiede di fare un preventivo, caricare, pubblicare, leggere un saldo o elencare record. Si trova sotto il percorso /api/v1/*.

Il flusso concettuale è breve:

Chiedi un preventivo.
Carica contenuto o testo cifrato, quando ci sono file di mezzo.
Pubblica la prova.
Traccia lo stato.
Leggi record e saldi.

È lo stesso percorso che usa il prodotto di riferimento. Se un flusso funziona per CardanoWall, è disponibile a chiunque attraverso il data plane pubblico.

Cos'è il control plane?

Il control plane è destinato agli operatori e ai backend di prodotto, e si trova sotto il percorso /control/v1/*.

Se un'azienda costruisce il proprio prodotto su un gateway, il suo backend deve creare account, applicare crediti di fatturazione, emettere token di account a vita breve, impostare margini per singolo account, creare chiavi API ed eseguire attività a livello di operatore. Questo è lavoro del control plane, e deve avvenire da un backend fidato — mai da codice del browser o da un client mobile.

Il control plane è ciò che permette a un gateway di supportare più di un prodotto. Un altro team può costruirci sopra il proprio strato vendor: i suoi utenti, la sua fatturazione, la sua UI, il suo supporto e la sua semantica di prodotto, mentre il gateway gestisce sotto la pipeline di pubblicazione di base. Il confine tra i due è l'API HTTP e il firehose dei webhook — non il database del gateway, che resta privato al motore.

Cosa significa «nessuna porta privata»?

Significa che il prodotto di riferimento pubblica attraverso le stesse superfici disponibili a tutti gli altri. Non c'è un percorso segreto, più veloce o privilegiato riservato a CardanoWall.

Questo conta per la credibilità. Se un progetto sostenesse che il suo standard è aperto ma pubblicasse attraverso macchinari interni nascosti, l'ecosistema resterebbe dipendente da quell'unico fornitore. Il modello a gateway elimina questa dipendenza: CardanoWall può essere il primo prodotto curato, mentre altri team costruiscono i propri strumenti, servizi, dashboard, client desktop e flussi di settore sull'identico percorso standard. Se ci stai costruendo sopra, vedi costruire su un gateway Label 309.

Un'azienda può far girare il proprio gateway?

Sì. Il core del gateway è open source — un singolo binario Rust più PostgreSQL — e un'azienda può farlo girare da sé: finanziare i propri wallet Cardano e Arweave, creare i propri account e le proprie chiavi API e pubblicare record Label 309 senza dipendere da CardanoWall come operatore in hosting.

Il self-hosting può avere senso per:

pubblicazione ad alto volume;
policy rigide sui fornitori;
ambienti regolamentati o air-gapped;
flussi di compliance interni;
sistemi di prove legali;
infrastrutture di provenienza per l'AI;
pipeline di prove in CI/CD;
team che già gestiscono la propria infrastruttura cloud e di catena.

Il self-hosting non cambia lo standard dei record — un gateway self-hosted produce gli stessi record, verificabili da chiunque. Cambia solo chi gestisce il servizio di pubblicazione. La configurazione pratica è trattata in far girare il proprio gateway.

Quando dovrei usare il gateway CardanoWall in hosting?

Usa il gateway in hosting quando la comodità conta più del gestire l'infrastruttura da te.

Il servizio in hosting gestisce per te il finanziamento, il pricing, l'invio, le conferme, lo storage e la gestione degli account. È adatto a singoli utenti, piccoli team, prime integrazioni e aziende che vogliono partire in fretta. Ottieni comunque record standard, puoi comunque verificarli a partire da dati pubblici e puoi comunque passare ai tuoi strumenti o al tuo gateway in seguito. In hosting non significa vincolato.

Quando dovrei invece fare self-hosting?

Fai self-hosting quando il controllo operativo conta più della comodità. Le buone ragioni includono:

pubblichi ad alto volume;
vuoi le tue policy di commissioni e di finanziamento;
la tua organizzazione non può affidarsi a un servizio di terze parti in hosting;
i tuoi record appartengono a un flusso interno e regolamentato;
il tuo prodotto ha bisogno del proprio modello di fatturazione;
vuoi offrire la pubblicazione Label 309 con il tuo brand;
vuoi il controllo diretto su chiavi API, account e webhook.

Il self-hosting è più impegnativo. Fai girare il gateway, finanzi i wallet, monitori i provider, gestisci i segreti, operi il database, ti occupi degli aggiornamenti e mantieni il servizio in salute. Il guadagno è l'indipendenza.

Come entra in gioco il pricing?

Pubblicare costa denaro perché il gateway sostiene costi reali. Ogni prova ancora una transazione Cardano, che comporta una commissione di rete. Quando ci sono file di mezzo, il gateway paga anche lo storage Arweave. A questo si aggiungono la gestione del tasso di cambio, il finanziamento, l'infrastruttura, il monitoraggio, il supporto, i rimborsi e il rischio.

Per questo un gateway in hosting addebita su base cost-pass-through più un margine di servizio. I tassi di cambio sono live — il gateway prezza ogni preventivo a partire dai tassi di mercato correnti anziché da una costante hardcoded — e il tasso dietro un preventivo può muoversi, ed è per questo che un preventivo è valido solo per una breve finestra. Il prezzo visualizzato può variare per account, partner o policy dell'operatore. Per il ragionamento dietro il fatto stesso di addebitare, vedi perché la pubblicazione ha un prezzo.

Se vuoi evitare il margine di un intermediario in hosting, la risposta non è la pubblicazione gratuita — i costi di catena e storage sono reali in ogni caso. La risposta è far girare un gateway, finanziarlo direttamente e prenderti in carico tu stesso il lavoro operativo.

Come si relaziona l'app desktop con il gateway?

CardanoWall Desktop — un'app desktop open source costruita sull'SDK Rust — è un client del gateway, non un operatore di catena.

Tiene le identità in locale, sincronizza e prova a decifrare a tentativi i record sigillati sulla tua stessa macchina, mette in cache i dati per l'uso offline, prepara e firma i record, cifra i file e verifica le prove — tutto in locale. Una cosa va detta chiaramente: non è un wallet. Non custodisce ADA e non costruisce né invia transazioni Cardano da sé. Per tutto ciò che tocca la catena o lo storage, punta a un gateway e lascia che sia il gateway a possedere la pipeline di pubblicazione.

Scegli tu quale gateway:

il gateway CardanoWall in hosting;
il gateway della tua azienda;
qualunque gateway di terze parti;
un gateway locale o di sviluppo.

Il desktop possiede l'esperienza locale; il gateway possiede la pubblicazione. Maggiori dettagli sull'app in CardanoWall Desktop.

Cosa dovrebbero tenere a mente gli sviluppatori?

Sviluppa basandoti sul confine dello standard — i piani HTTP e i webhook — non sugli interni del gateway.

Poche regole mantengono onesta un'integrazione:

Non interrogare direttamente il database del gateway; è interno al motore e può cambiare senza preavviso.
Non mettere credenziali dell'operatore nei client. Tutto ciò che richiede autorità di operatore appartiene al tuo backend.
Non trattare un saldo in cache come fonte di verità per una decisione di spesa; leggi il saldo del gateway quando questo vincola un addebito.
Non costruire un tuo percorso di rimborso per i fallimenti di pubblicazione — il gateway rimborsa già in automatico, e un secondo rimborso pagherebbe due volte.
Non chiedere al gateway di decifrare il contenuto dell'utente.

La forma pulita è semplice: il tuo client o backend cattura l'intento dell'utente, il tuo client tiene i segreti in locale, il gateway gestisce preventivo, upload, pubblicazione, conferma e indicizzazione, il tuo prodotto costruisce sopra la propria UI e i propri read model, e la verifica resta indipendente. È così che un unico standard può supportare molti prodotti senza trasformare ogni prodotto in un operatore di catena e storage.

In breve

Un gateway Label 309 è lo strato di pubblicazione. Fa preventivi, carica, pubblica, conferma, indicizza ed espone i record. Può essere ospitato da CardanoWall, gestito in self-hosting da un'azienda o integrato in un altro prodotto.

Non è la radice della fiducia e non detiene le tue chiavi private. Pubblica record standard che chiunque può verificare a partire da dati pubblici Cardano — che è esattamente ciò che mantiene aperto lo standard.

Letture di approfondimento

Costruire su un gateway Label 309 — pattern di integrazione per il data plane e il control plane.
Far girare il proprio gateway — gestire un'istanza self-hosted.
Perché la pubblicazione ha un prezzo — il modello di costo dietro un preventivo.
Verificare un record Label 309 — controllare una prova a partire dai soli dati pubblici.
Lo standard aperto su label309.org e il codice open source su github.com/cardanowall. Label 309 è stato sottoposto al processo CIP di Cardano ed è in revisione presso gli editor CIP come proposta di categoria Metadata (PR aperta).