Cardano · Fundamentos técnicos

Guia de nivelamento técnico de Cardano

Fundamentos de representação e criptografia, funcionamento de Cardano e arquitetura de aplicações.

Sobre este guia

Este guia acompanha o workshop técnico de Cardano e pode ser consultado antes ou depois dos encontros. As aulas combinam explicações, exemplos executáveis e atividades com respostas comentadas.

Os exemplos executáveis usam Pyodide para rodar Python no navegador. Não é preciso instalar Python: o ambiente e as bibliotecas são carregados pela internet quando você executa o código. Essa execução exige JavaScript.

Edições de código, respostas e resultados ficam salvos localmente neste navegador, quando o armazenamento está disponível. Não há sincronização entre dispositivos; limpar os dados do site pode apagar esse trabalho.

Sem JavaScript, o texto, o código e as respostas comentadas continuam acessíveis, mas a execução e a correção automática ficam indisponíveis. Para gerar um PDF, use a função de imprimir do navegador.

Sumário

0

Bytes, hashes, chaves e assinaturas

Vamos partir de um arquivo para entender quais bytes um programa recebe e o que muda quando esses bytes são reescritos. A partir daí, calcularemos hashes e usaremos chaves para assinar mensagens, distinguindo o que cada verificação permite concluir e o que continua dependendo de outras evidências.

4 aulas
  1. 0.1Do texto aos bytesEntender por que verificação começa por uma representação exata.
  2. 0.2Do byte ao hashUsar hashes para conferir bytes e interpretar os limites dessa comparação.
  3. 0.3Chave privada e chave públicaSeparar as capacidades de assinar e verificar e reconhecer os cuidados com o segredo.
  4. 0.4Assinatura digitalAssinar uma mensagem, verificar a combinação recebida e interpretar os limites do resultado.
1

A rede Cardano e seu funcionamento

Acompanharemos uma operação desde a aplicação que a prepara até a rede que a verifica e registra. Veremos como endereços e saídas identificam valores e autorizações, como construir e conferir transações e como ativos e scripts permitem representar mudanças de estado sem entregar todas as responsabilidades à blockchain.

13 aulas
  1. 1.1A rede Cardano e as aplicaçõesEntender a rede e distinguir aplicação, serviço de acesso e protocolo.
  2. 1.2Arquitetura do node e erasSeparar rede, consenso, ledger e indexação sob regras versionadas.
  3. 1.3Ouroboros, slots, epochs e stakeRaciocinar sobre produção de blocos e políticas de confirmação.
  4. 1.4CIPs, governança e parâmetrosEntender como propostas técnicas e governança se relacionam com os parâmetros usados pelas aplicações.
  5. 1.5Endereços Shelley e credenciaisDistinguir pagamento e stake, comparar base, enterprise e reward e interpretar a rede de um endereço.
  6. 1.6Transação como pacote verificávelRelacionar corpo CBOR, body hash e bytes assinados por uma witness Ed25519.
  7. 1.7UTxO e eUTxOEntender o saldo mostrado pela carteira, acompanhar o consumo de saídas e reconhecer o papel do datum.
  8. 1.8Taxas, validade e CIP-30Calcular custos, fechar o corpo e mesclar witnesses recebidas por CIP-30 antes de submeter.
  9. 1.9MetadataCriar metadata com PyCardano e observar como uma mudança no texto altera seu hash.
  10. 1.10Ativos nativos e políticasIdentificar ativos, fechar sua conservação e construir políticas nativas de assinatura e tempo.
  11. 1.11ExplorersAbrir uma transação real e localizar seu identificador, bloco, taxa e tamanho.
  12. 1.12Plutus e transiçõesComparar datum, redeemer e contexto; distinguir fases de validação e planejar migração.
  13. 1.13CIP-68 e estadoRelacionar os dois assets por CIP-67 e distinguir leitura por referência de atualização do datum.
2

Eventos, provas, escala e privacidade

Um sistema pode preservar seus registros fora da blockchain e publicar referências que permitam verificá-los depois. Vamos construir esse caminho, do histórico de eventos à prova de um item, e avaliar o custo, a espera e a exposição dos dados. Também veremos quando a interação entre participantes justifica um Hydra Head.

4 aulas
  1. 2.1Eventos, encadeamento e checkpointsEncadear mudanças, detectar reescritas e acrescentar correções sem apagar o histórico.
  2. 2.2Árvores Merkle e provas de inclusãoConstruir uma raiz e verificar um item com os hashes irmãos e a ordem correta.
  3. 2.3Escala, lotes, custos e HydraMedir publicações e espera por lote e acompanhar o ciclo de vida de um Hydra Head.
  4. 2.4Privacidade e publicaçãoTestar hashes previsíveis, abrir compromissos com nonce privado e preservar somente o necessário.
Módulo 0

Bytes, hashes, chaves e assinaturas

Vamos partir de um arquivo para entender quais bytes um programa recebe e o que muda quando esses bytes são reescritos. A partir daí, calcularemos hashes e usaremos chaves para assinar mensagens, distinguindo o que cada verificação permite concluir e o que continua dependendo de outras evidências.

Módulo 0 Aula 0.1

Do texto aos bytes

Objetivos
  1. Codificar texto em UTF-8 e representar seus bytes em hexadecimal ou base64.
  2. Distinguir uma cópia exata de um arquivo de outra escrita dos mesmos dados.
Antes de começar

Para acompanhar esta aula, você precisa saber ler pequenos trechos de Python: reconhecer variáveis, textos, dicionários e chamadas de funções como print().

Você executará os exemplos na própria apostila, pelo botão Executar. Não é necessário instalar Python.

Pergunta-guia

O que precisa ser igual para que dois arquivos sejam cópias exatas?

1. O registro e o arquivo

Registros digitais ajudam a documentar o que foi feito. O resultado de um teste, por exemplo, pode ser apresentado como evidência em uma auditoria. Para avaliar essa evidência, precisamos considerar também de onde o registro veio e o que aconteceu com ele até chegar às nossas mãos.

O auditor recebe esse registro em um arquivo JSON gerado por um equipamento. Antes de chegar às suas mãos, porém, o arquivo passou por outra aplicação, que importou os dados e gerou uma nova exportação. Ela pode ter preservado todos os valores e ainda assim mudado a ordem dos campos e os espaços. O auditor precisa distinguir uma cópia exata do arquivo original de uma nova representação dos mesmos dados.

Suponha que o equipamento tenha gerado este registro em JSON, um formato de texto que organiza os dados em campos e valores:

{
  "registro": "T-0142",
  "equipamento": "EQ-17",
  "instante": "2026-09-10T14:30:00-03:00",
  "resultado": "falha de comunicação"
}

Para recuperar esses campos, a aplicação lê uma sequência de bytes gravada no arquivo. Cada byte reúne oito bits, que podem valer 0 ou 1, permitindo 256 valores diferentes. Uma codificação define como o texto é escrito nessa sequência. Tanto os valores do registro quanto as aspas, os espaços e as quebras de linha precisam ser codificados.

Em Python, o tipo str representa texto Unicode. Unicode atribui códigos numéricos aos caracteres: e recebe 101, e é recebe 233. Esses identificadores são chamados de pontos de código. UTF-8 define como representá-los em bytes. A operação encode("utf-8") produz esses bytes; decode("utf-8") recupera o texto.

dados = "é".encode("utf-8")
print(dados)
print(dados.decode("utf-8"))

Um caractere pode ocupar mais de um byte. A palavra café, por exemplo, tem quatro caracteres, mas ocupa cinco bytes em UTF-8: o é ocupa dois. Por isso, contar letras e espaços na tela não é o mesmo que medir o tamanho do arquivo.

textopontos de códigobytes UTF-8cU+006363aU+006161fU+006666éU+00E9c3a94 caracteres, 5 bytes
Os valores dos bytes estão escritos em hexadecimal.

2. Hexadecimal e base64

Para examinar os bytes do arquivo, podemos escrevê-los em hexadecimal: dois dígitos por byte, usando 0-9 e a-f. Os cinco bytes de café ficam 63 61 66 c3 a9. Os pares c3 a9 correspondem ao é.

Base64 também permite transportar bytes em campos de texto. Nessa representação, os mesmos cinco bytes ficam Y2Fmw6k=. Decodificar o hexadecimal 636166c3a9 ou essa base64 recupera a mesma sequência. Nenhuma das duas formas impede a leitura nem verifica se o conteúdo foi alterado.

import base64

dados = "café".encode("utf-8")
hexadecimal = dados.hex()
em_base64 = base64.b64encode(dados).decode("utf-8")

print(hexadecimal, bytes.fromhex(hexadecimal).decode("utf-8"), sep="\t")
print(em_base64, base64.b64decode(em_base64).decode("utf-8"), sep="\t")

3. Os mesmos dados, bytes diferentes

Na importação do registro, a aplicação recupera os campos e valores do JSON. Ao exportá-los, produz um novo texto, que pode ter outra formatação. Essa transformação é uma forma de serialização.

Original do equipamento
{ "registro": "T-0142", "equipamento": "EQ-17" }
Aplicação importa e exporta
Arquivo reexportado
{"equipamento":"EQ-17", "registro":"T-0142"}
Entregue ao auditor
Neste recorte do registro, os campos e valores são os mesmos. A ordem e o espaçamento mudaram, produzindo outros bytes.

Os acentos também podem ter representações diferentes. Unicode permite escrever é como um único ponto de código ou como e seguido de um acento agudo combinante. As duas formas podem parecer iguais na tela e produzir bytes diferentes. A normalização Unicode permite convertê-las para uma forma comum.

Uma reexportação pode mudar apenas a formatação ou também alterar os valores registrados. O arquivo recebido, sozinho, não revela o que mudou. Para conferir sua preservação, o auditor precisa de uma referência do registro original.

Atividade 1: interprete a comparação

O arquivo reexportado tem o mesmo tamanho em bytes do original. O auditor também confirmou que os dois JSONs contêm os mesmos campos e valores.

Qual alteração poderia passar despercebida nessas duas conferências?

0 de 1 pergunta respondida.

Conferir resposta

Trocar a ordem dos campos mantém o tamanho e os dados, mas muda a sequência de bytes. Portanto, essas duas conferências não comprovam que o arquivo seja uma cópia exata.

Atividade 2: recupere a mensagem

Execute o código para ver a mensagem preparada para envio em base64. Depois, altere a linha de mensagem_recuperada para que a saída volte a mostrar o texto original, com seus acentos. Use Validar solução para conferir o resultado.

import base64

mensagem_original = "falha de comunicação"
mensagem_em_bytes = mensagem_original.encode("utf-8")
mensagem_em_base64 = base64.b64encode(mensagem_em_bytes).decode("utf-8")
mensagem_recuperada = mensagem_em_base64

print(mensagem_recuperada)
Conferir resposta

Desfazer a base64 recupera os bytes da mensagem. Se a saída aparecer com b'...' e sequências como \xc3\xa7, o conteúdo já foi recuperado, mas ainda está sendo exibido como bytes. Interpretar essa sequência em UTF-8 devolve o texto legível, incluindo os acentos.

O que aprendemos

  • Unicode identifica caracteres por pontos de código. UTF-8 os codifica em bytes, e um caractere pode ocupar mais de um byte.
  • Hexadecimal e base64 representam bytes como texto e permitem recuperá-los. Não oferecem sigilo nem verificam alterações.
  • Importar e reexportar um JSON pode preservar os dados e mudar os bytes. Uma cópia exata precisa preservar todos os bytes do original.

Próxima aula

Você já viu que uma reexportação pode preservar os dados e mudar os bytes. Na próxima aula, usaremos esses bytes para calcular hashes: resumos que ajudam a detectar alterações no arquivo. Veremos também o que a comparação desses resumos permite concluir.

Módulo 0 Aula 0.2

Do byte ao hash

Objetivos
  1. Calcular o SHA-256 de uma mensagem codificada em UTF-8.
  2. Comparar hashes e explicar o efeito de uma alteração na mensagem.
  3. Reconhecer os limites dessa comparação, incluindo colisões e a origem da referência.
Antes de começar

Para acompanhar esta aula, você precisa saber converter texto em bytes UTF-8 e reconhecer a representação hexadecimal, como fizemos na Aula 0.1.

Pergunta-guia

O que a comparação de hashes permite concluir sobre os dados?

1. Referências baseadas no conteúdo

Programas podem precisar reconhecer conteúdos repetidos ou detectar alterações nos dados. Uma forma de apoiar essas tarefas é calcular uma referência a partir dos próprios bytes do conteúdo, em vez de depender apenas de nomes ou identificadores atribuídos a ele.

Uma função hash realiza esse cálculo. Ela transforma uma sequência de bytes em um valor de tamanho fixo, chamado hash.

Usaremos SHA-256, uma função hash criptográfica. Seu hash tem 256 bits, ou 32 bytes, que podem ser escritos com 64 caracteres hexadecimais.

café5 bytes
SHA-256
850f…bf4e
32 bytes
falha de comunicação22 bytes
SHA-256
d3b2…7a67
32 bytes
Mensagens em UTF-8 de tamanhos diferentes geram hashes de 32 bytes. Os hashes estão abreviados na figura.

Para observar o cálculo, use a mensagem falha de comunicação. O exemplo troca apenas f por F e mostra cada mensagem acompanhada de seu hash.

import hashlib

mensagem_original = "falha de comunicação"
mensagem_alterada = "Falha de comunicação"

mensagem_original_em_bytes = mensagem_original.encode("utf-8")
mensagem_alterada_em_bytes = mensagem_alterada.encode("utf-8")
hash_original = hashlib.sha256(mensagem_original_em_bytes).hexdigest()
hash_alterado = hashlib.sha256(mensagem_alterada_em_bytes).hexdigest()

print(mensagem_original, hash_original, sep="\t")
print(mensagem_alterada, hash_alterado, sep="\t")

A função hashlib.sha256 calcula o hash dos bytes, e hexdigest() escreve esse resultado em hexadecimal. A saída mostra dois hashes diferentes, ambos com 64 caracteres. Experimente outra alteração em mensagem_alterada e execute novamente.

falha de comunicação
d3b2d6009b1e4b0a06d8c7f213afcacce38aec7d16a8cc6866100b4c92457a67
Falha de comunicação
a7c21cccec0718c76999e1e77093840bb67b4d3ebcb28bf670a00eab3890448d
As diferenças estão sublinhadas. Neste par, uma letra mudou na mensagem e 61 das 64 posições hexadecimais mudaram no hash. Os dois hashes continuam com 32 bytes.

Se você repetir o cálculo sem alterar as mensagens, os hashes se repetirão. Com os mesmos bytes e o mesmo algoritmo, o resultado é sempre o mesmo. Essa propriedade é chamada determinismo.

No par observado, uma pequena alteração na entrada mudou grande parte do hash. Esse comportamento é chamado de efeito avalanche.

2. O que a comparação permite concluir

Usando o mesmo algoritmo, hashes diferentes demonstram que os bytes são diferentes. O hash não aponta o caractere modificado, não mede a semelhança entre os conteúdos e não informa se a alteração foi autorizada. Para localizar uma diferença, é preciso comparar os conteúdos.

Quando os hashes coincidem

Duas entradas diferentes podem produzir o mesmo hash. Essa coincidência é chamada de colisão. Por isso, hashes iguais não são uma garantia matemática de bytes iguais.

Entrada A Entrada B A ≠ B SHA-256 SHA-256 mesmo hash H
Esquema de uma colisão: cada entrada é processada separadamente, pelo mesmo algoritmo, e os resultados coincidem.

Colisões existem porque há mais entradas possíveis do que hashes de 256 bits. Uma função hash criptográfica segura, como o SHA-256, é projetada para tornar impraticável encontrá-las. Na prática, a igualdade dos hashes é tratada como forte evidência de igualdade dos bytes.

3. A referência corresponde a quais bytes?

Um hash é uma referência aos bytes usados no cálculo. Se o objetivo é conferir uma cópia exata, preservar apenas os campos e valores de um arquivo não basta.

Conferir um registro de teste

Considere um equipamento que gera um arquivo JSON com o resultado de um teste. Antes de ser usado como evidência em uma auditoria, esse arquivo passa por uma aplicação que importa e reexporta seus dados.

O equipamento calcula o SHA-256 do arquivo original, antes da reexportação. O auditor calcula o SHA-256 da versão recebida e compara os resultados. Uma nova escrita pode preservar os campos e valores e ainda produzir um hash diferente, porque os bytes mudaram. Essa conferência testa a preservação dos bytes, não apenas dos dados lidos. É uma verificação de integridade.

4. Preservar a referência

Para detectar mudanças em relação a uma versão anterior, é preciso ter uma referência preservada dessa versão. Se alguém substituir tanto o conteúdo quanto o hash guardado, a comparação poderá coincidir sem revelar a substituição.

Por isso, importa saber de onde veio o hash de referência e como ele foi protegido. O cálculo, sozinho, não identifica quem produziu o conteúdo: qualquer pessoa com os bytes pode calcular o mesmo hash.

5. Hash não é sigilo

Um hash não é uma codificação reversível como a base64. Não há uma operação de decodificação que recupere o conteúdo original a partir dele. Isso, porém, não impede testar possibilidades.

Se você souber que um texto é uma das duas mensagens do exemplo, poderá calcular os dois hashes e descobrir qual corresponde ao hash observado. Não foi necessário inverter o cálculo, apenas comparar resultados. Publicar um hash pode, portanto, revelar informação sobre um conteúdo previsível.

Atividade: compare antes de descartar

Um programa encontrou dois arquivos com o mesmo SHA-256 e pretende manter apenas uma cópia. A regra é não descartar nenhum arquivo cujos bytes sejam diferentes dos que serão mantidos.

Qual conferência atende a essa regra?

0 de 1 pergunta respondida.

Conferir resposta

A alternativa C é a correta. O hash ajuda a encontrar possíveis cópias; a comparação direta confirma se todos os bytes são iguais antes de descartar uma delas. Arquivos diferentes podem ter o mesmo tamanho. Repetir o SHA-256 reproduz o resultado. Outro hash criptográfico seguro pode reduzir o risco de coincidência, mas não substitui a comparação exata exigida neste caso.

O que aprendemos

  • Um hash é calculado a partir dos bytes. Com a mesma entrada e o mesmo algoritmo, o resultado se repete.
  • Hashes diferentes indicam bytes diferentes. Hashes iguais são forte evidência de igualdade, mas colisões são possíveis.
  • Uma verificação de integridade depende de saber quais bytes foram usados e de preservar a referência.
  • Hash não identifica o autor nem protege conteúdos previsíveis contra tentativas de adivinhação.

Próxima aula

Um hash pode ser calculado por qualquer pessoa que tenha os bytes. Na próxima aula, veremos como um par de chaves separa a capacidade de assinar da de verificar, sem compartilhar o segredo usado para assinar.

Módulo 0 Aula 0.3

Chave privada e chave pública

Objetivos
  1. Distinguir as funções da chave privada e da chave pública em uma assinatura.
  2. Gerar bytes aleatórios para estudo e explicar por que uma frase previsível não os substitui.
  3. Reconhecer a exposição de um segredo, mesmo quando ele aparece em outra representação.
Antes de começar

Para acompanhar esta aula, você precisa reconhecer bytes e sua representação hexadecimal e saber que qualquer pessoa com os mesmos bytes pode repetir o cálculo de um hash.

Pergunta-guia

Como permitir a verificação sem compartilhar a capacidade de assinar?

1. Verificar sem receber o segredo

Ao receber uma mensagem, um programa pode precisar conferir um vínculo com uma chave conhecida. Um hash calculado apenas sobre a mensagem não cria esse vínculo: qualquer pessoa que tenha os bytes pode repetir o cálculo.

Uma assinatura digital depende também de um segredo. O desafio é permitir que outras pessoas a confiram sem lhes entregar esse segredo e, com ele, a capacidade de produzir assinaturas.

Um par de chaves separa essas funções. A chave privada permite assinar e precisa ficar protegida. A chave pública, matematicamente relacionada à privada, permite verificar e pode ser compartilhada. Em um esquema seguro, conhecer a pública não torna viável recuperar a privada nem forjar assinaturas.

Chave privadaPermite assinar.
Fica sob custódia.
derivar
Chave públicaPermite verificar.
Pode ser compartilhada.
O procedimento do esquema obtém a parte pública a partir do material privado. Com parâmetros seguros, o caminho inverso deve ser computacionalmente impraticável.

2. Gerar um segredo imprevisível

Nome, data ou frase comum oferecem possibilidades que um atacante pode testar. Calcular o hash desses dados não remove a previsibilidade: basta repetir a transformação em cada tentativa. O comprimento do resultado, por si só, não indica a dificuldade de adivinhar sua origem.

A geração de chaves usa uma fonte de aleatoriedade apropriada para segurança. A incerteza sobre o valor gerado é descrita pela entropia. Em Python, o módulo secrets permite obter bytes dessa fonte.

Execute o exemplo para gerar 32 bytes e vê-los em hexadecimal. O valor é exposto na saída e pode ficar salvo no navegador: use-o apenas para estudo, nunca como segredo de um sistema real.

import secrets

segredo = secrets.token_bytes(32)

print(segredo.hex())
print(len(segredo), "bytes")

A chamada token_bytes(32) retorna um objeto bytes. len(segredo) informa seu tamanho, enquanto hex() escreve cada byte com dois caracteres. Execute novamente: você verá uma nova amostra, também com 32 bytes. A aparência dos resultados não comprova a qualidade da fonte; a escolha de secrets é o que importa aqui.

Esses bytes são material para estudar a geração de segredos, não uma chave pronta para qualquer algoritmo. Para gerar um par de chaves real, uma biblioteca criptográfica aplica os procedimentos e formatos do esquema escolhido.

3. A parte pública não é outra escrita do segredo

Obter a chave pública a partir do material privado é uma derivação definida pelo esquema. Não basta escolher dois números aleatórios e chamar um de privado e o outro de público: eles precisam ter a relação matemática que permite assinar e verificar.

Essa derivação também não é uma conversão para hexadecimal ou base64. Essas representações preservam o valor e podem ser desfeitas. Se alguém receber a chave privada em hexadecimal, terá recebido a própria chave privada, não uma chave pública.

A chave pública pode circular sem oferecer a capacidade de assinar, mas seu valor não informa sozinho a quem ela pertence. Para verificar uma assinatura de uma pessoa ou equipamento específico, é preciso confirmar essa associação, por exemplo em um cadastro confiável ou por outro canal já conhecido.

4. Proteger todas as cópias

Considere uma aplicação que assina mensagens e registra seu funcionamento em um log. Esse registro pode ser encaminhado a uma equipe de suporte. Se contiver a chave privada, levará junto uma cópia do segredo, mesmo que o arquivo original da chave tenha acesso restrito.

O mesmo cuidado vale para configurações, cópias de segurança e conversas. Proteger o armazenamento e controlar quem acessa o material privado fazem parte da custódia da chave. O necessário para investigar uma falha de verificação são a mensagem, a assinatura e a chave pública usada, não a chave privada.

5. O efeito de uma cópia indevida

Suponha que outra pessoa tenha copiado a chave privada de um log. Ela passa a poder produzir assinaturas que serão verificadas com a mesma chave pública do emissor. O cálculo não distingue duas pessoas que usam o mesmo segredo.

