Usare la CLI di CardanoWall in CI/CD e negli script

Affidati alla CLI cardanowall quando la Proof of Existence deve girare dentro uno script invece che in un browser. È pensata per l'automazione: passa --json per ottenere dati leggibili dalla macchina su stdout, tratta stderr come canale diagnostico e ramifica su un piccolo insieme di exit code stabili. Tanto basta per integrarla in CI/CD, pipeline di rilascio, job di compliance e strumenti di audit interno.

La CLI può verificare record senza un account CardanoWall, pubblicare prove tramite qualsiasi gateway Label 309, firmare record in locale, derivare un'identità da un seed, costruire e controllare inclusion proof Merkle e leggere una Inbox sigillata. È lo stesso strumento open-source che chiunque può eseguire, pubblicato su crates.io come binario cardanowall — senza alias cw — e il codice sorgente risiede su github.com/cardanowall.

Perché usare la CLI invece del sito web?

Il sito web è costruito per le persone. L'automazione ha bisogno di qualcosa di diverso:

• comandi deterministici che puoi eseguire senza supervisione;
• output leggibile dalla macchina;
• exit code stabili su cui ramificare;
• nessuna sessione di browser da pilotare;
• configurazione esplicita del gateway invece di un account con login;
• segreti letti da stdin, da un file o da una variabile d'ambiente — mai digitati in un prompt;
• log che puoi archiviare insieme al job.

È esattamente ciò che ti offre la CLI, e mantiene la prova vicina al sistema che genera davvero il materiale probatorio.

Come verifico una prova in uno script?

La verifica è il comando più facile da automatizzare, e il più utile da poter eseguire ovunque:

cardanowall verify <tx-hash> --json

La verifica non richiede né un account CardanoWall né un operatore di gateway. Legge i metadati della transazione da un explorer Cardano pubblico (compatibile con Koios o Blockfrost), opzionalmente recupera il contenuto da gateway Arweave o IPFS pubblici, valida il record e controlla eventuali firme. È proprio questo il senso dello standard: una prova che hai verificato una volta resta verificabile in modo indipendente da chiunque, senza riporre fiducia nell'emittente, nel suo dominio o nel suo server.

Per un controllo più stretto, puntala sulla tua fonte dati e imposta una profondità di conferma:

cardanowall verify <tx-hash> \
  --cardano-gateway https://api.koios.rest/api/v1 \
  --threshold 20 \
  --json

I dati vanno su stdout e le diagnostiche su stderr, così la composizione dei comandi resta pulita:

if cardanowall verify "$TX_HASH" --json > verify-report.json; then
  echo "proof verified"
else
  code=$?
  echo "verification did not pass, exit code: $code" >&2
fi

Per un'analisi più approfondita di cosa controlla davvero un verificatore, leggi come verificare un record Label 309.

Cosa significano gli exit code?

Ramifica sull'exit code invece di analizzare il testo leggibile dall'uomo — il codice ti dice già a quale classe appartiene il risultato:

Per verify, i codici 0–3 corrispondono direttamente al verdetto del verificatore — valid, failed, unverifiable e pending rispettivamente — quindi lo stesso contratto vale sia che tu legga l'exit code, sia che tu legga il report --json.

Questo dà all'automazione una policy pulita:

• 0: prosegui.
• 1: fai fallire il job — il controllo della prova o del contenuto è fallito.
• 2: riprova, oppure segna l'esecuzione come inconclusiva.
• 3: attendi e riprova dopo altre conferme.
• 4: correggi lo script o i suoi input.

In un workflow di rilascio, non trattare pending come un successo. Una prova in attesa potrebbe assestarsi più tardi, ma non è ancora definitiva.

Come pubblico una prova dall'automazione?

La pubblicazione richiede un gateway, perché invia una vera transazione Cardano e attinge al tuo saldo del gateway per pagare la fee della transazione ed eventuale storage Arweave. (Per capire perché pubblicare ha comunque un costo, leggi perché pubblicare ha un prezzo.)

