CI/CD와 스크립트에서 CardanoWall CLI 사용하기

존재 증명을 브라우저가 아니라 스크립트 안에서 실행해야 한다면 cardanowall CLI를 사용하십시오. 이 도구는 자동화를 위해 만들어졌습니다. --json을 전달하면 stdout으로 기계가 읽을 수 있는 데이터를 받고, stderr는 진단 정보로 다루며, 소수의 안정적인 종료 코드로 분기하면 됩니다. 이것만으로 CI/CD, 릴리스 파이프라인, 컴플라이언스 작업, 내부 감사 도구에 연결하기에 충분합니다.

CLI는 CardanoWall 계정 없이 레코드를 검증하고, 어떤 Label 309 게이트웨이를 통해서도 증명을 게시하며, 로컬에서 레코드에 서명하고, 시드에서 신원을 파생하고, Merkle 증명을 만들고 확인하며, 봉인된 받은편지함을 읽을 수 있습니다. 누구나 실행할 수 있는 동일한 오픈소스 도구로, crates.io에 바이너리 cardanowall로 게시되어 있으며 — cw 별칭은 없습니다 — 소스는 github.com/cardanowall에 있습니다.

웹사이트 대신 CLI를 쓰는 이유는 무엇입니까?

웹사이트는 사람을 위해 만들어졌습니다. 자동화에는 다른 것이 필요합니다.

무인 실행이 가능한 결정론적 명령;
기계가 읽을 수 있는 출력;
분기할 수 있는 안정적인 종료 코드;
구동할 브라우저 세션이 없다는 점;
로그인된 계정 대신 명시적인 게이트웨이 설정;
프롬프트에 입력하지 않고 stdin, 파일, 환경 변수에서 읽어 들이는 시크릿;
작업과 함께 보관할 수 있는 로그.

CLI는 바로 이것을 제공하며, 실제로 증거를 만들어 내는 시스템 가까이에 증명을 둡니다.

스크립트에서 증명을 어떻게 검증합니까?

검증은 자동화하기 가장 쉬운 명령이자, 어디서든 실행하기에 가장 유용한 명령입니다.

cardanowall verify <tx-hash> --json

검증에는 CardanoWall 계정도, 게이트웨이 운영자도 필요하지 않습니다. CLI는 공개 Cardano 익스플로러(Koios 또는 Blockfrost 호환)에서 트랜잭션 메타데이터를 읽고, 선택적으로 공개 Arweave 또는 IPFS 게이트웨이에서 콘텐츠를 가져오며, 레코드를 검증하고 모든 서명을 확인합니다. 이것이 바로 표준의 핵심입니다. 한 번 검증한 증명은 발행자나 그 도메인, 그 서버를 신뢰하지 않고도 누구든지 독립적으로 검증할 수 있는 상태로 남습니다.

더 엄격하게 제어하려면 자체 데이터 소스를 지정하고 확인 깊이를 설정하십시오.

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

데이터는 stdout으로, 진단 정보는 stderr로 나가므로 명령을 조합해도 깔끔하게 유지됩니다.

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

이 세 가지 모드는 흔한 자동화 패턴에 깔끔하게 대응합니다. 소규모 작업은 파일 하나를 고정할 수 있습니다. 릴리스 시스템은 미리 계산한 매니페스트 다이제스트를 고정할 수 있습니다. 대용량 시스템은 수많은 항목 해시를 하나의 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에서는 대화형 프롬프트에 답하는 대신 stdin으로 키를 전달하십시오.

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

서비스 게이트웨이는 정해진 순서로 결정됩니다. 명시적 플래그가 우선이고, 그다음이 환경 변수, 마지막이 활성 프로필입니다. 이 구분은 두 환경 모두에 적합합니다 — 개발자는 저장된 프로필에 의존할 수 있고, CI는 CARDANOWALL_BASE_URL과 CARDANOWALL_API_KEY를 주입하고 설정 파일을 완전히 건너뜁니다.

명령줄에 시크릿이 남지 않게 하려면 어떻게 합니까?

