CardanoWall CLI を CI/CD とスクリプトで使う

存在証明（Proof of Existence）をブラウザではなくスクリプトの中で実行する必要があるなら、cardanowall CLI の出番です。自動化のために作られており、--json を渡せば機械可読なデータが標準出力に得られ、標準エラー出力は診断として扱い、少数の安定した終了コードで分岐できます。これだけで CI/CD、リリースパイプライン、コンプライアンスのジョブ、内部監査ツールへ組み込めます。

CLI は、CardanoWall アカウントなしでレコードを検証し、任意の Label 309 ゲートウェイ経由で証明を公開し、ローカルでレコードに署名し、シードからアイデンティティを導出し、Merkle 証明を構築・検証し、封印された受信トレイを読み取れます。これは誰でも実行できるオープンソースのツールそのものであり、crates.io にバイナリ cardanowall として公開されています（cw エイリアスはありません）。ソースは github.com/cardanowall にあります。

ウェブサイトではなく CLI を使うのはなぜか

ウェブサイトは人のために作られています。自動化には別のものが必要です。

無人で実行できる決定的なコマンド
機械可読な出力
分岐できる安定した終了コード
操作すべきブラウザセッションが不要
ログイン済みアカウントではなく明示的なゲートウェイ設定
標準入力・ファイル・環境変数から読み取るシークレット（プロンプトに入力させない）
ジョブと一緒にアーカイブできるログ

CLI はまさにこれらを提供し、しかも証明を、実際に証拠を生み出すシステムのすぐ近くに保ちます。

スクリプトで証明を検証するにはどうするか

検証は最も自動化しやすいコマンドであり、どこでも実行できる最も有用なコマンドでもあります。

cardanowall verify <tx-hash> --json

検証には CardanoWall アカウントも、ゲートウェイの運用者も不要です。公開された Cardano エクスプローラー（Koios または Blockfrost 互換）からトランザクションメタデータを読み取り、必要に応じて公開された Arweave や IPFS のゲートウェイからコンテンツを取得し、レコードを検証し、署名があればそれも検証します。これこそが標準の核心です。一度検証した証明は、発行者・そのドメイン・そのサーバーを信頼することなく、誰でも独立して検証し続けられます。

より厳密に制御したい場合は、独自のデータソースを指定し、確認深度を設定します。

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

データは標準出力へ、診断は標準エラー出力へ流れるので、コマンドの組み合わせがすっきりと保たれます。

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

検証ツールが実際に何を確認するのかをより詳しく知りたい方は、Label 309 レコードを検証する方法をご覧ください。

終了コードは何を意味するのか

人間向けのテキストを解析するのではなく、終了コードで分岐してください。コードはすでに結果の種類を伝えています。

コード	意味
`0`	有効／成功
`1`	完全性クラスの失敗（暗号的または構造的なチェックに失敗）
`2`	ネットワーククラスの失敗、または検証不能な結果（取得またはトランスポートのエラー）
`3`	保留（通常は確認数の不足）
`4`	CLI の入力エラー（引数の誤りや必須入力の欠落）

verify では、コード 0〜3 が検証ツールの判定（それぞれ valid、failed、unverifiable、pending）にそのまま対応します。したがって、終了コードを読んでも --json レポートを読んでも、同じ契約が成り立ちます。

これにより、自動化にすっきりとしたポリシーが与えられます。

0: 続行する。
1: ジョブを失敗させる。証明またはコンテンツのチェックに失敗しています。
2: 再試行するか、結果を不確定として記録する。
3: 確認数が増えるのを待ってから再試行する。
4: スクリプトまたはその入力を修正する。

リリースのワークフローでは、pending を成功として扱わないでください。保留中の証明は後で確定するかもしれませんが、まだ最終ではありません。

自動化から証明を公開するにはどうするか

公開にはゲートウェイが必要です。実際の Cardano トランザクションを送信し、トランザクション手数料と Arweave のストレージ費用を支払うためにゲートウェイの残高から引き落とすからです（そもそも公開になぜ費用がかかるのかは、公開に価格がある理由をご覧ください）。

ファイルをハッシュ化してチェーン上に記録します。

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

事前計算したダイジェストをチェーン上に記録します。

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

リーフのリストから構築した Merkle バッチをチェーン上に記録します。

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

この 3 つのモードは、よくある自動化のパターンにきれいに対応します。小さなジョブなら単一のファイルを記録できます。リリースシステムなら事前計算したマニフェストのダイジェストを記録できます。大量処理のシステムなら多数のアイテムのハッシュを 1 つの Merkle ルートにまとめて、単一のレコードを公開できます。最初の一通りの流れは最初の証明を公開するで扱っています。

cardanowall <command> --help を実行すると、バージョンに一致した正式なフラグ一覧が得られます。お使いのビルドのオプションについては、常にこれが最終的な情報源です。

ジョブごとではなく一度だけゲートウェイを設定するにはどうするか

ゲートウェイの URL と API キーをすべてのジョブにハードコードするのは脆弱です。代わりに CLI は名前付きのゲートウェイプロファイルを保存します。

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

CI では、対話的なプロンプトに答える代わりに、標準入力からキーを渡します。

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