Emissor Mantém a chave.
Pode assinar.
cópia
Quem copiou Tem o mesmo segredo.
Também pode assinar.
Copiar o segredo não o retira do emissor. Os dois passam a ter a capacidade de produzir assinaturas verificáveis com a mesma chave pública.

Apagar o log não desfaz cópias já obtidas. É preciso interromper o uso do par comprometido, gerar um substituto e atualizar as referências dos verificadores por um procedimento confiável. As assinaturas do período de exposição também precisam ser investigadas; o resultado da verificação, sozinho, não revela quem as produziu.

Atividade 1: avalie a exposição

Uma chave privada apareceu em hexadecimal num log compartilhado com a equipe de suporte. A equipe apagou o log e continuou usando o mesmo par de chaves.

Qual avaliação dessa decisão é correta?

0 de 1 pergunta respondida.

Conferir resposta

A alternativa B é a correta. Hexadecimal e base64 preservam o segredo em representações reversíveis. Apagar um arquivo não elimina cópias já obtidas, e assinaturas produzidas por quem copiou a chave podem continuar válidas. A exposição exige tratar a custódia e substituir o par, sem esperar uma falha de verificação.

Atividade 2: retire o segredo da saída

O programa abaixo deveria registrar apenas o tamanho do material gerado, mas está expondo seu valor. Execute para observar a saída. Depois, altere a linha de registro para mostrar a quantidade de bytes, sem reduzir nem exibir o segredo. Use Validar solução para conferir.

import secrets

segredo = secrets.token_bytes(32)
registro = segredo.hex()

print(registro, "bytes")
Conferir resposta

O tamanho é uma informação sobre o segredo, não uma escrita de seu valor. A função que conta os bytes permite obter essa quantidade sem converter nem expor o conteúdo. A saída deve mostrar 32 bytes. Converter para base64 ou omitir apenas alguns caracteres não atende ao pedido de registrar somente o tamanho.

O que aprendemos

  • A chave privada permite assinar; a pública permite verificar. A relação entre elas é definida pelo esquema criptográfico.
  • Segredos precisam de geração imprevisível. Um hash não acrescenta a entropia que falta a uma frase comum.
  • Hexadecimal e base64 não protegem uma chave privada. Logs, configurações e backups podem expor cópias dela.
  • A verificação não identifica quem usou uma cópia do segredo. A associação da chave pública ao emissor e a custódia precisam de cuidados próprios.

Próxima aula

Você já distinguiu as capacidades de assinar e verificar. Na próxima aula, vamos acompanhar as duas operações sobre uma mensagem: produzir uma assinatura com a parte privada e conferi-la com a parte pública. Também veremos o efeito de alterar os bytes recebidos.

Módulo 0 Aula 0.4

Assinatura digital

Objetivos
  1. Identificar as entradas e saídas da assinatura e da verificação.
  2. Assinar uma mensagem e observar o efeito de uma alteração na verificação.
  3. Distinguir uma verificação válida de uma confirmação de identidade, verdade ou permissão.
Antes de começar

Para acompanhar esta aula, você precisa saber converter texto em bytes UTF-8 e distinguir a chave privada da chave pública.

Pergunta-guia

O que uma assinatura válida permite concluir sobre a mensagem recebida?

1. Uma relação que pode ser verificada

Uma aplicação pode precisar conferir se uma mensagem foi assinada com uma chave que ela reconhece. Essa verificação deve funcionar tanto para mensagens que acabam de chegar quanto para registros guardados, sem exigir acesso ao segredo de quem assinou.

Uma assinatura digital é uma sequência de bytes calculada com a chave privada sobre uma mensagem. Para verificá-la, o programa reúne a mensagem em bytes, a assinatura e a chave pública escolhida. O resultado informa se essa combinação é válida segundo o esquema criptográfico.

Uma rubrica digitalizada é uma imagem que pode ser copiada para outro documento. A assinatura criptográfica depende dos bytes assinados, não de uma aparência visual. Em um esquema seguro, alterar a mensagem e recalcular seu hash não basta para produzir uma assinatura válida com a chave do emissor.

falha de comunicaçãomensagem em UTF-8
chave privada
assinar
assinatura
novo dado calculado
falha de comunicaçãobytes recebidos
assinatura
chave pública
verificar
válida ou inválidapara esta combinação
Assinar recebe a mensagem e a parte privada e produz a assinatura. Verificar reúne três entradas e devolve um resultado; a parte privada não entra nessa etapa.

2. Assinar e verificar uma mensagem

Usaremos Ed25519 por meio da biblioteca cryptography. O exemplo gera um par de chaves, assina uma mensagem e verifica duas versões dela.

from cryptography.hazmat.primitives.asymmetric import ed25519
from cryptography.exceptions import InvalidSignature

chave_privada = ed25519.Ed25519PrivateKey.generate()
chave_publica = chave_privada.public_key()

mensagem_original = "falha de comunicação"
assinatura = chave_privada.sign(mensagem_original.encode("utf-8"))

for mensagem_recebida in [mensagem_original, "Falha de comunicação"]:
    try:
        chave_publica.verify(assinatura, mensagem_recebida.encode("utf-8"))
        print("Assinatura confere:", mensagem_recebida)
    except InvalidSignature:
        print("Assinatura não confere:", mensagem_recebida)

sign() produz a assinatura em bytes. O laço for repete a verificação para as duas mensagens, mantendo a mesma assinatura e a mesma chave pública. Quando a combinação não confere, a biblioteca sinaliza InvalidSignature, tratado pelo bloco except.

A primeira mensagem confere; a segunda não. Experimente outra alteração no segundo texto e execute novamente.

3. Preservar os bytes assinados

O texto alterado continua legível, mas seus bytes já não correspondem à mensagem assinada.

Considere agora um equipamento que assina os bytes de um arquivo JSON com o resultado de um teste. Uma aplicação importa seus dados e reexporta o arquivo. Mesmo preservando campos e valores, essa nova escrita pode mudar os bytes. A assinatura foi produzida para a representação anterior.

Quem verifica precisa preservar os bytes assinados ou reconstruí-los por uma regra exata, combinada antes da assinatura. Dizer apenas que os dois arquivos contêm o mesmo JSON não define quais bytes entram no cálculo.

4. Escolher a chave pública esperada

Uma falha de verificação não aponta sozinha a causa. A mensagem pode ter mudado, a assinatura pode estar danificada ou a chave pública escolhida pode não ser a correspondente. O teste avalia a combinação, não cada entrada isoladamente.

Suponha que alguém apresente uma mensagem, uma assinatura e uma chave pública, todas preparadas por essa pessoa. A combinação pode ser válida. Isso não demonstra que a chave seja de quem você esperava receber a mensagem.

A associação com uma pessoa ou equipamento precisa vir de uma referência confiável, como um cadastro ou uma confirmação por outro canal conhecido. Um nome escrito na mensagem também é apenas uma declaração. E, como vimos na aula anterior, a verificação não revela se a parte privada foi copiada.

5. O que continua fora do cálculo

Uma assinatura pode ser válida para a mensagem falha de comunicação mesmo que o equipamento não tenha sofrido essa falha. O cálculo não observa o teste. Conferir o acontecimento exige evidências do processo; saber se o responsável podia aprovar o registro exige regras de autorização.

A mensagem também continua legível. Assinar não cifra seu conteúdo nem impede cópias. Quando é necessário restringir a leitura, entram mecanismos de confidencialidade, como cifragem e controle de acesso às chaves de leitura.

Atividade: interprete duas verificações

Um sistema guarda a chave pública confirmada de uma pessoa. Chega uma mensagem com uma assinatura e uma nova chave pública. A assinatura passa na verificação com a chave recebida, mas falha com a chave já cadastrada.

Que conclusão o sistema pode tirar?

0 de 1 pergunta respondida.

Conferir resposta

A alternativa C é a correta. Os testes usaram chaves diferentes, portanto não avaliaram a mesma combinação. Pode haver uma troca legítima de chave ou uma substituição indevida; a verificação não decide isso. A nova associação precisa ser confirmada antes de alterar o cadastro. A falha com a chave antiga também não comprova, isoladamente, alteração da mensagem ou corrupção da assinatura.

O que aprendemos

  • Assinar recebe a mensagem em bytes e a parte privada. Verificar recebe a mensagem, a assinatura e a parte pública.
  • A verificação depende dos bytes apresentados e da chave escolhida. Uma falha não identifica sozinha qual entrada está errada.
  • Uma assinatura válida não confirma, por si só, a identidade de uma pessoa, a verdade do conteúdo ou a permissão para aprová-lo.
  • Assinar não esconde a mensagem. Restringir a leitura exige mecanismos adicionais.

Para revisar os limites da comparação por hashes, retome a atividade da Aula 0.2.

Próxima aula

Até aqui, os programas puderam representar dados, calcular hashes e conferir assinaturas sem participar de uma rede pública. Na próxima aula, veremos como aplicações usam a infraestrutura da Cardano e quais responsabilidades ficam em cada lado. As operações que estudamos continuam presentes, mas a rede também precisa de regras para aceitar e ordenar as operações recebidas.

Referências do Módulo 0

Especificações de representação de dados, funções hash, assinaturas e proteção de segredos.

Módulo 1

A rede Cardano e seu funcionamento

Acompanharemos uma operação desde a aplicação que a prepara até a rede que a verifica e registra. Veremos como endereços e saídas identificam valores e autorizações, como construir e conferir transações e como ativos e scripts permitem representar mudanças de estado sem entregar todas as responsabilidades à blockchain.

Módulo 1 Aula 1.1

A rede Cardano e as aplicações

Uma infraestrutura pública, operada por participantes diferentes, que aplicações independentes podem usar.

Objetivos
  1. Distinguir a aplicação, os serviços de acesso e os nós da rede.
  2. Diferenciar uma consulta, a submissão de uma transação e sua inclusão no histórico.
  3. Explicar por que mudar uma interface não altera as regras da rede nem apaga os registros publicados.
Antes de começar

Os conceitos de hash e assinatura do Módulo 0 ajudam a acompanhar esta aula. Você não precisa conhecer blockchain nem instalar uma carteira.

Pergunta-guia

O que uma aplicação faz por conta própria e para quais operações recorre à rede Cardano?

1. A aplicação e a infraestrutura que ela usa

Uma aplicação web costuma ter uma interface, serviços que recebem solicitações e algum lugar para guardar dados. Quando alguém envia um formulário, por exemplo, a aplicação verifica os dados recebidos e decide o que registrar. Quem desenvolve esse sistema pode mudar suas regras, reorganizar o armazenamento ou trocar a interface conforme o produto evolui.

Quando essa aplicação usa Cardano, ela se conecta a uma rede que já existe e que outras aplicações também utilizam. Algumas solicitações buscam informações já registradas; outras propõem novas operações. Consultar esses dados e pedir a inclusão de uma operação são dois usos diferentes da rede.

Cardano é uma rede pública de computadores conectados pela internet e operados por pessoas e organizações diferentes. Esses computadores são os nós. Eles trocam informações sobre as operações e conferem o que recebem antes de aceitar uma mudança no registro que mantêm. O conjunto comum de regras que orienta essa comunicação e essas verificações é o protocolo.

NÓNÓNÓNÓ REDE CARDANO
Os círculos representam nós; as linhas, conexões para troca de informações. O desenho é esquemático: a rede real tem muitos nós, e cada um se conecta a uma parte deles.

Uma rede pública

Quem desenvolve uma aplicação pode consultar os dados públicos da Cardano e construir serviços que os utilizem. Também é possível operar um nó, assumindo o trabalho de manter esse software conectado e atualizado. A participação na rede não depende de pertencer à organização que criou uma aplicação específica.

Os operadores dos nós podem ser pessoas ou organizações diferentes. Isso importa porque distribuir servidores por vários lugares não é suficiente para distribuir o controle: uma empresa pode manter todos eles e decidir sozinha quais operações aceita.

Na Cardano, cada nó verifica as operações que recebe. Se um operador modificar o software do seu nó para aceitar uma operação sem a assinatura exigida, os outros nós que seguem o protocolo vão rejeitá-la por falta dessa assinatura.

Implementações de nó

O programa que um operador instala é uma implementação do nó. O cardano-node é a implementação de referência em Haskell, desenvolvida originalmente pela Input Output Global (IOG). Outros projetos desenvolvem implementações próprias, em diferentes linguagens:

  • Amaru, em Rust, da PRAGMA.
  • Dingo, em Go, da Blink Labs.

Esses programas podem organizar o código de formas diferentes, mas, para participar da mesma rede Cardano, precisam ser compatíveis na comunicação e aplicar as mesmas regras de verificação. A assinatura exigida no exemplo anterior precisa ser conferida independentemente da linguagem em que o nó foi escrito.

Os projetos têm estágios e limitações diferentes. Antes de usar uma versão para operar um nó, confira no respectivo repositório quais funções e redes ela suporta e se os mantenedores recomendam seu uso em produção. Para conhecer outros projetos, consulte o catálogo de nós da Cardano no Cardano Developer Portal.

2. Como a aplicação consulta a rede

A aplicação pode consultar os dados da Cardano por uma API, uma interface de comunicação entre programas. Ela envia uma solicitação a um serviço conectado à rede e recebe uma resposta com as informações pedidas.

Do registro à resposta da consulta

O nó acompanha os registros da rede, mas uma aplicação pode precisar pesquisar essas informações de várias formas. Para atender a consultas por período ou por identificador, por exemplo, um serviço pode usar um indexador: um software que lê os dados do nó e os organiza em um banco de dados para consulta. A API pode buscar a resposta nesse banco, sem percorrer o histórico inteiro a cada solicitação. Você pode conhecer exemplos no catálogo de indexadores.

Serviços como o Blockfrost e o Koios oferecem APIs para consultar dados da Cardano. Quem desenvolve a aplicação pode usar esses serviços ou operar um nó com seus próprios serviços de consulta. Nesse segundo caso, também será necessário cuidar da atualização dos dados e manter o acesso disponível. Outras opções de acesso estão no catálogo de provedores de API.

rota de acessoO serviço de acesso conecta a aplicação à rede.
Neste caminho, a aplicação usa a API de um provedor para consultar dados e enviar operações. O provedor mantém a conexão com a rede e os serviços que atendem à aplicação.

Um provedor pode exigir cadastro, limitar consultas ou cobrar pelo acesso. Essas condições pertencem ao serviço oferecido. Trocar de provedor pode exigir novas credenciais, outras chamadas de API e adaptações aos formatos de resposta, embora a aplicação continue consultando a mesma rede.

Se a API parar de responder, a aplicação pode ficar sem os dados que precisa mostrar. O erro indica uma falha naquele caminho de consulta; ele não informa, por si só, se os nós continuam aceitando operações. Também é possível receber uma resposta com dados atrasados, caso o serviço ainda não tenha acompanhado os registros mais recentes.

3. Como uma operação entra no registro

Consultar um dado já publicado não acrescenta uma operação ao histórico. Para propor uma mudança, a aplicação precisa preparar uma transação. Ela descreve o que se pretende fazer e reúne as autorizações exigidas, em um formato que os nós conseguem verificar.

Uma transferência de ADA, a moeda da Cardano, é um exemplo: a transação informa quais fundos serão usados e para onde vão. Os nós conferem as autorizações, como as assinaturas estudadas no Módulo 0, e verificam se esses fundos ainda estão disponíveis. Uma transação também pode publicar dados ou criar outros ativos digitais, desde que cumpra as regras correspondentes.

Enviar e acompanhar o resultado

A transação preparada precisa chegar a um nó. A aplicação pode enviá-la por um serviço de submissão, que recebe os dados e os encaminha à rede. Esse serviço pode estar disponível na mesma API usada para consultas. A mensagem de que o serviço recebeu o envio confirma essa etapa; ainda é necessário acompanhar o resultado para saber se a operação entrou no histórico.

As verificações feitas pelos nós podem impedir a aceitação da transação. Se faltar uma assinatura exigida, por exemplo, reenviar os mesmos dados por outro provedor não supre essa falta. As credenciais usadas para acessar a API autorizam o uso do serviço; elas não substituem as autorizações exigidas na transação. A operação também precisa cobrir as taxas da rede, que são distintas de uma eventual cobrança do provedor.

O histórico e o estado atual

Os nós que produzem blocos reúnem transações e propõem sua inclusão no histórico. Os demais nós verificam os blocos recebidos. Cada bloco traz uma referência ao anterior por meio de um hash; essas ligações formam a blockchain, ou cadeia de blocos. A escolha de qual cadeia acompanhar segue as regras de consenso do protocolo.

A verificação de uma nova transação depende do resultado das anteriores. O ledger reúne o estado atual da rede, como os recursos disponíveis para movimentação, e as regras usadas para atualizá-lo. Cada nó aplica essas regras às transações dos blocos que aceita. Esse estado pode ser reconstruído a partir do histórico da blockchain.

Depois do envio, a aplicação pode consultar uma fonte que indique a inclusão da transação em um bloco. Essa observação é diferente da resposta inicial do serviço de submissão. Conforme o uso e o risco, a aplicação pode aguardar mais blocos antes de tratar a operação como concluída. Esse é um exemplo de política de confirmação, que será discutida na Aula 1.3.

4. O que continua na aplicação

As regras da interface e as regras da rede

Desabilitar um botão de envio pode evitar um engano na interface, mas alguém ainda pode tentar construir a transação por outro programa. Quando uma autorização é exigida pelo protocolo, os nós a verificam independentemente da interface usada. Por isso, quem desenvolve a aplicação precisa saber quais restrições existem apenas em seu software e quais também serão verificadas pela rede.

Outras aplicações podem consultar os mesmos registros

Uma carteira consulta ativos e organiza o uso de chaves para autorizar movimentações. Um sistema de relatórios pode usar os mesmos registros para apresentar um histórico de operações. Cada aplicação organiza a informação conforme sua finalidade; a que criou uma transação não precisa ser a única capaz de consultá-la.

Escolher o que será publicado

A aplicação pode precisar guardar dados pessoais dos usuários e documentos que não devem se tornar públicos. Esses dados precisam de armazenamento e controles de acesso próprios. Usar Cardano não exige publicar todo o conteúdo do sistema; é necessário escolher quais informações podem fazer parte de uma transação pública.

Depois de publicada, uma informação pode ser copiada e consultada fora da aplicação. Retirá-la de uma tela muda a apresentação, mas não apaga a publicação da blockchain. Isso precisa ser considerado antes do envio, quando ainda é possível decidir o que divulgar.

A interface, os documentos e os serviços privados também continuam precisando de hospedagem e manutenção. Quem opera a aplicação cuida desse funcionamento e das informações que ela mostra ao usuário. A rede verifica as operações recebidas segundo o protocolo, sem assumir a operação desses outros serviços.

Atividade 1: acompanhe a consulta e o envio

Uma aplicação usa a API de um provedor para consultar registros e enviar transações a Cardano. Em cada situação abaixo, escolha a conclusão sustentada pelo que foi observado.

1. Ao consultar um histórico, a aplicação recebe da API a mensagem “serviço indisponível”. Nenhum dado é devolvido. Qual mensagem a aplicação pode mostrar ao usuário?

2. Ao enviar uma transação, a aplicação recebe a resposta “recebida para encaminhamento”. Essa resposta não informa um bloco. O que ela confirma?

3. Um nó rejeita uma transação porque falta uma assinatura exigida. A aplicação reenvia os mesmos dados por outro provedor, sem acrescentar a assinatura. O que muda?

4. Um site passa a ocultar um registro já publicado, mudando apenas o filtro de exibição da página. Qual é o alcance dessa alteração?

0 de 4 perguntas respondidas.

Conferir resposta
  1. A primeira alternativa descreve o que foi observado: a consulta falhou naquele serviço. Uma falha ao obter dados não demonstra que o histórico está vazio nem que a produção de blocos parou. Retome o caminho da consulta se você atribuiu o erro diretamente à rede.
  2. A segunda alternativa distingue o recebimento pelo serviço da inclusão no histórico. A ausência de um bloco nessa resposta também não demonstra rejeição. É preciso acompanhar o resultado do envio, como descrito em Como uma operação entra no registro.
  3. A terceira alternativa mantém a exigência da assinatura. Credenciais da API permitem usar o serviço de acesso, mas não autorizam o gasto dos fundos. O novo provedor pode receber o envio; os mesmos dados continuam sem atender à condição exigida pelos nós.
  4. A primeira alternativa limita a mudança à página em que o filtro foi aplicado. O site não apagou o registro da rede nem alterou o serviço consultado por outras aplicações. O indexador acompanha dados da rede, não as decisões de exibição de cada site. Retome a escolha do que publicar para rever essa diferença.

O que aprendemos

  • A aplicação consulta dados por serviços de acesso, que podem usar indexadores para organizar informações da rede. Uma falha nesse caminho não demonstra, sozinha, uma falha da rede inteira.
  • Uma transação propõe uma operação. O recebimento pelo serviço de submissão e a inclusão em um bloco são etapas distintas, que a aplicação precisa acompanhar.
  • Os nós verificam transações e blocos segundo o protocolo. O histórico da blockchain permite reconstruir o estado do ledger.
  • A interface e os dados privados continuam precisando de serviços próprios. Uma mudança na tela não dispensa autorizações da rede nem apaga registros já publicados.

Próxima aula

Uma operação pode chegar a um nó e ainda assim ser recusada. Na próxima aula, veremos como o software separa a comunicação com outros nós, a escolha da cadeia e a verificação das mudanças no ledger. Isso permite investigar essas etapas sem confundir um problema de consulta com uma falha na aceitação das operações.

Módulo 1 Aula 1.2

Arquitetura do node e eras

Separar difusão, seleção de cadeia e validação do ledger, reconhecendo que as regras dependem da era.

Objetivos

Ao final desta aula, você será capaz de:

  1. separar as funções de rede, consenso e ledger em um node Cardano;
  2. explicar por que serialização, inclusão e validação dependem das regras da era;
  3. diagnosticar em qual camada uma falha observada deve ser investigada.
Antes de começar

Retome a Aula 1.1 e a diferença entre transportar uma proposta e aceitar uma transição.

Pergunta-guia

Receber uma transação de outro nó significa que ela será aceita?

1. Rede transporta

A camada de rede mantém conexões com outros nós, chamados peers, e difunde blocos e transações. Receber um pacote significa apenas que os bytes chegaram por um caminho de rede. Ainda é necessário decodificar a estrutura, aplicar regras e decidir se o objeto participa da cadeia ou do estado local.

Uma transação pode chegar ao node e ser recusada porque tenta gastar um recurso já utilizado, oferece uma taxa insuficiente ou não apresenta uma assinatura exigida. Um bloco pode ser recebido e não pertencer à cadeia selecionada. Por isso, “o node recebeu” e “o ledger aceitou” descrevem eventos diferentes.

2. Consenso seleciona uma história

O consenso organiza produção de blocos e seleção de cadeia. Ele trata concorrência entre histórias candidatas e fornece as regras pelas quais os participantes convergem. Essa camada não decide se um relatório externo é verdadeiro nem interpreta a finalidade comercial de uma transação.

