Die CardanoWall CLI in CI/CD und Skripten nutzen

Greif zur cardanowall CLI, wenn ein Existenznachweis in einem Skript laufen muss statt im Browser. Sie ist für Automatisierung gebaut: Übergib --json, um maschinenlesbare Daten auf stdout zu bekommen, behandle stderr als Diagnose und verzweige anhand einer kleinen Menge stabiler Exit-Codes. Das reicht, um sie in CI/CD, Release-Pipelines, Compliance-Jobs und internes Audit-Werkzeug einzubinden.

Die CLI kann Einträge ohne CardanoWall-Konto verifizieren, Nachweise über jedes Label 309 Gateway veröffentlichen, Einträge lokal signieren, eine Identität aus einem Seed ableiten, Merkle-Nachweise bauen und prüfen sowie eine versiegelte Inbox lesen. Es ist dasselbe Open-Source-Werkzeug, das jeder ausführen kann, veröffentlicht auf crates.io als Binary cardanowall – ohne cw-Alias – und der Quellcode liegt unter github.com/cardanowall.

Warum die CLI statt der Website nutzen?

Die Website ist für Menschen gebaut. Automatisierung braucht etwas anderes:

deterministische Befehle, die du unbeaufsichtigt ausführen kannst;
maschinenlesbare Ausgabe;
stabile Exit-Codes, anhand derer du verzweigen kannst;
keine Browser-Session, die du steuern musst;
explizite Gateway-Konfiguration statt eines eingeloggten Kontos;
Secrets, die aus stdin, einer Datei oder einer Umgebungsvariable gelesen werden – niemals in eine Eingabeaufforderung getippt;
Logs, die du neben dem Job archivieren kannst.

Genau das gibt dir die CLI, und sie hält den Nachweis nahe an dem System, das die Belege tatsächlich erzeugt.

Wie verifiziere ich einen Nachweis in einem Skript?

Verifizierung ist der Befehl, der sich am leichtesten automatisieren lässt – und der nützlichste, den du überall ausführen kannst:

cardanowall verify <tx-hash> --json

Verifizieren braucht weder ein CardanoWall-Konto noch einen Gateway-Betreiber. Es liest die Transaktions-Metadaten aus einem öffentlichen Cardano-Explorer (Koios- oder Blockfrost-kompatibel), ruft optional Inhalte von öffentlichen Arweave- oder IPFS-Gateways ab, validiert den Eintrag und prüft etwaige Signaturen. Genau darum geht es im Standard: Ein Nachweis, den du einmal verifiziert hast, bleibt für jeden unabhängig verifizierbar – ohne Vertrauen in den Herausgeber, seine Domain oder seinen Server.

Für engere Kontrolle richte ihn auf deine eigene Datenquelle und setze eine Bestätigungstiefe:

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

Daten gehen auf stdout und Diagnosen auf stderr, sodass die Verkettung von Befehlen sauber bleibt:

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

Für einen tieferen Blick darauf, was ein Verifizierer tatsächlich prüft, sieh dir an, wie man einen Label-309-Eintrag verifiziert.

Was bedeuten die Exit-Codes?

Verzweige anhand des Exit-Codes, statt den menschenlesbaren Text zu parsen – der Code sagt dir bereits die Klasse des Ergebnisses:

Code	Bedeutung
`0`	gültig / Erfolg
`1`	Fehler der Integritätsklasse (eine kryptografische oder strukturelle Prüfung ist fehlgeschlagen)
`2`	Fehler der Netzwerkklasse oder ein nicht verifizierbares Ergebnis (ein Abruf- oder Transportfehler)
`3`	ausstehend – meist zu wenige Bestätigungen
`4`	CLI-Eingabefehler (falsche Argumente oder fehlende erforderliche Eingabe)

Bei verify werden die Codes 0–3 direkt aus dem Urteil des Verifizierers durchgereicht – valid, failed, unverifiable beziehungsweise pending –, sodass derselbe Vertrag gilt, ob du den Exit-Code oder den --json-Bericht liest.

Das gibt der Automatisierung eine klare Richtlinie:

0: weitermachen.
1: den Job fehlschlagen lassen – die Prüfung von Nachweis oder Inhalt ist fehlgeschlagen.
2: erneut versuchen oder den Lauf als ergebnislos markieren.
3: warten und nach weiteren Bestätigungen erneut versuchen.
4: das Skript oder seine Eingaben korrigieren.

