> 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/build-with-canton.md).

# Build with Canton

What you can target on Ostia beyond plain EVM contracts, the Canton pieces you can build with, and which you can do on your own on DevNet today and which Rome runs.

Ostia runs ordinary EVM contracts, and it also reaches Canton. A block's requests to Canton are legs, and they commit in the same Canton transaction as the block. This page lists what you can target, the pieces behind each target and who can do it on DevNet today.

The code for every piece is in the open repository, [rome-protocol/canton-zk-evm](https://github.com/rome-protocol/canton-zk-evm), under the Apache License 2.0.

| Target                                                          | What it is                                                                   | On DevNet today                                                                                                                                                                            |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [EVM contracts](#evm-contracts)                                 | Solidity apps, deployed with the tools you use on Ethereum.                  | You do it on your own.                                                                                                                                                                     |
| [Canton Coin in your contracts](#canton-coin-in-your-contracts) | Canton Coin as the CC ERC-20.                                                | You do it on your own, with the [Bridge](https://docs.rome.builders/canton-zk-evm/bridge.md).                                                                                              |
| [An EVM token on Canton as a twin](#erc-20-twins-on-canton)     | An ERC-20 with a twin, a CIP-0056 token.                                     | Rome runs it with WtROME (from tROME) and TKA. The Bridge moves them for a Canton wallet once wallets are switched on. No outside Canton wallet holds twins yet. Rome registers new twins. |
| [Payments with Canton parties](#payments-with-canton-parties)   | An ERC-20 payment that executes a Canton allocation in the same transaction. | Rome runs it with test parties; you cannot run it yourself on DevNet.                                                                                                                      |
| [A Canton venue](#a-canton-venue)                               | A Daml app that swaps a Canton token for an ERC-20.                          | Rome runs the venue; it has run once. You cannot run a venue on DevNet.                                                                                                                    |
| [Your own network](#your-own-network)                           | The whole stack on a local Canton network.                                   | You do all of it.                                                                                                                                                                          |

## EVM contracts

Deploy with Foundry or Hardhat, verify the source in the explorer and connect with viem or ethers. [Build on Ostia](https://docs.rome.builders/canton-zk-evm/build-on-ostia.md) has the steps and [Ostia DevNet](https://docs.rome.builders/canton-zk-evm/devnet.md#limits) has the limits. ERC-20, ERC-721, ERC-1155, an ERC-3643 permissioned token, Uniswap V2 and the contracts that check TACEO Merces proofs have all run on Ostia. A RedStone price consumer was deployed and verified.

## Canton Coin in your contracts

Canton Coin on Ostia is an ordinary ERC-20 with 10 decimals, at `0x4db3dea7c13116961fd3e438542ccfcca61a7547`. Any contract can hold and transfer it. The gateway's custody on Canton backs it one to one, and the explorer shows the two side by side on [`/twins`](https://ostia.devnet.romeprotocol.xyz/twins) and in `GET /api/twins`.

You get CC by depositing Canton Coin on the [Bridge](https://docs.rome.builders/canton-zk-evm/bridge.md) page, and you get Canton Coin back by withdrawing it. The page gives 20 test Canton Coin a day.

## ERC-20 twins on Canton

You pay an ERC-20 into the vault and a Canton party holds the same amount of its twin. The twin is a CIP-0056 token with the instrument id `erc20:<token address>`. Redeeming burns the twin and pays the ERC-20 back to an Ostia address.

**Who holds twins today.** Twins implement CIP-0056, but that does not make them appear in every Canton wallet. A party can hold a twin once every validator that hosts it has vetted `ostia-twin` 0.1.0 and 0.2.0, and a party that receives a lock must also sign a one-time `TwinAcceptance`. Only the parties that Rome runs meet that today. No outside Canton wallet holds or sends twins yet.

**Connect your own Canton wallet: built, not switched on.** The Bridge page connects the Canton wallet you already have, and the Bridge account made from a wallet signature was retired on 2026-11-17. Connecting is switched on wallet by wallet, with no date. It waits on three things that wallet makers and validators decide: they review a third-party Daml package before their wallet allows it, some of their rules block package names that start with `canton-` (our chain package is named `canton-zk-evm`), and the validators that host a wallet's parties must hold Ostia's packages. Until then no outside Canton wallet can make a move on the Bridge. On DevNet the twins are TKA and WtROME, and the vault is at `0x69f13a94f986021f1a7650eb611bf9b717aa495a`.

The twin registry service answers at `https://ostia.devnet.romeprotocol.xyz/twin-registry` (for example `GET /twin-registry/healthz`). It holds no key.

| Call                                                                             | What it gives you                                                                                                                                                            |
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /healthz`                                                                   | The twins and the vaults.                                                                                                                                                    |
| `GET /twin/v1/twins`                                                             | Each twin's token, instrument id and vaults.                                                                                                                                 |
| `GET /registry/...`                                                              | The token standard's registry API: the twin's metadata, and the transfer and allocation factories, so a wallet whose validators have vetted the twin package can send twins. |
| `POST /twin/v1/lock-parts` with `{"receiver": <Canton party id>, "ref": <text>}` | The lock id and the registered vaults, for the payer to use in a lock.                                                                                                       |

The receiver of a lock signs a `TwinAcceptance` once. Without one the registry answers 409 and the builder leaves the lock out of the block before it is proven, so the ERC-20 stays with the payer. A Canton wallet that you connect to the Bridge page signs its acceptance in its opt-in. The payer checks the lock id itself, the SHA-256 of `lock,<receiver>,<ref>`, and takes the vault from a source it trusts.

You can check that the vault is the reviewed build. `cast keccak $(cast code 0x69f13a94f986021f1a7650eb611bf9b717aa495a --rpc-url $RPC)` gives `0x2fbcf33083dd26a360690a0d8d24cd333997b3c7000d950aa5e564e01460d4da`, which is also the code hash that `GET /api/twins` reports.

Only Rome registers twins and vaults on DevNet today. To ask for a twin of your own ERC-20, open an issue in the [repository](https://github.com/rome-protocol/canton-zk-evm/issues) or ask in the Rome [Discord](https://discord.gg/vZ9rnCdNSB); Rome decides case by case.

## Payments with Canton parties

An EVM payer calls the gateway's `pay`. The Canton payer and payee have signed `DvpTerms` that name the allocation, the payment id, the EVM token, the EVM payee and the amount. In one Canton transaction the block commits and the allocation executes, so neither is final without the other. It ran on DevNet in blocks 783 and 1471. [Deposits, withdrawals and payments](https://docs.rome.builders/canton-zk-evm/deposits-withdrawals-payments.md#tie-a-payment-to-one-allocation) has the rules.

On DevNet, Rome's test parties run these payments. The Bridge page does not run them: it makes the four bridge moves. To run payments tied to an allocation between your own Canton parties, run your own network (below).

## A Canton venue

A venue is a Daml app that runs a trade between a Canton seller and an EVM buyer. The pieces:

* `otc-venue` 0.1.0, in [`apps/otc`](https://github.com/rome-protocol/canton-zk-evm/tree/main/apps/otc), holds the `TradeOffer` and the `Trade`. It depends only on the token standard, CIP-0056, and does not name the chain, so any venue can use it. The `Trade` shows the seller an allocation request in a standard wallet.
* The chain's Daml package (0.4.0 and later, 0.5.0 pinned) holds the `VenueTrade` and the `FundedClaim`. The venue and the seller sign the `VenueTrade` for each trade.
* The buyer pays through the gateway. The seller's allocation executes in the same Canton transaction as the payment, and the buyer then claims the wrapped token with a `FundedClaim`.

It ran on DevNet on 2026-10-27 at 15:55 UTC: the Canton token TKB was swapped for the ERC-20 TKA. The buyer's payment is in block 16816, in one Canton update, and the buyer's claim is in block 16823. A payment below the trade's amount was left out of block 16834 and moved nothing. The explorer lists swaps at [`/swaps`](https://ostia.devnet.romeprotocol.xyz/swaps), and `GET /api/swaps` returns them.

On DevNet the builder is started with the venue's party, so Rome adds a venue. The commands to run a swap are in the repository's demo, for a local network or your own run. A step in which the seller proposes the trade is planned before mainnet.

## Your own network

[Run your own Ostia](https://docs.rome.builders/canton-zk-evm/run-it-locally.md) starts a local Canton network and the whole stack: the chain, the prover or its stand-in, the gateway and the explorer. On it you run every piece above yourself except Canton Coin, which needs a Canton Network validator; for that, run Ostia on your own validator's participant (see [Run your own Ostia](https://docs.rome.builders/canton-zk-evm/run-it-locally.md#run-on-an-existing-participant)). You use your own parties and your own venue.

A Daml app sees the legs it signs for. Anyone can read every leg through `GET /api/legs` on the explorer.

## Where to go next

* [Use cases](https://docs.rome.builders/canton-zk-evm/use-cases.md): what these pieces make possible today.
* [Bridge](https://docs.rome.builders/canton-zk-evm/bridge.md): the browser page for the four moves and for sending on Canton.
* [How it works](https://docs.rome.builders/canton-zk-evm/how-it-works.md): a block from transaction to Canton commit.


---

# 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/build-with-canton.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.