Uma cadeia observada em determinado instante pode mudar perto da ponta. Aplicações precisam distinguir recepção, inclusão observada e aceitação segundo sua política de confirmação. O próximo capítulo aprofunda slots, epochs, stake e produção de blocos.

3. Ledger valida transições

O ledger verifica se a operação pode mudar o estado atual. Os recursos que ela pretende gastar ainda estão disponíveis? As autorizações exigidas foram apresentadas? Os valores e a taxa fecham a conta? Essas verificações seguem as regras da era e os parâmetros vigentes. Nas próximas aulas, veremos os campos que permitem realizá-las.

Indexadores e explorers formam outra camada. Eles organizam dados derivados para consulta. Um indexador atrasado pode omitir uma transação que já está na cadeia observada por um node; uma interface também pode truncar ou traduzir valores. A falha de consulta não deve ser atribuída automaticamente ao consenso.

CamadaPergunta principalExemplo de falha
RedeO objeto chegou e foi difundido?Peer indisponível ou pacote não propagado.
ConsensoQual cadeia candidata é selecionada?Bloco observado perto da ponta deixa a cadeia selecionada.
LedgerA transição respeita as regras da era?Input gasto, valor não conservado ou witness inválida.
IndexaçãoComo dados aceitos são organizados para consulta?Explorer atrasado ou campo apresentado de modo incompleto.

4. Eras e evolução do protocolo

Cardano evolui por eras. Cada era introduz ou altera capacidades, formatos e regras. O hard fork combinator coordena a transição entre protocolos no mesmo histórico Cardano. Ferramentas precisam conhecer a era ativa e a representação aplicável.

Conseguir ler os bytes de uma transação não basta para aceitá-la. Seus campos e efeitos também precisam respeitar as regras do ledger da era. Da mesma forma, uma biblioteca que reconhece um campo novo não garante que o node, a wallet e o indexador usados no ambiente ofereçam o mesmo suporte. Na Aula 1.6, veremos como os campos são representados em bytes.

Contexto da verificação

Ao investigar uma falha, registre a rede, a era, a versão do node ou biblioteca e a fonte dos parâmetros. Esses dados permitem repetir a verificação nas mesmas condições e identificar incompatibilidades entre ferramentas.

Atividade 1: localize a camada

Considere quatro observações: A recebe uma transação por um peer; B a rejeita porque um input já foi gasto; C não a encontra em seu indexador; D observa um bloco que depois deixa a cadeia selecionada. Classifique cada evento.

Associe o principal ponto de investigação.

0 de 1 pergunta respondida.

Conferir resposta

A recepção é rede; o input já gasto é ledger; a seleção da cadeia é consenso; a consulta derivada é indexador. A classificação não elimina causas combinadas, mas impede que transporte, validade, seleção e apresentação sejam tratados como o mesmo problema.

O que aprendemos

  • A camada de rede transporta informações entre participantes.
  • O consenso seleciona a cadeia que o nó acompanha; o ledger valida transições de estado.
  • As regras de validação dependem da era. Serializar uma transação não basta para torná-la válida.
  • Indexadores produzem visões de consulta. Uma falha nessa visão precisa ser distinguida de uma falha de rede, consenso ou validação.

Próxima aula

Como o consenso organiza oportunidades de produção de bloco e relaciona participação ao stake?

Módulo 1 Aula 1.3

Ouroboros, slots, epochs e stake

Entender o relógio do protocolo e formular conclusões proporcionais sobre produção e confirmação.

Objetivos

Ao final desta aula, você será capaz de:

  1. distinguir slot, bloco e epoch;
  2. explicar em alto nível como stake participa da seleção de líderes;
  3. formular uma política de confirmação sem prometer finalização instantânea.
Antes de começar

Retome as funções de consenso e ledger na Aula 1.2.

Pergunta-guia

Todo slot contém um bloco, e um bloco observado torna uma transação irreversível?

1. Slots, blocos e epochs

Slots são intervalos numerados usados pelo protocolo. Epochs agrupam slots e servem de referência para parâmetros e atividades que evoluem em ciclos. Um slot pode não produzir bloco, e um bloco pode conter várias transações. Portanto, slot, bloco e transação não formam uma relação de um para um.

Horários exibidos por uma interface são conversões feitas por ferramentas. Para uma observação reproduzível, preserve rede, slot, bloco, fonte e horário da consulta. Uma data amigável sem o contexto da rede não substitui o identificador técnico.

2. Stake, pools e liderança

Quem possui ADA pode delegar a participação associada a esse valor, chamada stake, a um pool. O operador do pool mantém a infraestrutura para produzir blocos. A delegação não transfere a propriedade do ADA nem entrega a chave de pagamento: o operador não pode gastar os valores do delegador.

Na família Ouroboros, o stake ativo associado ao pool influencia sua chance de produzir blocos. Uma parcela maior aumenta essa chance, mas não garante um bloco em cada intervalo. A seleção segue regras verificáveis do protocolo, sem um coordenador central escolhendo o próximo produtor.

O produtor de um bloco propõe uma extensão da cadeia. Os demais nós ainda verificam o bloco e aplicam as regras de consenso e ledger. Produzir não significa ter autoridade para alterar arbitrariamente as regras.

3. Inclusão observada e confiança operacional

Uma transação observada em um bloco está incluída na cadeia vista por aquela fonte naquele momento. Perto da ponta podem existir cadeias candidatas concorrentes. Aplicações aguardam profundidade adicional ou outra condição operacional conforme valor, risco e tolerância.

O protocolo oferece propriedades probabilísticas sob premissas de segurança. A aplicação precisa declarar sua política, em vez de escrever apenas “final”. Uma interface pode distinguir pelo menos três estados: submetida ao endpoint, incluída na cadeia observada e aceita pela política interna após a condição definida.

Conclusão proporcional

“Incluída no bloco observado e aceita após a política de confirmação configurada” é mais precisa que “irreversível”. A política deve registrar sua fonte, condição e versão.

4. O que consenso não prova

Consenso organiza uma história de transações válidas. Ele não verifica automaticamente a identidade jurídica de quem controla uma chave, a finalidade institucional de uma transferência nem a verdade de um documento citado por hash. Essas perguntas reaparecem nas aulas sobre assinaturas, metadata e evidência.

Atividade 1: reconheça o estado da transação

Uma aplicação submeteu uma transação e depois encontrou seu identificador em um explorer. O sistema só deve liberar o relatório após cumprir a política de confirmação definida pela equipe.

Qual texto evita confundir observação com garantia absoluta?

0 de 1 pergunta respondida.

Conferir resposta

Submetida: o endpoint recebeu o pacote. Incluída: uma fonte identificada mostra o tx id em um bloco e slot. Aceita internamente: a condição de profundidade, tempo ou corroboração definida pela operação foi atendida. A primeira alternativa registra o estado sem extrapolar a evidência.

O que aprendemos

  • Slots organizam oportunidades de produção de blocos; epochs agrupam slots. Slot e bloco não são a mesma coisa.
  • Stake participa da seleção de líderes e da segurança do protocolo.
  • Observar a inclusão de uma transação e aceitá-la operacionalmente são decisões diferentes. A política de confirmação precisa ser explícita.
  • O consenso não comprova a verdade de um fato externo registrado na transação.

Próxima aula

Os nós aplicam os parâmetros vigentes da rede, mas esses valores podem mudar. Na próxima aula, veremos como propostas técnicas e decisões de governança se relacionam com mudanças que afetam a construção de transações.

Módulo 1 Aula 1.4

CIPs, governança e parâmetros da rede

Objetivos
  1. Distinguir o papel de uma CIP do processo que coloca uma mudança em vigor na rede.
  2. Reconhecer os participantes da governança e sua relação com alterações de parâmetros.
  3. Explicar por que a construção de uma transação depende dos parâmetros vigentes.
Antes de começar

Retome a distinção entre aplicação e protocolo, apresentada na Aula 1.1, e o conceito de epoch da Aula 1.3.

Pergunta-guia

Como uma mudança discutida no ecossistema passa a afetar as transações que uma aplicação pode enviar?

1. CIPs: combinar como as ferramentas funcionam

Uma carteira e uma aplicação desenvolvidas por equipes diferentes precisam concordar sobre formatos e interfaces. As Cardano Improvement Proposals, ou CIPs, documentam propostas, padrões e convenções para esse trabalho conjunto. Também registram discussões sobre mudanças no protocolo.

A CIP-19, por exemplo, descreve a estrutura dos endereços que estudaremos na próxima aula. A CIP-30 padroniza a comunicação entre uma aplicação e uma carteira no navegador. Nesse segundo caso, carteiras e aplicações implementam a interface; isso não exige que cada chamada seja decidida por uma votação da rede.

O processo de elaboração e revisão está descrito na CIP-1. O status de uma CIP informa sua situação nesse processo. Publicar o documento não instala software, não garante que toda ferramenta o implemente e não altera automaticamente as regras aplicadas pelos nós.

2. O que a governança decide

As escolhas que afetam toda a rede exigem mecanismos de decisão comuns. A governança on-chain registra ações e votos para decisões previstas no protocolo, como alterar parâmetros, iniciar uma atualização de protocolo ou autorizar uma retirada da tesouraria.

O modelo descrito na CIP-1694 reúne três grupos com funções distintas:

  • DReps são representantes aos quais detentores de ADA podem delegar poder de voto. Eles votam nas ações em que esse grupo participa.
  • Operadores de stake pools (SPOs) participam de decisões previstas para esse grupo, incluindo atualizações de protocolo e mudanças de parâmetros relevantes para a segurança.
  • O comitê constitucional avalia a conformidade das ações com a Constituição da Cardano nas decisões em que sua aprovação é exigida.

Os grupos participantes e os limiares de aprovação dependem do tipo de ação. Delegar poder de voto a um DRep não transfere ADA para ele nem lhe entrega as chaves que autorizam pagamentos.

Uma CIP pode fundamentar tecnicamente uma mudança. A ação de governança, seus votos e sua entrada em vigor são acontecimentos distintos do processo editorial desse documento.

3. Parâmetros que chegam à aplicação

O protocolo usa parâmetros para definir limites e custos. Eles afetam diretamente o trabalho de quem constrói transações:

  • O tamanho máximo de uma transação limita quantos bytes ela pode ocupar.
  • Os coeficientes de taxa participam do cálculo de quanto a transação precisa pagar.
  • Os limites de execução restringem os recursos que scripts podem consumir.

O tamanho máximo de um bloco também é um parâmetro. Aumentá-lo pode permitir mais dados por bloco, mas exige mais dos nós na transmissão e no processamento. Essa escolha afeta operadores e aplicações, não apenas a tela de um produto.

Alterar um parâmetro já previsto no protocolo é diferente de introduzir uma regra nova que o software ainda não conhece. Uma atualização de protocolo pode exigir novas versões dos nós e uma transição coordenada, como um hard fork.

4. Da aprovação ao valor vigente

Uma ação ratificada cumpriu as condições de aprovação. Seu efeito acontece quando ela entra em vigor, conforme as regras do protocolo. Atualizações de parâmetros são aplicadas na transição entre epochs; receber votos favoráveis não muda imediatamente o limite que um nó usa para verificar uma transação.

Suponha que uma mudança aumente o tamanho máximo permitido. Uma transação que ultrapassa o limite atual não passa a ser aceita apenas porque a mudança foi anunciada ou aprovada. Até a entrada em vigor, o limite anterior continua sendo aplicado.

Ao construir uma transação, a aplicação obtém os parâmetros vigentes da rede pretendida por um nó ou serviço de acesso. Não deve usar um valor copiado de uma proposta como se ele já fosse a configuração da rede. Se a preparação atravessar uma mudança de epoch, é preciso conferir novamente os parâmetros antes de concluir ou submeter a transação. Uma mudança no corpo pode exigir novas assinaturas.

Atividade: use o limite vigente

Uma ação que aumenta o tamanho máximo de transação foi ratificada, mas ainda não entrou em vigor. A aplicação está prestes a enviar uma transação que ultrapassa o limite atual e cabe no novo.

Qual conduta respeita as regras da rede?

0 de 1 pergunta respondida.

Conferir resposta

A alternativa C é a correta. A aprovação permite que a ação avance no processo, mas não antecipa seu efeito. A aplicação pode preparar uma transação que respeite o limite atual ou esperar a mudança e confirmar os parâmetros então vigentes. Trocar de provedor ou atualizar uma biblioteca não altera a regra aplicada pelos nós.

O que aprendemos

  • CIPs documentam propostas e padrões que ajudam ferramentas e participantes a trabalhar de forma compatível.
  • A governança envolve DReps, operadores de stake pools e comitê constitucional, com participação e condições definidas por tipo de ação.
  • Parâmetros da rede afetam o tamanho, os custos e os limites de execução das transações.
  • Ratificação e entrada em vigor são etapas diferentes. A aplicação precisa trabalhar com os valores vigentes.

Próxima aula

A participação associada ao stake e a autorização de pagamentos têm funções distintas. Na próxima aula, veremos como os endereços Shelley combinam credenciais de pagamento, stake e identificação de rede.

Módulo 1 Aula 1.5

Endereços Shelley, credenciais e rede

Objetivos
  1. Distinguir as funções das credenciais de pagamento e de stake.
  2. Comparar os formatos base, enterprise e reward e reconhecer o uso de credenciais de chave ou de script.
  3. Inspecionar um endereço com uma biblioteca e explicar por que testnet não identifica uma rede de teste específica.
Antes de começar

Retome bytes, codificações, hashes e assinaturas do Módulo 0. A separação entre aplicação e rede e a participação associada ao stake, vistas neste módulo, ajudam a interpretar as funções do endereço.

Pergunta-guia

O que um endereço informa sobre pagamento, stake e rede, e o que ele não permite concluir sozinho?

1. O que está por trás do endereço

Ao preparar um recebimento, uma aplicação precisa indicar para onde o valor será destinado e sob qual condição ele poderá ser gasto. Na Cardano, o endereço carrega informações sobre essa condição. Ele não é apenas o nome de uma conta nem uma chave privada que deve ser entregue a quem vai pagar.

Os formatos introduzidos com Shelley continuam em uso nas eras seguintes. A CIP-19 descreve sua estrutura: um header, ou cabeçalho, identifica o tipo e a rede; os bytes seguintes identificam as credenciais previstas por aquele tipo.

Uma credencial identifica uma chave pública ou um script por meio de um hash. No caso de uma chave, Cardano usa BLAKE2b-224 para produzir esse hash de 28 bytes. A chave privada permanece fora do endereço.

2. Pagamento e stake são funções separadas

A credencial de pagamento identifica a autorização necessária para gastar os valores destinados ao endereço. Quando é uma credencial de chave, a transação apresenta a chave pública correspondente e uma assinatura válida. Quando é de script, o gasto precisa satisfazer a regra identificada por esse script.

A credencial de stake participa de operações como delegação para uma stake pool e saque de recompensas. Na governança atual, também é usada para delegar poder de voto a um DRep. Controlar essa credencial não concede a autorização de gasto da credencial de pagamento.

Uma carteira normalmente gerencia as duas funções, mas usa chaves distintas para elas. É possível combinar uma credencial de pagamento e uma de stake controladas por responsáveis diferentes. Essa separação permite decidir quem movimenta os valores e quem administra a participação associada ao stake.

Uma carteira, vários endereços

Carteiras hierárquicas podem derivar várias chaves a partir do mesmo material de recuperação, seguindo um esquema como o da CIP-1852. Por isso, uma carteira pode apresentar vários endereços, em vez de um único identificador fixo. Ela consulta o ledger para encontrar os valores associados a eles.

A frase de recuperação permite reconstruir chaves em uma carteira compatível. Ela não é um endereço de recebimento e não deve ser fornecida a um dApp ou a quem vai enviar um pagamento.

3. Base, enterprise e reward

Vamos comparar três formatos que aparecem nas aplicações. A diferença está nas credenciais que cada um reúne e na função que exerce.

Base: pagamento e stake

Um base address reúne uma credencial de pagamento e uma de stake. Pode receber valores e associar o ADA daquele endereço à participação em stake. Ter as duas partes no mesmo endereço não mistura suas autorizações.

Enterprise: apenas pagamento

Um enterprise address tem a credencial de pagamento, sem a parte de stake. Permite recebimentos e gastos, mas o ADA nesse endereço não fica associado a uma credencial de stake para delegação.

Reward: conta de recompensas

Um reward address, também chamado de stake address, identifica uma conta de recompensas pela credencial de stake. Ele aparece em operações como o saque dessas recompensas. Não pode ser usado como destino de uma saída de transação para receber ADA ou tokens. O saque leva as recompensas dessa conta para um endereço de pagamento.

BaseHeader1 bytePagamento28 bytesStake28 bytes57 bytes
EnterpriseHeader1 bytePagamento28 bytes29 bytes
RewardHeader1 byteStake28 bytes29 bytes
O header identifica tipo e rede. Cada credencial ocupa 28 bytes: base tem duas; enterprise e reward têm uma, com funções diferentes.

E os endereços de script?

Base e enterprise podem ter uma credencial de pagamento de chave ou de script. Assim, endereço de script descreve o mecanismo de autorização, não uma quarta alternativa aos três formatos acima. Uma credencial de stake também pode ser de script.

Por exemplo, uma aplicação pode receber valores em um enterprise address cuja credencial de pagamento é o hash de um script. Para gastá-los, a transação precisa satisfazer esse script; não existe uma chave privada do script que possa ser recuperada por uma frase.

4. Bech32 apresenta os bytes; a rede dá o contexto

A forma que copiamos da carteira normalmente é uma codificação Bech32 do endereço. Como hexadecimal e base64, ela escreve bytes em texto; também inclui uma verificação que ajuda a detectar erros de digitação. O protocolo trabalha com os bytes, não com a aparência do texto na tela.

Os prefixos definidos na CIP-5 ajudam na leitura:

  • addr1… e addr_test1… são usados para endereços de pagamento de mainnet e de teste, respectivamente. O formato base ou enterprise é confirmado pela decodificação.
  • stake1… e stake_test1… são usados para endereços de recompensas de mainnet e de teste.

No header, o identificador de rede é 1 para mainnet e 0 para testnets. Preprod e Preview usam o mesmo identificador de teste. Portanto, um endereço addr_test1… não informa sozinho qual delas deve ser consultada.

A aplicação precisa combinar o endereço com a rede pretendida e o serviço de acesso correspondente. Alternar a rede na carteira muda o ambiente consultado; não transfere valores entre redes. Um endereço bem formado também não confirma a identidade de quem o forneceu: confira o destino completo com a origem esperada.

5. Inspecionar e compor endereços

A biblioteca PyCardano permite ler as partes de um endereço e compor outros formatos. O exemplo usa um endereço base público dos vetores de teste da CIP-19. Depois, usa apenas sua parte de pagamento para formar um enterprise e apenas sua parte de stake para formar um reward.

from pycardano import Address

endereco_base = Address.from_primitive(
    "addr_test1qz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3n"
    "0d3vllmyqwsx5wktcd8cc3sq835lu7drv2xwl2wywfgs68faae"
)
endereco_enterprise = Address(endereco_base.payment_part, network=endereco_base.network)
endereco_reward = Address(staking_part=endereco_base.staking_part, network=endereco_base.network)

print("Rede:", endereco_base.network.name)
print("Base:", len(bytes(endereco_base)), "bytes")
print("Enterprise:", len(bytes(endereco_enterprise)), "bytes")
print("Reward:", len(bytes(endereco_reward)), "bytes")

A saída mostra TESTNET e os comprimentos de 57, 29 e 29 bytes. As credenciais foram reaproveitadas, mas os três endereços têm estruturas e funções diferentes. O código apenas compõe endereços; não consulta a rede nem movimenta valores.

Atividade: escolha pela função
1. Uma aplicação quer receber valores sob uma regra de script, sem associá-los a stake. Qual estrutura corresponde a esse uso?

2. A biblioteca decodificou um endereço base e informou TESTNET. Qual informação ainda falta para consultar seus recebimentos?

0 de 2 perguntas respondidas.

Conferir resposta
  1. A alternativa B é a correta. Enterprise omite a parte de stake, e a credencial de pagamento de script identifica a regra exigida para gastar. Colocar o script na parte de stake não controla o gasto de pagamentos; reward identifica a conta de recompensas, não um destino de pagamento.
  2. A alternativa C é a correta. TESTNET e o prefixo addr_test não distinguem Preprod de Preview. A consulta precisa apontar para o ambiente pretendido. O tamanho identifica a estrutura, não essa escolha de rede, e consultar um endereço público não exige sua chave privada.

O que aprendemos

  • Pagamento e stake são funções distintas. Controlar uma delas não concede automaticamente o controle da outra.
  • Base reúne pagamento e stake; enterprise tem apenas pagamento; reward identifica a conta de recompensas.
  • Uma credencial pode identificar uma chave ou um script. O formato do endereço e a regra de autorização são escolhas relacionadas, mas diferentes.
  • Bech32 apresenta os bytes do endereço. O identificador de testnet não distingue Preprod de Preview; a aplicação também precisa saber qual rede acessar.

Próxima aula

Com o endereço de destino e suas condições de autorização identificados, falta descrever a operação. Na próxima aula, veremos quais dados compõem uma transação e quais bytes serão usados na assinatura e na verificação.

Módulo 1 Aula 1.6

Transação como pacote verificável: intenção, bytes e regras

Entender como uma intenção vira estrutura, bytes CBOR, identificador, assinatura e pacote verificável pelas regras da rede.

Objetivos

Ao final desta aula, você será capaz de:

  1. diferenciar intenção humana e pacote técnico de transação;
  2. identificar corpo, witnesses, representação CBOR e bytes usados no identificador de uma transação;
  3. explicar como regras de validação aceitam ou recusam um pacote;
Antes de começar

Você precisa lembrar que bytes podem representar texto, números e estruturas; que hashes dependem dos bytes exatos; que assinaturas digitais vinculam bytes específicos a uma chave; e que carteira, endereço e rede fazem parte do contexto operacional.

Pergunta-guia

Como uma rede sai de uma frase como "quero registrar este compromisso" para um pacote de bytes que pode ser aceito ou recusado por regras compartilhadas?

1. Intenção humana e pacote técnico

“Enviar 5 unidades e registrar o hash de um documento” ainda não especifica uma transação. O builder precisa definir rede, ativo, quantidade inteira, endereço, digest, condições de autorização e validade. Esses campos permitem verificar a operação sem depender da frase que a motivou.

Para facilitar a leitura, esta aula usa JSON fictício. Transações reais de Cardano usam CBOR. A Seção 4 abre essa representação e separa estrutura lógica, bytes binários, hexadecimal de transporte e visão JSON.

2. Campos, regras e validação

Um campo é uma posição nomeada ou definida dentro de uma estrutura. Ele tem um valor e, normalmente, um tipo esperado. Um campo de quantidade deve se comportar como número inteiro. Um campo de rede deve indicar um contexto reconhecido. Um campo de digest deve ter formato e tamanho compatíveis com o algoritmo declarado.

Regras são condições que o pacote precisa satisfazer. Algumas regras verificam forma: campo obrigatório presente, tipo correto, tamanho correto, codificação correta. Outras regras verificam estado: recurso disponível, credencial ou condição de script satisfeita, validade temporal, taxa suficiente e ausência de conflito com algo já consumido.

