> 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/deposits-withdrawals-payments.md).

# Deposits, withdrawals and payments

How the gateway ties EVM deposits, withdrawals and payments to their Canton legs, and how ERC-20 twins and Canton Coin move both ways.

The gateway is an EVM contract included in the chain's genesis. It records what a block needs Canton to do. Each request is a leg. The block's proof commits to the gateway's state, including the hash of the legs in the order they were recorded.

Deposits, withdrawals and payments are live on Ostia DevNet, run by Rome with test parties. They first ran in the 2026-10-05 local demo. On 2026-10-25 a Canton test token, TKB (the reference test token that Splice ships), was registered with the gateway, and its wrapped form, wTKB, exists on Ostia at `0x294d3049874526910a69f6b61da14d10a8b1b3af`. Since 2026-11-08 you can deposit and withdraw Canton Coin yourself from the explorer's [Bridge](https://docs.rome.builders/canton-zk-evm/bridge.md) page; see [Live on DevNet](#live-on-devnet) below.

Since 2026-10-29 the gateway also carries two-way Canton assets: an ERC-20 can stand on Canton as a twin, and Canton Coin can come onto Ostia and go back. See [Canton twins of ERC-20 tokens](#canton-twins-of-erc-20-tokens) and [Canton Coin](#canton-coin).

Most links on this page go to release `v0.1.0`; the gateway README link goes to the main branch. DevNet now runs code from the repository's main branch with Daml package 0.5.0, and the legs follow the same rules. [Status](https://docs.rome.builders/canton-zk-evm/status.md) names the commit. For what you can build on the legs, see [Build with Canton](https://docs.rome.builders/canton-zk-evm/build-with-canton.md). Read the full [gateway README](https://github.com/rome-protocol/canton-zk-evm/blob/main/gateway/README.md) and [Daml interface](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/daml/README.md).

| Leg        | Gateway call                     | EVM action                                      | Canton action in `Advance`                                    |
| ---------- | -------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- |
| Deposit    | `claim(id, token, amount)`       | Mint wrapped tokens to the caller.              | Execute the depositor's allocation to the gateway.            |
| Withdrawal | `withdraw(token, amount, party)` | Burn the caller's wrapped tokens.               | Pay the Canton token from gateway custody to the named party. |
| Payment    | `pay(id, token, to, amount)`     | Transfer an ERC-20 from the payer to the payee. | Execute the allocation named by the agreed payment terms.     |

## Live on DevNet

A deposit, a payment and a withdrawal ran on DevNet twice on 2026-10-25:

| Run                                                  | Deposit                            | Payment                                                                                                 | Withdrawal                                |
| ---------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| First, 08:08 to 08:10 UTC                            | Block 780: 10 TKB in, 10 wTKB out. | Block 783: V paid U 1 WtROME (wrapped tROME, an ERC-20 on Ostia) against U's allocation of 10 TKB to V. | Block 784: 4 wTKB burnt, 4 TKB paid to U. |
| Second, 11:31 to 11:34 UTC, under Daml package 0.2.0 | Block 1465.                        | Block 1471.                                                                                             | Block 1473.                               |

Each leg was in a block of its own. In each, the block record and the change to the holding were one Canton update. After the second run the wTKB supply was 12, which anyone can read on Ostia. Rome's run checked that the gateway then held 12 TKB on Canton, equal to that supply. Since 2026-10-25 the explorer shows this too: wTKB's token page has a "Backed on Canton" card with a custody of 12 TKB next to a supply of 12 wTKB.

U and V are test parties that Rome created and runs on its own participant, and Rome ran every step. You can watch the legs on the explorer: open [`/legs`](https://ostia.devnet.romeprotocol.xyz/legs) for the list, or a block's page for the legs it carried. A withdrawal names the Canton party it paid. wTKB is an ordinary ERC-20 with 10 decimals, so its supply and balances read like any other token's (see [Explorer](https://docs.rome.builders/canton-zk-evm/explorer.md#legs-and-custody)).

Rome runs a deposit, a payment and a withdrawal every 10 minutes, and their health is watched every 30 seconds.

To deposit and withdraw Canton Coin yourself, connect your Canton wallet on the explorer's [Bridge](https://docs.rome.builders/canton-zk-evm/bridge.md) page, once it is switched on for your wallet. The Bridge page also locks tROME and TKA for Canton (a gateway `pay` into the vault). The other payments and the TKB deposits on this page are run by Rome's test parties.

## Deposit a Canton token

The depositor allocates a Canton token to the gateway, with the operator as executor. The depositor signs a `DepositRequest` naming the deposit id, the EVM address allowed to claim and the allocation. The deposit id is the SHA-256 of `deposit,<depositor's party id>,<label>`, so only the depositor can make an id from their own party.

That EVM address calls `claim`. The gateway mints to its caller and records the deposit leg. The recipient needs tROME for gas. The builder matches the leg to the request, the registered token and the allocation.

`Advance` executes the allocation into gateway custody and commits the block that minted the wrapped tokens. A wrapped token has 10 decimals, matching Canton amounts. The conversion between the two amounts is exact, with no rounding.

## Withdraw to a Canton party

The holder calls `withdraw` with the wrapped token, amount and full Canton party id. The gateway burns the wrapped tokens and records the receiver in the leg.

The receiver must have signed a `WithdrawalAcceptance`. It remains active until archived. The builder also needs enough unlocked gateway holdings of the registered instrument. It leaves the transaction out if these conditions do not hold.

`Advance` pays the receiver through the token registry's transfer factory. The Canton transfer and the block containing the burn commit together. The builder includes at most one withdrawal of an instrument per block, as described in the [builder README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/builder/README.md).

## Tie a payment to one allocation

The Canton payer allocates a Canton token to the Canton payee. The two sign `DvpTerms` naming the allocation, payment id, EVM token, EVM payee and amount. The payment id is the SHA-256 of the UTF-8 text `<Canton payer's party id>,<Canton payee's party id>,<label>`, written in lowercase hex. The terms reject any other id.

An EVM payer approves the gateway and calls `pay` with the agreed id, token, recipient and amount. The gateway moves the ERC-20 from that payer to the EVM payee and records the payment leg. In the demo the payer was controlled by the Canton payee; the protocol does not require that relationship. `Advance` uses the signed terms to execute the allocation from the Canton payer to the Canton payee. The ERC-20 payment and the Canton payment commit together, so neither is final without the other.

A plain ERC-20 transfer records no leg. Even a transfer of the same token to the same payee in the same block cannot stand in for `pay`. The [design's payment flow](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/docs/DESIGN.md#the-flows) explains this binding.

## Canton twins of ERC-20 tokens

A twin is the Canton form of an ERC-20 that lives on Ostia. It is a CIP-0056 token, the Canton token standard, with the instrument id `erc20:<token address>`, and it moves by the token standard's transfer between parties whose participants have vetted ostia-twin, which today means accounts on Rome's participants. Each twin is one to one with the ERC-20 that the vault holds. TKA and WtROME (wrapped tROME) have twins on DevNet.

**Lock.** You pay the ERC-20 into the vault with a plain gateway `pay`, and name the Canton party that should hold the twin. Before paying, you tell the twin registry service the receiver and a `ref` of your choosing; it answers with the lock id, which is the SHA-256 of `lock,<receiver>,<ref>`. The block commits the payment into the vault and, in the same Canton transaction, mints the same amount of the twin to the receiver. The twin's supply then equals what the vault holds.

**Redeem.** The holder signs a redeem request on Canton, and then `release` is called on the vault with the same `ref`. The vault pays the ERC-20 to the EVM address in the request, and the twin is burnt in the same block. Canton settles a release only against a matching redeem request.

Under the chain's rules a twin is minted only in `Advance`, against a proven payment into a registered vault; the twin's admin, the gateway party, can also mint and burn on its own today. [Trust model and limits](https://docs.rome.builders/canton-zk-evm/trust-model.md#what-the-twins-trust) says what that rests on.

| Step   | Where it happens                                             | Canton action in `Advance`     |
| ------ | ------------------------------------------------------------ | ------------------------------ |
| Lock   | A gateway `pay` to the vault.                                | Mint the twin to the receiver. |
| Redeem | `release` on the vault, against the holder's signed request. | Burn the holder's twin.        |

On 2026-10-29 a lock of 5 TKA for a Canton party went into block 28389 and the party held 5 twin. It sent 2 twin to a second party on Canton, and a redeem of those 2 went into block 28392. The twin's supply and the vault's balance were both 3 afterwards. The explorer's [`/twins`](https://ostia.devnet.romeprotocol.xyz/twins) page shows each twin's supply beside the vault's balance (see [Explorer](https://docs.rome.builders/canton-zk-evm/explorer.md#twins-and-canton-assets)).

A lock is made only for a receiver that has accepted twins. A party signs once that it accepts them, and the builder builds a lock only for a party that has. Connecting a Canton wallet on the [Bridge](https://docs.rome.builders/canton-zk-evm/bridge.md) page signs that acceptance in its opt-in, so you can run the whole cycle with a party of your own.

## Canton Coin

Canton Coin comes onto Ostia through the same gateway deposit as any Canton token. The wrapped token CC (`0x4db3dea7c13116961fd3e438542ccfcca61a7547`, 10 decimals; earlier records call it wCC) is registered with the factory that the validator's scan proxy names. A party allocates Canton Coin to the gateway and signs a labelled deposit request, the recipient claims CC on Ostia, and a withdrawal pays the Canton Coin back. Canton Coin needs one extra input, a choice context that the scan proxy supplies, and the builder fetches it before it proves the block.

On 2026-10-29 a party put 5 Canton Coin in through block 28473, so that it held 15, the gateway held 5 and the CC supply was 5. The withdrawal in block 28474 put all three back: 20, 0 and 0. DevNet charged no fee on these transfers.

## What the proof fixes

Each leg records its kind, id, token, account, amount and Canton party where applicable. The gateway hashes the legs in order. `Advance` checks that its attached legs produce the hash in the proven gateway state. A missing, extra, reordered or changed leg makes the transaction fail. The check also covers blocks with no legs.

Proving the block does not reserve its Canton allocation. The sender can still take the allocation back before settlement. If that happens after proving, Canton refuses `Advance` and reth returns to the last committed block. The same proven block cannot be resubmitted with its leg removed. The next build leaves out the payment, as demonstrated in [run 4](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md#results).

## Token and custody limits

Who holds the Canton tokens, and which token behaviours the gateway does not cover, are set out in [Trust model and limits](https://docs.rome.builders/canton-zk-evm/trust-model.md).


---

# 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/deposits-withdrawals-payments.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.
