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

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.

This page describes commit `a84e84e439a5cc669c0ae61facf7c8c995d9d564`. Read the full [gateway README](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/gateway/README.md) and [Daml interface](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/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.     |

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

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/a84e84e439a5cc669c0ae61facf7c8c995d9d564/builder/README.md).

## Tie a payment to one allocation

U allocates a Canton token to V. U and V 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 `<U's party id>,<V's party id>,<label>`, written in lowercase hex. The terms reject any other id.

V approves the gateway and calls `pay` with that id. The gateway moves the ERC-20 from V to the payee and records the payment leg. `Advance` uses the signed terms to execute the allocation from U to V.

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/a84e84e439a5cc669c0ae61facf7c8c995d9d564/docs/DESIGN.md#the-flows) explains this binding.

## 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/a84e84e439a5cc669c0ae61facf7c8c995d9d564/demo/README.md#results).

## Token and custody limits

The Canton tokens are held by the gateway party on the operator's participant. Whoever runs that participant can move them. Registering a token also means trusting its registry's Daml code, which runs with the gateway's authority.

Tokens sent directly to the gateway's EVM address cannot be recovered. If a token charges a transfer fee or otherwise transfers a different amount, the payment leg still records the requested amount, rather than the amount actually transferred. Read [Trust model and limits](/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.