3. Assinaturas dentro de uma transação em nível conceitual

Assinatura digital tem função no pacote: ela permite verificar a relação entre determinados bytes, uma assinatura e uma chave pública, conforme um esquema criptográfico. A chave privada não vai dentro da transação. O pacote leva a assinatura e a informação necessária para conferir a chave ou credencial esperada.

Em nível conceitual, pense primeiro em dois conjuntos centrais. O corpo da transação reúne os campos que dizem o que a operação tenta fazer. O conjunto de witnesses reúne assinaturas, scripts e outros dados usados para satisfazer condições técnicas definidas pelas regras do ledger. Na serialização completa, também aparecem o indicador de validade de script e, quando houver, os dados auxiliares. Esses elementos não fazem parte do transaction body nem do witness set.

Intençãohumana builder TRANSAÇÃO Corpocampos e valores Witnessesassinaturas e scripts Serializar em CBOR bytes NODEAplica as regras AceitaouRecusa Aceitação ≠ inclusão.
A intenção vira um pacote cujos dois conjuntos centrais são o corpo, que declara a operação, e as witnesses, que ajudam a satisfazer condições exigidas pelas regras. A serialização completa pode incluir ainda o indicador de validade de script e dados auxiliares. A rede valida os bytes finais, não a frase original.

Consumir um output controlado por credencial de chave exige a key witness correspondente. Sem essa witness válida, a transação falha; o conteúdo público anexado não precisa ter uma assinatura documental própria.

4. CBOR: da estrutura aos bytes de Cardano

Os campos que você viu até aqui ainda são uma estrutura lógica. Para transmitir, assinar e validar uma transação, Cardano precisa de uma representação binária definida. Essa representação usa CBOR, sigla de Concise Binary Object Representation.

O RFC 8949 define como valores como inteiros, bytes, textos, listas e mapas podem ser codificados. CBOR não define o significado de uma transação Cardano. As regras do ledger e a especificação da era definem quais campos existem, seus tipos e as combinações aceitas.

CamadaExemploUso
Estrutura da aplicaçãoObjeto produzido pelo builderFacilita construção e validação antes da serialização.
Bytes CBORSequência bináriaÉ a representação processada pelas bibliotecas e pelo protocolo.
Hexadecimala2647265...É uma forma textual de transportar ou inspecionar os bytes CBOR.
JSON do explorerCampos legíveis na páginaÉ uma visão reconstruída para leitura; não é o CBOR original.

Um mapa pequeno em CBOR

Considere o mapa didático {"rede": "preprod", "quantidade": 5}. Uma codificação determinística desse mapa produz 26 bytes. Escritos em hexadecimal, eles ficam assim:

a2                                      # mapa com 2 pares
  64 72656465                           # texto "rede"
  67 70726570726f64                     # texto "preprod"
  6a 7175616e746964616465               # texto "quantidade"
  05                                    # inteiro 5

hex contínuo:
a264726564656770726570726f646a7175616e74696461646505

Transações reais contêm estruturas maiores e campos específicos da era. Endereços, hashes e identificadores aparecem como bytes, não como os textos amigáveis exibidos pela interface. Não tente montar esse CBOR manualmente: use uma biblioteca compatível com a era e confira a estrutura antes de assinar.

Do objeto Python ao CBOR

Com PyCardano, os campos ficam em um objeto TransactionBody. Este exemplo tem uma entrada, uma saída de 100 ADA, taxa de 200000 lovelace e limite de validade no slot 1000. A entrada é fictícia: estamos estudando o corpo, não preparando uma transferência para envio.

inputs identifica o recurso consumido; outputs descreve o destino e o valor. fee guarda a taxa e ttl guarda o limite superior de validade. Execute o código para ver esses campos serializados por to_cbor_hex().

from pycardano import (
    Address, TransactionBody, TransactionId, TransactionInput,
    TransactionOutput, Value,
)

destino = Address.from_primitive(
    "addr_test1qz5p9x623ngvjtzf89gcz2pjhxcahq7rper4q534ejegyd406v8dc860wkryxpgsaeqzvwz7y2nmp7caz35yfpqsw7as9v22t0"
)
corpo = TransactionBody(
    inputs=[TransactionInput(TransactionId(bytes(32)), 0)],
    outputs=[TransactionOutput(destino, Value(100_000_000))],
    fee=200_000,
    ttl=1000,
)
print(corpo.to_cbor_hex())

A saída é o corpo em CBOR escrito como hexadecimal. TransactionBody.from_cbor() faz o caminho de volta: recebe essa representação e recupera os campos do objeto.

Corpo, identificador e witnesses

O corpo da transação é serializado antes da coleta de witnesses. Em Cardano, o identificador da transação é o digest Blake2b-256 dos bytes CBOR do transaction body conforme a era do ledger. As vkey witnesses assinam esse mesmo body hash. A assinatura não pode fazer parte dos bytes sobre os quais ela é calculada; ela entra no transaction witness set anexado ao corpo. O witness set também pode carregar scripts, datums e redeemers exigidos pela transação, conforme a era e o tipo de script.

Esse alcance precisa ficar explícito. O transaction ID e a vkey witness não abrangem diretamente o witness set nem o indicador is_valid, que fica fora do body na serialização completa. Auxiliary data também fica fora, mas seus bytes são comprometidos indiretamente pelo auxiliary_data_hash incluído no body. O ledger valida a combinação completa segundo as regras da era; uma key witness válida não significa que cada byte externo ao body foi assinado por aquela chave.

O transaction ID é um digest opaco, sem prefixo textual que identifique a rede. O body pode incluir o campo opcional network_id, e endereços de outputs ou contas de recompensa carregam contexto de rede em suas codificações. Ainda assim, wallet, nó, API e parâmetros precisam estar configurados para o mesmo ambiente. Registre a rede separadamente e não use apenas o transaction ID para distinguir Mainnet, Preprod ou Preview.

Em interfaces como CIP-30, os bytes CBOR costumam atravessar a API escritos como hexadecimal. Um argumento chamado cbor ou uma string como 84a4... não é JSON, não é texto do contrato e não é material secreto. É uma representação textual dos bytes serializados.

CBOR válido não basta

CBOR admite mais de uma forma válida de representar certos valores. Cardano restringe a estrutura com regras próprias e descrições CDDL específicas da era. Uma biblioteca precisa produzir a forma aceita pelo ledger, não apenas qualquer documento que um decoder CBOR consiga abrir.

5. Ed25519 e a mensagem de uma key witness

Na Aula 0.4, usamos Ed25519 para assinar os bytes de uma mensagem. Ed25519 é um esquema real de assinatura EdDSA sobre a curva Edwards25519, especificado no RFC 8032. Curva, esquema, implementação e uso pelo protocolo são camadas distintas: Cardano determina qual mensagem deve ser entregue à biblioteca.

No formato Ed25519, a chave pública tem 32 bytes e a assinatura tem 64 bytes. A assinatura recebe material privado e mensagem em bytes; a verificação recebe chave pública, a mesma mensagem e assinatura. Ed25519 usa SHA-512 internamente e deriva deterministicamente seu valor efêmero; a aplicação não inventa um nonce para a operação. Formatos de chave privada variam entre seed, chave expandida e objeto opaco. Chaves estendidas de uma wallet Cardano não são intercambiáveis com qualquer arquivo chamado “Ed25519”.

Para uma vkey witness de Cardano, a mensagem é o body hash de 32 bytes, calculado com Blake2b-256. Assinar esse digest conforme o protocolo não significa usar a variante Ed25519ph. Também não significa assinar seus 64 caracteres hexadecimais: texto hex e bytes decodificados são entradas diferentes. A witness contém verification key e assinatura. No gasto por chave, o ledger verifica a assinatura e relaciona o hash da verification key à credencial exigida. Há ainda required signers e condições de scripts; verificar uma assinatura isolada não verifica toda a transação.

Do corpo à mensagem que será assinada

Agora recupere o corpo serializado no exemplo anterior e chame hash(). Compare o digest de 32 bytes com os 64 caracteres da sua representação hexadecimal. A assinatura recebe os bytes do digest.

from pycardano import TransactionBody

corpo = TransactionBody.from_cbor(
    "a400818258200000000000000000000000000000000000000000000000000000"
    "00000000000000018182583900a8129b4a8cd0c92c493951812832b9b1db83c3"
    "0e47505235ccb28236afd30edc1f4f7586430510ee4026385e22a7b0fb1d1468"
    "44841077bb1a05f5e100021a00030d40031903e8"
)
digest = corpo.hash()
print("digest:", len(digest), "bytes")
print("hex:", digest.hex())
print("hex como texto:", len(digest.hex().encode("ascii")), "bytes")
print("mesma entrada?", digest == digest.hex().encode("ascii"))
Atividade: corrija a taxa, preserve o prazo

A taxa precisa passar de 200000 para 200001 lovelace, mantendo o prazo em 1000. A função abaixo altera o campo errado. Corrija somente essa atribuição e use Validar solução.

O corpo do exemplo anterior já está em CBOR. A função deve devolver o corpo revisado e o hash correspondente a ele: mudar a taxa também muda a mensagem que será assinada.

from pycardano import TransactionBody

corpo_exemplo = TransactionBody.from_cbor(
    "a400818258200000000000000000000000000000000000000000000000000000"
    "00000000000000018182583900a8129b4a8cd0c92c493951812832b9b1db83c3"
    "0e47505235ccb28236afd30edc1f4f7586430510ee4026385e22a7b0fb1d1468"
    "44841077bb1a05f5e100021a00030d40031903e8"
)

def mensagem_do_signer(body_cbor_hex, nova_taxa):
    corpo = TransactionBody.from_cbor(body_cbor_hex)
    corpo.ttl = nova_taxa
    return corpo.to_cbor_hex(), corpo.hash()

body_hex, mensagem = mensagem_do_signer(corpo_exemplo.to_cbor_hex(), 200_001)
revisado = TransactionBody.from_cbor(body_hex)
print("taxa:", revisado.fee, "prazo:", revisado.ttl)
print("mensagem:", mensagem.hex())
Conferir resposta

Troque corpo.ttl = nova_taxa por corpo.fee = nova_taxa. A taxa passa a 200001 lovelace e o prazo continua 1000. O hash é calculado depois da revisão. Se alguém já tivesse assinado o corpo anterior, aquela assinatura não serviria para o corpo com a nova taxa.

Uma witness válida vincula chave e corpo. O cadastro que relaciona a chave a uma pessoa, sua vigência e sua competência para aprovar o documento continuam sendo evidências separadas. O signer deve revisar os efeitos antes de assinar, pois uma assinatura correta sobre o corpo errado continua autorizando a operação descrita por aquele corpo.

O que aprendemos

  • Uma transação é um pacote estruturado que descreve uma operação para a rede verificar.
  • Estrutura, representação em CBOR, corpo da transação e witnesses têm papéis distintos. O identificador depende dos bytes do corpo.
  • Uma vkey witness usa Ed25519 sobre o body hash binário Blake2b-256, não sobre seu texto hexadecimal. A aceitação ainda depende das demais regras do ledger.

Próxima aula

Se uma transação precisa apontar para recursos disponíveis e produzir novos resultados, como a rede sabe exatamente o que está sendo consumido e o que está sendo criado?

Módulo 1 Aula 1.7

UTxO e eUTxO: saídas, gasto e troco

Objetivos
  1. Relacionar o saldo da carteira às saídas não gastas que ela consulta.
  2. Identificar uma saída e acompanhar seu consumo, o pagamento e o troco.
  3. Distinguir os dados associados a uma saída da regra que autoriza seu gasto.
Antes de começar

Na Aula 1.5, o endereço identificava as condições de gasto. Na 1.6, vimos entradas e saídas no corpo da transação. Agora veremos o que essas entradas apontam e o que acontece com os valores quando a transação é aceita.

Pergunta-guia

Se você usa uma saída de 7 ADA para pagar 5 ADA, onde fica o restante?

1. O saldo que a carteira mostra

Você abre a carteira e vê 11 ADA. Esse número pode reunir valores recebidos em momentos diferentes: uma saída de 7 ADA e outra de 4 ADA, por exemplo. A carteira consulta as saídas disponíveis nos seus endereços e soma os valores para apresentar o saldo.

Cada uma dessas saídas é uma UTxO, abreviação de Unspent Transaction Output: uma saída de transação ainda não gasta. Ela foi criada por uma transação anterior e continua disponível para ser usada em outra.

Saídas não gastas no ledger
UTxO7 ₳8f3c2a91d6e4…#0Endereço de pagamento
UTxO4 ₳2b7e4d90a6c1…#0Endereço de pagamento
A carteira mostra 11 ADA, mas há duas saídas distintas disponíveis para gasto. Hashes ilustrativos e abreviados.

Pense nessas saídas como notas de dinheiro, cada uma com seu valor. Em Cardano, cada “nota” também está associada a um endereço que identifica a condição para gastá-la. Os valores não precisam seguir denominações fixas, como as cédulas de papel.

2. Qual saída será gasta, e quem pode gastá-la?

Conhecer o saldo não basta para construir uma transação. É preciso identificar as saídas que serão usadas como entradas. Cada saída é identificada pelo hash da transação que a criou e pelo índice que ocupa na lista de saídas, começando em zero.

UTxO7 ₳8f3c2a91d6e4…#0Endereço de pagamento

8f3c2a91d6e4… é o hash abreviado da transação que criou a saída. #0 indica sua primeira saída.

O endereço identifica a condição de gasto. A referência identifica qual saída será gasta. Várias saídas podem ter o mesmo endereço e, ainda assim, referências diferentes.

Uma entrada aponta para a saída pelo par hash e índice; não apenas pelo endereço.

Para consumir uma saída, a transação precisa satisfazer a condição identificada pela credencial de pagamento. No caso de uma chave, isso exige a chave pública correspondente e uma assinatura válida. Se a credencial for de script, o gasto precisa satisfazer a regra desse script. Copiar o endereço ou conhecer a referência não fornece essa autorização.

3. O pagamento consome a saída inteira

Considere que Ana controla as duas saídas do exemplo e quer pagar 5 ADA a Bruno. Suponha uma taxa de 0,2 ADA para essa transação. A saída de 7 ADA é suficiente para cobrir os dois valores; a de 4 ADA pode ficar sem uso.

A entrada referencia 8f3c2a91d6e4…#0. Quando a transação é aceita, essa saída de 7 ADA é consumida por inteiro. O pagamento de 5 ADA e os 1,8 ADA de troco são novas saídas, criadas pela transação c9047f2a61bd….

Entrada de AnaSAÍDA7 ₳8f3c2a91d6e4…#0CONSUMIDAPermanece no histórico
Pagamento a BrunoUTxO5 ₳c9047f2a61bd…#0Endereço de Bruno
Troco de AnaUTxO1,8 ₳c9047f2a61bd…#1Endereço de Ana
UTxO4 ₳2b7e4d90a6c1…#0Endereço de Ana

Não foi usada.
Continua disponível para Ana.

7 ADA = 5 ADA de pagamento + 1,8 ADA de troco + 0,2 ADA de taxa. A taxa não é uma saída de pagamento.

O troco pode voltar ao mesmo endereço de Ana, mas tem uma nova referência: c9047f2a61bd…#1. A antiga 8f3c2a91d6e4…#0 permanece no histórico como saída gasta e não pode ser usada novamente. A carteira agora soma os 4 ADA que ficaram intactos aos 1,8 ADA de troco e mostra 5,8 ADA.

Se duas transações tentarem gastar a mesma saída, ambas podem ser preparadas, mas não podem efetivar esse gasto na mesma cadeia. Depois que uma consome a saída, a outra precisa ser reconstruída com entradas ainda disponíveis. Por isso, uma aplicação acompanha as referências usadas, além do saldo total.

Em um pagamento simples de ADA, o valor das entradas deve cobrir o valor das saídas e a taxa. O troco precisa ser incluído na construção; ele não aparece automaticamente no ledger. A carteira ou o SDK costuma fazer essa seleção e esse cálculo. A taxa de uma transação real e o ADA mínimo de cada saída dependem de seus dados e dos parâmetros vigentes. Na próxima aula, calcularemos a taxa e definiremos a validade da transação.

4. O que o eUTxO acrescenta

Além de transferir valores, uma aplicação pode precisar guardar dados que serão usados para decidir um gasto futuro. O modelo eUTxO, ou extended UTxO, mantém o consumo e a criação de saídas e amplia o que uma regra de script pode verificar.

O datum contém dados associados à saída.

Esses dados são chamados de datum. Uma saída pode conter o datum ou o hash que o identifica. No segundo caso, quem a gasta fornece o dado correspondente quando ele é exigido pelo script.

O datum não é a regra de gasto. A regra é código: o script lê os dados e verifica as condições previstas para aquela transação.

Por exemplo, o datum pode registrar versão = 3, enquanto o script exige que uma atualização crie uma nova saída com versão = 4. A mudança ocorre pelo consumo da saída anterior e pela criação da sucessora, sem editar o datum da saída antiga. Quais sucessoras são exigidas depende da regra escrita no script.

Ao gastar, a transação pode fornecer também um redeemer, com informações sobre a ação pretendida. O script verifica essa ação junto do datum e do contexto da transação. Vamos trabalhar com esses elementos na Aula 1.12; por enquanto, a distinção importante é entre o dado associado à saída e o código que decide se ela pode ser gasta.

Atividade 1: selecione as entradas

Você tem três saídas disponíveis: 7 ADA, 4 ADA e 1 ADA. Quer fazer um pagamento de 8 ADA, com taxa de 0,2 ADA.

Qual construção cobre o pagamento e a taxa usando o menor número de entradas?

0 de 1 pergunta respondida.

Conferir resposta

A alternativa C é a correta. São necessários 8,2 ADA. Nenhuma saída isolada cobre esse valor, mas as de 7 e 4 ADA cobrem: 11 − 8 − 0,2 = 2,8 ADA de troco. A saída de 1 ADA continua disponível. A alternativa D também fecha a conta, mas usa uma entrada desnecessária; A e B não deixam valor para a taxa.

Atividade 2: acompanhe a referência

No pagamento ilustrado, 8f3c2a91d6e4…#0 foi consumida, c9047f2a61bd…#1 recebeu o troco e 2b7e4d90a6c1…#0 permaneceu intacta. O troco foi enviado ao mesmo endereço da saída consumida.

Quais referências ficam disponíveis para quem fez o pagamento?

0 de 1 pergunta respondida.

Conferir resposta

A alternativa B é a correta. O troco é uma nova saída de 1,8 ADA, identificada por c9047f2a61bd…#1. A saída 2b7e4d90a6c1…#0, de 4 ADA, não foi consumida. Já 8f3c2a91d6e4…#0 foi gasta e c9047f2a61bd…#0 está sob a condição de gasto do destinatário. Assinar a transação que criou um pagamento não concede autorização para gastá-lo depois.

O que aprendemos

  • A carteira calcula o saldo a partir das saídas não gastas associadas aos seus endereços.
  • Uma entrada identifica a saída pelo hash da transação que a criou e pelo índice. O endereço identifica a condição de gasto.
  • A saída selecionada é consumida inteira. Pagamento e troco têm novas referências; saídas não utilizadas permanecem disponíveis.
  • No eUTxO, o datum fornece dados associados à saída. O script contém a regra que usa esses dados para verificar um gasto.

Próxima aula

O pagamento fechou a conta porque já tínhamos um valor de taxa. Na próxima aula, veremos como calcular esse custo a partir dos bytes da transação e dos parâmetros da rede, definir sua validade e usar a carteira para assinar e submeter o resultado.

Módulo 1 Aula 1.8

Taxas, validade e CIP-30: preparar, assinar e submeter

Fechar custo e validade antes de pedir assinatura por CIP-30, preservar witnesses e acompanhar a submissão.

Objetivos

Ao final desta aula, você será capaz de:

  1. explicar taxa como uma regra de uso de recursos da rede;
  2. medir a transação serializada e calcular sua taxa mínima com parâmetros consultados;
  3. usar o contrato CIP-30 para separar construção, assinatura, merge de witnesses e submissão sem transferir a custódia da chave ao dApp;
Antes de começar

Você precisa lembrar que uma transação consome saídas, cria novas saídas, carrega campos verificáveis e depende de bytes finais. Também precisa lembrar que a taxa entra na contabilidade: entradas precisam cobrir pagamentos, troco e taxa.

Pergunta-guia

Se uma transação já expressa entradas, saídas e condições técnicas de gasto, o que ainda precisa estar correto para que a rede aceite o custo e o momento de validade desse pacote?

1. Taxa como regra de recurso

Uma taxa é uma parte verificável do desenho do pacote, não apenas um preço colocado por fora da transação. A rede precisa limitar uso de espaço, processamento e armazenamento. Se qualquer pessoa pudesse enviar pacotes grandes ou caros sem custo proporcional, os nós teriam de gastar recursos sem contrapartida e a rede ficaria mais fácil de saturar.

A taxa cumpre duas funções técnicas ao mesmo tempo. Primeiro, atribui um custo mínimo ao espaço e ao processamento exigidos, o que torna abuso em massa mais caro. Segundo, fornece uma condição objetiva do ledger: a taxa declarada precisa ser pelo menos a taxa mínima calculada para a transação sob os parâmetros vigentes.

Nas regras atuais, a parcela básica usa uma fórmula linear sobre o tamanho serializado, a × tamanho(tx) + b. Transações Plutus acrescentam o preço das execution units de memória e CPU; reference scripts usados pela transação podem acrescentar custo próprio. Os parâmetros pertencem ao protocolo e podem mudar. Você não precisa decorá-los agora: precisa construir o pacote final e consultar os valores da rede e da era usadas.

2. Tamanho e complexidade

O tamanho de uma transação importa porque os nós precisam receber, propagar, armazenar e validar seus bytes. Mais campos, mais metadados e mais witnesses aumentam o pacote. Mesmo quando o conteúdo parece pequeno na tela, a representação final pode incluir estruturas que não aparecem no resumo amigável da carteira.

O pacote abaixo já contém uma assinatura e um anexo contendo um hash de 32 bytes. PyCardano recupera a transação do CBOR e mede sua serialização completa. Depois retiramos a assinatura de uma cópia para mostrar quanto uma estimativa sobre o pacote incompleto deixaria de contar.

Usamos a = 44 lovelace por byte e b = 155381 lovelace, consultados para Preprod na API Koios em 17/09/2026 (versão de protocolo 11.0). São valores de referência daquela consulta, não parâmetros a manter fixos numa aplicação. O exemplo não usa execução Plutus nem reference scripts.

from copy import deepcopy
from pycardano import Transaction, TransactionWitnessSet

