← Todos os posts

9 min de leitura

Use a CLI do CardanoWall em CI/CD e scripts

Execute Proof of Existence a partir de um script: a CLI cardanowall coloca JSON no stdout, diagnósticos no stderr, oferece códigos de saída de verificação estáveis, recebe segredos com segurança e publica através de qualquer gateway Label 309.

Recorra à CLI cardanowall quando o Proof of Existence (prova de existência) precisar rodar dentro de um script em vez de um navegador. Ela foi feita para automação: passe --json para obter dados legíveis por máquina no stdout, trate o stderr como diagnósticos e ramifique a partir de um pequeno conjunto de códigos de saída estáveis. Isso já basta para integrá-la a CI/CD, pipelines de lançamento, tarefas de conformidade e ferramentas de auditoria interna.

A CLI consegue verificar registros sem uma conta CardanoWall, publicar provas através de qualquer gateway Label 309, assinar registros localmente, derivar uma identidade a partir de uma semente, montar e checar provas Merkle e ler uma inbox selada. É a mesma ferramenta de código aberto que qualquer pessoa pode executar, publicada no crates.io como o binário cardanowall — sem o atalho cw — e o código-fonte fica em github.com/cardanowall.

Por que usar a CLI em vez do site?

O site foi feito para pessoas. A automação precisa de algo diferente:

  • comandos determinísticos que você pode executar sem supervisão;
  • saída legível por máquina;
  • códigos de saída estáveis nos quais você pode ramificar;
  • nenhuma sessão de navegador para conduzir;
  • configuração explícita de gateway em vez de uma conta logada;
  • segredos lidos do stdin, de um arquivo ou de uma variável de ambiente — nunca digitados em um prompt;
  • logs que você pode arquivar junto com a tarefa.

É exatamente isso que a CLI oferece, e ela mantém a prova perto do sistema que de fato produz a evidência.

Como verifico uma prova em um script?

A verificação é o comando mais fácil de automatizar e o mais útil para rodar em qualquer lugar:

cardanowall verify <tx-hash> --json

Verificar não exige uma conta CardanoWall nem um operador de gateway. O comando lê os metadados da transação de um explorador público Cardano (compatível com Koios ou Blockfrost), opcionalmente busca o conteúdo em gateways públicos de Arweave ou IPFS, valida o registro e checa quaisquer assinaturas. É justamente esse o objetivo do padrão: uma prova que você verificou uma vez continua verificável de forma independente por qualquer pessoa, sem confiar no emissor, no domínio dele ou no servidor dele.

Para um controle mais rígido, aponte o comando para sua própria fonte de dados e defina uma profundidade de confirmação:

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

Os dados vão para o stdout e os diagnósticos vão para o stderr, então a composição de comandos permanece limpa:

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

Para um olhar mais detalhado sobre o que um verificador realmente checa, veja como verificar um registro Label 309.

O que significam os códigos de saída?

Ramifique a partir do código de saída em vez de fazer parsing do texto legível por humanos — o código já indica a classe do resultado:

CódigoSignificado
0válido / sucesso
1falha de classe de integridade (uma verificação criptográfica ou estrutural falhou)
2falha de classe de rede ou um resultado não verificável (um erro de busca ou de transporte)
3pendente — geralmente confirmações insuficientes
4erro de entrada da CLI (argumentos inválidos ou entrada obrigatória ausente)

Para o verify, os códigos 0–3 mapeiam diretamente o veredito do verificador — valid, failed, unverifiable e pending, respectivamente — então o mesmo contrato vale, quer você leia o código de saída, quer leia o relatório --json.

Isso dá à automação uma política limpa:

  • 0: continue.
  • 1: faça a tarefa falhar — a verificação da prova ou do conteúdo falhou.
  • 2: tente novamente ou marque a execução como inconclusiva.
  • 3: aguarde e tente de novo após mais confirmações.
  • 4: corrija o script ou suas entradas.

Em um fluxo de lançamento, não trate pending como sucesso. Uma prova pendente pode liquidar mais tarde, mas ainda não é final.

Como publico uma prova a partir da automação?

Publicar exige um gateway, porque submete uma transação Cardano real e usa o saldo do seu gateway para pagar a taxa da transação e qualquer armazenamento no Arweave. (Para entender por que publicar custa algo, veja por que publicar tem um preço.)

Calcule o hash de um arquivo e ancore-o:

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

Ancore um digest pré-computado:

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

Ancore um lote Merkle montado a partir de uma lista de folhas:

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

Esses três modos se encaixam de forma clara em padrões comuns de automação. Uma tarefa pequena pode ancorar um único arquivo. Um sistema de lançamento pode ancorar o digest de um manifesto pré-computado. Um sistema de alto volume pode condensar muitos hashes de itens em uma única raiz Merkle e publicar um único registro. A primeira passagem completa está em publique sua primeira prova.

Execute cardanowall <command> --help para a lista de flags autoritativa e compatível com sua versão — essa é sempre a palavra final sobre as opções da build que você instalou.

Como configuro gateways uma vez em vez de a cada tarefa?

Embutir uma URL de gateway e uma chave de API em cada tarefa é frágil. Em vez disso, a CLI armazena perfis nomeados de gateway:

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

Em CI, forneça a chave pelo stdin em vez de responder a um prompt interativo:

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

