> For the complete documentation index, see [llms.txt](https://docs.rome.builders/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rome.builders/pt-br/canton-zk-evm/how-it-works.md).

# Como funciona

Acompanhe um bloco do Ostia desde o reth, passando pela prova, até seu commit no Canton.

O builder fica em execução o tempo todo. Ele cria um bloco sempre que há transações aguardando, gera uma prova para ele e o envia ao Canton. Por padrão, o código permite apenas um bloco em andamento por vez; no DevNet, são executados até dois, com um provador de GPU. Os blocos ainda são confirmados no Canton em ordem. No DevNet, quando nenhum bloco é criado por 60 segundos, o builder cria um bloco vazio, um heartbeat (desativado por padrão no código), para que uma cadeia sem atividade ainda produza um bloco aproximadamente uma vez por minuto. O Canton decide se cada bloco se torna o próximo cabeçalho da cadeia. Um bloco EVM e as operações do Canton que ele registrou são confirmados na mesma transação.

Esta página descreve a versão `v0.1.0` e, quando indicado, o que está em execução no DevNet atualmente. [Status](https://docs.rome.builders/pt-br/canton-zk-evm/status.md) identifica o commit em execução no DevNet. Leia o [design](https://github.com/rome-protocol/canton-zk-evm/blob/main/docs/DESIGN.md). Para acompanhar sua própria transação nessas etapas, vá para [Da sua transação à confirmação final no Canton](#from-your-transaction-to-final-on-canton).

```mermaid
flowchart TD
    W["Transações EVM"] --> Q["RPC público: mostra apenas blocos finais"]
    Q --> R["reth cria blocos sob demanda"]
    R --> B["O builder lê as operações do gateway e encontra os contratos correspondentes no Canton"]
    B -->|"Uma operação não pode ser liquidada: exclua sua transação e crie o bloco novamente"| R
    B -->|"Todas as operações podem ser liquidadas"| P["ZisK gera a prova do bloco"]
    P --> A["Advance: bloco, prova e operações em uma única transação do Canton"]
    A --> S["Chamada externa: os sidecars verificam a prova e o estado do gateway"]
    S --> D["O Daml verifica o cabeçalho e liquida as operações"]
    D --> C["O Canton confirma o bloco e suas operações em conjunto"]
    C --> F["reth marca o bloco como final"]
    F --> Q
    C --> X["O indexador do explorador lê o registro do bloco e o compara com o reth"]
```

## Criar blocos com base no cabeçalho do Canton

As carteiras enviam transações EVM ao RPC público, que as encaminha ao reth. O RPC mostra apenas blocos finais no Canton, então um recibo aparece quando o bloco é final. O iniciador fornecido mantém a descoberta de pares desativada. O reth cria um bloco quando o builder solicita.

Primeiro, o builder lê o contrato `ZkChain` ativo no Canton. Ele ajusta os cabeçalhos head, safe e finalized do reth para apontarem para esse cabeçalho confirmado. Ele seleciona as transações pendentes por preço, mantendo a ordem dos nonces de cada remetente. Desde 2026-10-25, ele preenche o bloco com base no gás usado pelas transações, calculado pelo reth, e não nos limites de gás declarados: as carteiras costumam declarar cerca de três vezes o que usam, e contabilizar os limites declarados faria o bloco parar quando estivesse preenchido em apenas cerca de um terço. O bloco termina ao atingir o limite de gás. No DevNet, normalmente o builder também oferece ao reth no máximo 393,216 bytes brutos de transações, pois o trabalho do participante em um bloco aumenta com seu tamanho; ainda assim, ele oferece uma transação inicial que exceda esse limite, para que ela não fique esperando para sempre. O builder solicita ao reth a criação do bloco com essa lista explícita de transações.

Uma transação EVM que exige uma ação no Canton chama o gateway. O gateway registra uma operação e a incorpora a um hash acumulado para o bloco. O builder lê os eventos do gateway na ordem dos logs e encontra os contratos do Canton necessários para cada operação.

Se uma alocação não existir mais, se um destinatário não tiver aceitado saques ou se outro contrato necessário estiver ausente, o builder exclui a transação e as transações posteriores daquele remetente. Ele retorna o reth ao cabeçalho do Canton e cria o bloco novamente. Essas verificações ocorrem antes da geração da prova. O [README do builder](https://github.com/rome-protocol/canton-zk-evm/blob/main/builder/README.md) lista as verificações de cada operação.

## Gerar a prova do bloco

O builder salva o bloco e o testemunho de execução do reth. A ferramenta de entrada combina o bloco, o testemunho e o genesis para compor a entrada do provador. O ZisK executa o guest, que valida o bloco de acordo com as regras fixas da cadeia.

O provador retorna uma prova encapsulada de 1,344 bytes, que confirma o hash do bloco. O builder envia `Advance` com o cabeçalho, as transações, a prova, as operações e as provas de conta e armazenamento do gateway na raiz de estado do bloco.

## Verificar e liquidar em uma única transação

Cada participante confirmador executa um sidecar. A chamada externa do Canton envia o bloco ao sidecar desse participante para `verify`. Ele verifica a prova, a chave do programa fixada e a versão do ZisK, o hash do cabeçalho e a raiz da lista de transações.

No Ostia DevNet, Rome executa o único participante que hospeda todas as partes do Ostia; portanto, seu único sidecar é o único confirmador, e a prova é verificada pelo próprio nó de Rome. O sincronizador do Canton ordena os blocos e não vê a prova. A rede de demonstração local tem dois participantes confirmadores. [Modelo de confiança e limitações](https://docs.rome.builders/pt-br/canton-zk-evm/trust-model.md) explica o que isso altera.

O Daml verifica a resposta em relação ao `ZkChain`: o pai precisa ser o cabeçalho atual, o número precisa ser o próximo e o limite de gás e o gás usado precisam respeitar o teto. O Daml compara as respostas do sidecar; ele não verifica a prova de conhecimento zero em si.

Em seguida, o Daml registra uma linha para cada operação com base nos contratos do Canton que ela identifica. O ID, o burner e o valor de um saque vêm do builder; o hash provado os vincula ao que foi registrado no bloco. A função `legs` do sidecar verifica as provas de conta e armazenamento do gateway, calcula o hash dessas linhas em ordem e compara o resultado com o valor do gateway no estado provado. Um bloco sem operações precisa passar pela mesma verificação com uma lista vazia.

O Daml liquida as operações em ordem e cria o `BlockRecord` e o seguinte `ZkChain`. O Canton confirma essas alterações em conjunto. Se uma verificação ou liquidação falhar, nada é confirmado. Consumir o único contrato de estado da cadeia torna o Canton a autoridade sobre a ordem dos blocos. Consulte a [interface Daml](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/daml/README.md) e as [verificações auxiliares](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/sidecar/README.md).

## O vault e os twins

Além do primeiro gateway, o registro da cadeia lista os contratos EVM em que confia, cada um deles um gateway ou um vault, junto com o hash do código. Um bloco contém as operações de todos os gateways registrados, e o Daml verifica o hash do código de cada gateway em relação à prova da conta incluída no bloco. Um vault não tem operações próprias: seus bloqueios e liberações são pagamentos do gateway, e o Daml confia no endereço do vault como destinatário ou pagador. O confirmador verifica o código de um vault antes de aceitar a entrada. Uma nova entrada é adicionada da mesma forma que um programa é alterado: o operador e o gateway a propõem, e o confirmador a aceita.

O vault é um contrato pequeno que guarda os tokens ERC-20 por trás dos twins do Canton. Não tem proprietário, chave nem mecanismo de atualização. Um bloqueio é um simples `pay` do gateway, tendo o vault como destinatário. Uma liberação é `release(ref, token, to, amount)`, que o vault paga por meio do gateway usando um identificador que nenhum outro tipo de pagamento pode ter; o Canton só a liquida em resposta a uma solicitação de resgate assinada pelo titular.

Um twin é um token do Canton correspondente a um ERC-20, administrado pela parte do gateway. O registro da cadeia fixa cada twin: o endereço do token, suas casas decimais e o contrato de regras que o emite, queima e transfere. `Advance` emite um twin somente em resposta a um bloqueio fixado pela prova e só o queima em resposta a uma solicitação de resgate assinada.

O serviço de registro de twins fica ao lado do builder. Antes de pagar, o pagador informa o destinatário e um `ref` ; o serviço responde com o ID do bloqueio, e o builder lê os mesmos dados para anexar o bloqueio ao bloco. O serviço também disponibiliza a API de registro do padrão de token para os twins, para que uma carteira cujos validadores tenham aprovado o pacote do twin possa enviá-los. Ele não guarda chaves nem grava nada no Canton, e o `Advance` verifica se os dados geram o ID. Consulte [Depósitos, saques e pagamentos](https://docs.rome.builders/pt-br/canton-zk-evm/deposits-withdrawals-payments.md#canton-twins-of-erc-20-tokens) para ver os fluxos.

## Quando o Canton recusa

Depois que o Canton confirma o bloco, o builder o marca como final no reth. Se o Canton o recusar, o builder retorna o reth ao último bloco confirmado pelo Canton e envia as transações do bloco recusado de volta ao pool. O bloco seguinte verifica novamente as operações. Um pagamento cuja alocação tenha sido revertida é deixado de fora. Após dois blocos recusados consecutivos, o builder suspeita que a transação compartilhada entre eles seja a causa e a deixa de fora durante um período de espera.

Se o builder perder a resposta ao envio, o comando ainda pode ser confirmado. Antes de enviá-lo, o builder registra o fim do ledger. Em seguida, lê a conclusão do próprio comando a partir desse ponto. Uma conclusão bem-sucedida conta como confirmação. Uma conclusão com falha é uma recusa.

O head do Canton pode confirmar uma transação, mas nunca indica sozinho que ela "não foi confirmada". Sem uma conclusão, o builder só decide que ela "não foi confirmada" depois que se passam 300 segundos no relógio do Canton (`CZE_RESOLVE_SECONDS`). Até lá, ele não constrói nada e mantém o reth onde está. Essas regras de recuperação estão no [README do builder](https://github.com/rome-protocol/canton-zk-evm/blob/main/builder/README.md#what-one-run-does).

## Da sua transação à finalização no Canton

1. Você envia uma transação para o RPC público. Ela aguarda no pool pelo próximo bloco.
2. O builder monta um bloco assim que há uma transação aguardando e uma vaga disponível (o padrão no código é um bloco em andamento; o DevNet executa até dois). Enquanto a cadeia estava ocupada, um novo bloco sucedia o anterior a cada 16,6 segundos, na mediana (período de 24 horas até 2026-10-25 01:34 UTC).
3. O ZisK prova o bloco. Na carga de uma hora de 2026-10-24, a mediana do tempo de prova foi de 9,03 segundos para blocos com 11 a 100 transações.
4. O registro do bloco, junto com sua prova, é confirmado no Canton. Essa confirmação é o que torna o bloco final, e então o RPC público exibe o recibo da sua transação.

Nessa mesma hora, uma transação levou, na mediana, 19,5 segundos desde sua aceitação pelo RPC até a finalização do bloco correspondente no Canton; no percentil 95, levou 27,1 segundos. Um recibo demora mais do que na maioria das cadeias, portanto, as ferramentas que aguardam por ele precisam de um tempo limite longo.

[Medições](https://docs.rome.builders/pt-br/canton-zk-evm/measurements.md) define cada intervalo e lista as execuções. No explorador, abra sua transação e depois o bloco correspondente para ver a atualização do Canton que contém o registro. [O explorador](https://docs.rome.builders/pt-br/canton-zk-evm/explorer.md) mostra como.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rome.builders/pt-br/canton-zk-evm/how-it-works.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