publicacao = Transaction.from_cbor(
    "84a5008182582000000000000000000000000000000000000000000000000000"
    "0000000000000000018182583900a8129b4a8cd0c92c493951812832b9b1db83"
    "c30e47505235ccb28236afd30edc1f4f7586430510ee4026385e22a7b0fb1d14"
    "6844841077bb1a05f5e100021a00030d40031903e8075820c2ddb7ed36466d97"
    "3a1f247b271c5eea6ecb42f689c2590704b8667eac2f9f2ba100818258207ba0"
    "6f84ca4c85d83b1ab9e73fb37dd5a005658c2515b026a0cf26f5130ad42a5840"
    "907414df5ba4ef1d1a362e2eabd3dd40081a24d9b4b6bb8b5e78e76c98345eed"
    "277f427ba99fc70d5980ae4604d1175f3b4ced3a16f7ccc27b2a69d77e212606"
    "f5d90103a100a11903e9a164726f6f7458202da39bbe8eb68096f77d903e70fb"
    "6b88b3d8d55ad8b4e8efa5f6f092c673163a"
)
a, b = 44, 155381
tamanho = len(publicacao.to_cbor())
print("com assinatura:", tamanho, "bytes; mínimo:", a * tamanho + b, "lovelace")

sem_assinatura = deepcopy(publicacao)
sem_assinatura.transaction_witness_set = TransactionWitnessSet()
tamanho_incompleto = len(sem_assinatura.to_cbor())
print("sem assinatura:", tamanho_incompleto, "bytes; conta incompleta:",
      a * tamanho_incompleto + b, "lovelace")

O pacote assinado mede 306 bytes: o mínimo calculado é 168845 lovelace. Sem a assinatura, a conta daria 164313, uma diferença de 4532 lovelace. A taxa declarada no corpo é 200000, acima do mínimo; o cálculo não altera esse campo. Se precisar alterá-lo, reconstrua o corpo e recolha novas assinaturas.

As chaves são de estudo e o input é fictício, como na Aula 1.6. A medição usa CBOR e assinatura reais, mas o pacote não é uma transferência pronta para envio.

Antes da assinatura: 203 bytescorpo, anexo e estrutura do pacoteCom a assinatura: 306 bytes+103 bytes
A diferença medida na serialização inclui a witness e sua estrutura CBOR. Contar apenas os 64 bytes da assinatura também subestimaria o pacote.

3. Validade temporal

Uma aplicação costuma declarar uma janela de validade para limitar quando a intenção pode ser aceita. No ledger Cardano, os limites inferior e superior são campos opcionais conforme a era; sua ausência ou presença precisa seguir as regras vigentes e a política da aplicação. Um limite superior finito evita que aquela proposta específica permaneça aceitável indefinidamente.

Pense em uma carteira que monta uma transação agora. Ela seleciona entradas, calcula taxa, cria troco e pede assinatura. Se esse pacote ficar parado por muito tempo, várias coisas podem mudar: uma entrada pode ser consumida por outra transação, os parâmetros da rede podem mudar, o usuário pode desistir, ou a aplicação pode não querer mais registrar aquela operação.

Uma assinatura matematicamente válida não torna a transação eterna. Se o corpo assinado inclui um intervalo de validade, o ledger só pode aceitar o pacote dentro desse intervalo.

Em Cardano, o corpo pode declarar um intervalo com limite inferior inclusivo (invalid_before) e limite superior exclusivo (invalid_hereafter). Para um slot s, a condição é invalid_before <= s < invalid_hereafter quando os dois limites existem. O ledger compara esse intervalo com o slot em que a transação é processada. O “slot atual” mostrado por wallet, API ou explorer não é um campo mágico da transação: é uma observação externa usada pelo builder para escolher margens e pelo operador para decidir se ainda há tempo de submeter.

janela de validadeexpirada: recusadamesmo bem assinadaslots182440monta e assina182470submete e propaga182500invalid_hereafter
O pacote só é válido no intervalo declarado no corpo: no slot 182500 e depois ele está expirado, ainda que a assinatura continue matematicamente correta.

4. Do builder à wallet por CIP-30

Uma aplicação que já conhece inputs, outputs e parâmetros pode construir o corpo sem custodiar a chave privada. O builder seleciona inputs ainda disponíveis, calcula taxa para o tamanho final esperado, cria troco e fixa a validade. O signer revisa a transação e produz witnesses sobre o body hash. CIP-30 padroniza essa conversa entre dApp e wallet externa no navegador.

A pessoa autoriza a conexão por enable(). O dApp consulta getNetworkId(), getUtxos() e getChangeAddress(). O ID de rede 0 identifica ambiente de teste, mas não distingue Preprod de Preview: wallet e provedor do builder ainda precisam apontar para a mesma testnet. UTxOs retornam como CBOR em hexadecimal; o endereço de troco também vem em representação binária hex, não necessariamente no texto Bech32 exibido na tela.

Chamada CIP-30Objeto que atravessa a fronteiraTrabalho que ainda falta
signTx(txCborHex, true)Entra a transação CBOR; sai somente o witness set produzido pela wallet.Validar e mesclar o retorno à mesma transação.
submitTx(txCompletaCborHex)Entra a transação completa; retorna seu transaction ID.Observar inclusão em bloco na rede correta.

partialSign=true permite que a wallet assine apenas a parte que consegue. Com false, ela deve retornar erro se não puder assinar a transação inteira. Um retorno parcial não demonstra que todas as condições foram satisfeitas. A aplicação precisa reunir os demais signers e preservar scripts, datums e redeemers existentes. Substituir o witness set inteiro pelo retorno da última wallet perde componentes já coletados.

A taxa deve prever todas as witnesses esperadas. Se a transação pronta exige outra taxa, a mudança afeta o corpo e o troco: é necessário reconstruir, revisar e assinar novamente. Auxiliary data fica fora do body, comprometido pelo hash nele; is_valid também fica fora e não é diretamente assinado pela vkey witness. Portanto, verificar o body hash não dispensa preservar o pacote completo revisado.

5. Mesclar sem perder a primeira assinatura

Primeiro, veja o que uma assinatura produz. O digest abaixo é o body hash da publicação medida na seção 2. Uma chave descartável assina esses 32 bytes; VerificationKeyWitness reúne a chave pública e a assinatura. A verificação usa a chave pública, a mesma mensagem e a assinatura recebida.

from pycardano import PaymentSigningKey, VerificationKeyWitness, TransactionWitnessSet
from nacl.signing import VerifyKey

mensagem = bytes.fromhex("1a2232772e3aeca8ec28f1f2bc82d36761ef1ca7084b9e010786245157a6e0f1")
chave = PaymentSigningKey.generate()
witness = VerificationKeyWitness(chave.to_verification_key(), chave.sign(mensagem))
VerifyKey(witness.vkey.payload).verify(mensagem, witness.signature)
pacote = TransactionWitnessSet(vkey_witnesses=[witness])
print("chave pública:", len(witness.vkey.payload), "bytes")
print("assinatura:", len(witness.signature), "bytes")
print("witness set CBOR:", pacote.to_cbor_hex())

Troque apenas a mensagem passada a verify por bytes(32). A verificação deve falhar: a assinatura continua tendo 64 bytes, mas pertence a outro corpo. Restaure a mensagem. As chaves geradas aqui são descartáveis e não controlam fundos.

Um retorno CIP-30 traz o witness set em CBOR. TransactionWitnessSet.from_cbor() recupera seus componentes. No exercício seguinte, os dois conjuntos já têm assinaturas compatíveis com o mesmo corpo. O recorte reúne vkey witnesses e scripts nativos; outros componentes exigem tratamento próprio.

Atividade: preserve o pacote já reunido

O primeiro conjunto contém uma assinatura e um script. O segundo acrescenta outra assinatura. A função já copia o pacote e reúne scripts sem repetição, mas deixa de incluir a primeira assinatura. Corrija o argumento None na chamada a unir e use Validar solução. O resultado deve ter duas assinaturas e um script.

from copy import deepcopy
from pycardano import TransactionWitnessSet, NonEmptyOrderedSet

def unir(a, b):
    return NonEmptyOrderedSet([*(a or []), *(b or [])]) or None

def mesclar(existentes, recebidas):
    resultado = deepcopy(existentes)
    resultado.vkey_witnesses = unir(None, recebidas.vkey_witnesses)
    resultado.native_scripts = unir(existentes.native_scripts, recebidas.native_scripts)
    return resultado

existentes = TransactionWitnessSet.from_cbor(
    "a200818258207ba06f84ca4c85d83b1ab9e73fb37dd5a005658c2515b026a0cf"
    "26f5130ad42a5840907414df5ba4ef1d1a362e2eabd3dd40081a24d9b4b6bb8b"
    "5e78e76c98345eed277f427ba99fc70d5980ae4604d1175f3b4ced3a16f7ccc2"
    "7b2a69d77e21260601818200581c70e402284201ec81d7aa495d17e52209c8bb"
    "47489395b16bcd7a2a67"
)
recebidas = TransactionWitnessSet.from_cbor(
    "a100818258209be9aca30d6e4c708ec6c0642454e623edbeabf6975013520337"
    "780b3d7fa0ea5840fb04a8dafb497689bc14f7d9432f538b30953667772d9596"
    "8f99dff898213254175e9925b6e49159890a21ad3d1c49378c569c3eafcef571"
    "a2f52dbdf18f9102"
)
resultado = mesclar(existentes, recebidas)
print("assinaturas:", len(resultado.vkey_witnesses or []))
print("scripts:", len(resultado.native_scripts or []))
Conferir resposta

Substitua None por existentes.vkey_witnesses. A função passa a reunir as duas coleções, e NonEmptyOrderedSet evita repetir componentes iguais. A cópia preserva os scripts e mantém os pacotes de entrada intactos. O merge não modifica o corpo nem substitui a verificação das assinaturas mostrada antes da atividade.

Ao recusar a assinatura ou quando a janela expira, a aplicação interrompe o envio. O retorno de submitTx indica submissão, não inclusão. Se houver timeout, consulte o ID antes de criar outra operação: falta de resposta não demonstra ausência na rede.

Na rota CIP-30, a chave permanece na wallet externa, e o dApp depende da disponibilidade e da aprovação do signer. Um aplicativo que incorpora uma wallet por SDK assume a custódia local; um signer no servidor assume a proteção do segredo e os controles de autorização do serviço. Automatizar não exige entregar a seed ao frontend. Um dApp comum nunca deve pedir frase de recuperação, e conectar uma wallet não autoriza silenciosamente todos os gastos futuros.

O que aprendemos

  • Taxa, tamanho e uso de recursos fazem parte da construção da transação.
  • A medição deve incluir witnesses e dados auxiliares. Os parâmetros consultados determinam o mínimo; scripts podem acrescentar parcelas específicas.
  • O intervalo de validade limita quando a transação pode ser aceita. Uma transação construída corretamente pode deixar de ser utilizável com a passagem do tempo.
  • CIP-30 devolve witnesses, que precisam ser mescladas à mesma transação. Submissão não comprova inclusão em bloco.

Próxima aula

Se anexar metadata muda os bytes, o tamanho e a taxa do pacote, o que vale publicar como anexo e o que deve permanecer em um documento externo?

Módulo 1 Aula 1.9

Metadata: anexar uma mensagem à transação

Objetivos
  1. Criar metadata a partir de um dicionário Python.
  2. Observar sua representação em CBOR e seu hash.
  3. Explicar como o corpo da transação fica ligado a esses dados.
Antes de começar

Retome o cálculo de hashes na Aula 0.2 e a representação da transação em CBOR na Aula 1.6.

Pergunta-guia

Se alguém alterar uma mensagem anexada à transação, o que acontece com o hash desses dados?

1. Uma mensagem na transação

Metadata são dados opcionais que podem acompanhar uma transação, como uma mensagem. Escrever uma mensagem não cria tokens nem faz a rede verificar se o texto é verdadeiro.

Em Python, podemos representar esses dados com um dicionário: {1001: {"mensagem": "Olá, Cardano!"}}. A chave externa precisa ser um inteiro; escolhemos 1001 para este exemplo. A chave mensagem e seu texto são escolhidos por quem prepara os dados.

2. Criar metadata com PyCardano

Metadata recebe o dicionário. As classes AlonzoMetadata e AuxiliaryData montam o anexo no formato usado pela transação. Execute o exemplo: ele mostra a mensagem, o anexo em CBOR escrito como hexadecimal e o hash do anexo.

from pycardano import Metadata, AlonzoMetadata, AuxiliaryData

mensagem = "Olá, Cardano!"
dados = Metadata({1001: {"mensagem": mensagem}})
anexo = AuxiliaryData(AlonzoMetadata(metadata=dados))

print("mensagem:", dados[1001]["mensagem"])
print("CBOR:", anexo.to_cbor_hex())
print("hash:", anexo.hash().payload.hex())

Use mensagens curtas: cada texto de metadata pode ocupar até 64 bytes. Caracteres como á ocupam mais de um byte em UTF-8.

Atividade: altere a mensagem

Execute o código acima. Troque Olá, Cardano! por Olá, Ada! e execute novamente. O que mudou no CBOR e no hash?

Depois restaure a mensagem original e execute mais uma vez. Compare o resultado com o da primeira execução.

Conferir resposta

Alterar a mensagem muda os bytes do anexo e seu hash. Ao restaurar a mensagem original, o mesmo código produz novamente o CBOR e o hash iniciais. O cálculo depende dos dados, não do momento da execução.

3. Como esses dados ficam ligados à transação

O anexo fica nos auxiliary data, fora do corpo da transação. O corpo guarda o hash desse anexo no campo auxiliary_data_hash.

Se a mensagem mudar, é preciso atualizar esse campo. Isso muda o corpo e seu body hash. Portanto, uma transação já assinada precisa de novas assinaturas depois dessa alteração.

Ao publicar a transação, a mensagem fica acessível junto dos demais dados.

O que aprendemos

  • Um dicionário Python pode fornecer os dados para criar metadata com PyCardano.
  • Alterar a mensagem muda o CBOR e o hash do anexo.
  • O campo auxiliary_data_hash liga o corpo da transação ao anexo.

Próxima aula

Uma mensagem em metadata não cria unidades transferíveis. Na próxima aula veremos como os ativos nativos aparecem nos valores da transação.

Módulo 1 Aula 1.10

Ativos nativos e políticas: identidade, quantidade e multisig

Entender que a identidade técnica de um ativo nativo combina policy ID e asset name, e não apenas um rótulo legível.

Objetivos

Ao final desta aula, você será capaz de:

  1. diferenciar metadata anexada a uma transação de um ativo nativo representado pelo ledger;
  2. explicar por que policy ID faz parte da identidade de um ativo;
  3. interpretar asset names como bytes e avaliar um native script de assinaturas e tempo;
  4. explicar como mint, burn e transferência alteram quantidades inteiras sob uma minting policy.
Antes de começar

Você precisa lembrar que uma transação consome saídas e cria novas saídas, que taxas dependem dos bytes finais do pacote, e que metadata é um anexo estruturado, não uma prova automática de verdade externa.

Pergunta-guia

Se dois ativos aparecem com o mesmo nome em uma interface, quando a rede os trata como o mesmo ativo e quando ela os trata como ativos diferentes?

1. Ativo nativo em nível conceitual

Um ativo nativo é um ativo que o ledger consegue representar diretamente no valor de uma saída. Em vez de aparecer apenas como texto em metadata, ele aparece como uma quantidade dentro da contabilidade da transação.

Você pode imaginar uma saída com um valor assim:

Componente do valor Quantidade
ada 10
ativo definido por uma política e um nome 50

Escrever nome: TOKEN em metadata não cria unidades no ledger. Um native asset aparece no valor dos outputs, mas não herda o papel de ADA em taxas, staking, depósitos ou governança.

2. Policy ID como parte da identidade

O policy ID é uma parte da identidade do ativo. Em Cardano, ele é o hash de 28 bytes da minting policy, normalmente exibido como 56 caracteres hexadecimais. Não é um rótulo livre. A política define as condições técnicas para permitir mint positivo ou negativo daquele ativo; autoridade institucional e finalidade continuam externas.

O exemplo usa dois policy IDs calculados a partir de políticas de assinatura. ScriptHash guarda o ID; AssetName guarda os bytes do nome. MultiAsset organiza quantidades primeiro por política e depois por nome.

from pycardano import ScriptHash, AssetName, Asset, MultiAsset

p1 = ScriptHash(bytes.fromhex("b42438993a121732d88cf0719ef8a895953e5cd686c48782bccec209"))
p2 = ScriptHash(bytes.fromhex("d3b22f481e20b76f395e04df54fc7e480c385cdc83f9b99412d295dd"))
nome = AssetName(b"TOKEN")
minusculo = AssetName(b"token")
saldo = MultiAsset({p1: Asset({nome: 50, minusculo: 3}), p2: Asset({nome: 7})})
for politica, ativos in saldo.items():
    for nome_do_ativo, quantidade in ativos.items():
        print(politica.payload.hex(), nome_do_ativo.payload.hex(), quantidade)
print("CBOR:", saldo.to_cbor_hex())

A saída mostra três identidades distintas. Há 50 unidades de TOKEN e 3 de token sob b42438993a12…, e 7 de TOKEN sob d3b22f481e20…. Criar esse objeto em Python descreve um valor; emitir as unidades no ledger exige uma transação de mint autorizada pela política.

Usar apenas TOKEN como chave no banco de dados pode misturar saldos de ativos com políticas diferentes.

POLÍTICA b42438993a12… POLÍTICA d3b22f481e20… 544f4b454eTOKEN 746f6b656etoken Mesma política, bytes diferentes. 544f4b454eTOKEN ≠Mesmo nome, outra política. policy ID + asset nameformam a identidade do ativo.
Os três ativos têm identidades distintas: mudar os bytes do nome ou o policy ID muda a identidade. Os policy IDs estão abreviados; os bytes dos nomes estão completos.

3. Asset name como bytes

O asset name não é, conceitualmente, uma palavra. Ele é uma sequência de zero a 32 bytes. Muitas vezes esses bytes são escolhidos para formar um texto legível em UTF-8, mas isso é uma escolha de emissão e de integração, não uma garantia universal.

Por isso, ferramentas frequentemente mostram asset names em hexadecimal. Hexadecimal é uma forma estável de escrever bytes. Cada par de caracteres hex representa um byte. Por exemplo, o texto TOKEN, quando codificado em UTF-8, vira os bytes:

54 4f 4b 45 4e
544f4b454e

Também pode existir asset name vazio. Nesse caso, a identidade ainda precisa ser lida com cuidado: o asset name é a sequência de zero bytes, não um texto ausente por esquecimento.

4. Quantidades inteiras, mint, burn e transferência

O ledger contabiliza cada ativo nativo em quantidades inteiras. Se uma interface exibe casas decimais, essa escala pertence ao esquema e à apresentação da aplicação; o valor on-chain continua inteiro. Por isso, a unidade mínima precisa ser definida antes de emitir ou integrar o ativo.

Para um asset_id específico, uma forma compacta de ler a conservação é:

quantidade nos inputs + quantidade em mint = quantidade nos outputs

O campo mint usa quantidades com sinal. Um valor positivo cria unidades; um valor negativo remove unidades que também entram pelos inputs; zero significa que a transação não altera a quantidade total daquele ativo. Mint positivo e negativo exigem que a minting policy correspondente seja executada e satisfeita.

OperaçãoInputs do ativoMintOutputs do ativoLeitura
Mint0+100100A quantidade total aumenta em 100.
Transferência70020 + 50As mesmas 70 unidades são realocadas entre outputs.
Burn100-2575Vinte e cinco unidades deixam a contabilidade.

Transferir não é cunhar novamente. Quando mint = 0 para o ativo, sua minting policy não é executada apenas por causa da transferência; as condições de gasto dos inputs continuam sendo verificadas. Já mint e burn usam o campo mint e precisam satisfazer a política cujo hash forma o policy_id.

Atividade 1: feche a conservação de um ativo

Considere que cada linha descreve todos os inputs, o campo mint e todos os outputs do mesmo asset_id. Classifique cada linha como mint, transferência, burn ou inválida e justifique com inputs + mint = outputs.

  • A: inputs 0; mint +60; outputs 60.
  • B: inputs 60; mint 0; outputs 15 + 45.
  • C: inputs 60; mint -10; outputs 50.
  • D: inputs 60; mint 0; outputs 55.
Conferir resposta

A é mint: 0 + 60 = 60. B é transferência: 60 + 0 = 15 + 45, sem mudança na quantidade total. C é burn: 60 - 10 = 50. D é inválida neste exemplo, que informa todas as entradas e saídas, pois 60 + 0 não é igual a 55. Em A e C, a minting policy precisa ser executada e satisfeita; em B, ela não é reexecutada apenas pela transferência.

5. Native scripts: quais chaves, em qual intervalo?

Uma minting policy pode ser um native script, que combina condições de assinatura e tempo. O mesmo tipo de script também pode funcionar como credencial de gasto de um output. Os pontos de controle são distintos: a policy verifica mint ou burn sob seu policy ID; a credencial de gasto verifica o consumo da eUTxO. Possuir um token não concede automaticamente capacidade de emitir mais unidades.

O formato nativo oferece sig para exigir uma chave, all e any para combinar condições e atLeast para exigir um limiar. Timelocks usam after e before. A regra compara os limites de validade da transação: after 100 exige limite inferior pelo menos 100; before 200 exige limite superior no máximo 200. O ledger também verifica se o slot de processamento pertence ao intervalo. Uma assinatura criada antes do prazo não autoriza inclusão depois dele.

Em PyCardano, ScriptNofK(2, ...) exige duas das condições de assinatura. ScriptAll combina esse limiar com as duas condições temporais. As credenciais abaixo são hashes de três chaves públicas de estudo.

from pycardano import (
    VerificationKeyHash, ScriptPubkey, ScriptNofK, ScriptAll,
    InvalidBefore, InvalidHereAfter,
)

chaves = [
    VerificationKeyHash(bytes.fromhex("70e402284201ec81d7aa495d17e52209c8bb47489395b16bcd7a2a67")),
    VerificationKeyHash(bytes.fromhex("b44173e4bc81916bb53443b01ce8d8d635b618ca7fa197265a0cb2a2")),
    VerificationKeyHash(bytes.fromhex("d5c6555b5a7c12cc53893955e9b779c9320afb2411994a5c70cee206")),
]
assinaturas = ScriptNofK(2, [ScriptPubkey(chave) for chave in chaves])
politica = ScriptAll([InvalidBefore(100), InvalidHereAfter(200), assinaturas])
print("CBOR:", politica.to_cbor_hex())
print("policy ID:", politica.hash().payload.hex())

Execute e depois troque o limite 200 por 201. A política mudou, portanto seu CBOR e seu policy ID também mudam. Restaure 200. Para satisfazer a política original, uma transação pode usar o intervalo [120, 180) e assinaturas válidas de duas dessas chaves. Serializar o script não executa a validação do ledger.

O native script não lê datum, redeemer ou metadata e não inspeciona asset name ou quantidade cunhada. Assim, “duas assinaturas antes do prazo” não impõe, por si só, supply máxima de 100 ou emissão única.

Atividade 2: não conte a mesma chave duas vezes

A função deve construir a mesma política de duas entre três chaves distintas, dentro da janela recebida. Mas uma credencial aparece duas vezes. Corrija a referência repetida, sem mudar o limiar nem os limites, e use Validar solução.

from pycardano import (
    VerificationKeyHash, ScriptPubkey, ScriptNofK, ScriptAll,
    InvalidBefore, InvalidHereAfter,
)

