Come costruire un prodotto su un gateway Label 309

Per realizzare una funzionalità di Proof of Existence senza dover gestire tu stesso una blockchain, costruisci su un gateway. Un gateway Label 309 è il motore di pubblicazione dietro un prodotto Proof-of-Existence: fa il lavoro operativo difficile — preventivi, upload, submission delle transazioni Cardano, conferma, gestione dei reorg, indicizzazione dei record, saldi degli account, finanziamento dello storage, API key e webhook — ed espone tutto questo su semplice HTTP. Il tuo prodotto chiama quegli endpoint e si occupa di tutto ciò che i tuoi utenti vedono davvero: l'interfaccia, il rapporto di fatturazione, il flusso di lavoro del dominio e il brand.

Il gateway core è open source, e CardanoWall è il prodotto di riferimento costruito su di esso. La parte utile per gli sviluppatori è che non c'è nessuna porta privata: CardanoWall raggiunge il gateway attraverso gli stessi endpoint pubblici che useresti tu, quindi qualunque pattern funzioni per il prodotto di riferimento funziona anche per te.

Chi dovrebbe costruire su un gateway?

Costruisci su un gateway se vuoi la Proof of Existence all'interno di un prodotto, e non come un'azione manuale che un utente compie su un sito web.

Tra i casi più adatti ci sono:

prodotti di notarizzazione di documenti;
archivi di prove per la compliance;
piattaforme di provenienza dell'AI e di governance dei dataset;
sistemi di prova per l'integrazione continua;
strumenti per le prove legali;
portali di divulgazione cifrata;
servizi di autenticità dei media;
strumenti di audit aziendali interni;
pagine di prova per editori.

In tutti questi casi gli utenti non vogliono pensare alla costruzione delle transazioni Cardano, al finanziamento delle UTxO, ai crediti di storage o alle conferme on-chain. Vogliono un flusso di lavoro che produca prove durevoli e verificabili. Il gateway rende possibile quel flusso senza che il tuo team debba diventare operatore di infrastruttura Cardano.

Di cosa si occupa il gateway, e di cosa si occupa il tuo prodotto?

La separazione è tutto: vale quindi la pena dirlo chiaramente. Il gateway si occupa del base plane — la pipeline di pubblicazione e tutto lo stato di denaro, catena e storage che le sta dietro:

preventivo, upload e pubblicazione;
build, submit, conferma, gestione dei reorg e refund su fallimento permanente delle transazioni Cardano;
upload di contenuto e testo cifrato verso lo storage, più il finanziamento dello storage che li sostiene;
un indice condiviso dei record on-chain che copre ogni record Label 309 presente sulla rete;
saldi degli account e le voci di ledger che li muovono;
pricing e margini di cambio valuta;
credenziali API e consegna dei webhook.

Questo è lavoro infrastrutturale. Deve essere preciso, osservabile e noioso in produzione. La tua applicazione non dovrebbe reimplementarlo, a meno che gestire un gateway non sia il tuo vero lavoro — e se lo è, vedi gestire il proprio gateway.

Il tuo prodotto si occupa del vendor plane — tutto ciò che ha forma di fornitore:

account utente e sessioni;
onboarding e fatturazione;
permessi del prodotto;
la tua interfaccia e le tue email;
il prezzo che presenti ai clienti;
concetti di dominio come «caso», «release», «dataset» o «pacchetto di prove»;
read model costruiti a partire dagli eventi del gateway;
flussi di lavoro di supporto.

Il gateway non ha bisogno di sapere che una prova appartiene a una causa legale, a una sessione di addestramento di un modello, a un pacchetto di compliance trimestrale o a un numero di rivista. Deve soltanto pubblicare record Label 309 corretti e mantenere lo stato operativo che li circonda. Quella separazione mantiene entrambi i sistemi più puliti: il tuo prodotto può essere ricostruito o rinominato senza toccare lo stato di catena o di denaro, e il gateway può essere aggiornato senza sapere che il tuo prodotto esiste.

