Publique sua primeira Proof of Existence na Cardano

A prova Label 309 mais simples é um hash ancorado na Cardano.

Você pega um arquivo, calcula seu hash criptográfico, publica esse hash em um registro Label 309 sob o rótulo de metadados 309 da Cardano e guarda o hash da transação resultante. Depois, qualquer pessoa com o arquivo original pode recalcular o hash e confirmar que o comprometimento correspondente estava na cadeia, no máximo, até o tempo do bloco da transação. Ninguém precisa do seu servidor, do seu domínio ou da sua identidade para verificar — basta a referência da transação e um explorador público da Cardano.

Esse é o primeiro nível de Proof of Existence (prova de existência). Tudo o mais se constrói a partir dele. Este guia percorre a publicação de uma prova, principalmente pela ferramenta de linha de comando cardanowall, e termina mostrando como confirmar que ela realmente funcionou.

O que você está publicando, de fato?

Ao criar uma prova básica, você não está publicando o arquivo em si.

Você está publicando um comprometimento com o arquivo: o seu digest. Um digest é uma impressão digital criptográfica de tamanho fixo. Se o arquivo mudar um único byte, o digest muda por completo. É essa propriedade que faz do hash um substituto confiável para os bytes exatos.

Uma prova somente de hash combina bem com coisas como:

contratos e faturas;
artefatos de lançamento e manifestos de build;
saídas de IA e instantâneos de conjuntos de dados;
documentos de políticas e pacotes de evidências;
somas de verificação que outro sistema já produziu.

A prova não revela o conteúdo do arquivo. Ela revela apenas o hash, o algoritmo de hash que você escolheu e quaisquer metadados opcionais que você decida incluir no registro. Para saber mais sobre quais campos vão parar na cadeia, veja o que vai para a blockchain.

O que você precisa antes de publicar?

Publicar exige um gateway. Verificar, não.

A verificação roda inteiramente a partir de dados públicos da cadeia. Publicar é diferente: algo precisa construir e submeter a transação Cardano, pagar a taxa de rede, cuidar da confirmação e — se você armazenar arquivos fora da cadeia — pagar o custo de armazenamento. Um gateway Label 309 é o serviço que faz tudo isso. O gateway de código aberto e as ferramentas em torno dele são agnósticos quanto ao gateway, então você aponta as ferramentas para o gateway do qual você tem uma chave.

Para sua primeira prova, você precisa de:

um arquivo ou um digest pré-calculado;
a URL base de um gateway Label 309;
uma API key ou um token de conta de curta duração para esse gateway;
saldo suficiente na sua conta do gateway;
opcionalmente, uma Identity Seed, se você quiser assinar o registro.

Se você usa o gateway hospedado da CardanoWall, a CardanoWall opera a conta do gateway e o saldo pré-pago por você. Se você roda seu próprio gateway, você mesmo abastece as carteiras Cardano e de armazenamento dele. De qualquer forma, publicar custa dinheiro porque taxas reais são pagas em seu nome — o tema de por que publicar tem um preço.

Por que o fluxo é cotar primeiro e só então publicar?

Um gateway nunca deveria publicar silenciosamente e surpreender você com uma conta. Por isso, toda publicação tem o mesmo formato em dois passos: travar um preço e então submeter.

Construa ou estime o registro.
Peça uma cotação ao gateway.
Receba um id de cotação e um detalhamento de preço (taxa de rede, armazenamento, margem de serviço).
Submeta o registro finalizado com aquela cotação.
Receba um id de registro do gateway na hora, enquanto a transação ainda está sendo submetida.
Acompanhe o status até a transação ser confirmada na cadeia.
Verifique o resultado de forma independente.

Uma cotação trava o preço por uma janela limitada — atualmente 15 minutos. Se ela expirar antes de você publicar, basta solicitar uma nova; o preço pode mudar se as taxas de câmbio mudaram, mas nada além disso se altera.

Esse padrão de dois passos é o que torna a automação segura. Seu script pode registrar a cotação, aplicar sua própria política de gastos e só então publicar — assim, um salto de preço ou um lote disparado por engano nunca consome seu saldo de forma descontrolada.

Publicar um arquivo com a CLI

Para um arquivo local, o fluxo de linha de comando é deliberadamente enxuto:

cardanowall submit \
  --file ./contract.pdf \
  --base-url https://your-gateway.example \
  --api-key "$CARDANOWALL_API_KEY"

A CLI calcula o hash do arquivo, constrói o registro Label 309, pede ao gateway para cotar e publicar e imprime o resultado. --base-url e --api-key também leem das variáveis de ambiente CARDANOWALL_BASE_URL e CARDANOWALL_API_KEY, então elas saem do comando no CI.

Para uso repetido, salve o gateway como um perfil nomeado em vez de passar o endpoint toda vez:

cardanowall gateway add prod --base-url https://your-gateway.example
cardanowall gateway use prod
cardanowall submit --file ./contract.pdf

O binário cardanowall é uma ferramenta nativa única e autocontida, sem runtime para instalar. Instale-o a partir do crates.io com cargo install cardanowall-cli (o crate é cardanowall-cli; o comando instalado é cardanowall), ou compile-o a partir do repositório de código aberto em github.com/cardanowall.

Como publicar um hash que você já tem?

Às vezes o digest já existe — vindo de um pipeline de build, de um registro de contêineres, de um processo de lançamento ou de um arquivo de dados. Nesse caso, publique o digest diretamente, sem nenhum arquivo envolvido:

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

O modo de hash padrão é sha2-256. Passe --alg blake2b-256 quando precisar desse algoritmo. O registro anota qual algoritmo você usou, para que um verificador saiba como recalcular o digest depois.

Publicar um hash pré-calculado também é a escolha certa quando o arquivo de origem é grande, sensível ou controlado demais para passar por uma ferramenta de propósito geral. A única coisa que importa é que os bytes exatos e o processo exato de hash continuem reproduzíveis — caso contrário, ninguém consegue recalcular um digest correspondente.

Você deve assinar o registro?

Assine o registro quando quiser provar que uma identidade Label 309 específica respondeu por ele.

Uma prova somente de hash diz: estes bytes existiam até este momento. Uma prova assinada acrescenta: e esta chave de assinatura está por trás deste registro exato. Essa afirmação extra importa para registros de lançamento de empresa, arquivos oficiais, pipelines de CI/CD, fluxos de trabalho de prova jurídica, logs de proveniência de IA e qualquer identidade pública e duradoura de quem publica.

As assinaturas são sempre opcionais. Uma prova não assinada ainda é uma prova de existência completa e totalmente verificável — o Label 309 é agnóstico quanto ao emissor por concepção, e um verificador nunca precisa confiar em quem publica. Assinar apenas responde a uma pergunta diferente: quem responde pelo registro, não se os bytes existiram.

A Identity Seed nunca deve ser enviada ao gateway. A CLI e o SDK são construídos de modo que a assinatura acontece localmente e somente a assinatura pronta trafega. Forneça a semente por --seed-stdin ou --seed-file em vez de um argumento --seed direto, porque argumentos de linha de comando vazam pelo histórico do shell, pelas listagens de processos e pelos logs de CI:

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

Você deve anexar o arquivo ou apenas o hash?

Você tem três opções, em ordem crescente do que você compromete na cadeia.

Somente hash. A prova menor e mais privada. É suficiente quando você já sabe que o arquivo será preservado em algum lugar que você controla. O registro carrega o digest e nada sobre recuperação.

Hash mais um link endereçado por conteúdo. Anexe uma URI ar:// (Arweave) ou ipfs:// (IPFS) para que verificadores possam buscar os bytes depois. O hash ainda decide se os bytes buscados correspondem — uma URI endereçada por conteúdo vincula os bytes ao próprio link, então um verificador nunca precisa confiar no gateway, no DNS ou no TLS para saber que buscou o arquivo certo.

Selado. Cifre o arquivo, armazene o texto cifrado fora da cadeia e coloque o envelope selado no registro. Este é o caminho para registros confidenciais, entrega a um destinatário nomeado e recuperação do conteúdo depois, caso sua cópia local seja perdida.

Para uma primeira prova, comece com somente hash. Adicione assinatura, armazenamento fora da cadeia, agrupamento Merkle ou entrega selada quando um caso de uso real exigir.

Como você sabe que realmente funcionou?

Não pare em “o gateway aceitou”. A prova só está completa quando a transação está na cadeia e verifica.