def criar_politica(chaves, inicio, fim):
    assinaturas = ScriptNofK(2, [
        ScriptPubkey(chaves[0]), ScriptPubkey(chaves[0]), ScriptPubkey(chaves[2])
    ])
    return ScriptAll([InvalidBefore(inicio), InvalidHereAfter(fim), assinaturas])

chaves = [
    VerificationKeyHash(bytes.fromhex("70e402284201ec81d7aa495d17e52209c8bb47489395b16bcd7a2a67")),
    VerificationKeyHash(bytes.fromhex("b44173e4bc81916bb53443b01ce8d8d635b618ca7fa197265a0cb2a2")),
    VerificationKeyHash(bytes.fromhex("d5c6555b5a7c12cc53893955e9b779c9320afb2411994a5c70cee206")),
]
politica = criar_politica(chaves, 100, 200)
print("CBOR:", politica.to_cbor_hex())
print("policy ID:", politica.hash().payload.hex())
Conferir resposta

Troque a segunda ocorrência de chaves[0] por chaves[1]. Com A, A e C, a mesma assinatura de A pode satisfazer as duas condições repetidas. Com A, B e C, o limiar exige duas credenciais distintas. PyCardano serializa ambas as versões: produzir CBOR não garante que você escreveu a política pretendida. Os testes conferem a estrutura construída, sem simular a aceitação de uma transação pelo ledger.

Mesmo uma combinação válida de duas chaves não comprova duas pessoas independentes nem uma deliberação válida. O processo externo precisa relacionar chaves a responsáveis e papéis. Além disso, se a policy deixar de aceitar mint após um prazo, o mesmo bloqueio temporal pode impedir burn; retirada de circulação precisa ser planejada antes da emissão.

6. Uma contabilidade curta de EAC

Um certificado de atributo ambiental (EAC) tem unidade e critérios definidos por uma metodologia externa. Neste exemplo, uma decisão externa autoriza 8.400 unidades inteiras do ativo de nome UTF-8 EAC-DEMO-VINTAGE-A. Sob o mesmo policy ID e sem outras emissões, mint de +8400 seguido de retiradas por burn de -1250 e -700 deixa 6.450 unidades.

supply = 0
for mint in (8400, -1250, -700):
    supply += mint
    print("mint:", mint, "supply:", supply)

A saída é 8400, 7150 e 6450. Para executar cada burn, a transação precisa trazer pelos inputs as unidades removidas e satisfazer a policy. Uma transferência não altera supply. A soma de três operações só demonstra a supply global se o histórico de mint e burn estiver completo. O ledger não mede o benefício ambiental nem impede dupla contagem em outro sistema. Esse exemplo usa burn como retirada; o significado institucional dessa operação é definido fora do protocolo.

7. CIP-25 para descrição de media tokens

CIP-25 é uma convenção de metadata para media tokens sob o label 721, associando policy ID e asset name a campos como name e image. Ela não é padrão universal para todo native asset e não é necessária para a aritmética do EAC. Nome e imagem exibidos por uma wallet não substituem a identidade técnica.

Essa metadata permanece na transação de mint positivo. Transferir o ativo não a move nem a edita. Pelo padrão, uma publicação posterior considerada atualização também depende de mint positivo sob a policy correspondente; burn não satisfaz essa regra. Uma policy já encerrada pode impedir tal atualização. Quando a aplicação precisa de um estado de referência substituível, CIP-68 oferece outro desenho, estudado depois de Plutus.

O que aprendemos

  • Um native asset aparece no valor contabilizado pelo ledger. Metadata descritiva, sozinha, não cria esse ativo.
  • A identidade técnica combina policy ID e asset name. Um nome ou rótulo visível não basta para identificar o ativo.
  • Asset names são bytes; texto e hexadecimal são formas de representá-los.
  • Mint e burn alteram supply sob a policy; transferência apenas redistribui unidades. A aritmética de EAC não comprova o benefício externo.
  • Native scripts combinam chaves e tempo, em papéis de minting ou gasto. CIP-25 descreve media tokens, sem impor regras sobre o conteúdo.

Próxima aula

Como localizar uma transação real e conferir os dados que foram publicados? Na próxima aula, abriremos o mesmo registro em explorers diferentes e compararemos o que eles mostram.

Módulo 1 Aula 1.11

Explorers: consultar uma transação

Objetivos
  1. Encontrar uma transação pelo seu identificador.
  2. Localizar bloco, taxa e tamanho em um explorer.
  3. Conferir a mesma transação em dois sites.
Antes de começar

Um explorer é um site para consultar transações, endereços e blocos. Não é necessário conectar uma carteira para fazer uma consulta.

Pergunta-guia

Onde posso conferir uma transação e quanto ela pagou de taxa?

1. Explorers que você pode usar

As redes têm históricos separados. Uma transação de Preprod deve ser consultada na versão Preprod do explorer. Os links do exemplo abaixo já apontam para essa rede.

2. Abra esta transação de Preprod

Este é o identificador de uma transação real:

d9b7a0b3c9bdb62e5a76d9ab675342be002c335a05e1be5d7bc04872bf99865f

Abra a mesma transação no Cardanoscan, no AdaStat ou no Cexplorer.

O identificador pode aparecer como Transaction ID, Transaction Hash ou Tx Hash. É ele que você copia para procurar a transação em outro site.

3. Localize os campos

  • Bloco: indica onde a transação foi incluída. Neste exemplo, é o bloco 5114018.
  • Taxa: é o valor pago pelo processamento da transação. Neste exemplo, 600628 lovelace, equivalentes a 0,600628 ADA. Não confunda taxa com valor enviado.
  • Tamanho: é o tamanho serializado da transação. Neste exemplo, 1473 bytes.

Esses valores foram consultados na API Koios de Preprod em 17/09/2026. Os explorers podem usar nomes e formatos diferentes para mostrar os mesmos dados.

As listas de inputs e outputs mostram as entradas consumidas e as saídas criadas. Clique em um endereço de saída para abrir sua página no explorer e ver outras transações relacionadas a ele.

4. Confira em outro explorer

Atividade: encontre a taxa em dois explorers

Abra os links de Cardanoscan e AdaStat acima. Localize o identificador e a taxa nos dois sites. Confirme que está olhando a mesma transação.

Se um site mostrar ADA e o outro lovelace, use 1 ADA = 1000000 lovelace para comparar.

Conferir resposta

A taxa é 600628 lovelace, ou 0,600628 ADA. O identificador deve ser o mesmo nas duas páginas. A comparação é entre os dados da transação, não entre a aparência das telas.

O que aprendemos

  • Cardanoscan, AdaStat e Cexplorer permitem consultar transações; explorer.cardano.org oferece um redirecionamento.
  • O identificador permite encontrar a mesma transação em outro explorer, na mesma rede.
  • Bloco, taxa e tamanho são campos distintos. ADA e lovelace são unidades diferentes do mesmo valor.

Próxima aula

Agora veremos como scripts Plutus expressam condições que uma transação precisa satisfazer.

Módulo 1 Aula 1.12

Plutus: validar os efeitos de uma mudança de estado

Objetivos
  1. Localizar estado, ação solicitada e efeitos observáveis em uma tentativa de gasto.
  2. Testar uma regra de continuação de estado, sem confiar apenas no redeemer.
  3. Distinguir falhas de fase 1, fase 2 e migração entre versões de script.
Antes de começar

Retome eUTxO na Aula 1.7, taxa e validade na Aula 1.8 e native scripts na Aula 1.10. Você já sabe que uma transação propõe consumir outputs e criar outros; agora examinaremos a regra que aceita ou recusa essa proposta.

Pergunta-guia

O redeemer pede “incrementar”. Como impedir que a transação crie uma versão diferente da solicitada?

1. Uma regra que precisa enxergar os outputs

Um registro tem versão 3 e deve avançar exatamente para 4. Exigir duas assinaturas antes de um prazo caberia em native script. Exigir que a nova saída mantenha o registro e contenha a versão correta exige observar dados e efeitos da transação. Esse é um uso de Plutus.

Um spending validator Plutus é executado quando a transação tenta consumir um output protegido por sua credencial de script. Ele não é um serviço que fica rodando nem uma função que altera o ledger por dentro. O builder propõe inputs e outputs; o script decide se a tentativa satisfaz suas condições. O ledger aplica a transição somente sob as regras de validação e inclusão pertinentes.

Native script e Plutus são alternativas conforme a informação necessária. Plutus acrescenta expressividade e custos de execução; não é uma etapa obrigatória de toda emissão ou transferência. Linguagens como Aiken, OpShin e plu-ts permitem escrever essas regras. Seus compiladores produzem código em UPLC (Untyped Plutus Core), que a rede avalia. O programa escrito pelo desenvolvedor e o código executado pelo ledger são representações diferentes; compilar sem erros não demonstra que a regra está correta.

2. Datum, redeemer e contexto

O datum é o dado associado ao estado protegido. Pode estar diretamente no output como inline datum, conforme CIP-32, ou ser comprometido por um datum hash e fornecido quando necessário. O redeemer é fornecido na transação candidata: declara qual ação está sendo solicitada. O ScriptContext é construído pelo ledger e expõe informações da transação relevantes à finalidade do script.

Inputs, outputs, mint, intervalo de validade, signatários e reference inputs podem entrar na decisão conforme a versão de Plutus e o propósito. A forma exata dos argumentos varia entre versões; a separação entre estado, pedido e contexto continua útil. Os signatários visíveis ao script não são uma lista arbitrária de todas as witnesses: o builder deve declarar os required signers pertinentes no corpo, e o ledger exige suas assinaturas.

Saída atual UTxO2 ₳ a61f8e4c2d90…#0Script: contador Datum · REC-0042versão = 3
Transação candidata Redeemer Incrementar
Saída proposta UTxO2 ₳ c8b03a7d19e2…#0Script: contador Datum · REC-0042versão = 4

O script contador exige uma única sucessora, no mesmo script, com o mesmo valor e versão anterior + 1.

Pedir “Incrementar” não autoriza um salto para a versão 7. A saída proposta só é criada se a transação for validada e incluída. Hashes ilustrativos e abreviados; taxas e outras entradas e saídas omitidas.

Transaction metadata é auxiliary data e não aparece no ScriptContext. Colocar aprovado: true em metadata não oferece ao validator uma condição verificável. Informações necessárias à regra precisam chegar por estruturas visíveis, como datum, redeemer ou outputs. O script também não baixa um relatório pela URL; verifica os dados fornecidos e os compromissos definidos na aplicação.

3. Conferir a saída, não apenas o pedido

O exemplo acompanha a continuação de um único registro. A lista sucessoras contém todas as saídas candidatas para esse registro. A regra exige exatamente uma, presa ao mesmo script, com o mesmo valor e versão anterior mais um. Em uma aplicação real, é preciso identificar o estado sem ambiguidade, por exemplo com um token único cuja policy garanta essa unicidade. Apenas encontrar um output com o mesmo nome ou datum não autentica a origem do estado.

Atividade 1: valide a continuação

O código inicial confere somente o redeemer. Corrija continua para conferir também a quantidade de sucessoras, o script, o valor e a versão de fato proposta. Mantenha os dados de teste: a função precisa aceitar a atualização correta e rejeitar as demais. O código é Python didático, não um validator compilável nem uma transação completa.

def continua(anterior, redeemer, sucessoras):
    return redeemer == "Incrementar"

anterior = {"script": "contador", "valor": 2, "versao": 3}
correta = {"script": "contador", "valor": 2, "versao": 4}
salto = {"script": "contador", "valor": 2, "versao": 7}
print("incremento:", continua(anterior, "Incrementar", [correta]))
print("salto:", continua(anterior, "Incrementar", [salto]))
Conferir resposta

Primeiro rejeite redeemer diferente de Incrementar ou lista com tamanho diferente de 1. Depois compare a única sucessora: script e valor iguais aos anteriores e versao == anterior["versao"] + 1. A tentativa correta passa; o salto para 7 falha. Preservar dois campos não compensa a violação do terceiro. O builder deve ainda satisfazer taxa, contabilidade, identificação do estado e demais regras fora desse recorte.

4. Falha de fase 1, fase 2 e collateral

A fase 1 verifica condições como estrutura, inputs disponíveis, conservação de valor, witnesses de chave, native scripts e validade temporal. Uma falha nessa fase rejeita a transação sem executar o caminho de cobrança por falha Plutus. Na fase 2, os scripts Plutus são avaliados com budgets de CPU e memória. Uma regra lógica correta ainda pode falhar por recursos insuficientes ou montagem incorreta.

Se a avaliação Plutus for válida e a transação for incluída pelo caminho normal, os inputs normais são consumidos e os outputs propostos são criados. O collateral não é coletado nesse caminho. Se uma transação passar pela fase 1 e for incluída marcada como inválida em fase 2, a transição normal não ocorre: a eUTxO do registro continua disponível e os outputs normais não são criados. O ledger aplica separadamente o caminho de collateral.

Collateral inputs são referências explícitas a UTxOs apropriadas, não um saldo abstrato na wallet. A quantia líquida coletável deve atender às regras e aos parâmetros vigentes. Nas regras com collateral return, o excesso pode voltar em um output próprio; tokens eventualmente presentes precisam voltar, pois a coleta líquida é em ADA. Uma seleção simples usa collateral somente em ADA. total_collateral, quando presente, deve corresponder à diferença aplicável. Uma simulação local que falha não cobra automaticamente collateral: é preciso distinguir avaliação, submissão e inclusão.

O mínimo de ADA dos outputs depende do tamanho e dos parâmetros da era, não é universalmente 1 ADA. Use uma biblioteca compatível e a avaliação de scripts antes de solicitar assinatura.

Atividade 2: acompanhe a tentativa inválida

A transação que propõe versão 7 passa pela fase 1, falha na fase 2 e é incluída marcada como inválida. Qual estado permanece?

Qual consequência corresponde ao caminho de fase 2 inválida?

0 de 1 pergunta respondida.

Conferir resposta

A segunda alternativa preserva os inputs normais e separa a cobrança de collateral. Não existe aplicação parcial do incremento rejeitado. A versão 3 continua no output de script.

5. Uma nova versão de código não move o estado

Mudar os bytes do script muda seu hash e a credencial do endereço. Publicar V2 ou apontar a interface para outro endereço não transfere os outputs protegidos por V1. Uma migração precisa consumir o estado antigo por uma transação aceita pelas regras de V1 e criar estado compatível com V2.

Planeje essa saída antes de bloquear valor: destino permitido, autorização, formato do novo datum e preservação dos ativos. Teste o caminho normal, tentativas inválidas e migração, com auditoria e monitoramento proporcionais ao risco. Se V1 não permite uma saída adequada, não se pode acrescentar retroativamente essa permissão só publicando outro script; o estado pode ficar imobilizado.

O que aprendemos

  • Plutus confere uma transação candidata usando estado, pedido e contexto.
  • O redeemer não substitui a conferência dos efeitos nos outputs.
  • Fase 2 inválida não aplica a transição normal; collateral tem um caminho separado.
  • Migrar estado exige uma transação aceita pelo script que atualmente o protege.

Próxima aula

Usaremos essa regra de continuação para entender CIP-68: um token pode circular com o usuário enquanto outro identifica o output que contém o estado de referência atualizável.

Módulo 1 Aula 1.13

CIP-68: token do usuário e estado de referência

Objetivos
  1. Relacionar User Token e Reference NFT por policy ID, label CIP-67 e base name.
  2. Interpretar o wrapper do datum sem confundir versão do padrão com revisão do registro.
  3. Distinguir reference input de gasto normal e delimitar o que um validator confere.
Antes de começar

Retome identidade de ativos e CIP-25 na Aula 1.10 e a validação de sucessoras Plutus na Aula 1.12. Aqui aplicamos esses mecanismos a um estado descoberto por meio de um par de ativos.

Pergunta-guia

Como atualizar a descrição de um registro sem retirar do usuário o token que identifica esse registro?

1. Dois ativos com controles distintos

Considere o registro REC-0042. Seu usuário recebe um token que pode transferir. A aplicação precisa atualizar a descrição de referência de REC-0042 quando o relatório é revisado. Se o estado depender do output do usuário, cada atualização exigiria consumir esse output. A convenção CIP-68 separa o ativo transferível do ativo que identifica o estado de referência.

O User Token fica no output controlado pelo usuário. O Reference NFT identifica o output que carrega o datum de referência. Os dois pertencem à mesma policy e têm o mesmo nome-base, mas prefixos diferentes no asset name. São dois assets distintos; compartilhar policy não significa compartilhar condição de gasto.

Nesta aplicação, o User Token é um NFT com quantidade 1, em endereço de chave. O Reference NFT tem quantidade 1 e está em endereço de script Plutus, com um validator que limita atualizações. CIP-68 organiza representação e descoberta; a segurança da emissão, a unicidade do Reference NFT e as regras de gasto dependem das políticas e scripts escolhidos.

2. Os labels são bytes do asset name

CIP-67 define um prefixo de quatro bytes que codifica label e checksum. O Reference NFT usa label 100; o User Token usa 222 para NFT, 333 para token fungível (FT) ou 444 para Rich Fungible Token (RFT). Não escreva os dígitos “100” ou “222” como texto e não coloque o label apenas em metadata: o prefixo faz parte dos bytes do nome.

PapelLabelPrefixo CIP-67 em hex
Reference NFT100000643b0
User Token NFT222000de140
User Token FT3330014df10
User Token RFT444001bc280

O nome-base REC-0042 tem bytes UTF-8 5245432d30303432. Para a mesma policy, os nomes completos ficam:

base = "REC-0042".encode("utf-8")
usuario = bytes.fromhex("000de140") + base
referencia = bytes.fromhex("000643b0") + base
print("User Token:", usuario.hex())
print("Reference NFT:", referencia.hex())
print("nomes iguais?", usuario == referencia)
print("mesma base?", usuario[4:] == referencia[4:])

A saída tem nomes diferentes e bases iguais. O limite total de 32 bytes do asset name continua valendo, deixando no máximo 28 bytes para o nome-base. Em produção, valide o prefixo CIP-67, inclusive o checksum, com ferramenta compatível. Os prefixos completos da tabela bastam para reconhecer os três tipos usados no exercício.

Atividade 1: derive o nome da referência

Complete nome_referencia: receba os bytes do nome de um User Token, reconheça um dos três prefixos permitidos, conserve o nome-base e troque o prefixo pelo label 100. Rejeite com ValueError nomes menores que 4 ou maiores que 32 bytes e prefixos desconhecidos. A função não altera nem procura o policy ID; a consulta posterior deve manter a mesma policy.

def nome_referencia(nome_usuario):
    return nome_usuario

usuario = bytes.fromhex("000de1405245432d30303432")
print(nome_referencia(usuario).hex())
Conferir resposta

Depois de validar tamanho e os quatro bytes iniciais contra a tabela, devolva bytes.fromhex("000643b0") + nome_usuario[4:]. Para REC-0042, o resultado é 000643b05245432d30303432. Procurar esse nome sob outra policy pode encontrar um ativo sem relação com o usuário; o par é determinado pelos dois componentes.

3. O datum contém um wrapper, não apenas uma descrição

O output do Reference NFT guarda um inline datum segundo CIP-32. CIP-68 define um constructor 0 de Plutus Data com três campos: [metadata, version, extra]. A primeira posição é o mapa de metadata; a segunda é a versão de representação do padrão; a terceira contém Plutus Data adicional. Essa metadata em datum é visível a Plutus e não se confunde com transaction metadata dos auxiliary data.

Para o NFT de label 222 do exemplo, a metadata direta inclui name e image. Nossa aplicação acrescenta record_version e artifact_hash. O hash abaixo está abreviado e a notação utf8 apenas indica bytes de texto; este bloco não é CBOR serializado.

constructor 0 [
  {
    utf8("name"): utf8("Registro REC-0042"),
    utf8("image"): utf8("https://example.org/rec-0042.svg"),
    utf8("record_version"): 3,
    utf8("artifact_hash"): h'7c20...'
  },
  1,
  unit
]

A revisão do registro é 3; a versão do wrapper usada aqui é 1. Atualizar o relatório para revisão 4 não significa trocar automaticamente version para 4. O aplicativo deve interpretar a versão suportada antes de ler os demais campos. Dar ao campo da aplicação o nome record_version evita misturar esses contadores.

4. Ler por referência ou consumir para atualizar

O ativo fica no valor da UTxO; o datum é outro campo

Deslize cada desenho para ver os dois lados.

Dois ativos distintos, em UTxOs com controles diferentes. Os ativos têm a mesma policy e nome-base REC-0042. A UTxO 7a91c4e2b860…#0 está em endereço de chave e contém uma unidade do User Token, label 222. A UTxO d42e8a1b6c90…#0 está em endereço de script e contém uma unidade do Reference NFT, label 100. Seu inline datum tem record_version 3 e wrapper version 1. Notas verdes são UTxOs; fichas azuis dentro delas são ativos; a etiqueta verde pendurada representa o datum, não transaction metadata. Ter o User Token não autoriza gastar d42e8a1b6c90…#0.

Ler por referência não consome a UTxO

Reference input permite ler o estado sem gastá-lo. Uma transação referencia d42e8a1b6c90…#0 por um reference input. Ela pode ler seu datum, mas esse vínculo não consome a UTxO, não financia a transação com seu valor e não executa por si só seu spending validator. O Reference NFT permanece em d42e8a1b6c90…#0; record_version continua 3 e wrapper version continua 1.

Atualizar exige consumir e criar outro output

O mesmo Reference NFT sai de d42e8a1b6c90…#0 e aparece em 0c7f92a6e4b1…#0, com um novo datum. Este é o resultado de uma atualização validada e incluída. A transação consome d42e8a1b6c90…#0 como input normal e cria 0c7f92a6e4b1…#0 sob o mesmo script. Ambos os estados mostram o mesmo Reference NFT, mesma policy, nome-base REC-0042, label 100 e quantidade 1: não há mint nem burn neste recorte. O datum de d42e8a1b6c90…#0 tinha record_version 3; o de 0c7f92a6e4b1…#0 tem record_version 4. O wrapper version permanece 1. O User Token e sua UTxO 7a91c4e2b860…#0 não são consumidos. Ler por referência, mostrado na cena anterior, não realiza esta atualização.
A nota é a UTxO; a ficha azul é o ativo contido no seu valor; a etiqueta verde é o datum. Ler por referência e atualizar são operações diferentes. Na atualização, o mesmo Reference NFT continua na sucessora; a revisão do registro muda de 3 para 4, mas a versão do wrapper permanece 1. Posse do User Token não autoriza essa atualização. Hashes ilustrativos e abreviados; ADA, taxas e outros campos omitidos.

Um reference input, definido na CIP-31, torna um output disponível para leitura sem consumi-lo. Seu valor não financia a transação, e só referenciá-lo não executa seu spending validator. Um script que lê essa referência precisa conferir a identidade completa do Reference NFT e o formato dos dados; não deve confiar em qualquer datum encontrado no mesmo endereço.

Para atualizar, a transação usa o output de referência como input normal, satisfaz seu spending validator e cria uma sucessora com o mesmo Reference NFT e datum atualizado. A regra deve conferir autorização, continuação do token e transição permitida, como no exercício Plutus. O User Token pode permanecer onde estava. Se outra transação já consumiu a referência, o builder precisa consultar o estado ativo e reconstruir sua tentativa.

