Pubblica la tua prima Proof of Existence su Cardano

La prova Label 309 più semplice è un hash ancorato su Cardano.

Prendi un file, ne calcoli l'hash crittografico, pubblichi quell'hash in un record Label 309 sotto la label dei metadati 309 di Cardano e conservi l'hash della transazione che ne risulta. In seguito, chiunque possieda il file originale può ricalcolare l'hash e confermare che l'impegno corrispondente era on-chain entro il block time della transazione. Per controllarlo non serve il tuo server, il tuo dominio o la tua identità — basta il riferimento della transazione e un explorer Cardano pubblico.

Questo è il primo livello della Proof of Existence (prova dell'esistenza). Tutto il resto si costruisce su di esso. Questa guida ti accompagna nella pubblicazione di una prova, perlopiù dallo strumento da riga di comando cardanowall, e si chiude mostrando come confermare che ha davvero funzionato.

Cosa stai pubblicando davvero?

Quando crei una prova di base, non stai pubblicando il file in sé.

Stai pubblicando un impegno sul file: il suo digest. Un digest è un'impronta crittografica di dimensione fissa. Se il file cambia anche di un solo byte, il digest cambia completamente. È proprio questa proprietà a rendere un hash un sostituto affidabile dei byte esatti.

Una prova solo-hash si adatta bene a casi come:

contratti e fatture;
artefatti di rilascio e build manifest;
output di IA e snapshot di dataset;
documenti di policy e raccolte di prove;
checksum già prodotti da un altro sistema.

La prova non rivela il contenuto del file. Rivela soltanto l'hash, l'algoritmo di hash che hai scelto e gli eventuali metadati opzionali che decidi di includere nel record. Per saperne di più su quali campi finiscono on-chain, leggi cosa finisce sulla blockchain.

Cosa ti serve prima di pubblicare?

Per pubblicare serve un gateway. Per verificare no.

La verifica si svolge interamente a partire dai dati pubblici della catena. Pubblicare è diverso: qualcosa deve costruire e inviare la transazione Cardano, pagare la commissione di rete, gestire la conferma e — se conservi i file off-chain — pagare il costo dello storage. Un gateway Label 309 è il servizio che fa tutto questo. Il gateway open-source e gli strumenti che lo circondano sono indipendenti dal gateway, quindi punti gli strumenti verso qualunque gateway per cui possiedi una chiave.

Per la tua prima prova ti serve:

un file o un digest precalcolato;
l'URL base di un gateway Label 309;
una API key o un account token a vita breve per quel gateway;
saldo sufficiente sul tuo account del gateway;
facoltativamente, un Identity Seed, se vuoi firmare il record.

Se usi il gateway CardanoWall ospitato, è CardanoWall a gestire per te l'account del gateway e il saldo prepagato. Se gestisci il tuo gateway, sei tu a finanziarne i wallet Cardano e di storage. In ogni caso pubblicare costa, perché vengono pagate commissioni reali per tuo conto — l'argomento di perché pubblicare ha un prezzo.

Perché il flusso è prima il preventivo, poi la pubblicazione?

Un gateway non dovrebbe mai pubblicare di nascosto e sorprenderti con un addebito. Per questo ogni pubblicazione ha la stessa forma in due passaggi: blocca un prezzo, poi invia.

Costruisci o stima il record.
Chiedi un preventivo al gateway.
Ricevi un id di preventivo e una scomposizione del prezzo (commissione di rete, storage, margine di servizio).
Invia il record finalizzato con quel preventivo.
Ricevi subito un id di record del gateway, mentre la transazione è ancora in fase di invio.
Segui lo stato finché la transazione non è confermata on-chain.
Verifica il risultato in modo indipendente.

Un preventivo blocca il prezzo per una finestra limitata — attualmente 15 minuti. Se scade prima che tu pubblichi, ne richiedi uno nuovo; il prezzo può cambiare se sono cambiati i tassi di cambio, ma nient'altro cambia.

È proprio questo schema in due passaggi a rendere sicura l'automazione. Il tuo script può registrare il preventivo, applicare la propria politica di spesa e solo a quel punto pubblicare — così un'impennata di prezzo o un batch inviato per errore non possono mai prosciugare il tuo saldo.

Pubblica un file con la CLI

Per un file locale, il flusso da riga di comando è volutamente essenziale:

cardanowall submit \
  --file ./contract.pdf \
  --base-url https://your-gateway.example \
  --api-key "$CARDANOWALL_API_KEY"

La CLI calcola l'hash del file, costruisce il record Label 309, chiede al gateway di preventivarlo e pubblicarlo e stampa il risultato. --base-url e --api-key si leggono anche dalle variabili d'ambiente CARDANOWALL_BASE_URL e CARDANOWALL_API_KEY, così spariscono dal comando in CI.

Per un uso ripetuto, salva il gateway come profilo con nome invece di passare l'endpoint ogni volta:

cardanowall gateway add prod --base-url https://your-gateway.example
cardanowall gateway use prod
cardanowall submit --file ./contract.pdf

Il binario cardanowall è un unico strumento nativo autonomo, senza alcun runtime da installare. Installalo da crates.io con cargo install cardanowall-cli (il crate è cardanowall-cli; il comando installato è cardanowall), oppure compilalo dal repository open-source su github.com/cardanowall.

Come pubblichi un hash che hai già?

A volte il digest esiste già — da una pipeline di build, da un container registry, da un processo di rilascio o da un archivio dati. In quel caso, pubblica il digest direttamente, senza coinvolgere alcun file:

cardanowall submit --hash <64-hex-digest>

La modalità di hash predefinita è sha2-256. Passa --alg blake2b-256 quando ti serve quell'algoritmo. Il record registra quale algoritmo hai usato, così un verificatore sa come ricalcolare il digest in seguito.

Pubblicare un hash precalcolato è anche la mossa giusta quando il file di origine è troppo grande, troppo sensibile o troppo strettamente controllato per passare attraverso uno strumento generico. L'unica cosa che conta è che i byte esatti e l'esatto processo di hashing restino riproducibili — altrimenti nessuno potrà ricalcolare un digest corrispondente.

Dovresti firmare il record?

Firma il record quando vuoi dimostrare che una specifica identità Label 309 ne ha garantito il contenuto.

Una prova solo-hash dice: questi byte esistevano entro questo momento. Una prova firmata aggiunge: e questa chiave di firma sta dietro a questo record esatto. Quell'affermazione in più conta per i record di rilascio aziendali, gli archivi ufficiali, le pipeline CI/CD, i flussi di prove legali, i log di provenienza dell'IA e qualunque identità pubblica di chi pubblica destinata a durare nel tempo.

Le firme sono sempre opzionali. Una prova non firmata è comunque una proof of existence completa e pienamente verificabile — Label 309 è indipendente dall'emittente per progettazione, e un verificatore non deve mai fidarsi di chi pubblica. La firma risponde semplicemente a una domanda diversa: chi garantisce per il record, non se i byte esistevano.

L'Identity Seed non deve mai essere inviato al gateway. La CLI e l'SDK sono costruiti in modo che la firma avvenga localmente e che viaggi solo la firma finita. Fornisci il seed tramite --seed-stdin o --seed-file invece di passarlo direttamente con --seed, perché gli argomenti da riga di comando trapelano attraverso la cronologia della shell, gli elenchi dei processi e i log della CI:

cardanowall submit --file ./release-manifest.json --seed-stdin

Dovresti allegare il file o solo l'hash?

Hai tre scelte, in ordine crescente di quanto vincoli on-chain.

Solo hash. La prova più piccola e più riservata. Basta quando sai già che il file sarà conservato da qualche parte sotto il tuo controllo. Il record porta con sé il digest e nulla riguardo al recupero.

Hash più un link indirizzato per contenuto. Allega un URI ar:// (Arweave) o ipfs:// (IPFS) così i verificatori possono recuperare i byte in seguito. È sempre l'hash a decidere se i byte recuperati corrispondono — un URI indirizzato per contenuto lega i byte al link stesso, quindi un verificatore non deve mai fidarsi del gateway, del DNS o del TLS per sapere di aver recuperato il file giusto.

Sigillato. Cifra il file, conserva il testo cifrato off-chain e inserisci la busta sigillata nel record. Questo è il percorso per i record riservati, per la consegna a un destinatario specifico e per recuperare il contenuto in seguito se la tua copia locale va perduta.

Per una prima prova, parti dal solo hash. Aggiungi la firma, lo storage off-chain, il Merkle batching o la consegna sigillata quando un caso d'uso reale lo richiede.

Come fai a sapere che ha davvero funzionato?

Non fermarti a «il gateway l'ha accettato». La prova è completa solo quando la transazione è on-chain e si verifica.

Quando pubblichi, il gateway restituisce subito un id di record e l'hash della transazione si completa in modo asincrono, una volta che la transazione è stata costruita e inviata. Quindi, dopo aver pubblicato, conserva:

l'hash della transazione Cardano;
l'id di record del gateway, se hai usato un gateway;
il file originale o il digest;
l'identità pubblica della chiave di firma, se hai firmato;
l'eventuale lista delle foglie Merkle o la inclusion proof, se hai usato un batch;
l'eventuale materiale di recupero, se la prova è sigillata.

Poi verifica la transazione esattamente come farebbe qualunque terza parte — a partire dalla catena pubblica, senza coinvolgere alcun gateway:

cardanowall verify <tx-hash> --json

Un verdetto valid è il traguardo. Gli altri verdetti ti dicono cosa fare dopo:

pending — la transazione non si è ancora consolidata a sufficienza. Attendi ulteriori conferme e riprova.
unverifiable — nessun difetto nel record, ma un controllo necessario non è potuto partire. Controlla le tue fonti di dati, la disponibilità dello storage off-chain e la policy di rete.
failed — un problema reale, attribuibile al record. Indaga sul record stesso.

La distinzione tra failed e unverifiable è voluta: failed significa che il record è sbagliato, mentre unverifiable significa che il verificatore non è riuscito a portare a termine un controllo. Per il flusso di verifica completo, leggi verifica un record Label 309.

Cosa dovrebbe mostrare un'interfaccia dopo la pubblicazione?

Una buona interfaccia mostra più della parola «pubblicato». Per una prima prova, metti in evidenza:

l'hash breve della transazione, con un pulsante per copiarlo;
l'hash completo della transazione nella vista di dettaglio;
l'algoritmo di hash e il digest;
lo stato della pubblicazione;
il block time, una volta confermato;
il verdetto di verifica;
se il record è stato firmato;
se sono stati allegati o sigillati file;
se sono stati saltati dei controlli.

Così la prova diventa comprensibile senza costringere nessuno a leggere la specifica.

Cosa può andare storto durante la pubblicazione?

La maggior parte dei fallimenti in fase di pubblicazione è di natura operativa, non misteriosa. L'account può essere a corto di saldo. Il preventivo può essere scaduto. Il record può essere troppo grande per una transazione Cardano. Un file caricato può non riuscire a essere conservato. La transazione Cardano può fallire in modo permanente — nel qual caso un gateway ben costruito annulla da sé l'addebito, così ti viene fatturato solo ciò che finisce on-chain. Oppure il wallet finanziato del gateway può semplicemente avere bisogno di attenzione.

Un flusso di pubblicazione serio gestisce i ritentativi in modo idempotente. Un gateway deduplica un ritentativo di pubblicazione in base ai byte esatti del record — reinviare il record identico restituisce il risultato esistente invece di spendere due volte — e accetta una chiave di idempotenza sui batch di upload, così un upload riconsegnato è a prova di replay. In un prodotto rivolto all'utente, progetta il percorso di ritentativo prima che il tuo primo cliente reale incappi in un timeout di rete, non dopo.

Se stai integrando tutto questo in una pipeline, usare la CLI in automazione approfondisce l'output JSON, gli exit code e la gestione sicura dei segreti.

Cosa non dimostra la tua prima prova?

Una proof of existence è precisa su ciò che afferma, il che significa che è altrettanto precisa su ciò che non afferma.

Non dimostra la proprietà.
Non dimostra la paternità — a meno che tu non la firmi e non riesca a legare la chiave di firma all'identità rivendicata.
Non dimostra che il file sia vero, lecito o originale.
Non conserva il file, a meno che tu non lo archivi da qualche parte in modo durevole.

Ciò che dimostra, invece, è esatto e duraturo: i byte precisi corrispondenti all'hash vincolato esistevano entro il block time della transazione, e qualunque firma opzionale, controllo di storage o controllo di contenuto sigillato è risultato valido secondo la policy del verificatore.

È abbastanza per essere davvero utile, e abbastanza preciso per essere degno di fiducia. Per il confine più ampio di ciò che un timestamp può e non può stabilire, leggi cosa non dimostra una prova.

Per approfondire

Verifica un record Label 309 — l'altra metà del flusso, senza fiducia e senza account.
Perché pubblicare ha un prezzo — cosa paga la commissione.
Usare la CLI in automazione — output JSON, exit code e segreti in CI.
Cosa finisce sulla blockchain — i campi che un record porta davvero con sé.
Lo standard aperto e le implementazioni di riferimento: label309.org e il codice sorgente su github.com/cardanowall.