← Tous les articles

9 min de lecture

Utiliser la CLI CardanoWall en CI/CD et dans vos scripts

Exécutez une preuve d'existence depuis un script : la CLI cardanowall écrit du JSON sur stdout, les diagnostics sur stderr, vous donne des codes de sortie de vérification stables, accepte les secrets en toute sécurité et publie via n'importe quel gateway Label 309.

Tournez-vous vers la CLI cardanowall lorsque la preuve d'existence doit s'exécuter dans un script plutôt que dans un navigateur. Elle est conçue pour l'automatisation : passez --json pour obtenir des données lisibles par une machine sur stdout, traitez stderr comme un flux de diagnostics, et branchez votre logique sur un petit ensemble de codes de sortie stables. Cela suffit à l'intégrer dans vos pipelines CI/CD, vos chaînes de publication, vos tâches de conformité et votre outillage d'audit interne.

La CLI peut vérifier des records sans compte CardanoWall, publier des preuves via n'importe quel gateway Label 309, signer des records en local, dériver une identité à partir d'une graine, construire et vérifier des preuves Merkle, et lire une boîte de réception scellée. C'est le même outil open source que tout le monde peut exécuter, publié sur crates.io sous le binaire cardanowall — sans alias cw — et dont le code source vit sur github.com/cardanowall.

Pourquoi utiliser la CLI plutôt que le site web ?

Le site web est conçu pour les humains. L'automatisation a besoin d'autre chose :

  • des commandes déterministes que vous pouvez exécuter sans surveillance ;
  • une sortie lisible par une machine ;
  • des codes de sortie stables sur lesquels brancher votre logique ;
  • aucune session de navigateur à piloter ;
  • une configuration explicite du gateway au lieu d'un compte connecté ;
  • des secrets lus depuis stdin, un fichier ou une variable d'environnement — jamais saisis dans une invite ;
  • des journaux que vous pouvez archiver aux côtés de la tâche.

C'est exactement ce que vous offre la CLI, et elle garde la preuve au plus près du système qui produit réellement les éléments de preuve.

Comment vérifier une preuve dans un script ?

La vérification est la commande la plus simple à automatiser, et la plus utile à exécuter n'importe où :

cardanowall verify <tx-hash> --json

Vérifier ne nécessite ni compte CardanoWall ni opérateur de gateway. La commande lit les métadonnées de la transaction depuis un explorateur Cardano public (compatible Koios ou Blockfrost), récupère optionnellement le contenu depuis des gateways publics Arweave ou IPFS, valide le record et vérifie d'éventuelles signatures. C'est tout l'intérêt du standard : une preuve que vous avez vérifiée une fois reste vérifiable de manière indépendante par quiconque, sans aucune confiance accordée à l'émetteur, à son domaine ou à son serveur.

Pour un contrôle plus fin, pointez la commande vers votre propre source de données et fixez une profondeur de confirmation :

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

Les données partent sur stdout et les diagnostics sur stderr, ce qui garde la composition des commandes propre :

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

Pour un examen plus détaillé de ce qu'un vérificateur contrôle réellement, voyez comment vérifier un record Label 309.

Que signifient les codes de sortie ?

Branchez votre logique sur le code de sortie plutôt que d'analyser le texte lisible par un humain — le code vous indique déjà la classe du résultat :

CodeSignification
0valide / succès
1échec de classe « intégrité » (un contrôle cryptographique ou structurel a échoué)
2échec de classe « réseau » ou résultat invérifiable (une erreur de récupération ou de transport)
3en attente — généralement un nombre insuffisant de confirmations
4erreur d'entrée de la CLI (mauvais arguments ou entrée requise manquante)

Pour verify, les codes 0 à 3 correspondent directement au verdict du vérificateur — respectivement valid, failed, unverifiable et pending — de sorte que le même contrat s'applique, que vous lisiez le code de sortie ou le rapport --json.