A versão antiga continua no histórico, mas já não é um output disponível. Ler uma cópia em cache não demonstra que ela seja a versão atual; confira a referência e seu estado de consumo. Mudar código do validator continua exigindo a migração aceita pelo script anterior.

Atividade 2: o relatório mudou

REC-0042 passa de revisão 3 para 4. A versão CIP-68 continua compatível com 1. Uma aplicação propõe somente adicionar d42e8a1b6c90…#0 como reference input e alterar o datum em memória. Anote o que falta para efetivar a atualização.

Conferir resposta

Reference input apenas lê. A atualização precisa consumir d42e8a1b6c90…#0 como input normal e criar 0c7f92a6e4b1…#0 com o mesmo Reference NFT, sob a condição de gasto esperada, preservando o wrapper version 1 e alterando record_version para 4. O validator precisa aceitar essa transição. Alterar a memória da aplicação não altera o ledger.

5. O que a atualização não verifica

Mesmo um validator correto só verifica as condições implementadas sobre dados visíveis. CIP-68 não obriga o ledger a recuperar a imagem ou o relatório e não comprova sua correção. Para conferir artifact_hash, obtenha o original e use o mesmo algoritmo e a mesma representação de bytes definidos para o registro, como estudamos nas Aulas 0.1 e 0.2. Posse do User Token também não prova entrega do artefato, autorização institucional ou acesso ao repositório.

O par CIP-68 é útil quando a aplicação precisa dessa relação entre ativo transferível e estado descoberto por referência. Um estado de script sem token do usuário pode bastar em outro caso; adotar o padrão não elimina a necessidade de definir quem atualiza, como o estado é identificado e como os artefatos permanecem recuperáveis.

O que aprendemos

  • CIP-68 relaciona dois assets por policy e base name, com labels CIP-67 distintos.
  • O wrapper contém metadata, version e extra; revisão do registro é um campo separado.
  • Reference input lê sem gastar. Atualizar exige consumo e sucessora sob a regra aplicável.
  • O padrão organiza estado e descoberta, sem comprovar o conteúdo externo.

Próxima aula

No Módulo 2, começaremos por eventos encadeados e checkpoints. Veremos como registrar mudanças e acrescentar correções a um histórico externo, sem confundir a visão atual com a sequência que a produziu.

Referências do Módulo 1

Consulte as especificações e a documentação operacional quando precisar de regras exatas da rede.

  • Cardano architecture: visão dos componentes.
  • Ouroboros consensus documentation: consenso e seleção de cadeia.
  • CIP-1: processo de elaboração e revisão das Cardano Improvement Proposals.
  • CIP-1694: participantes da governança, ações, ratificação e entrada em vigor.
  • CIP-5: prefixos Bech32 para endereços e outros objetos Cardano.
  • CIP-19: estrutura e codificação dos endereços Cardano.
  • RFC 8949: formato CBOR.
  • Cardano Ledger: implementação, especificações e regras por era.
  • Cardano Docs: EUTxO: modelo de saídas consumidas e criadas.
  • Cardano Developer Portal: taxas: tamanho, parâmetros e custos de execução.
  • Cardano Developer Portal: transações: anatomia, auxiliary data e visibilidade para scripts.
  • Cardano Developer Portal: native tokens: políticas, mint, burn e identificação de ativos.
  • CIP-25: media-token metadata sob o label 721, incluindo condições de publicação e atualização.
  • RFC 8032: Ed25519, formatos e vetores de teste. Ed25519ctx e Ed25519ph são variantes distintas, não nomes intercambiáveis de uma API.
  • CIP-1852: caminhos de derivação hierárquica de carteiras Cardano.
  • CIP-30: interface de acesso, assinatura parcial, witness set e submissão entre dApps e wallets.
  • CIP-10: registro de labels de transaction metadata.
  • RFC 8785: JSON Canonicalization Scheme, para perfis que comprometem JSON canônico em vez dos bytes integrais de um arquivo.
  • Cardano Developer Portal: smart contracts: validators, datum, redeemer e transições eUTxO.
  • CIP-31 e CIP-32: reference inputs e inline datums.
  • CIP-40: collateral outputs; confira também as regras e os parâmetros da era no ledger.
  • CIP-67 e CIP-68: prefixos rotulados de asset names, classes de User Token e wrapper de datum metadata.
Módulo 2

Eventos, provas, escala e privacidade

Um sistema pode preservar seus registros fora da blockchain e publicar referências que permitam verificá-los depois. Vamos construir esse caminho, do histórico de eventos à prova de um item, e avaliar o custo, a espera e a exposição dos dados. Também veremos quando a interação entre participantes justifica um Hydra Head.

Módulo 2 Aula 2.1

Eventos, encadeamento e checkpoints

Objetivos
  1. Construir três eventos ligados por hashes e localizar uma quebra.
  2. Comparar uma sequência com um checkpoint obtido por uma fonte independente.
  3. Acrescentar uma correção e distinguir o histórico da visão atual.
Antes de começar

Retome bytes e hashes no Módulo 0, metadata na Aula 1.9 e consulta de transações na Aula 1.11. Os exemplos usam somente Python disponível na apostila, sem wallet nem envio à rede.

Pergunta-guia

Se alguém consegue recalcular todos os hashes, o que impede que apresente uma história diferente?

1. O resultado mudou, mas a notificação já saiu

Um sistema acompanha o teste T-0142. Primeiro cria o registro como pendente. Depois registra o resultado aprovado. Por fim, registra que enviou uma notificação ao portal. A tela mostra apenas aprovado, mas essa palavra não explica como o registro chegou ali.

Um evento registra uma mudança ou ação declarada. A visão atual é calculada a partir dos eventos segundo uma regra da aplicação. Neste exemplo, criação, resultado e correção podem definir o resultado exibido; uma notificação não o altera. Os três eventos ficam em um arquivo externo. Não estamos criando três transações Cardano.

O campo seq determina a ordem de acréscimo. O campo prev contém o hash do evento anterior; o primeiro usa null. O hash de um evento inclui todos os seus campos, inclusive prev, mas não contém o próprio hash.

Mudar o evento 2 quebra a referência no evento 3

Deslize o desenho para acompanhar os três eventos.

O resultado muda de aprovado para reprovado, mas o evento seguinte ainda referencia H2. Três registros pertencem ao mesmo arquivo externo. O evento 1 foi criado como pendente, prev é null e seu hash é H1. O evento 2 referencia H1, mas seu resultado foi editado; seu hash passa de H2 a H2′. O evento 3 continua declarando a notificação ao portal e prev igual a H2. A ligação entre H2′ e esse campo prev falha; o ponto da divergência aparece em vermelho.

E se todos os hashes forem recalculados?

Uma reescrita consistente produz H3′, mas não substitui o checkpoint independente H3. O arquivo reescrito tem elos consistentes: o evento 3 passa a apontar para H2′ e sua cabeça passa a H3′. Do outro lado da fronteira permanece a cópia independente obtida antes da edição, com quantidade 3 e cabeça H3. Os vínculos internos conferem, mas H3′ diverge de H3. Portanto a reescrita não passa pela comparação com esse checkpoint.
As folhas representam registros externos, não transações Cardano. H1, H2 e H3 abreviam hashes. Recalcular também o terceiro evento repara os vínculos internos, mas produz outra cabeça. O checkpoint independente continua comprometendo a sequência anterior.

2. Experimento: quebrar e reescrever

Fixaremos uma receita local chamada guia.eventos.v1: JSON em UTF-8, chaves ASCII ordenadas, sem espaços opcionais, somente strings, inteiros e null usados neste exemplo, sem normalização Unicode. Antes dos bytes colocamos o prefixo ASCII GUIA-EVENTO:v1 e um byte zero. Calculamos SHA-256 sobre essa sequência. O prefixo identifica o uso e a versão.

Essa receita limitada torna a demonstração reproduzível; json.dumps com essas opções não implementa todo o JCS do RFC 8785. Uma integração precisa fixar um perfil interoperável e testar seus casos de borda, em vez de copiar o exemplo para qualquer JSON.

Execute. A primeira comparação aceita a cadeia. A segunda detecta a edição isolada. A terceira aceita os vínculos de uma reescrita inteira, mas a quarta rejeita sua cabeça contra o checkpoint guardado antes.

import hashlib
import json
from copy import deepcopy