O gateway de serviço é resolvido em uma ordem fixa: uma flag explícita vence, depois a variável de ambiente, depois o perfil ativo. Essa separação atende a ambos os ambientes — um desenvolvedor pode se apoiar em um perfil salvo, enquanto o CI injeta CARDANOWALL_BASE_URL e CARDANOWALL_API_KEY e dispensa o arquivo de configuração por completo.

Como mantenho os segredos fora da linha de comando?

Esse é o erro fácil de cometer, então torne-o difícil de cometer. Nunca coloque uma Identity Seed bruta ou uma chave de destinatário diretamente nos argumentos do comando — o argv vaza para o histórico do shell, os logs de CI e as listagens de processos (ps).

Em vez disso, use uma fonte de entrada segura:

  • --seed-stdin ou --seed-file;
  • --secret-key-stdin ou --secret-key-file;
  • uma variável de ambiente, apenas quando o tratamento de segredos do seu CI estiver limpo.

Por exemplo, passe a semente pelo stdin:

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

Um segredo deve vir de exatamente uma fonte; fornecê-lo de duas ao mesmo tempo (digamos, um --seed-file desatualizado mais CARDANOWALL_SEED) é um erro de entrada bloqueante, de modo que um valor antigo nunca consiga silenciosamente sobrepor o que você pretendia. As flags brutas --seed e --secret-key no argv ainda existem para valores de teste descartáveis, mas imprimem um aviso de uma linha no stderr quando usadas. Trate esse aviso como um controle real, não como ruído. E como as chaves nunca precisam viajar até um servidor para realizar esse trabalho, a semente permanece na máquina que executa o comando — o princípio por trás de por que as chaves nunca saem do dispositivo.

Como assino um registro em um pipeline?

Um registro assinado prova não apenas que o conteúdo existiu, mas que uma chave específica de um projeto ou organização atestou por ele. As assinaturas de autoria são sempre opcionais no Label 309 — uma prova somente de hash é igualmente válida —, mas elas são úteis quando a proveniência importa.

Para uma assinatura local direta, anexe a semente com segurança na própria publicação:

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

Para ambientes mais rígidos, mantenha a chave totalmente fora do host de build e assine em duas etapas:

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

Essa separação permite que um KMS, um HSM, uma estação de trabalho offline ou um serviço de assinatura protegido produza a assinatura Ed25519, enquanto o pipeline de automação cuida da montagem e da publicação do registro sem nunca tocar na chave privada.

Como agrupo milhares de artefatos em um único registro?

As raízes Merkle são o que permite a um fluxo de trabalho de CLI escalar. Em vez de uma transação por artefato, monte uma lista de folhas e ancore a raiz:

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

Mais tarde, prove uma única folha com sua prova de inclusão:

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

Isso se encaixa muito bem em evidências de lançamento de CI/CD, lotes de conteúdo gerado por IA, manifestos de conjuntos de dados, instantâneos de conformidade, arquivos de logs e pacotes de proveniência de mídia. Guarde a lista de folhas e as provas de inclusão junto com o resto das suas evidências de lançamento: a raiz na cadeia é apenas metade da história da verificação posterior. O padrão está detalhado em profundidade em um registro para milhares de arquivos, e o ângulo de CI em provas no seu pipeline de CI/CD.

Quando a automação deve lidar com registros selados?

A CLI também consegue trabalhar com PoE selado — registros cifrados endereçados a um ou mais destinatários:

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

Execute esses comandos apenas em máquinas autorizadas a deter a chave do destinatário. Não solte uma chave de destinatário em um ambiente de CI genérico, a menos que essa tarefa faça parte explicitamente do limite de processamento confiável do destinatário. Decifrar também produz texto claro: um processo que consegue decifrar pode, em princípio, vazar o que decifra, então coloque essa etapa no lugar a que a chave já pertence.

Para a maior parte da automação pública, você verificará provas assinadas ou somente de hash e nunca tocará em uma chave de destinatário. Recorra aos comandos de inbox selada quando estiver construindo um recebimento privado de evidências, uma entrega confidencial ou um arquivamento controlado.

O que uma tarefa de CI deve arquivar?

Arquive o relatório da prova, não apenas o hash da transação. Uma boa execução preserva:

  • a versão da CLI;
  • os argumentos do comando, com os segredos redigidos;
  • o manifesto de entrada ou o digest do arquivo;
  • o hash da transação;
  • a saída de publicação --json;
  • o relatório de verificação --json;
  • a lista de folhas Merkle e as provas de inclusão, se usadas;
  • a identidade do signatário de qualquer registro assinado;
  • os logs de novas tentativas para resultados pendentes ou não verificáveis.

Isso dá a futuros auditores contexto suficiente para reproduzir a checagem sem que ninguém precise reconstruir como uma tarefa de lançamento foi configurada meses antes.

Um padrão prático de lançamento

Uma tarefa de lançamento pode ter este formato:

  1. Construa os artefatos.
  2. Gere checksums, SBOMs, atestações e um manifesto de lançamento.
  3. Calcule o hash do manifesto ou monte uma lista de folhas Merkle.
  4. Publique com cardanowall submit.
  5. Capture o hash da transação e aguarde as confirmações.
  6. Execute cardanowall verify.
  7. Armazene os relatórios JSON junto com os artefatos de lançamento.
  8. Faça o lançamento falhar em failed; tente novamente ou segure o lançamento em pending e unverifiable.

Nada disso é complicado, e é esse justamente o ponto. A prova deve ser entediante o suficiente para rodar em todo lançamento.

Leitura adicional

cliautomationci-cd