Cela donne à l'automatisation une politique claire :

  • 0 : continuer.
  • 1 : faire échouer la tâche — le contrôle de la preuve ou du contenu a échoué.
  • 2 : réessayer, ou marquer l'exécution comme non concluante.
  • 3 : attendre et réessayer après davantage de confirmations.
  • 4 : corriger le script ou ses entrées.

Dans un flux de publication, ne traitez pas pending comme un succès. Une preuve en attente peut se stabiliser plus tard, mais elle n'est pas encore définitive.

Comment publier une preuve depuis l'automatisation ?

La publication nécessite un gateway, car elle soumet une véritable transaction Cardano et puise dans le solde de votre gateway pour payer les frais de transaction et l'éventuel stockage Arweave. (Pour comprendre pourquoi publier a un coût, voyez pourquoi la publication a un prix.)

Hacher et ancrer un fichier :

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

Ancrer un condensé précalculé :

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

Ancrer un lot Merkle construit à partir d'une liste de feuilles :

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

Ces trois modes s'alignent proprement sur des schémas d'automatisation courants. Une petite tâche peut ancrer un seul fichier. Un système de publication peut ancrer le condensé précalculé d'un manifeste. Un système à fort volume peut replier de nombreuses empreintes d'éléments dans une seule racine de Merkle et publier un unique record. Le premier parcours complet est traité dans publiez votre première preuve.

Exécutez cardanowall <command> --help pour obtenir la liste des options qui fait autorité et qui correspond à votre version — c'est toujours la référence finale pour les options de votre build installé.

Comment configurer les gateways une seule fois plutôt qu'à chaque tâche ?

Coder en dur une URL de gateway et une clé d'API dans chaque tâche est fragile. La CLI stocke plutôt des profils de gateway nommés :

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

En CI, fournissez la clé depuis stdin plutôt que de répondre à une invite interactive :

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

Le gateway de service se résout dans un ordre fixe : un flag explicite l'emporte, puis la variable d'environnement, puis le profil actif. Cette répartition convient aux deux environnements — un développeur peut s'appuyer sur un profil enregistré, tandis que la CI injecte CARDANOWALL_BASE_URL et CARDANOWALL_API_KEY et contourne entièrement le fichier de configuration.

Comment garder les secrets hors de la ligne de commande ?

C'est l'erreur facile à commettre, alors faites en sorte qu'elle soit difficile à commettre. Ne placez jamais une graine d'identité brute ou une clé de destinataire directement dans les arguments d'une commande — argv se retrouve dans l'historique du shell, les journaux de CI et la liste des processus (ps).

Utilisez plutôt une source d'entrée sûre :

  • --seed-stdin ou --seed-file ;
  • --secret-key-stdin ou --secret-key-file ;
  • une variable d'environnement, uniquement lorsque la gestion des secrets de votre CI est irréprochable.

Par exemple, transmettez la graine sur stdin :

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

Un secret doit provenir d'une seule et unique source ; le fournir depuis deux à la fois (disons un --seed-file périmé en plus de CARDANOWALL_SEED) constitue une erreur d'entrée bloquante, de sorte qu'une ancienne valeur ne peut jamais masquer silencieusement celle que vous vouliez utiliser. Les flags argv bruts --seed et --secret-key existent toujours pour des valeurs de test jetables, mais ils affichent un avertissement d'une ligne sur stderr lorsqu'on les utilise. Considérez cet avertissement comme un vrai garde-fou, pas comme du bruit. Et puisque les clés n'ont jamais besoin de transiter vers un serveur pour accomplir ce travail, la graine reste sur la machine qui exécute la commande — le principe au cœur de pourquoi les clés ne quittent jamais l'appareil.

Comment signer un record dans un pipeline ?

Un record signé prouve non seulement qu'un contenu existait, mais aussi qu'une clé précise — d'un projet ou d'une organisation — s'est portée garante de ce contenu. Les signatures d'auteur sont toujours optionnelles dans Label 309 — une preuve fondée sur la seule empreinte est tout aussi valide — mais elles sont utiles lorsque la provenance compte.