def hash_evento(evento):
    dados = json.dumps(evento, sort_keys=True,
        ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    return hashlib.sha256(b"GUIA-EVENTO:v1\x00" + dados).hexdigest()

def anexar(cadeia, campos):
    evento = dict(campos, seq=len(cadeia) + 1,
        prev=hash_evento(cadeia[-1]) if cadeia else None)
    return cadeia + [evento]

def elos_conferem(cadeia):
    anterior = None
    for seq, evento in enumerate(cadeia, 1):
        if evento["seq"] != seq or evento["prev"] != anterior:
            return False
        anterior = hash_evento(evento)
    return True

cadeia = []
for campos in [
    {"tipo": "criado", "registro": "T-0142", "resultado": "pendente"},
    {"tipo": "resultado", "resultado": "aprovado"},
    {"tipo": "notificado", "canal": "portal"},
]:
    cadeia = anexar(cadeia, campos)
checkpoint = (len(cadeia), hash_evento(cadeia[-1]))
print("original:", elos_conferem(cadeia))

editada = deepcopy(cadeia)
editada[1]["resultado"] = "reprovado"
print("edição isolada:", elos_conferem(editada))
reescrita = []
for evento in editada:
    reescrita = anexar(reescrita, evento)
print("reescrita consistente:", elos_conferem(reescrita))
print("mesma cabeça:", hash_evento(reescrita[-1]) == checkpoint[1])

Mude também o resultado do primeiro evento e repita. O efeito se propaga pelos hashes posteriores. Remover o último evento, por outro lado, deixa os vínculos restantes consistentes: sem saber qual cabeça esperar, o verificador pode receber apenas um prefixo antigo.

3. O checkpoint fica fora da história apresentada

Um checkpoint associa uma posição a um hash de cabeça. No experimento, guardamos a dupla antes da edição. Num sistema real, ela precisa chegar por uma fonte que o apresentador da cadeia não possa substituir junto com os eventos: uma cópia previamente conferida, um checkpoint assinado por uma chave confiável ou uma publicação localizada na rede esperada.

Publicar a dupla em uma transação permite voltar ao compromisso observado. É preciso conferir o publicador esperado e a inclusão; aceitar qualquer transação com outro hash permitiria trocar a referência. A rede preserva a publicação, mas não avalia o resultado do teste.

Um checkpoint de três eventos compromete aquele prefixo. Uma cadeia com quatro eventos pode preservá-lo. Isso não demonstra que o quarto é o mais recente, que nenhum evento deixou de ser capturado ou que todos os resultados são corretos. Para avaliar atualidade, obtenha também a cabeça mais recente pela rota definida para o registro.

4. Corrigir por acréscimo

A revisão do arquivo de origem revela que o resultado deveria ser reprovado. O sistema acrescenta o evento 4 com tipo correcao, resultado reprovado, motivo e dois vínculos diferentes: prev aponta para o evento 3, enquanto alvo aponta para o hash do evento 2. O primeiro continua a cadeia; o segundo identifica a declaração corrigida.

A visão passa a mostrar reprovado e deve permitir abrir a correção. O histórico ainda mostra que houve um resultado aprovado e uma notificação. Acrescentar uma correção não desfaz a notificação nem elimina a necessidade de avisar seu destinatário.

Se a correção declara ocorrido_em = 2026-09-10T10:00:00Z e seu checkpoint foi observado às 11:30, esses horários descrevem coisas diferentes. O primeiro foi declarado pelo emissor; o segundo registra a consulta da publicação. Bloco e slot localizam a inclusão. Nenhum deles comprova que o teste ocorreu às 10:00. Não reordene a cadeia pelo horário declarado para “consertar” essa diferença.

Atividade: aceite a correção, rejeite a reescrita

O verificador abaixo já confere os elos, mas esquece o checkpoint e termina com True. Repare sua conclusão: rejeite uma cadeia menor que quantidade e compare o hash na posição comprometida com cabeca. Não exija que a cadeia termine nessa posição, pois correções podem ter sido acrescentadas. O contrato recebe checkpoints com quantidade positiva.

import hashlib
import json

def hash_evento(evento):
    dados = json.dumps(evento, sort_keys=True,
        ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    return hashlib.sha256(b"GUIA-EVENTO:v1\x00" + dados).hexdigest()

def anexar(cadeia, campos):
    return cadeia + [dict(campos, seq=len(cadeia) + 1,
        prev=hash_evento(cadeia[-1]) if cadeia else None)]

def verificar(cadeia, quantidade, cabeca):
    anterior = None
    for seq, evento in enumerate(cadeia, 1):
        if evento["seq"] != seq or evento["prev"] != anterior:
            return False
        anterior = hash_evento(evento)
    return True

cadeia = []
for tipo in ["criado", "resultado", "notificado"]:
    cadeia = anexar(cadeia, {"tipo": tipo})
cabeca = hash_evento(cadeia[-1])
corrigida = anexar(cadeia, {
    "tipo": "correcao", "alvo": hash_evento(cadeia[1]),
    "resultado": "reprovado", "motivo": "erro de leitura",
})
print("prefixo preservado:", verificar(corrigida, 3, cabeca))
print("cauda omitida:", verificar(cadeia[:2], 3, cabeca))
Conferir resposta

Antes da comparação, teste len(cadeia) < quantidade e retorne False nesse caso. Caso contrário, a conclusão é hash_evento(cadeia[quantidade - 1]) == cabeca. A subtração converte a posição contada a partir de 1 em índice Python. A saída correta é True para a correção acrescentada e False para a cauda omitida.

Comparar apenas o último hash rejeitaria uma extensão legítima. Aceitar apenas os elos permitiria a reescrita consistente. Precisamos das duas conferências.

O que aprendemos

  • A visão atual aplica regras aos eventos; ela não substitui o histórico.
  • Elos detectam inconsistências locais. Um checkpoint independente permite comparar a história com um prefixo conhecido.
  • Uma correção aponta para a cabeça anterior e identifica separadamente o evento corrigido.
  • Horário declarado, inclusão e observação da publicação não são o mesmo instante.

Próxima aula

Na Aula 2.2 construiremos uma árvore Merkle. Ela permitirá conferir um item de um lote com poucos hashes, sem receber a cadeia ou o lote inteiro.

Módulo 2 Aula 2.2

Árvores Merkle e provas de inclusão

Objetivos
  1. Transformar bytes em folhas e combinar hashes até uma raiz.
  2. Montar uma prova mínima para um item entre quatro.
  3. Reparar um verificador que confunde a ordem esquerda/direita.
Antes de começar

Você precisa calcular hashes de bytes e entender por que a referência esperada deve vir de fora do material apresentado. Retome a Aula 2.1 para essa segunda distinção.

Pergunta-guia

Como conferir o evento B sem receber também os arquivos A, C e D?

1. Quatro arquivos, um compromisso

Um serviço fecha um lote com quatro arquivos de eventos, chamados A, B, C e D. O destinatário de B quer verificar que recebeu os bytes incluídos naquele lote. Entregar todos os arquivos funcionaria, mas aumentaria o tráfego e daria acesso a conteúdo que ele não solicitou.

Uma árvore Merkle combina hashes em níveis. Cada arquivo produz uma folha. Dois hashes adjacentes produzem um hash pai, e o processo continua até sobrar a raiz, também chamada root. Uma raiz SHA-256 tem 32 bytes, mesmo quando resume muitos arquivos. Isso não comprime os arquivos de forma recuperável: a raiz não permite reconstruí-los.

A ordem do lote faz parte do desenho. A ocupa o índice 0; B, o índice 1; C, o índice 2; D, o índice 3. O serviço preserva essa ordem e a receita de cálculo junto dos arquivos.

2. A receita vem antes da árvore

O exemplo usa quatro folhas. Os arquivos são textos exatos codificados em UTF-8, sem quebra de linha no final. H significa SHA-256; || significa concatenar bytes, não suas representações hexadecimais.

  • Folha: H(0x00 || dados).
  • Nó interno: H(0x01 || hash_esquerdo || hash_direito).

Os prefixos 0x00 e 0x01 distinguem uma folha de um nó interno. A folha depende dos bytes do arquivo. Sua posição é dada pelo caminho na árvore. Cada nó interno combina dois digests binários de 32 bytes, mantendo a ordem esquerda/direita.

Ordenar os digests por valor ou concatenar seus textos hexadecimais mudaria a receita. Quem constrói e quem verifica a árvore precisam usar as mesmas regras.

Partir de B e reconstruir a raiz

Deslize o desenho para acompanhar os dois ramos.

B e dois hashes irmãos bastam para recalcular a raiz. A árvore tem quatro folhas, na ordem A, B, C, D. O verificador recebe o arquivo B, seu índice 1, LA à esquerda e N(C,D) à direita. Calcula LB a partir dos bytes de B, depois N(A,B) como no(LA,LB), depois a raiz como no(N(A,B),N(C,D)). Compara essa raiz calculada com a raiz esperada obtida da publicação conferida. A, C, D, LC e LD aparecem apenas para situar a árvore e não precisam ser recebidos.
Leia de baixo para cima. O verificador calcula LB a partir de B. Os dois irmãos recebidos estão em laranja: LA entra à esquerda de LB; N(C,D), à direita do pai calculado. Os nós verdes são recalculados. A raiz escura vem da publicação conferida, não do remetente de B. A, C, D, LC e LD aparecem só como contexto.

3. Calcule a raiz e abra um caminho

Execute o código. As funções retornam digests binários; .hex() aparece somente na exibição. A prova de B contém dois pares: lado do irmão e hash desse irmão. O caminho é percorrido de baixo para cima.

import hashlib

def folha(dados):
    return hashlib.sha256(b"\x00" + dados).digest()

def no(esquerdo, direito):
    return hashlib.sha256(b"\x01" + esquerdo + direito).digest()

arquivos = [texto.encode("utf-8") for texto in [
    "T-0141|criado", "T-0142|revisão",
    "T-0143|criado", "T-0144|correção",
]]
A, B, C, D = [folha(dados) for dados in arquivos]
raiz_publicada = no(no(A, B), no(C, D))
prova_B = [("E", A), ("D", no(C, D))]

recalculada = folha(arquivos[1])
for lado, irmao in prova_B:
    recalculada = (no(irmao, recalculada) if lado == "E"
                  else no(recalculada, irmao))
print("raiz:", raiz_publicada.hex())
print("inclusão:", recalculada == raiz_publicada)

B_alterado = folha(arquivos[1] + b"!")
print("arquivo alterado:", no(no(A, B_alterado), no(C, D))
      == raiz_publicada)
print("bytes de hashes na prova:", sum(len(h) for _, h in prova_B))

A saída mostra inclusão True, arquivo alterado False e 64 bytes de hashes na prova. O pacote ainda precisa levar o arquivo B, os lados e a localização da raiz. Se a consulta especifica um índice, o caminho também precisa corresponder a essa posição. “64 bytes” não é o tamanho de uma transação nem de todo o pacote.

Experimente trocar o primeiro lado da prova, de ("E", A) para ("D", A), mantendo a raiz publicada. A comparação falha. Se também trocar a raiz esperada, deixará de testar o compromisso anterior. Na aplicação, obtenha a raiz da publicação já conferida, não de um campo substituível no pacote do remetente.

Veja também o demo de Merkle em Cardano.

4. Repare a orientação

Atividade: o irmão pode estar à esquerda

Este verificador usa o irmão à direita em todos os passos. Ele funciona para A, mas rejeita B. Repare o cálculo dentro do laço para respeitar E e D. Preserve as checagens do índice, do número de irmãos e do lado esperado. Execute para observar a falha e use Validar solução para testar outros arquivos, posições e adulterações.

A checagem do caminho já está pronta: em uma posição par, o irmão fica à direita; em uma posição ímpar, à esquerda. A divisão inteira por dois encontra a posição do pai no nível seguinte.

import hashlib

def folha(dados):
    return hashlib.sha256(b"\x00" + dados).digest()

def no(esquerdo, direito):
    return hashlib.sha256(b"\x01" + esquerdo + direito).digest()

def verificar_inclusao(indice, dados, prova, raiz):
    if not 0 <= indice < 4 or len(prova) != 2:
        return False
    atual = folha(dados)
    posicao = indice
    for lado, irmao in prova:
        lado_esperado = "E" if posicao % 2 else "D"
        if lado != lado_esperado:
            return False
        atual = no(atual, irmao)
        posicao //= 2
    return atual == raiz

arquivos = [b"A", b"B", b"C", b"D"]
A, B, C, D = [folha(d) for d in arquivos]
raiz = no(no(A, B), no(C, D))
prova = [("E", A), ("D", no(C, D))]
print("B incluído:", verificar_inclusao(1, b"B", prova, raiz))
Conferir resposta

Para E, use no(irmao, atual); para D, use no(atual, irmao). B precisa primeiro de LA à esquerda e depois de N(C,D) à direita. D exige irmãos à esquerda nos dois níveis. Por isso, testar somente A esconderia o defeito.

O verificador mantém a raiz fixa. Se uma comparação falhar, obtenha o arquivo original e confira a receita, o índice e a prova antes de atribuir a divergência a uma adulteração.

5. O que cresce e o que permanece fora da prova

Em uma árvore binária completa com 1.024 folhas, cada caminho tem dez níveis. Bastam dez irmãos, ou 320 bytes de hashes SHA-256, em vez dos outros 1.023 arquivos. O número de irmãos cresce como o logaritmo do número de folhas, enquanto construir a árvore ainda exige processar o lote.

Esta aula fixa quatro folhas para não esconder uma decisão de formato. Para lotes de tamanho arbitrário, a construção precisa definir a forma da árvore, o tratamento de níveis ímpares e o compromisso com a quantidade. Duplicar a última folha e separar subárvores de tamanhos diferentes são convenções distintas. Uma prova de inclusão também não é uma prova de que um log novo preservou todo o antigo. Logs crescentes podem usar provas de consistência específicas; isso exige outra receita.

A inclusão confirma que aqueles bytes, naquela posição, recompõem a raiz esperada. Ela não revela arquivos ausentes da captura nem comprova que o resultado de B é verdadeiro. Também não oferece sigilo automático: hashes irmãos de dados previsíveis podem permitir tentativas. Trataremos dessa exposição na Aula 2.4.

O que aprendemos

  • Folhas e nós internos têm receitas diferentes, com bytes e ordem explícitos.
  • A prova de B contém LA e N(C,D), com seus lados, sem exigir os outros arquivos.
  • Alterar arquivo, posição, irmão ou orientação invalida a comparação contra a mesma raiz.
  • A raiz compromete o lote; disponibilidade, completude da captura e sigilo exigem controles adicionais.

Próxima aula

Na Aula 2.3 calcularemos quantas publicações restam ao agrupar eventos, qual espera esse agrupamento introduz e quando a interação entre participantes pode justificar um Hydra Head.

Módulo 2 Aula 2.3

Escala, lotes, custos e Hydra

Objetivos
  1. Separar quantidade de eventos, publicações e bytes preservados fora da rede.
  2. Estimar o efeito de uma janela de lote sobre custo e latência.
  3. Explicar inicialização, commit, snapshots, fechamento, contestação e fanout de um Hydra Head.
Antes de começar

Retome a raiz e a prova Merkle da Aula 2.2, além de inputs, outputs e taxas do Módulo 1. O fluxo de eventos é uma hipótese de cálculo. Tamanho e taxa da publicação vêm da medição com PyCardano na Aula 1.8, não de um preço atual garantido.

Pergunta-guia

Dois eventos por segundo exigem duas transações por segundo?

1. A janela transforma eventos em publicações

Um serviço recebe dois eventos por segundo durante uma hora: 7.200 eventos. Seu requisito é permitir que cada evento seja verificado contra um compromisso público. Isso não determina uma transação por evento. O serviço pode fechar lotes e publicar uma raiz Merkle por lote.

Com uma janela fixa de 60 segundos, os eventos recebidos no intervalo [0, 60) pertencem ao primeiro lote; um evento no instante 60 pertence ao seguinte. Com fluxo contínuo, uma hora produz 60 lotes de 120 eventos. A aplicação publica 60 raízes, mas ainda precisa armazenar e processar os 7.200 eventos.

Cinco eventos, duas raízes para publicar

Deslize o desenho para ver o que sai de cada lote.

O evento de 60 segundos pertence ao lote seguinte. Na aplicação, o lote 0 contém os eventos de 0, 1 e 59 segundos. Fecha aos 60 segundos e produz R0. O lote 1 contém os eventos de 60 e 61 segundos. Fecha aos 120 segundos e produz R1. Cada raiz segue em metadata de uma transação para publicação na L1. Os eventos continuam na aplicação. O fechamento não significa inclusão: submissão, inclusão e confirmações acrescentam espera.
Recorte com cinco eventos. O de 59 s espera 1 segundo para fechar seu lote. O de 60 s espera 60 segundos. As etiquetas amarelas levam as raízes, não os registros completos. Inclusão da transação e confirmações acrescentam espera depois do fechamento.

Uma janela maior reduz publicações, mas aumenta a espera. Com chegadas aproximadamente uniformes, a espera média pelo fechamento fica perto de meia janela. Isso não é uma promessa de latência total: fila, construção, submissão, inclusão e a política de confirmações também entram na medição.

2. Faça as contas sem transformar o exemplo em orçamento

Na Aula 1.8, o pacote com uma raiz de 32 bytes e uma assinatura mediu 306 bytes. Com os parâmetros de Preprod consultados em 17/09/2026, a = 44 e b = 155381, seu mínimo foi 168845 lovelace. Reutilizaremos essa medição para comparar frequências de publicação, sem reconstruir o pacote aqui.

from math import ceil

segundos = 3600
eventos_por_segundo = 2
bytes_por_evento = 200
bytes_por_transacao = 306  # Pacote medido na Aula 1.8.
a, b = 44, 155_381  # Consulta de Preprod usada naquela medição.
taxa = a * bytes_por_transacao + b
eventos = segundos * eventos_por_segundo

print("eventos:", eventos)
print("bytes dos eventos:", eventos * bytes_por_evento)
print("uma tx por evento, ADA:", eventos * taxa / 1_000_000)
for janela in (60, 300, 900):
    publicacoes = ceil(segundos / janela)
    total = publicacoes * taxa
    print("janela:", janela, "publicações:", publicacoes,
          "taxas em ADA:", total / 1_000_000,
          "espera média aproximada:", janela / 2)

As janelas de 60, 300 e 900 segundos produzem 60, 12 e 4 publicações: 10,1307, 2,02614 e 0,67538 ADA sob essas premissas. Uma transação por evento produziria 1215,684 ADA. Mantivemos o mesmo tamanho de pacote para isolar a frequência. Outros inputs, assinaturas, anexos ou parâmetros exigem nova medição. Se a aplicação exigir fechamento em até dois minutos, a janela de 300 segundos já falha nesse requisito, mesmo custando menos.

Para um orçamento real, fixe rede, era e um snapshot dos parâmetros de protocolo. Construa a transação completa, incluindo witnesses e dados auxiliares, serialize em CBOR e calcule a taxa com ferramenta compatível. Transações com scripts podem incluir custos de execução e outros componentes aplicáveis. O mínimo de ADA de um output é valor mantido nele, não a mesma coisa que taxa paga.

Os 7200 registros de 200 bytes somam 1440000 bytes. Agrupar reduz o número de transações, mas a aplicação continua precisando guardar os registros completos.

Uma aplicação também pode levar várias raízes na mesma transação. Isso reduz envios, mas aumenta os bytes do anexo e pode exigir aguardar outros lotes. É outro desenho, que precisa de nova medição.

Atividade: uma publicação por minuto com registros

Seis registros chegam nos segundos 0, 1, 59, 60, 61 e 180. Vamos juntar os que chegam no mesmo minuto:

  • De 0 a 59 segundos: três registros.
  • De 60 a 119 segundos: dois registros.
  • De 120 a 179 segundos: nenhum registro.
  • De 180 a 239 segundos: um registro.

Publicamos uma transação para cada grupo com registros. Portanto, são três publicações. O código abaixo ainda conta as repetições e retorna seis. Corrija a contagem para considerar cada grupo uma única vez.

def contar_lotes(instantes, janela):
    grupos = [segundo // janela for segundo in instantes]
    return len(grupos)

instantes = [0, 1, 59, 60, 61, 180]
print("Grupo de cada registro:", [segundo // 60 for segundo in instantes])
publicacoes = contar_lotes(instantes, 60)
print("Publicações:", publicacoes)

segundo // 60 identifica o minuto. A lista impressa é [0, 0, 0, 1, 1, 3]: aparecem apenas três grupos diferentes, 0, 1 e 3. Use Validar solução depois de corrigir a função.

Conferir resposta

Troque len(grupos) por len(set(grupos)). O conjunto retira as repetições: {0, 1, 3} tem três elementos. O minuto sem registros não gera publicação.

3. Quando o problema é interação frequente

Publicar raízes na camada 1, ou L1, resolve o compromisso periódico com lotes. Outro problema aparece quando participantes definidos precisam executar muitas transferências entre si com baixa latência. Um Hydra Head é um canal de estado multiparticipante: UTxOs são comprometidas na L1, transações evoluem o estado fora dela e um protocolo permite resolver o estado final na L1.

Considere três participantes, A, B e C. A figura acompanha 20 unidades didáticas, omitindo taxas da L1. Ela não é uma transação real nem promete rendimento.

Do commit às transferências no Head

Deslize o desenho para acompanhar A, B e C.

Três participantes comprometem UTxOs e confirmam novos estados fora da L1. A inicialização define participantes e período de contestação. Na L1, A seleciona UTxOs que totalizam 10 unidades, B seleciona 8 e C seleciona 2. Os commits colocam essas UTxOs sob o protocolo do Head. Reunidos os commits, o Head abre. Fora da L1, o snapshot 6 confirmado registra A 10, B 8 e C 2. Após transferências, o snapshot 9 confirmado registra A 7, B 9 e C 4. Ambos estão assinados por A, B e C. Os tickets entre eles representam transações off-chain, não blocos. A soma permanece 20 unidades didáticas, sem taxas da L1.

Fechar com 6 não apaga o snapshot 9

B contesta no prazo com o snapshot 9; só depois do prazo ocorre o fanout. O close na L1 apresenta o snapshot 6 e abre o período de contestação. B possui o snapshot 9 assinado por todos e submete uma contestação válida antes do prazo aplicável. O estado resolvido passa a 9. Após o prazo, fanout distribui UTxOs desse estado na L1: A recebe 7 unidades, B 9 e C 4. A atualização exige a contestação válida e tempestiva; não é automática nem uma publicação de metadata comum.
As notas verdes representam grupos de UTxOs; os números são totais em unidades didáticas, não saldos de contas. Os selos laranja indicam as assinaturas dos participantes. O fechamento não deve liquidar o estado antigo se a contestação válida com o snapshot mais recente chegar no prazo. Só depois do prazo aplicável o fanout materializa as UTxOs na L1.

Na inicialização, o grupo e os parâmetros do Head ficam definidos. Cada participante faz commit das UTxOs escolhidas; não entrega toda sua wallet. Reunir os commits abre o Head. Se a inicialização não terminar, o protocolo prevê abortar e recuperar os valores comprometidos.

No Head aberto, os nós validam transações com regras compatíveis com o modelo eUTxO. Snapshots numerados confirmam o estado por assinaturas dos participantes. Uma transação enviada não equivale, por si só, a um snapshot confirmado. Um participante indisponível pode impedir a confirmação de novos snapshots; manter os nós responsivos faz parte da operação.

Um participante pode iniciar close na L1 com um estado permitido pelo protocolo. Durante o período de contestação, outro apresenta um snapshot confirmado mais recente. Após o prazo aplicável, fanout materializa na L1 as UTxOs do estado resolvido. Guardar snapshots e monitorar a L1 permite reagir a um fechamento desatualizado.

Atividade: um fechamento desatualizado
O Head fechou com o snapshot 6. B possui o snapshot 9 assinado por todos, e o prazo ainda está aberto. Qual ação preserva o estado confirmado mais recente?

0 de 1 pergunta respondida.

Conferir resposta

B precisa usar o caminho de contestação do Head. Metadata comum não substitui a evidência exigida por esse protocolo. Depois do fechamento, novas transações off-chain não sobrescrevem a disputa. O prazo torna monitoramento e disponibilidade dos snapshots requisitos concretos, não detalhes opcionais.

Hydra não é uma base privada de documentos nem um rollup genérico para qualquer carga. Os participantes compartilham informações do Head; movimentações de entrada e saída passam pela L1. Se uma raiz por minuto já atende à verificação assíncrona, abrir um Head pode apenas acrescentar operação. Compare o ciclo completo, incluindo commits, fechamento, disponibilidade dos participantes e recuperação, com a necessidade real de interação.

O que aprendemos

  • Uma janela agrupa eventos em publicações e acrescenta espera antes da inclusão.
  • Taxas dependem da transação e dos parâmetros; provas e arquivos continuam exigindo armazenamento e entrega.
  • Hydra mantém interação frequente entre participantes definidos, com snapshots confirmados fora da L1.
  • Fechamento, contestação no prazo e fanout resolvem o estado na L1.

Próxima aula

Na Aula 2.4 testaremos o que um observador consegue descobrir a partir de hashes públicos e montaremos uma abertura verificável com nonce privado.

Módulo 2 Aula 2.4

Privacidade e publicação

Objetivos
  1. Recuperar um valor previsível por enumeração de hashes.
  2. Construir e verificar um compromisso com nonce privado.
  3. Separar divulgação limitada, anonimato e recuperação controlada dos artefatos.
Antes de começar

Retome as provas Merkle da Aula 2.2 e a separação entre publicações e arquivos da Aula 2.3. Use somente os dados fictícios fornecidos. Não coloque documentos privados, credenciais ou frases de recuperação nos editores, que salvam rascunhos neste navegador.

Pergunta-guia

Quem vê um hash consegue testar o que ele esconde?

1. Nove candidatos bastam

Um portal deseja publicar o compromisso com um resultado sem revelar o resultado. O arquivo é sempre o texto status=...|revisao=..., codificado em UTF-8. Existem três status possíveis e três revisões. Um observador conhece esse formato e as opções, embora não tenha recebido o arquivo.

SHA-256 produz o mesmo digest para a mesma entrada. O observador não precisa inverter o algoritmo: pode gerar os nove arquivos candidatos e comparar seus hashes com o valor público.

import hashlib
from itertools import product

def mensagem(status, revisao):
    return f"status={status}|revisao={revisao}".encode("utf-8")

opcoes = list(product(
    ["aprovado", "pendente", "reprovado"], ["R1", "R2", "R3"]))
publicado = hashlib.sha256(mensagem("aprovado", "R2")).digest()
for status, revisao in opcoes:
    candidato = mensagem(status, revisao)
    if hashlib.sha256(candidato).digest() == publicado:
        print("encontrado:", candidato.decode("utf-8"))
print("candidatos possíveis:", len(opcoes))

Troque o status real por pendente e execute outra vez. O ataque continua funcionando. Tornar o digest mais comprido não aumenta o número de mensagens possíveis. Identificadores sequenciais, datas próximas e arquivos com poucas combinações também podem permitir testes. Um sal publicado junto do digest pode impedir tabelas pré-calculadas comuns, mas não impede que o observador refaça essa pequena busca para cada registro.

2. Acrescente um segredo aleatório ao compromisso

Para dificultar a busca, geraremos um nonce privado: 16 bytes aleatórios novos para cada compromisso, produzidos por secrets.token_bytes(16). O observador que não recebe o nonce deixa de ter apenas nove entradas para testar. Precisa também descobrir um valor escolhido entre 2 elevado a 128 possibilidades.

O perfil didático guia.abertura.v1 calcula SHA-256(domínio || nonce || tamanho || dados). O domínio é o texto ASCII GUIA-ABERTURA:v1 seguido de um byte zero; o nonce tem exatamente 16 bytes; o tamanho tem oito bytes sem sinal, do mais significativo ao menos significativo; e os dados são os bytes exatos do arquivo. A receita fixa as fronteiras para não confundir concatenações.

Na abertura, o destinatário recebe os dados e o nonce por um canal autorizado. Ele aplica a mesma receita e compara com o compromisso obtido da publicação. A resistência do hash a encontrar entradas alternativas sustenta o vínculo com esses bytes. O nonce aumenta a dificuldade de adivinhar a entrada antes da abertura; não criptografa o arquivo armazenado.

import hashlib
import secrets

DOMINIO = b"GUIA-ABERTURA:v1\x00"
def comprometer(dados, nonce):
    if len(nonce) != 16:
        raise ValueError("O nonce precisa ter 16 bytes.")
    entrada = DOMINIO + nonce + len(dados).to_bytes(8, "big") + dados
    return hashlib.sha256(entrada).digest()

dados = b"status=aprovado|revisao=R2"
nonce = secrets.token_bytes(16)
publicado = comprometer(dados, nonce)
print("abertura correta:", comprometer(dados, nonce) == publicado)
nonce_errado = bytes([nonce[0] ^ 1]) + nonce[1:]
print("nonce alterado:", comprometer(dados, nonce_errado) == publicado)

candidatos = [f"status={s}|revisao={r}".encode("utf-8")
    for s in ["aprovado", "pendente", "reprovado"]
    for r in ["R1", "R2", "R3"]]
print("busca com nonce zero:", any(
    comprometer(c, bytes(16)) == publicado for c in candidatos))
# Simulação de vazamento: o observador passa a conhecer o nonce.
print("com nonce vazado:", [c.decode("utf-8") for c in candidatos
    if comprometer(c, nonce) == publicado])

A abertura correta passa; alterar um bit do nonce falha. A busca com nonce zero deve falhar, salvo a probabilidade desprezível de o nonce sorteado ser exatamente zero. Isso, isoladamente, não prova segurança: a dificuldade vem da aleatoriedade secreta, não apenas de mudar a fórmula. A última linha entrega o nonce ao observador e a enumeração volta a encontrar o arquivo.

Não substitua o sorteio por data, contador ou senha humana, nem reutilize um nonce entre compromissos. Preservar o nonce aumenta o material que exige controle de acesso e backup. Perder o nonce impede abrir aquele compromisso, mesmo que o arquivo ainda exista. Um novo nonce produz outro compromisso e não repara o antigo.

3. O arquivo fica fora da blockchain

Imagine que alguém precise conferir o resultado publicado pelo portal. O arquivo original e o nonce continuam no sistema da aplicação. Na blockchain entram o compromisso e o nome do perfil usado para calculá-lo. Consultar a transação permite obter essa referência, mas não recupera o arquivo nem o nonce: quem vai fazer a verificação precisa recebê-los por outro caminho.

Publicar sem enviar o arquivo

Deslize o desenho para ver os dois lados da fronteira.

O arquivo e o nonce ficam na aplicação; o compromisso e o perfil são publicados na blockchain. O sistema da aplicação guarda o arquivo original e o nonce privado de 16 bytes. Aplica a receita guia.abertura.v1 e calcula o compromisso. Somente o compromisso e o perfil atravessam a fronteira tracejada, na etiqueta amarela de metadata da transação incluída em um bloco da Cardano. O esquema mostra a publicação já incluída, não uma promessa de inclusão ao submeter.

Como alguém confere o arquivo

Quem verifica recebe o arquivo e o nonce da aplicação e busca o compromisso publicado na blockchain. A aplicação entrega cópias do arquivo e do nonce a quem tem autorização para recebê-los. Pelo caminho azul tracejado, essa pessoa consulta a publicação e obtém o compromisso publicado. Recalcula o compromisso com o arquivo e o nonce, seguindo o perfil guia.abertura.v1, e compara o compromisso recalculado com o publicado. Se coincidirem, a abertura corresponde ao compromisso. A aplicação controla a entrega; o hash não controla o uso posterior das cópias.
Quem confere o arquivo precisa de duas fontes: a aplicação entrega o original e o nonce; a blockchain fornece o compromisso para comparação. Depois da entrega, essa pessoa também pode copiar o arquivo e o nonce. O hash não impede esse uso.

Neste exemplo, basta publicar o compromisso e o nome do perfil. O portal continua responsável por guardar o arquivo e o nonce, controlar quem pode recebê-los e manter uma forma de recuperá-los. Se for necessário publicar um endereço para localizar o arquivo, confira o que esse endereço revela: não inclua nomes de pessoas, caminhos internos ou tokens de acesso. O endereço ajuda a encontrar o arquivo; o compromisso permite conferir seus bytes.

Também é possível colocar compromissos desse tipo nas folhas de um lote Merkle. O destinatário recebe abertura, posição e prova, e compara a raiz com a publicação. Isso exige um perfil próprio, que defina exatamente como o compromisso entra na folha. Não misture essa variante silenciosamente com a receita de arquivos da Aula 2.2.

Atividade: recupere a abertura correta

A aplicação entregou um nonce de 16 bytes, mas o verificador o substitui por zeros. Repare abrir para usar o nonce recebido e comparar o digest calculado com o compromisso esperado. Mantenha o perfil de cálculo e os dados de teste. O nonce fixo abaixo é público e exclusivamente didático; não oferece ocultação.

import hashlib

def comprometer(dados, nonce):
    if len(nonce) != 16:
        raise ValueError("O nonce precisa ter 16 bytes.")
    return hashlib.sha256(b"GUIA-ABERTURA:v1\x00" + nonce
        + len(dados).to_bytes(8, "big") + dados).digest()

def abrir(esperado, dados, nonce):
    if len(nonce) != 16:
        return False
    return comprometer(dados, bytes(16)) == esperado

dados = "resultado da revisão".encode("utf-8")
nonce = bytes.fromhex("00112233445566778899aabbccddeeff")
publicado = comprometer(dados, nonce)
print("abertura:", abrir(publicado, dados, nonce))
print("outro arquivo:", abrir(publicado, dados + b"!", nonce))
Conferir resposta

A conclusão deve ser comprometer(dados, nonce) == esperado. A saída passa a mostrar True e False. Se o teste com outro arquivo também passar, o verificador não está comparando os bytes certos. Se apenas o exemplo inicial passar, confira se você fixou seu nonce no código em vez de usar o argumento.

4. Divulgação limitada não é anonimato

Uma prova Merkle revela menos arquivos que o lote completo, mas ainda expõe o item aberto, sua posição e hashes irmãos. Se um irmão corresponde a uma folha previsível sem nonce, ele também pode ser enumerado. Revelar menos conteúdo não esconde automaticamente quem publicou, quem recebeu ou quais publicações estão relacionadas.

Um endereço usado repetidamente, um identificador estável ou horários coincidentes podem ligar registros. Mesmo sem nomes, informações adicionais podem permitir reidentificação. Pseudonimização mantém essa possibilidade; a avaliação de anonimização exige considerar contexto e meios razoavelmente disponíveis. Hash, nonce e endereço novo, isoladamente, não autorizam declarar dados anônimos.

A exposição pública é persistente. Retirar um campo do portal não remove cópias do histórico nem o material já entregue. Dados pessoais e segredos operacionais devem permanecer fora da rede quando exigirem controle de acesso ou retenção limitada. Se não há necessidade de compromisso público, manter o registro em um sistema controlado, ou não coletar um campo desnecessário, evita essa exposição.

5. Teste a recuperação antes de depender dela

Para o período de retenção necessário, preserve o arquivo exato, o nonce, o perfil e, se houver lote, os dados para recuperar a prova. Proteja as cópias e as chaves de criptografia do armazenamento. O prazo e o acesso precisam corresponder à finalidade; não guarde tudo indefinidamente por conveniência.

Faça um teste de restauração com dados fictícios: recupere o pacote por uma conta autorizada, obtenha o compromisso pela rota de consulta definida e execute a verificação. Depois simule a ausência do nonce e de um irmão da prova. O resultado deve ser “material insuficiente”, não “documento falso”. Excluir o material restrito no fim da retenção pode encerrar a possibilidade de abertura; não apaga o compromisso público nem revoga cópias já compartilhadas.

O que aprendemos

  • Um domínio pequeno permite descobrir dados por comparação de hashes candidatos.
  • Um nonce privado aleatório dificulta essa busca; sua abertura exige preservar os bytes, o nonce e a receita.
  • Divulgação limitada reduz conteúdo revelado, mas não elimina correlação nem garante anonimato.
  • A publicação mínima depende de recuperação controlada e de uma decisão explícita sobre retenção.

Para continuar

Esta é a última aula do guia.

Nas referências do módulo, retome as especificações antes de adaptar os perfis didáticos. Para revisar o percurso, reproduza uma alteração de evento, uma prova de inclusão e uma abertura sem trocar a referência esperada.

Referências do Módulo 2

Os perfis guia.eventos.v1 e guia.abertura.v1 são receitas didáticas definidas nas aulas, não padrões de Cardano. Consulte as especificações e registre a revisão usada antes de implementar uma integração.

  • NIST FIPS 180-4: definição de SHA-256, usado nos exemplos de eventos, Merkle e abertura.
  • RFC 8785: JSON Canonicalization Scheme. A serialização limitada da Aula 2.1 não implementa todo esse esquema.
  • RFC 9162, seção 2: árvores Merkle, provas de inclusão e provas de consistência no protocolo Certificate Transparency. A Aula 2.2 usa os mesmos prefixos para folhas e nós internos em um exemplo de quatro arquivos; não implementa o protocolo completo.
  • Cardano Developer Portal: taxas: componentes das taxas e parâmetros. A Aula 2.3 combina um fluxo hipotético de eventos com a medição de transação e os parâmetros consultados na Aula 1.8.
  • Cardano Ledger: implementação e especificações para conferir as regras da era usada no cálculo de transações.
  • Hydra Head protocol: participantes, commits, estado aberto, snapshots, fechamento, contestação e fanout.
  • Python: secrets: fonte de aleatoriedade usada para o nonce descartável da Aula 2.4.
  • LGPD e GDPR: fontes oficiais para finalidade, minimização e proteção de dados pessoais. Um mecanismo criptográfico, sozinho, não estabelece conformidade.

Este material orienta aprendizagem técnica. Não substitui especificações vigentes, parecer jurídico ou avaliação de conformidade.