Come verificare un record Label 309

Verifichi un record Label 309 direttamente dalla blockchain Cardano pubblica, partendo da un solo dato in ingresso: un riferimento a una transazione Cardano. Niente, nella risposta, dipende da CardanoWall, da chi ha pubblicato il record o dal fatto che un qualsiasi server sia ancora online.

Un verificatore recupera i byte grezzi della transazione dall'infrastruttura Cardano pubblica, estrae la label dei metadati 309, ricompone il corpo del record, controlla il CBOR canonico e lo schema, verifica le eventuali firme di autenticità e — quando sono disponibili i byte del contenuto o un payload cifrato — ricalcola gli hash. L'intero controllo è una sequenza di confronti crittografici, non una richiesta a un servizio fidato.

Il gateway che ha pubblicato il record non è l'autorità. Lo è il record. È proprio questo il senso dello standard: una prova che verifichi una volta resta verificabile da chiunque, per sempre, con qualunque strumento Label 309 conforme.

Cosa ti serve per verificare?

Il dato minimo in ingresso è un hash di transazione Cardano.

Con quel solo hash di transazione, un verificatore può rispondere a queste domande:

• in questa transazione c'è un record Label 309?
• il record è strutturalmente valido?
• la transazione è confermata a una profondità sufficiente?
• le firme a livello di record si verificano, se sono presenti?
• quali hash, quali URI di storage, quali Merkle root e quali buste sigillate dichiara il record?

Per dimostrare che un file specifico è il file che sta dietro all'hash, il verificatore ha bisogno anche dei byte del file oppure di un oggetto di storage attribuibile e referenziato dal record.

Per decifrare un record sigillato, il verificatore ha bisogno della chiave privata del destinatario. Quella chiave viene usata in locale e non viene mai rimandata a chi ha pubblicato il record né a CardanoWall — l'intera costruzione è pensata perché la verifica non chiami mai casa.

Cosa controlla davvero un verificatore?

Un buon verificatore dovrebbe controllare il record a strati.

Il primo strato è il validatore strutturale. È una funzione pura sui byte del record. Non effettua chiamate di rete, non decifra nulla e non verifica firme. Controlla il CBOR canonico, i tipi dei campi, lo schema chiuso, i nomi degli algoritmi registrati, le regole sugli URI e i vincoli incrociati tra campi, come «deve esserci almeno un item o un impegno Merkle».

Il secondo strato è il verificatore pubblico. Risolve la transazione a partire da una fonte dati Cardano scelta dal verificatore, lega i byte recuperati all'hash della transazione, estrae la label 309, controlla la profondità di conferma e verifica le firme del record. È lo strato che possono eseguire un audit pubblico, un job di CI o un explorer.

Il terzo strato è il verificatore destinatario. Fa tutto ciò che fa il verificatore pubblico, poi prova a decifrare gli item sigillati con la chiave locale del destinatario e ricalcola gli hash del testo in chiaro dopo la decifratura.

Questa stratificazione conta perché non tutte le prove richiedono tutti i controlli. Un record solo-hash può essere valido anche quando non ha alcun payload cifrato. Un verificatore pubblico può validare un record firmato senza essere in grado di decifrare un file sigillato.

Perché verificare dai byte grezzi della transazione e non da una vista JSON?

La verifica Label 309 funziona a partire dai dati grezzi della catena, non da una comoda proiezione JSON — e la differenza non è solo estetica.

Il record è CBOR canonico. Le firme coprono il CBOR canonico byte per byte. I metadati della transazione Cardano hanno stringhe di byte, stringhe di testo, array, mappe e regole di ordinamento che il JSON non riesce a conservare senza perdite.

Quindi un verificatore dovrebbe recuperare il CBOR grezzo della transazione, ricalcolare l'id della transazione, legare i dati ausiliari al corpo della transazione e poi ricomporre l'array di chunk della label 309 nel corpo originale del record.

Un explorer può essere un'infrastruttura utile. Non dovrebbe diventare ciò di cui ti fidi. Il verificatore dovrebbe trattare le risposte di un explorer come dati da legare, controllare e verificare in modo incrociato.

Cosa c'è dentro un record label 309?

Un record Label 309 è trasportato sotto la label dei metadati 309 della transazione Cardano.

