> 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/canton-zk-evm/how-it-works.md).

# How it works

Follow one Ostia block from reth through proving to its Canton commit.

Each builder run makes, proves and submits one block. Canton decides whether that block becomes the chain's next head. An EVM block and the Canton legs it recorded commit in the same transaction.

This page describes commit `a84e84e439a5cc669c0ae61facf7c8c995d9d564`. Read the full [design](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/docs/DESIGN.md).

```mermaid
flowchart TD
    W["EVM transactions"] --> R["reth builds on demand"]
    R --> B["Builder reads gateway legs and finds their Canton contracts"]
    B -->|"A leg cannot settle: leave its transaction out and rebuild"| R
    B -->|"Every leg can settle"| P["ZisK proves the block"]
    P --> A["Advance: block, proof and legs in one Canton transaction"]
    A --> S["External call: sidecars check proof and gateway state"]
    S --> D["Daml checks the head and settles the legs"]
    D --> C["Canton commits the block and its legs together"]
    C --> F["reth marks the block final"]
```

## Build on Canton's head

Wallets send EVM transactions to reth. The supplied launcher keeps peer discovery off. reth makes a block when the builder asks for one.

The builder first reads the active `ZkChain` contract on Canton. It moves reth's head, safe block and finalized block to that committed head. It chooses pending transactions by price, keeping each sender's nonce order and staying within the gas cap. It asks reth to build with that explicit transaction list.

An EVM transaction that requires a Canton action calls the gateway. The gateway records a leg and folds it into a running hash for the block. The builder reads the gateway's events in log order and finds the Canton contracts needed by each leg.

If an allocation is gone, a receiver has not accepted withdrawals, or another required contract is missing, the builder leaves out the transaction and that sender's later transactions. It returns reth to Canton's head and builds again. These checks happen before proving. The [builder README](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/builder/README.md) lists the checks for each leg.

## Prove the block

The builder saves the block and reth's execution witness. The input tool combines the block, witness and genesis into the prover input. ZisK runs the guest, which validates the block under the chain's fixed rules.

The prover returns a 1,344-byte wrapped proof that commits to the block hash. The builder submits `Advance` with the header, transactions, proof, legs and the gateway's account and storage proofs at the block's state root.

## Check and settle in one transaction

Each confirming participant runs a sidecar. Canton's external call sends the block to that participant's sidecar for `verify`. It checks the proof, the pinned program key and ZisK release, the header's hash and the transaction list's root.

Daml checks the answer against `ZkChain`: the parent must be the current head, the number must be the next one, and the gas limit and gas used must fit the cap. Daml compares the sidecar's answers; it does not verify the zero-knowledge proof itself.

Daml then writes a line for each leg from the Canton contracts it names. A withdrawal's id, burner and amount come from the builder; the proven hash binds them to what the block recorded. The sidecar's `legs` function checks the gateway's account and storage proofs, hashes those lines in order and compares the result with the gateway's value in the proven state. A block with no legs must pass the same check with an empty list.

Daml settles the legs in order and creates the `BlockRecord` and the next `ZkChain`. Canton commits these changes together. If a check or settlement fails, nothing commits. Consuming the chain's one state contract makes Canton the authority on block order. See the full [Daml interface](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/daml/README.md) and [sidecar checks](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/sidecar/README.md).

## When Canton refuses

After Canton commits the block, the builder marks it final in reth. If Canton refuses it, the builder returns reth to Canton's last committed block and sends the refused block's transactions back to the pool. The next run checks their legs again. A payment whose allocation was taken back is left out.

If the builder loses the submission reply, it reads Canton's head again to determine whether the block committed. If that read also fails, it reports an unknown outcome and leaves reth where it is. The next run starts from Canton's head. These recovery rules are in the [builder README](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/builder/README.md#what-one-run-does).


---

# 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/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.