이것은 저지르기 쉬운 실수이므로, 저지르기 어렵게 만들어 두십시오. 원시 신원 시드나 수신자 키를 명령 인수에 직접 넣지 마십시오 — argv는 셸 기록, CI 로그, 프로세스 목록(ps)으로 새어 나갑니다.

대신 안전한 입력 소스를 사용하십시오.

--seed-stdin 또는 --seed-file;
--secret-key-stdin 또는 --secret-key-file;
CI 시크릿 처리가 깨끗할 때에 한해 환경 변수.

예를 들어, 시드를 stdin으로 파이프하십시오.

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

시크릿은 정확히 한 곳에서만 와야 합니다. 두 곳에서 동시에 공급하면(예: 오래된 --seed-file과 CARDANOWALL_SEED를 함께 쓰면) 곧바로 입력 오류가 되므로, 오래된 값이 의도한 값을 조용히 가리는 일은 결코 생기지 않습니다. 원시 --seed와 --secret-key argv 플래그는 일회성 테스트 값을 위해 여전히 존재하지만, 사용하면 stderr에 한 줄짜리 경고를 출력합니다. 그 경고는 잡음이 아니라 실제 통제 장치로 여기십시오. 그리고 이 작업을 하는 데 키가 서버로 이동할 필요가 전혀 없으므로, 시드는 명령을 실행하는 머신에 그대로 남습니다 — 이는 키가 기기를 떠나지 않는 이유의 바탕이 되는 원칙입니다.

파이프라인에서 레코드에 어떻게 서명합니까?

서명된 레코드는 콘텐츠가 존재했다는 사실뿐 아니라, 특정 프로젝트나 조직의 키가 그것을 보증했다는 사실까지 증명합니다. 작성자 서명은 Label 309에서 언제나 선택 사항이며 — 해시만 담은 증명도 똑같이 유효합니다 — 출처가 중요할 때 유용합니다.

간단한 로컬 서명이라면, 게시 자체에 시드를 안전하게 붙이십시오.

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

더 엄격한 환경이라면, 키를 빌드 호스트에서 완전히 떼어 놓고 두 단계로 서명하십시오.

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

이 구분 덕분에 KMS, HSM, 오프라인 워크스테이션, 보호된 서명 서비스가 Ed25519 서명을 만들고, 자동화 파이프라인은 개인 키에 한 번도 닿지 않고 레코드 조립과 게시를 처리할 수 있습니다.

수천 개의 산출물을 하나의 레코드로 어떻게 묶습니까?

Merkle 루트는 CLI 워크플로를 확장하는 방법입니다. 산출물마다 트랜잭션을 하나씩 만드는 대신, 리프 목록을 만들고 그 루트를 고정하십시오.

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 생성 콘텐츠 배치, 데이터셋 매니페스트, 컴플라이언스 스냅샷, 로그 아카이브, 미디어 출처 증명 패키지에 매우 잘 들어맞습니다. 리프 목록과 포함 증명은 나머지 릴리스 증거와 함께 보관하십시오. 온체인 루트는 나중의 검증 과정 중 절반에 불과합니다. 이 패턴은 수천 개 파일을 위한 레코드 하나에서 깊이 있게 다루며, CI 관점은 CI/CD 파이프라인 속의 증명에서 다룹니다.

자동화는 언제 봉인된 레코드를 다뤄야 합니까?

CLI는 봉인된 존재 증명 — 한 명 이상의 수신자에게 보내는 암호화된 레코드 — 도 다룰 수 있습니다.

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이면 재시도하거나 보류합니다.

이 가운데 복잡한 것은 없으며, 바로 그것이 핵심입니다. 증명은 모든 릴리스마다 돌릴 수 있을 만큼 지루해야 합니다.

더 읽어보기

CardanoWall API 위에서 빌드하기 — 스크립트로는 부족해 게이트웨이를 직접 제어하고 싶을 때.
오픈소스 CLI와 SDK: github.com/cardanowall
Label 309 표준: label309.org