Come chiami il data plane per conto di un utente?

Il data plane (/api/v1/*) è l'API rivolta agli account. Usalo ogni volta che l'azione avviene per conto di un utente o di un account:

chiedere un preventivo per una pubblicazione;
caricare contenuto o testo cifrato;
pubblicare un record;
leggere un saldo o il ledger dell'account;
elencare, recuperare o verificare record pubblici;
registrare webhook con ambito account.

In un prodotto wrapper, il tuo backend conia un account token di breve durata per l'account gateway dell'utente, e il client chiama il data plane con i soli scope di cui ha bisogno. Gli scope sono il confine dei permessi: una schermata di pubblicazione ha bisogno di poe:create, un widget di saldo ha bisogno di account:read, e gli endpoint dei record pubblici non richiedono alcuna credenziale — rispondono a chiamanti anonimi, ed è questo che rende l'indice un bene pubblico anziché una vista per singolo cliente.

I token sono di breve durata per scelta progettuale (un'ora per impostazione predefinita). Conia un token per sessione e riconialo alla scadenza, così un token trafugato è un problema di un'ora anziché un incidente. E non inviare mai le credenziali dell'operatore al browser — è l'unica regola che la prossima sezione ha proprio lo scopo di proteggere.

Come chiami il control plane in qualità di operatore?

Il control plane (/control/v1/*) è riservato ai soli backend fidati e agli operatori. Usalo per:

creare account gateway, e abilitarli o disabilitarli;
applicare aggiustamenti al ledger dopo che il tuo sistema di fatturazione ha incassato il denaro;
impostare margini per singolo account;
coniare account token e API key;
registrare il firehose di webhook dell'operatore;
registrare e gestire wallet e fonti di finanziamento dello storage;
leggere lo stato di audit e operativo.

Questo piano vive dietro il tuo backend. Tratta le credenziali dell'operatore come segreti di produzione con autorità di spesa — perché ce l'hanno davvero. Un operator token di breve durata (24 ore per impostazione predefinita) gestisce l'amministrazione quotidiana; un singolo root secret, conservato in un secret store, è riservato alle poche operazioni che registrano wallet e fonti di storage.

Il control plane è il modo in cui il tuo sistema di fatturazione e il saldo prepagato del gateway restano collegati. Un pagamento va a buon fine nel tuo sistema, e poi il tuo backend applica un unico aggiustamento idempotente al ledger dell'account gateway. È tutto qui il binario dei crediti, e le prossime due sezioni spiegano perché è costruito esattamente così.

Perché non dovresti interrogare direttamente le tabelle del gateway?

Perché lo schema non è un contratto — lo sono l'API HTTP e i webhook.

Il motore del gateway possiede i propri schemi Postgres (cw_core e cw_api). Il tuo prodotto non dovrebbe leggerli né scriverli, nemmeno quando entrambi i sistemi condividono la stessa istanza Postgres. La coesistenza degli schemi è una forma di deployment supportata, ma il confine è lo schema, non il database: quegli schemi del motore sono interni e possono cambiare senza preavviso, mentre i piani HTTP e il firehose sono stabili. Se attraversi quel confine, un normale aggiornamento del gateway può rompere il tuo prodotto in silenzio.

Se ti servono dati che l'API non espone, trattalo come una lacuna dell'API da segnalare — non come un permesso per fare join tra gli schemi.

Come costruisci le tue schermate a partire dagli eventi del gateway?

Ogni prodotto ha bisogno delle proprie viste: record inviati, cronologia dei clienti, saldi, fallimenti di pubblicazione, timeline dei casi, pacchetti di prove, dashboard di audit. Non costruirle facendo polling di ogni riga o join sugli interni del gateway.

Registra invece i webhook e proietta gli eventi nelle tue tabelle. Il gateway espone un firehose dell'operatore — ogni evento del ciclo di vita sull'istanza — più sottoscrizioni di webhook con ambito account per flussi più ristretti. Una vista «elementi inviati» è l'esempio canonico: consuma gli eventi di stato della pubblicazione, proiettali nella tua tabella e renderizza da lì.

La consegna è almeno-una-volta, quindi rendi idempotente la tua proiezione. Un read model pratico può usare come chiave:

l'id dell'evento o l'id di consegna (così una riconsegna è un no-op);
l'id del record del gateway;
l'hash finale della transazione;
il tuo id utente;
l'id del tuo oggetto di dominio;
stato e timestamp.

La tua interfaccia renderizza poi dalle tue tabelle, mentre il gateway resta l'autorità per la spesa, il ciclo di vita della pubblicazione e i fatti di catena. Ogni consegna è firmata; verifica la firma e applica una finestra di tolleranza sul timestamp prima di fidarti di un evento.

Come dovrebbe fluire il denaro tra la tua fatturazione e il gateway?

Mantieni il modello semplice: il saldo del gateway è il saldo spendibile, e il tuo sistema di fatturazione è solo uno dei modi in cui il denaro lo raggiunge.

Il tuo binario di fatturazione potrebbe incassare carte, fatture, pagamenti in cripto, crediti aziendali manuali o grant. Il gateway non ha bisogno di sapere nulla di tutto ciò. Il pattern pulito è:

Il tuo sistema di fatturazione conferma un pagamento.
Il tuo backend applica un unico aggiustamento idempotente al ledger dell'account gateway, con chiave sull'id del pagamento.
Il saldo del gateway aumenta.
Le future operazioni di pubblicazione e upload addebitano quel saldo.
Se una pubblicazione fallisce in modo permanente, il gateway annulla l'addebito da solo.

Ne derivano due conseguenze. Primo, l'idempotenza conta perché le pipeline di fatturazione consegnano almeno-una-volta: passa l'id stesso del pagamento come riferimento dell'aggiustamento, e cinque consegne di un solo pagamento accreditano il saldo una volta sola. Secondo, non replicare il ledger del gateway in una tua tabella per poi trattare la copia come verità nelle decisioni di spesa — mettila in cache per il rendering se proprio devi, ma leggi il gateway ogni volta che la decisione muove davvero del denaro. Poiché è il gateway a emettere i propri refund, non dovresti nemmeno costruire un percorso di refund lato fornitore per i fallimenti di pubblicazione; produrrebbe un doppio refund.

Dove dovrebbe vivere ciascun tipo di chiave?

Un gateway non dovrebbe mai aver bisogno dell'Identity Seed di un utente. Il client o l'SDK può calcolare l'hash del contenuto, cifrare i payload sigillati e firmare i record in locale; il gateway pubblica soltanto i byte finali del record e fa la submission della transazione Cardano. (Per capire perché quel confine conta da un capo all'altro, vedi perché le chiavi non lasciano mai il dispositivo.)

Un'integrazione completa ha diverse classi di chiavi distinte, e l'errore da evitare è appiattirle tutte in un unico «API secret». Hanno raggi d'azione molto diversi:

gli Identity Seed degli utenti e le chiavi private dei destinatari — l'identità crittografica dell'utente, che appartiene all'edge;
le chiavi di firma dei record derivate da quell'identità;
le API key dell'account e gli account token di breve durata — che appartengono al prodotto o al contesto client che ne ha bisogno;
gli operator token e il root secret — che appartengono soltanto ai backend fidati;
le chiavi di firma Cardano e di storage del gateway stesso, e i suoi segreti di firma dei webhook — che appartengono al keyring del gateway.

Mappa ogni classe sul posto più piccolo capace di contenerla, e una singola fuga resta circoscritta.

Quando dovresti ospitare in proprio il gateway invece di usarne uno gestito?

Ospitalo in proprio quando l'indipendenza operativa conta più della comodità.

Un gateway gestito è il percorso più semplice per la maggior parte delle integrazioni: pubblichi attraverso un servizio già pronto su superfici API standard e non gestisci mai operazioni di catena o di storage. L'hosting in proprio scambia quella semplicità con il controllo — il finanziamento del tuo wallet Cardano, il finanziamento del tuo storage, le tue policy operative, il tuo uptime e le tue dipendenze di rete, i tuoi margini, il tuo confine di compliance, e nessuna dipendenza da terze parti per la pubblicazione.

Ma il controllo è anche responsabilità. Ospitare in proprio significa finanziare ADA e crediti di storage, proteggere il keyring, far funzionare Postgres, monitorare i provider di catena, gestire i backup, ruotare le credenziali, gestire i webhook e rispondere agli incidenti. Elimina una dipendenza da un fornitore; non elimina il lavoro operativo. Gestire il proprio gateway illustra cosa comporta davvero.

Cosa dovrebbero vedere i tuoi utenti in una prova?

La maggior parte degli utenti dovrebbe vedere prima i concetti del tuo prodotto. A loro interessa «pubblicare una prova», «sigillare questo file», «dimostrare questo snapshot del dataset» o «ancorare questa release». Non dovrebbero leggere una specifica di metadati per usare il prodotto.

Ciò detto, ogni vista di una prova dovrebbe esporre i fatti che rendono la sua affermazione verificabile in modo indipendente:

l'hash della transazione;
il block time e lo stato di conferma;
l'algoritmo di hash e il digest;
la chiave pubblica del firmatario, quando il record è firmato;
gli URI dello storage, quando presenti;
lo stato del destinatario sigillato, quando rilevante;
la Merkle root e l'inclusion proof della foglia, quando il record raggruppa molti file;
il verdetto della verifica stesso.

È così che il prodotto resta piacevole da usare senza nascondere l'affermazione crittografica che ci sta sotto.

Come eviti di vincolare il tuo prodotto a un solo gateway?

Il gateway ti aiuta a pubblicare; non dovrebbe mai diventare la prova.

Il record on-chain è metadato Label 309, e la verifica è progettata per funzionare a partire da soli tre input: i metadati della transazione, facoltativamente i byte del contenuto e un explorer Cardano pubblico — con le chiavi del destinatario aggiunte solo per decifrare i record sigillati. In quel percorso di fiducia non c'è alcun server dell'emittente. Se il tuo gateway sparisse domani, un record valido dovrebbe comunque verificarsi con strumenti indipendenti. Vale la pena ricordare anche cosa una prova del genere afferma e cosa non afferma: dimostra che quei byte esatti esistevano entro un momento pubblico, non che una qualunque affermazione su di essi sia vera, di proprietà di qualcuno o autorizzata.

Costruisci il tuo prodotto attorno a questa promessa:

conserva gli hash delle transazioni in modo durevole;
consenti agli utenti di esportare report di verifica e di scaricare pacchetti di prove;
conserva le liste delle foglie Merkle e le loro inclusion proof;
documenta come verificare un record al di fuori della tua interfaccia;
evita campi privati che solo il tuo backend è in grado di interpretare.

È questa la differenza tra «abbiamo una riga in un database» e «abbiamo prodotto una prova che chiunque può controllare».

Approfondimenti

Che cos'è un gateway Label 309? e gestire il proprio gateway — il gateway visto dal lato dell'operatore.
Costruire sull'API di CardanoWall e usare la CLI in automazione — le superfici rivolte agli sviluppatori, più in dettaglio.
Perché pubblicare ha un prezzo — cosa paga davvero il saldo prepagato.
Label 309 è open source — lo standard e il suo codice di riferimento.
Lo standard open source vive su label309.org; il gateway, gli SDK e la CLI sono su github.com/cardanowall. Label 309 è stato sottoposto al processo CIP di Cardano ed è in revisione presso gli editor CIP come proposta della categoria Metadata.