Calcola l'hash di un file e ancoralo:

cardanowall submit \
  --file ./release-manifest.json \
  --base-url https://your-gateway.example \
  --api-key "$CARDANOWALL_API_KEY" \
  --json

Ancora un digest precalcolato:

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

Ancora un batch Merkle costruito da una lista di foglie:

cardanowall submit --merkle ./leaves.txt --json

Queste tre modalità si mappano in modo netto sui pattern di automazione più comuni. Un piccolo job può ancorare un singolo file. Un sistema di rilascio può ancorare il digest precalcolato di un manifest. Un sistema ad alto volume può ripiegare molti hash di item sotto un'unica Merkle root e pubblicare un singolo record. La prima esecuzione completa è descritta in pubblica la tua prima prova.

Esegui cardanowall <command> --help per la lista autorevole dei flag, allineata alla tua versione — è sempre l'ultima parola sulle opzioni della build che hai installato.

Come configuro i gateway una volta sola invece che a ogni job?

Scrivere in modo fisso un URL del gateway e una API key dentro ogni job è fragile. La CLI memorizza invece profili di gateway con un nome:

cardanowall gateway add prod --base-url https://your-gateway.example
cardanowall gateway use prod
cardanowall gateway list

In CI, alimenta la chiave da stdin invece di rispondere a un prompt interattivo:

cardanowall gateway add prod \
  --base-url https://your-gateway.example \
  --api-key-stdin < ./gateway-api-key.txt

Il gateway di servizio si risolve in un ordine fisso: vince un flag esplicito, poi la variabile d'ambiente, poi il profilo attivo. Questa suddivisione si adatta a entrambi gli ambienti — uno sviluppatore può appoggiarsi a un profilo salvato, mentre la CI inietta CARDANOWALL_BASE_URL e CARDANOWALL_API_KEY e salta del tutto il file di configurazione.

Come tengo i segreti fuori dalla riga di comando?

Questo è l'errore facile da commettere, quindi rendilo difficile da commettere. Non mettere mai un Identity Seed o una chiave del destinatario direttamente negli argomenti del comando — argv finisce nella cronologia della shell, nei log della CI e negli elenchi dei processi (ps).

Usa invece una fonte di input sicura:

• --seed-stdin o --seed-file;
• --secret-key-stdin o --secret-key-file;
• una variabile d'ambiente, solo quando la gestione dei segreti della tua CI è pulita.

Per esempio, passa il seed via stdin:

printf '%s' "$CARDANOWALL_SEED" | \
  cardanowall submit --file ./manifest.json --seed-stdin --json

Un segreto deve provenire da una sola fonte; fornirlo da due fonti contemporaneamente (per esempio un vecchio --seed-file più CARDANOWALL_SEED) è un errore di input bloccante, così un valore datato non può mai oscurare in silenzio quello che intendevi usare. I flag argv grezzi --seed e --secret-key esistono ancora per valori di test usa e getta, ma stampano un avviso di una riga su stderr quando li usi. Tratta quell'avviso come un vero controllo, non come rumore. E poiché le chiavi non hanno mai bisogno di viaggiare verso un server per svolgere questo lavoro, il seed resta sulla macchina che esegue il comando — il principio dietro perché le chiavi non lasciano mai il dispositivo.

Come firmo un record in una pipeline?

Un record firmato dimostra non solo che il contenuto esisteva, ma che una specifica chiave di un progetto o di un'organizzazione ne ha garantito la paternità. Le firme di paternità sono sempre opzionali in Label 309 — una prova solo-hash è altrettanto valida — ma sono utili quando la provenienza conta.

Per una firma locale lineare, allega il seed in sicurezza sulla pubblicazione stessa:

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

Per ambienti più rigorosi, tieni la chiave completamente fuori dall'host di build e firma in due passaggi:

cardanowall sign prepare --signer-pubkey <hex> --hash <hex>
cardanowall sign assemble --signer-pubkey <hex> --signature <hex> --in record.cbor

