Como verificar um registro Label 309

Você verifica um registro Label 309 diretamente da blockchain Cardano pública, partindo de uma única entrada: uma referência de transação Cardano. Nada na resposta depende da CardanoWall, de quem publicou o registro ou de algum servidor continuar online.

Um verificador busca os bytes brutos da transação na infraestrutura Cardano pública, extrai o rótulo de metadados 309, remonta o corpo do registro, confere o CBOR canônico e o esquema, verifica eventuais assinaturas de autoria e — quando os bytes do conteúdo ou uma carga cifrada estão disponíveis — recalcula os hashes. Toda a checagem é uma sequência de comparações criptográficas, não uma requisição a um serviço confiável.

O gateway que publicou o registro não é a autoridade. O registro é. Esse é o ponto do padrão: uma prova que você confere uma vez permanece conferível por qualquer pessoa, para sempre, com qualquer ferramenta em conformidade com Label 309.

Do que você precisa para verificar?

A entrada mínima é um hash de transação Cardano.

Apenas com esse hash de transação, um verificador consegue responder:

existe um registro Label 309 nesta transação?
o registro é estruturalmente válido?
a transação está liquidada com confirmações suficientes?
as assinaturas no nível do registro verificam, caso existam assinaturas?
quais hashes, URIs de armazenamento, raízes Merkle e envelopes selados o registro afirma?

Para provar que um arquivo específico é o arquivo por trás do hash, o verificador também precisa dos bytes do arquivo ou de um objeto de armazenamento atribuível referenciado pelo registro.

Para decifrar um registro selado, o verificador precisa da chave privada do destinatário. Essa chave é usada localmente e nunca é enviada de volta para quem publicou nem para a CardanoWall — toda a construção é projetada para que a verificação nunca precise contatar nenhum servidor.

O que um verificador realmente confere?

Um bom verificador deve conferir o registro em camadas.

A primeira camada é o validador estrutural. Esta é uma função pura sobre os bytes do registro. Ela não faz chamadas de rede, nenhuma decifração e nenhuma verificação de assinatura. Ela confere o CBOR canônico, os tipos de campo, o esquema fechado, os nomes de algoritmos registrados, as regras de URI e as restrições entre campos, como "deve haver ao menos um item ou um compromisso Merkle".

A segunda camada é o verificador público. Ele resolve a transação a partir de uma fonte de dados Cardano escolhida pelo verificador, vincula os bytes obtidos ao hash da transação, extrai o rótulo 309, confere a profundidade de confirmação e verifica as assinaturas do registro. Esta é a camada que uma auditoria pública, um job de CI ou um explorador podem executar.

A terceira camada é o verificador do destinatário. Ele faz tudo o que o verificador público faz e, em seguida, tenta decifrar os itens selados com a chave local do destinatário e recalcula os hashes do texto claro após a decifração.

Essas camadas importam porque nem toda prova precisa de toda checagem. Um registro somente de hash ainda pode ser válido mesmo sem nenhuma carga cifrada. Um verificador público consegue validar um registro assinado sem conseguir decifrar um arquivo selado.

Por que verificar a partir dos bytes brutos da transação, e não de uma visão JSON?

A verificação Label 309 funciona a partir dos dados brutos da cadeia, não de uma projeção JSON conveniente — e a diferença não é cosmética.

O registro é CBOR canônico. As assinaturas cobrem CBOR canônico exato em bytes. Os metadados de transação Cardano têm strings de bytes, strings de texto, arrays, mapas e regras de ordenação que o JSON não consegue preservar sem perda.

Por isso, um verificador deve buscar o CBOR bruto da transação, recalcular o id da transação, vincular os dados auxiliares ao corpo da transação e então remontar o array de chunks do rótulo 309 no corpo original do registro.

Um explorador pode ser uma infraestrutura útil. Ele não deve se tornar aquilo em que você confia. O verificador deve tratar as respostas do explorador como dados a vincular, conferir e cruzar com outras fontes.

O que há dentro de um registro Label 309?

Um registro Label 309 é carregado sob o rótulo de metadados de transação Cardano 309.

O valor na cadeia não é um objeto JSON solto. O corpo do registro é serializado uma vez como CBOR canônico e então transportado como um array de chunks de string de bytes, porque as strings de bytes e de texto dos metadados Cardano são limitadas a 64 bytes.