Quando você publica, o gateway devolve um id de registro na hora, e o hash da transação é preenchido de forma assíncrona assim que a transação é construída e submetida. Por isso, depois de publicar, guarde:

o hash da transação Cardano;
o id de registro do gateway, se você usou um gateway;
o arquivo original ou o digest;
a identidade pública da chave de assinatura, se você assinou;
qualquer lista de folhas Merkle ou prova de inclusão, se você agrupou;
qualquer material de recuperação, se a prova for selada.

Então verifique a transação da mesma forma que qualquer terceiro faria — a partir da cadeia pública, sem nenhum gateway envolvido:

cardanowall verify <tx-hash> --json

Um veredito valid é a linha de chegada. Os outros vereditos dizem o que fazer em seguida:

pending — a transação ainda não foi liquidada com confirmações suficientes. Aguarde mais confirmações e tente novamente.
unverifiable — nenhuma falha no registro, mas uma verificação necessária não pôde ser executada. Confira suas fontes de dados, a disponibilidade do armazenamento fora da cadeia e a política de rede.
failed — um problema real, atribuível ao registro. Investigue o próprio registro.

A separação entre failed e unverifiable é deliberada: failed significa que o registro está errado, enquanto unverifiable significa que o verificador não conseguiu concluir uma verificação. Para o fluxo completo de verificação, veja verifique um registro Label 309.

O que uma interface deve mostrar depois de publicar?

Uma boa interface mostra mais do que a palavra “publicado”. Para uma primeira prova, exponha:

o hash curto da transação, com um botão de copiar;
o hash completo da transação na visão de detalhes;
o algoritmo de hash e o digest;
o status da publicação;
o tempo do bloco, uma vez confirmado;
o veredito da verificação;
se o registro foi assinado;
se arquivos foram anexados ou selados;
se alguma verificação foi pulada.

Isso torna a prova compreensível sem obrigar ninguém a ler a especificação.

O que pode dar errado ao publicar?

A maioria das falhas de publicação é operacional, não misteriosa. A conta pode estar sem saldo. A cotação pode ter expirado. O registro pode ser grande demais para uma transação Cardano. Um arquivo enviado pode falhar ao ser armazenado. A transação Cardano pode falhar permanentemente — caso em que um gateway bem construído reverte a cobrança por conta própria, de modo que você só é cobrado pelo que chega à cadeia. Ou a carteira abastecida do gateway pode simplesmente precisar de atenção.

Um fluxo de publicação sério lida com novas tentativas de forma idempotente. Um gateway deduplica uma nova tentativa de publicação pelos bytes exatos do registro — ressubmeter o registro idêntico retorna o resultado existente em vez de gastar duas vezes — e aceita uma chave de idempotência em lotes de upload, de modo que um upload reentregue é seguro contra repetição. Em um produto voltado ao usuário, projete o caminho de nova tentativa antes que seu primeiro cliente real esbarre em um timeout de rede, não depois.

Se você está integrando isso a um pipeline, usar a CLI em automação aprofunda a saída em JSON, os códigos de saída e o manejo seguro de segredos.

O que sua primeira prova não prova?

Uma prova de existência é precisa quanto ao que afirma, o que significa que também é precisa quanto ao que não afirma.

Ela não prova propriedade.
Ela não prova autoria — a menos que você a assine e consiga vincular a chave de assinatura à identidade alegada.
Ela não prova que o arquivo é verdadeiro, lícito ou original.
Ela não preserva o arquivo, a menos que você o armazene em algum lugar durável.

O que ela prova é exato e durável: os bytes precisos que correspondem ao hash comprometido existiam, no máximo, até o tempo do bloco da transação, e quaisquer assinaturas opcionais, verificações de armazenamento ou verificações de conteúdo selado foram validadas conforme a política do verificador.

Isso é suficiente para ser genuinamente útil e preciso o bastante para merecer confiança. Para o limite mais completo do que um carimbo de tempo pode e não pode estabelecer, veja o que uma prova não prova.

Leituras complementares

Verifique um registro Label 309 — a outra metade do fluxo, sem confiança e sem conta.
Por que publicar tem um preço — o que a taxa paga.
Use a CLI em automação — saída em JSON, códigos de saída e segredos no CI.
O que vai para a blockchain — os campos que um registro de fato carrega.
O padrão aberto e as implementações de referência: label309.org e o código-fonte em github.com/cardanowall.