Pour une signature locale simple, attachez la graine en toute sécurité au moment même de la publication :

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

Pour des environnements plus stricts, gardez la clé entièrement hors de l'hôte de build et signez en deux étapes :

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

Cette séparation permet à un KMS, un HSM, un poste de travail hors ligne ou un service de signature protégé de produire la signature Ed25519, tandis que le pipeline d'automatisation se charge de l'assemblage et de la publication du record sans jamais toucher à la clé privée.

Comment regrouper des milliers d'artefacts dans un seul record ?

Les racines de Merkle sont la façon dont un flux CLI passe à l'échelle. Au lieu d'une transaction par artefact, construisez une liste de feuilles et ancrez la racine :

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

Plus tard, prouvez une feuille isolée à l'aide de sa preuve d'inclusion :

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

Cela convient parfaitement aux éléments de preuve de publication CI/CD, aux lots de contenus générés par IA, aux manifestes de jeux de données, aux instantanés de conformité, aux archives de journaux et aux dossiers de provenance de médias. Conservez la liste de feuilles et les preuves d'inclusion avec le reste de vos éléments de preuve de publication : la racine sur la chaîne n'est que la moitié de la vérification ultérieure. Le schéma est traité en profondeur dans un seul record pour des milliers de fichiers, et son volet CI dans des preuves dans votre pipeline CI/CD.

Quand l'automatisation doit-elle traiter des records scellés ?

La CLI peut aussi travailler avec une PoE scellée — des records chiffrés adressés à un ou plusieurs destinataires :

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

N'exécutez ces commandes que sur des machines autorisées à détenir la clé du destinataire. Ne déposez pas une clé de destinataire dans un environnement de CI générique, à moins que cette tâche ne fasse explicitement partie du périmètre de traitement de confiance du destinataire. Le déchiffrement produit aussi du texte en clair : un processus capable de déchiffrer peut, en principe, divulguer ce qu'il déchiffre, alors placez cette étape là où la clé a déjà sa place.

Pour la plupart des automatisations publiques, vous vérifierez des preuves signées ou fondées sur la seule empreinte sans jamais toucher à une clé de destinataire. Tournez-vous vers les commandes de boîte de réception scellée lorsque vous construisez une réception d'éléments de preuve privée, une livraison confidentielle ou un archivage contrôlé.

Que devrait archiver une tâche de CI ?

Archivez le rapport de preuve, pas seulement l'empreinte de transaction. Une bonne exécution conserve :

  • la version de la CLI ;
  • les arguments de la commande, secrets masqués ;
  • le manifeste d'entrée ou le condensé du fichier ;
  • l'empreinte de transaction ;
  • la sortie de publication --json ;
  • le rapport de vérification --json ;
  • la liste de feuilles Merkle et les preuves d'inclusion, le cas échéant ;
  • l'identité du signataire de tout record signé ;
  • les journaux de nouvelle tentative pour les résultats en attente ou invérifiables.

Cela donne aux futurs auditeurs assez de contexte pour reproduire le contrôle sans que personne ait à reconstituer la manière dont une tâche de publication avait été câblée des mois plus tôt.

Un schéma de publication concret

Une tâche de publication peut prendre cette forme :

  1. Construire les artefacts.
  2. Générer les sommes de contrôle, les SBOM, les attestations et un manifeste de version.
  3. Hacher le manifeste, ou construire une liste de feuilles Merkle.
  4. Publier avec cardanowall submit.
  5. Capturer l'empreinte de transaction et attendre les confirmations.
  6. Exécuter cardanowall verify.
  7. Stocker les rapports JSON avec les artefacts de version.
  8. Faire échouer la publication sur failed ; réessayer ou suspendre sur pending et unverifiable.

Rien de tout cela n'est compliqué, et c'est précisément le but. La preuve devrait être assez banale pour s'exécuter à chaque publication.

Pour aller plus loin

cliautomationci-cd