Il valore on-chain non è un oggetto JSON sciolto. Il corpo del record viene serializzato una sola volta come CBOR canonico e poi trasportato come array di chunk di stringhe di byte, perché nei metadati Cardano le stringhe di byte e le stringhe di testo sono limitate a 64 byte.

Dopo la ricomposizione, il corpo del record è una singola mappa CBOR. Le sue chiavi di primo livello sono:

• v, la versione dello schema (attualmente 1);
• items, un array opzionale di impegni per ciascun contenuto — ogni item porta una mappa hashes obbligatoria e, opzionalmente, una propria lista uris per lo storage indirizzato per contenuto (ar://, ipfs://) e una busta enc per il contenuto sigillato;
• merkle, impegni di lista opzionali che legano una root on-chain a una lista di foglie off-chain — il modo in cui si ancorano i batch di grandi dimensioni;
• sigs, firme di autenticità opzionali a livello di record;
• supersedes, un puntatore opzionale e append-only a un record precedente;
• crit più chiavi di estensione con namespace, per aggiunte compatibili con le versioni future.

Un record conforme deve impegnarsi su almeno una voce items o un impegno merkle. Gli URI di storage e la busta sigillata risiedono all'interno di un item, non al livello superiore — un dettaglio da non sbagliare quando analizzi il record da solo.

L'affermazione centrale è sempre content-first: questi hash, o questa Merkle root, sono stati ancorati in questa transazione non più tardi del block time.

Quali verdetti deve aspettarsi l'automazione?

La verifica non dovrebbe ridurre ogni problema a «valido» o «non valido».

Il modello del verificatore Label 309 usa quattro verdetti pensati per le macchine:

• valid: ogni controllo richiesto è passato.
• failed: il record stesso non ha superato un controllo strutturale, di firma o di integrità attribuibile.
• unverifiable: un controllo richiesto non ha potuto essere completato per motivi non attribuibili al record, come un'infrastruttura non disponibile o un contenuto che non è stato possibile recuperare.
• pending: la transazione è on-chain ma sotto la soglia di conferma del verificatore.

Questa distinzione è importante nei sistemi reali.

Se un gateway di storage è giù, il record non dovrebbe essere condannato. Se i byte recuperati sono attribuibili a un URI su cui ci si è impegnati e il loro hash non corrisponde, il record dovrebbe fallire. Se la transazione ha una sola conferma, il verificatore dovrebbe dire che è in pending invece di fingere che la definitività sia già avvenuta.

La CLI open-source cardanowall mappa quegli stati direttamente sui codici di uscita, così il verdetto sopravvive in uno script di shell senza dover analizzare alcun JSON:

cardanowall verify <tx-hash> --json

Questa distinzione è esattamente ciò che vuoi nell'integrazione continua: lo script sa distinguere «la prova non è valida» (uscita 1, che un explorer malfunzionante non può mai produrre artificiosamente) da «riprova più tardi» (uscita 2). Lo stesso verificatore è incluso negli SDK TypeScript, Python e Rust, così un'applicazione può leggere il report strutturato completo invece di un codice di uscita. Per gli schemi su come integrarlo in una pipeline, vedi come usare la CLI nell'automazione.

Come verifichi un file?

Per una semplice prova su file, il flusso di lavoro è questo:

1. Prendi l'hash della transazione.
2. Recupera e verifica il record Label 309.
3. Individua l'algoritmo di hash e il digest su cui ci si è impegnati.
4. Calcola l'hash dei byte del file in locale.
5. Confronta il tuo digest con il digest nel record.
6. Controlla la profondità di conferma e il block time.
7. Controlla le eventuali firme del record, se sono presenti.

Se il file differisce anche di un solo byte, l'hash sarà diverso.

È questa la forza di una prova basata su hash del contenuto. Non dimostra che il file sia vero, legale, originale o di valore. Dimostra che gli esatti byte che corrispondono all'hash esistevano non più tardi del block time ancorato, secondo la politica di definitività del verificatore.

Come verifichi un record sigillato?

Un record sigillato aggiunge contenuto cifrato.

Il record pubblico continua a impegnarsi sull'hash del testo in chiaro. Il testo cifrato può essere conservato off-chain, per esempio tramite Arweave o IPFS. La busta on-chain contiene le informazioni necessarie a un destinatario previsto per recuperare in locale la chiave del contenuto.

Il verificatore destinatario dovrebbe:

1. Eseguire prima il percorso di verifica pubblica.
2. Provare la chiave privata fornita contro gli slot sigillati.
3. Se uno slot si apre, decifrare il testo cifrato.
4. Ricalcolare l'hash del testo in chiaro.
5. Confrontarlo con l'impegno sull'hash on-chain.

Quel controllo finale sull'hash è il ponte tra «ho decifrato qualcosa» e «questo è l'esatto contenuto a cui è stato applicato il timestamp». Decifrare i byte non basta da solo: l'hash del testo in chiaro ricalcolato deve corrispondere all'impegno che il record ha preso prima che qualsiasi cosa fosse cifrata.

La chiave del destinatario resta in locale. La verifica non richiede alcun account CardanoWall fidato, nessun server dell'emittente e nessun callback verso la persona che ha pubblicato il record. Un record sigillato mantiene il proprio testo in chiaro confidenziale per chi possiede le chiavi — ma attenzione ai suoi limiti: non garantisce l'anonimato e, una volta che un destinatario decifra il contenuto, può farne ciò che vuole.

Come verifichi un impegno Merkle?

Gli impegni Merkle servono per i batch.

Invece di pubblicare migliaia di hash direttamente in un unico record, un produttore può pubblicare una sola Merkle root e tenere off-chain la lista ordinata delle foglie e le inclusion proof.

Per verificare un item del batch:

1. Calcola l'hash dell'item oppure ottieni il digest della foglia su cui ci si è impegnati.
2. Verifica la inclusion proof contro la Merkle root.
3. Controlla che la root e leaf_count siano nel record Label 309.
4. Verifica la transazione Cardano e la profondità di conferma.

La root da sola non basta. Il produttore o l'archivio deve conservare la lista delle foglie e le inclusion proof. Label 309 dà al batch un'àncora pubblica; le prove operative attorno al batch vanno comunque conservate. È così che un solo record dimostra migliaia di file a un costo on-chain fisso.

Di cosa non bisogna fidarsi?

Non fidarti del sito di chi pubblica come fonte di verità.

Non fidarti di uno screenshot di una transazione.

Non fidarti di una vista JSON di un explorer come input crittografico.

Non fidarti di un gateway di storage solo perché ha restituito dei byte.

Non fidarti dei badge «verificato» che non dicono cosa è stato controllato.

Il verificatore dovrebbe essere in grado di produrre un report: hash della transazione, fonti dati Cardano usate, profondità di conferma, block time, digest del record, risultati delle firme, risultati degli hash del contenuto, risultati del recupero dallo storage, controlli Merkle ed eventuali controlli saltati.

È quel report a rendere la prova utilizzabile negli audit e nell'automazione.

Cosa non dimostra la verifica?

La verifica è precisa. Non andrebbe sopravvalutata.

Un record Label 309 valido non dimostra, di per sé:

• la proprietà legale del contenuto, né i diritti esclusivi su di esso;
• che il contenuto sia vero;
• che chi pubblica avesse il permesso di pubblicarlo;
• che una persona reale controlli una chiave di firma;
• che un tribunale, un'autorità di regolamentazione o un cliente accetterà la prova senza prove a supporto — l'ammissibilità dipende dalla giurisdizione, e una prova può sostenere una causa ma non sostituisce il parere di un legale;
• che lo storage off-chain resterà disponibile per sempre, a meno che la durabilità dello storage non venga mantenuta separatamente.

Dimostra l'affermazione che il record fa davvero: un hash o una Merkle root sono stati ancorati su Cardano, le eventuali firme sul record si sono verificate e gli eventuali controlli sul contenuto o sulla decifratura hanno corrisposto agli impegni. In altre parole, stabilisce tempistica e integrità — non verità, proprietà o diritti.

È proprio quell'affermazione più ristretta a renderla utile. Per il confine completo di ciò che un timestamp può e non può fare, vedi cosa una prova non dimostra.

Per approfondire

• Lo standard Label 309, comprensivo dell'intero flusso di verifica, degli stati di verdetto e del catalogo tipizzato degli errori: label309.org.
• Il verificatore open-source — la CLI cardanowall più gli SDK TypeScript, Python e Rust, che eseguono tutti gli stessi controlli: github.com/cardanowall.
• Label 309 è stato presentato al processo CIP di Cardano ed è in revisione presso gli editor CIP come proposta della categoria Metadata: la pull request aperta.