Questa suddivisione consente a un KMS, a un HSM, a una postazione offline o a un servizio di firma protetto di produrre la firma Ed25519, mentre la pipeline di automazione gestisce l'assemblaggio e la pubblicazione del record senza mai toccare la chiave privata.

Come raggruppo migliaia di artefatti in un solo record?

Le Merkle root sono il modo in cui un workflow da CLI scala. Invece di una transazione per artefatto, costruisci una lista delle foglie e ancora la root:

cardanowall merkle build --in leaves.txt --json > merkle.json
cardanowall submit --merkle ./leaves.txt --json

In seguito, dimostra una singola foglia con la sua inclusion proof:

cardanowall merkle verify \
  --root <hex32> \
  --leaf <hex32> \
  --proof proof.json

Questo si adatta benissimo alle prove di rilascio in CI/CD, ai batch di contenuti generati dall'IA, ai manifest di dataset, agli snapshot di compliance, agli archivi di log e ai pacchetti di provenienza dei media. Conserva la lista delle foglie e le inclusion proof insieme al resto delle prove di rilascio: la root on-chain è solo metà della storia per la verifica successiva. Il pattern è trattato in profondità in un record per migliaia di file, e il taglio CI in prove nella tua pipeline CI/CD.

Quando l'automazione dovrebbe gestire record sigillati?

La CLI può anche lavorare con la PoE sigillata — record cifrati indirizzati a uno o più destinatari:

cardanowall inbox sync --seed-stdin
cardanowall inbox list --seed-stdin --json
cardanowall inbox decrypt <tx-hash> --secret-key-stdin

Esegui questi comandi solo su macchine autorizzate a custodire la chiave del destinatario. Non lasciare una chiave del destinatario in un ambiente CI generico, a meno che quel job non faccia esplicitamente parte del perimetro di elaborazione fidato del destinatario. La decifratura produce anche testo in chiaro: un processo che può decifrare può, in linea di principio, far trapelare ciò che decifra, quindi colloca quel passaggio dove la chiave è già al suo posto.

Per la maggior parte dell'automazione pubblica verificherai prove firmate o solo-hash e non toccherai mai una chiave del destinatario. Ricorri ai comandi di Inbox sigillata quando stai costruendo un'acquisizione privata di prove, una consegna confidenziale o un'archiviazione controllata.

Cosa dovrebbe archiviare un job di CI?

Archivia il report della prova, non solo l'hash della transazione. Una buona esecuzione conserva:

• la versione della CLI;
• gli argomenti del comando, con i segreti oscurati;
• il manifest di input o il digest del file;
• l'hash della transazione;
• l'output di pubblicazione --json;
• il report di verifica --json;
• la lista delle foglie Merkle e le inclusion proof, se usate;
• l'identità del firmatario di ogni record firmato;
• i log dei retry per risultati in attesa o non verificabili.

Questo dà a futuri auditor abbastanza contesto per riprodurre il controllo senza che nessuno debba ricostruire come fosse cablato un job di rilascio mesi prima.

Un pattern di rilascio concreto

Un job di rilascio può prendere questa forma:

1. Costruisci gli artefatti.
2. Genera checksum, SBOM, attestazioni e un manifest di rilascio.
3. Calcola l'hash del manifest, oppure costruisci una lista delle foglie Merkle.
4. Pubblica con cardanowall submit.
5. Cattura l'hash della transazione e attendi le conferme.
6. Esegui cardanowall verify.
7. Salva i report JSON insieme agli artefatti di rilascio.
8. Fai fallire il rilascio su failed; riprova o sospendi su pending e unverifiable.

Niente di tutto questo è complicato, ed è proprio questo il punto. La prova dovrebbe essere abbastanza noiosa da poter girare a ogni rilascio.

Approfondimenti

• Costruisci sull'API di CardanoWall — quando uno script non basta e vuoi pilotare il gateway direttamente.
• La CLI e gli SDK open-source: github.com/cardanowall
• Lo standard Label 309: label309.org