Behandle in einem Release-Workflow pending nicht als Erfolg. Ein ausstehender Nachweis wird sich vielleicht später abschließen, ist aber noch nicht final.

Wie veröffentliche ich einen Nachweis aus der Automatisierung?

Veröffentlichen braucht ein Gateway, weil es eine echte Cardano-Transaktion einreicht und dein Gateway-Guthaben belastet, um die Transaktionsgebühr und etwaigen Arweave-Speicher zu bezahlen. (Warum Veröffentlichen überhaupt etwas kostet, erfährst du unter warum Veröffentlichen einen Preis hat.)

Eine Datei hashen und verankern:

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

Einen vorberechneten Digest verankern:

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

Ein Merkle-Bündel aus einer Liste von Blättern verankern:

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

Diese drei Modi bilden gängige Automatisierungsmuster sauber ab. Ein kleiner Job kann eine einzelne Datei verankern. Ein Release-System kann einen vorberechneten Manifest-Digest verankern. Ein System mit hohem Volumen kann viele Item-Hashes in eine einzige Merkle-Wurzel falten und einen einzigen Eintrag veröffentlichen. Den ersten Durchlauf behandelt veröffentliche deinen ersten Nachweis.

Führe cardanowall <command> --help aus, um die maßgebliche, versionsgenaue Flag-Liste zu erhalten – das ist immer das letzte Wort zu den Optionen deines installierten Builds.

Wie konfiguriere ich Gateways einmal statt pro Job?

Eine Gateway-URL und einen API-Key in jeden Job fest einzucodieren, ist fragil. Die CLI speichert stattdessen benannte Gateway-Profile:

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

In der CI gib den Key über stdin ein, statt eine interaktive Eingabeaufforderung zu beantworten:

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

Das Service-Gateway wird in einer festen Reihenfolge aufgelöst: Ein explizites Flag gewinnt, dann die Umgebungsvariable, dann das aktive Profil. Diese Aufteilung passt zu beiden Umgebungen – ein Entwickler kann sich auf ein gespeichertes Profil stützen, während die CI CARDANOWALL_BASE_URL und CARDANOWALL_API_KEY injiziert und die Konfigurationsdatei komplett überspringt.

Wie halte ich Secrets aus der Kommandozeile heraus?

Das ist der Fehler, den man leicht macht – also sorg dafür, dass er sich nur schwer machen lässt. Setze niemals einen rohen Identity Seed oder Empfängerschlüssel direkt in Befehlsargumente – argv leckt in die Shell-History, CI-Logs und Prozesslisten (ps).

Nutze stattdessen eine sichere Eingabequelle:

--seed-stdin oder --seed-file;
--secret-key-stdin oder --secret-key-file;
eine Umgebungsvariable, nur wenn dein CI-Umgang mit Secrets sauber ist.

Leite zum Beispiel den Seed über stdin hinein:

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

Ein Secret muss aus genau einer Quelle kommen; es aus zweien gleichzeitig zu liefern (etwa ein veraltetes --seed-file plus CARDANOWALL_SEED) ist ein harter Eingabefehler, sodass ein alter Wert niemals stillschweigend den überdecken kann, den du gemeint hast. Die rohen argv-Flags --seed und --secret-key existieren weiterhin für Wegwerf-Testwerte, geben aber bei Nutzung eine einzeilige Warnung auf stderr aus. Behandle diese Warnung als echte Kontrolle, nicht als Rauschen. Und weil Schlüssel für diese Arbeit niemals zu einem Server reisen müssen, bleibt der Seed auf der Maschine, die den Befehl ausführt – das Prinzip hinter warum Schlüssel das Gerät nie verlassen.

Wie signiere ich einen Eintrag in einer Pipeline?

Ein signierter Eintrag beweist nicht nur, dass Inhalt existierte, sondern dass ein bestimmter Projekt- oder Organisationsschlüssel dafür einsteht. Urheberschaftssignaturen sind in Label 309 immer optional – ein reiner Hash-Nachweis ist genauso gültig –, aber sie sind nützlich, wenn Provenienz zählt.

Für unkompliziertes lokales Signieren häng den Seed sicher direkt an die Veröffentlichung an:

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

Für strengere Umgebungen halte den Schlüssel ganz vom Build-Host fern und signiere in zwei Schritten:

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