サービスゲートウェイは固定の順序で解決されます。まず明示的なフラグが優先され、次に環境変数、最後にアクティブなプロファイルです。この分担は両方の環境に適しています。開発者は保存したプロファイルに頼れますし、CI は CARDANOWALL_BASE_URL と CARDANOWALL_API_KEY を注入して設定ファイルを完全に省けます。

シークレットをコマンドラインから締め出すにはどうするか

これはやってしまいがちなミスなので、起こりにくくしておきましょう。生の Identity Seed や受信者の鍵を、コマンド引数に直接置かないでください。argv はシェル履歴、CI ログ、プロセス一覧（ps）に漏れます。

代わりに安全な入力ソースを使ってください。

--seed-stdin または --seed-file
--secret-key-stdin または --secret-key-file
環境変数（ただし CI のシークレット管理がクリーンな場合に限る）

たとえば、シードを標準入力でパイプ渡しします。

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

シークレットは必ず 1 つのソースだけから来なければなりません。2 つから同時に与えること（たとえば古い --seed-file と CARDANOWALL_SEED の併用）は明確な入力エラーになります。これにより、古い値が意図した値を黙って上書きしてしまうことは決して起こりません。生の --seed と --secret-key の argv フラグは、使い捨てのテスト値のために今も残っていますが、使うと標準エラー出力に 1 行の警告を表示します。この警告はノイズではなく、本物の制御として扱ってください。そして、この処理のために鍵がサーバーへ移動する必要は一切ないため、シードはコマンドを実行するマシン上にとどまります。これが鍵がデバイスから出ない理由の背後にある原則です。

パイプラインでレコードに署名するにはどうするか

署名付きのレコードは、コンテンツが存在したことだけでなく、特定のプロジェクトや組織の鍵がそれを保証したことも証明します。作成者を示す署名は Label 309 では常に任意であり（ハッシュのみの証明も同じく有効です）、来歴が重要な場合に役立ちます。

単純なローカル署名なら、公開そのものに対してシードを安全に添付します。

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

より厳格な環境では、鍵をビルドホストから完全に外し、2 段階で署名します。

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

この分割により、KMS、HSM、オフラインのワークステーション、あるいは保護された署名サービスが Ed25519 署名を生成し、その間に自動化パイプラインは、秘密鍵に一切触れることなくレコードの組み立てと公開を担えます。

数千件のアーティファクトを 1 つのレコードにまとめるにはどうするか

Merkle ルートは、CLI のワークフローを規模拡大させる方法です。アーティファクトごとに 1 トランザクションを使うのではなく、リーフリストを構築してルートを記録します。

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

後から、包含証明とともに単一のリーフを証明します。

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

これは、CI/CD のリリース証拠、AI 生成コンテンツのバッチ、データセットのマニフェスト、コンプライアンスのスナップショット、ログのアーカイブ、メディアの来歴パッケージに非常によく合います。リーフリストと包含証明は、残りのリリース証拠と一緒に保管してください。オンチェーンのルートは、後で検証する際に必要なものの半分にすぎません。このパターンは数千ファイルを 1 つのレコードにで詳しく扱い、CI の観点はCI/CD パイプラインの中の証明で扱っています。

自動化が封印付きレコードを扱うべきはいつか

CLI は封印付き存在証明も扱えます。これは 1 人以上の受信者に宛てた暗号化されたレコードです。

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

これらは、受信者の鍵を保持することを許可されたマシン上でのみ実行してください。そのジョブが受信者の信頼された処理境界に明示的に含まれているのでない限り、受信者の鍵を一般的な CI 環境に持ち込まないでください。復号は平文も生み出します。復号できるプロセスは、原理的には復号した内容を漏らし得るため、その手順は鍵が本来あるべき場所に置いてください。

ほとんどの公開向け自動化では、署名付きまたはハッシュのみの証明を検証し、受信者の鍵に触れることはありません。封印された受信トレイのコマンドの出番は、非公開の証拠取り込み、機密性の高い配信、管理されたアーカイブを構築するときです。

CI ジョブは何をアーカイブすべきか

トランザクションハッシュだけでなく、証明レポートをアーカイブしてください。良い実行は次を保存します。

CLI のバージョン
コマンド引数（シークレットは伏せたもの）
入力のマニフェストまたはファイルのダイジェスト
トランザクションハッシュ
--json の公開出力
--json の検証レポート
使った場合は、Merkle のリーフリストと包含証明
署名付きレコードがあれば、その署名者のアイデンティティ
保留または検証不能の結果に対する再試行ログ

これにより、リリースジョブが数か月前にどう組まれていたかを誰も再構築しなくても、将来の監査担当者がチェックを再現するのに十分な文脈が得られます。

実践的なリリースのパターン

リリースジョブは次のような形を取れます。

アーティファクトをビルドする。
チェックサム、SBOM、アテステーション、リリースマニフェストを生成する。
マニフェストをハッシュ化するか、Merkle のリーフリストを構築する。
cardanowall submit で公開する。
トランザクションハッシュを取得し、確認を待つ。
cardanowall verify を実行する。
JSON レポートをリリースアーティファクトと一緒に保存する。
failed ならリリースを失敗させる。pending と unverifiable なら再試行するか保留する。

どれも複雑ではありません。そこが肝心です。証明は、毎回のリリースで実行できるほど退屈であるべきなのです。