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

The builder runs all the time. It cuts a block whenever transactions wait, proves it and submits it to Canton. The code's default is one block in flight at a time, and DevNet runs up to two, with one GPU prover. Blocks still commit on Canton in order. On DevNet, when no block has been made for 60 seconds, the builder cuts an empty block, a heartbeat (the code's default is off), so a quiet chain still makes a block roughly once a minute. Canton decides whether each block becomes the chain's next head. An EVM block and the Canton legs it recorded commit in the same transaction.

This page describes release `v0.1.0` and, where it says so, what DevNet runs now. [Status](https://docs.rome.builders/canton-zk-evm/status.md) names the commit DevNet runs. Read the full [design](https://github.com/rome-protocol/canton-zk-evm/blob/main/docs/DESIGN.md). To follow your own transaction through these steps, jump to [From your transaction to final on Canton](#from-your-transaction-to-final-on-canton).

```mermaid
flowchart TD
    W["EVM transactions"] --> Q["Public RPC: shows final blocks only"]
    Q --> 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"]
    F --> Q
    C --> X["Explorer indexer reads the block record and checks it against reth"]
```

## Build on Canton's head

Wallets send EVM transactions to the public RPC, which forwards them to reth. The RPC shows only blocks that are final on Canton, so a receipt appears once the block is final. 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. Since 2026-10-25 it fills the block by the gas the transactions use, which reth works out, not by the gas limits they declare: wallets often declare about three times what they use, and counting the declared limits would stop a block at about a third of what fits. A block ends at the gas cap. The builder also normally offers reth no more than 393,216 raw bytes of transactions on DevNet, because the participant's work on a block grows with its size; it still offers an oversized first transaction, so that one does not wait for ever. The builder 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/main/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.

On Ostia DevNet Rome runs the one participant that hosts every Ostia party, so its one sidecar is the only confirmer, and the proof is checked by Rome's own node. Canton's synchronizer orders the blocks and does not see the proof. The local demo network has two confirming participants. [Trust model and limits](https://docs.rome.builders/canton-zk-evm/trust-model.md) says what that changes.

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/v0.1.0/daml/README.md) and [sidecar checks](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/sidecar/README.md).

## The vault and the twins

Besides the first gateway, the chain record lists the EVM contracts it trusts, each a gateway or a vault, with the hash of its code. A block carries the legs of every registered gateway, and Daml checks each gateway's code hash against the account proof the block carries. A vault has no legs of its own: its locks and releases are gateway payments, and Daml trusts its address as their payee or payer. The confirmer checks a vault's code before it accepts the entry. A new entry is added the way a program is changed: the operator and the gateway propose it, and the confirmer accepts it.

The vault is a small contract that holds the ERC-20 tokens behind the Canton twins. It has no owner, no key and no upgrade. A lock is a plain gateway `pay` with the vault as the payee. A release is `release(ref, token, to, amount)`, which the vault pays through the gateway against an id that no other kind of payment can have, and Canton settles it only against a redeem request that the holder signed.

A twin is a Canton token for one ERC-20, administered by the gateway party. The chain record pins each twin: the token's address, its decimals and the rules contract that mints, burns and transfers it. `Advance` mints a twin only against a lock the proof fixed, and burns it only against a signed redeem request.

The twin registry service sits beside the builder. A payer tells it the receiver and a `ref` before paying; it answers with the lock id, and the builder reads the same parts to attach the lock to the block. It also serves the token standard's registry API for the twins, so a wallet whose validators have vetted the twin package can send them. It holds no key and writes nothing to Canton, and `Advance` checks that the parts give the id. See [Deposits, withdrawals and payments](https://docs.rome.builders/canton-zk-evm/deposits-withdrawals-payments.md#canton-twins-of-erc-20-tokens) for the flows.

## 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 block checks their legs again. A payment whose allocation was taken back is left out. After two refused blocks in a row, the builder suspects the transaction they shared and leaves it out for a cool-down.

If the builder loses the submission reply, the command may still commit. Before it submits, the builder records the ledger end. It then reads the command's own completion from that point. A completion that succeeded counts as a commit. A failed one is a refusal.

Canton's head can confirm a commit, but it never shows "not committed" by itself. With no completion, the builder decides "not committed" only after 300 seconds of Canton time have passed (`CZE_RESOLVE_SECONDS`). Until then it builds nothing and leaves reth where it is. These recovery rules are in the [builder README](https://github.com/rome-protocol/canton-zk-evm/blob/main/builder/README.md#what-one-run-does).

## From your transaction to final on Canton

1. You send a transaction to the public RPC. It waits in the pool for the next block.
2. The builder cuts a block as soon as a transaction waits and a place is free (the code's default is one block in flight, DevNet runs up to two). While the chain was busy, a new block followed the previous one every 16.6 seconds at the median (24 hours to 2026-10-25 01:34 UTC).
3. ZisK proves the block. In the one-hour load of 2026-10-24, the median proof took 9.03 seconds for blocks of 11 to 100 transactions.
4. The block's record, with its proof, commits on Canton. That commit is what makes the block final, and the public RPC then shows your receipt.

In that same hour, a transaction took a median of 19.5 seconds from the RPC accepting it to its block being final on Canton, and 27.1 seconds at the 95th percentile. A receipt takes longer than on most chains, so tools that wait for one need a long timeout.

[Measurements](https://docs.rome.builders/canton-zk-evm/measurements.md) defines each interval and lists the runs. In the explorer, open your transaction and then its block to see the Canton update that holds the record. [Explorer](https://docs.rome.builders/canton-zk-evm/explorer.md) shows how.


---

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