Diese Aufteilung lässt ein KMS, ein HSM, eine Offline-Workstation oder einen geschützten Signierdienst die Ed25519-Signatur erzeugen, während die Automatisierungs-Pipeline den Zusammenbau und die Veröffentlichung des Eintrags übernimmt, ohne den privaten Schlüssel jemals zu berühren.

Wie bündele ich Tausende von Artefakten in einen Eintrag?

Über Merkle-Wurzeln skaliert ein CLI-Workflow. Statt einer Transaktion pro Artefakt baust du eine Blattliste und verankerst die Wurzel:

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

Später beweist du ein einzelnes Blatt mit seinem Inklusionsnachweis:

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

Das passt hervorragend zu CI/CD-Release-Belegen, Bündeln von KI-generierten Inhalten, Dataset-Manifesten, Compliance-Snapshots, Log-Archiven und Medien-Provenienz-Paketen. Bewahre die Blattliste und die Inklusionsnachweise zusammen mit dem Rest deiner Release-Belege auf: Die on-chain Wurzel ist nur die halbe Geschichte der späteren Verifizierung. Das Muster wird ausführlich behandelt in ein Eintrag für Tausende von Dateien, und der CI-Aspekt in Nachweise in deiner CI/CD-Pipeline.

Wann sollte Automatisierung versiegelte Einträge verarbeiten?

Die CLI kann auch mit versiegelten Existenznachweisen arbeiten – verschlüsselten Einträgen, die an einen oder mehrere Empfänger adressiert sind:

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

Führe diese nur auf Maschinen aus, die berechtigt sind, den Empfängerschlüssel zu halten. Lege keinen Empfängerschlüssel in eine allgemeine CI-Umgebung, es sei denn, dieser Job ist ausdrücklich Teil der vertrauenswürdigen Verarbeitungsgrenze des Empfängers. Entschlüsseln erzeugt außerdem Klartext: Ein Prozess, der entschlüsseln kann, kann im Prinzip auch das leaken, was er entschlüsselt – platziere diesen Schritt also dort, wo der Schlüssel ohnehin hingehört.

Für die meiste öffentliche Automatisierung wirst du signierte oder reine Hash-Nachweise verifizieren und nie einen Empfängerschlüssel berühren. Greif zu den Befehlen der versiegelten Inbox, wenn du eine private Annahme von Beweismitteln, vertrauliche Zustellung oder kontrollierte Archivierung baust.

Was sollte ein CI-Job archivieren?

Archiviere den Nachweis-Bericht, nicht nur den Transaktions-Hash. Ein guter Lauf bewahrt:

die CLI-Version;
die Befehlsargumente, mit redigierten Secrets;
das Eingabe-Manifest oder den Datei-Digest;
den Transaktions-Hash;
die --json-Ausgabe der Veröffentlichung;
den --json-Verifizierungsbericht;
die Merkle-Blattliste und die Inklusionsnachweise, falls genutzt;
die Signaturidentität jedes signierten Eintrags;
Retry-Logs für ausstehende oder nicht verifizierbare Ergebnisse.

Das gibt künftigen Prüfern genug Kontext, um die Prüfung zu reproduzieren, ohne dass jemand rekonstruieren muss, wie ein Release-Job Monate zuvor verdrahtet war.

Ein praktisches Release-Muster

Ein Release-Job kann diese Form annehmen:

Baue die Artefakte.
Erzeuge Prüfsummen, SBOMs, Attestierungen und ein Release-Manifest.
Hashe das Manifest oder baue eine Merkle-Blattliste.
Veröffentliche mit cardanowall submit.
Erfasse den Transaktions-Hash und warte auf Bestätigungen.
Führe cardanowall verify aus.
Speichere die JSON-Berichte zusammen mit den Release-Artefakten.
Lass das Release bei failed fehlschlagen; versuche es erneut oder halte an bei pending und unverifiable.

Nichts davon ist kompliziert, und genau das ist der Punkt. Der Nachweis sollte langweilig genug sein, um bei jedem Release zu laufen.

Weiterführende Lektüre

Auf der CardanoWall API aufbauen – wenn ein Skript nicht ausreicht und du das Gateway direkt steuern willst.
Die Open-Source-CLI und -SDKs: github.com/cardanowall
Der Label 309 Standard: label309.org