Após a remontagem, o corpo do registro é um único mapa CBOR. Suas chaves de nível superior são:

v, a versão do esquema (atualmente 1);
items, um array opcional de compromissos por conteúdo — cada item carrega um mapa hashes obrigatório e, opcionalmente, sua própria lista uris para armazenamento endereçado por conteúdo (ar://, ipfs://) e um envelope enc para conteúdo selado;
merkle, compromissos de lista opcionais que vinculam uma raiz na cadeia a uma lista de folhas fora da cadeia — a forma como grandes lotes são ancorados;
sigs, assinaturas de autoria opcionais no nível do registro;
supersedes, um ponteiro de substituição opcional, somente de acréscimo, para um registro anterior;
crit mais chaves de extensão com namespace, para acréscimos compatíveis com versões futuras.

Um registro em conformidade deve se comprometer com ao menos uma entrada items ou um compromisso merkle. As URIs de armazenamento e o envelope selado vivem dentro de um item, não no nível superior — um detalhe que vale acertar quando você mesmo analisa o registro.

A afirmação central é sempre centrada no conteúdo: estes hashes, ou esta raiz Merkle, foram ancorados nesta transação não depois do tempo do bloco.

Quais veredictos a automação deve esperar?

A verificação não deve reduzir todo problema a "válido" ou "inválido".

O modelo de verificador Label 309 usa quatro veredictos de máquina:

valid: toda checagem obrigatória passou.
failed: o próprio registro falhou em uma checagem estrutural, de assinatura ou de integridade atribuível.
unverifiable: uma checagem obrigatória não pôde ser concluída por motivos não atribuíveis ao registro, como infraestrutura indisponível ou conteúdo que não pôde ser obtido.
pending: a transação está na cadeia, mas abaixo do limiar de confirmação do verificador.

Essa distinção é importante em sistemas reais.

Se um gateway de armazenamento está fora do ar, o registro não deve ser condenado. Se os bytes obtidos são atribuíveis a uma URI comprometida e o hash deles não corresponde, o registro deve falhar. Se a transação tem apenas uma confirmação, o verificador deve dizer que ela está pendente em vez de fingir que a finalidade já ocorreu.

A CLI de código aberto cardanowall mapeia esses estados diretamente em códigos de saída, de modo que o veredicto sobrevive em um shell script sem analisar nenhum JSON:

cardanowall verify <tx-hash> --json

Código de saída	Veredicto	Significado
`0`	valid	toda checagem obrigatória passou
`1`	failed	uma checagem atribuível ao registro falhou (integridade, estrutura ou assinatura)
`2`	unverifiable	sem falha do registro, mas uma checagem obrigatória não pôde rodar (rede ou política)
`3`	pending	confirmações ainda insuficientes — nenhum resultado de um registro pendente é final
`4`	—	erro de entrada da CLI (argumentos inválidos ou entrada obrigatória ausente)

Essa distinção é exatamente o que você quer na integração contínua: o script consegue separar "a prova é ruim" (saída 1, e que um explorador defeituoso jamais consegue fabricar) de "tente novamente mais tarde" (saída 2). O mesmo verificador acompanha os SDKs em TypeScript, Python e Rust, então uma aplicação pode ler o relatório estruturado completo em vez de um código de saída. Para os padrões de como conectar isso a um pipeline, veja como usar a CLI em automação.

Como você verifica um arquivo?

Para uma prova de arquivo simples, o fluxo de trabalho é:

Pegue o hash da transação.
Busque e verifique o registro Label 309.
Identifique o algoritmo de hash e o digest comprometidos.
Calcule o hash dos bytes do arquivo localmente.
Compare o seu digest com o digest no registro.
Confira a profundidade de confirmação e o tempo do bloco.
Confira eventuais assinaturas do registro, caso existam.

Se o arquivo diferir em um único byte, o hash será diferente.

Essa é a força de uma prova por hash de conteúdo. Ela não prova que o arquivo é verdadeiro, legal, original ou valioso. Ela prova que os bytes exatos correspondentes ao hash existiam não depois do tempo do bloco ancorado, sujeito à política de finalidade do verificador.

Como você verifica um registro selado?

Um registro selado acrescenta conteúdo cifrado.

O registro público ainda se compromete com o hash do texto claro. O texto cifrado pode ser armazenado fora da cadeia, por exemplo através do Arweave ou do IPFS. O envelope na cadeia contém a informação necessária para que um destinatário pretendido recupere a chave de conteúdo localmente.

O verificador do destinatário deve:

Rodar primeiro o caminho de verificação pública.
Testar a chave privada fornecida contra os compartimentos selados.
Se um compartimento abrir, decifrar o texto cifrado.
Recalcular o hash do texto claro.
Compará-lo com o compromisso de hash na cadeia.

Essa checagem final de hash é a ponte entre "eu decifrei algo" e "este é o conteúdo exato que foi carimbado no tempo". Decifrar os bytes não basta por si só; o hash do texto claro recalculado tem que corresponder ao compromisso que o registro fez antes de qualquer coisa ser cifrada.

A chave do destinatário permanece local. A verificação não precisa de nenhuma conta CardanoWall confiável, de nenhum servidor emissor e de nenhum retorno à pessoa que publicou o registro. Um registro selado mantém seu texto claro confidencial para os detentores da chave — mas observe seus limites: ele não garante anonimato e, uma vez que um destinatário decifra o conteúdo, ele pode fazer o que quiser com o texto claro.

Como você verifica um compromisso Merkle?

Os compromissos Merkle são para lotes.

Em vez de publicar milhares de hashes diretamente em um registro, um produtor pode publicar uma única raiz Merkle e manter a lista ordenada de folhas e as provas de inclusão fora da cadeia.

Para verificar um item do lote:

Calcule o hash do item ou obtenha o digest da folha comprometida.
Verifique a prova de inclusão contra a raiz Merkle.
Confira que a raiz e o leaf_count estão no registro Label 309.
Verifique a transação Cardano e a profundidade de confirmação.

A raiz não basta por si só. O produtor ou o arquivo deve preservar a lista de folhas e as provas de inclusão. O Label 309 dá ao lote uma âncora pública; as evidências operacionais em torno do lote ainda precisam ser mantidas. É assim que um registro prova milhares de arquivos a um custo fixo na cadeia.

No que não se deve confiar?

Não confie no site de quem publica como fonte da verdade.

Não confie em uma captura de tela de uma transação.

Não confie em uma visão JSON de explorador como entrada criptográfica.

Não confie em um gateway de armazenamento apenas porque ele retornou bytes.

Não confie em selos de "verificado" que não dizem o que foi conferido.

O verificador deve ser capaz de produzir um relatório: hash da transação, fontes de dados Cardano usadas, profundidade de confirmação, tempo do bloco, digest do registro, resultados de assinatura, resultados de hash de conteúdo, resultados de busca no armazenamento, checagens Merkle e quaisquer checagens ignoradas.

Esse relatório é o que torna a prova utilizável em auditorias e automação.

O que a verificação não prova?

A verificação é precisa. Ela não deve ser supervalorizada.

Um registro Label 309 válido não prova, por si só:

a propriedade legal do conteúdo, nem direitos exclusivos sobre ele;
que o conteúdo é verdadeiro;
que quem publicou tinha permissão para publicá-lo;
que uma pessoa do mundo real controla uma chave de assinatura;
que um tribunal, regulador ou cliente aceitará a prova sem provas de apoio — a admissibilidade depende da jurisdição, e uma prova pode sustentar um caso, mas não substitui um advogado;
que o armazenamento fora da cadeia permanecerá disponível para sempre, a menos que a durabilidade do armazenamento seja mantida separadamente.

Ela prova a afirmação que o registro de fato faz: um hash ou uma raiz Merkle foi ancorado na Cardano, eventuais assinaturas sobre o registro verificaram e eventuais checagens de conteúdo ou de decifração corresponderam aos compromissos. Em outras palavras, ela estabelece tempo e integridade — não verdade, propriedade ou direitos.

Essa afirmação mais estreita é exatamente o que a torna útil. Para o limite completo do que um carimbo de tempo pode e não pode fazer, veja o que uma prova não prova.

Leitura adicional

O padrão Label 309, incluindo o pipeline de verificação completo, os estados de veredicto e o catálogo tipado de erros: label309.org.
O verificador de código aberto — a CLI cardanowall mais os SDKs em TypeScript, Python e Rust, que executam todos as mesmas checagens: github.com/cardanowall.
O Label 309 foi submetido ao processo de CIP da Cardano e está em análise pelos editores de CIP como uma proposta da categoria Metadata: o pull request aberto.