> 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/pt-br/canton-zk-evm/deposits-withdrawals-payments.md).

# Depósitos, saques e pagamentos

Como o gateway vincula depósitos, saques e pagamentos de EVM às suas contrapartes no Canton e como os gêmeos ERC-20 e o Canton Coin se movem nos dois sentidos.

O gateway é um contrato EVM incluído no gênesis da cadeia. Ele registra o que um bloco precisa que Canton faça. Cada solicitação é uma etapa. A prova do bloco se compromete com o estado do gateway, incluindo o hash das etapas na ordem em que foram registradas.

Depósitos, saques e pagamentos estão ativos na Ostia DevNet, operada pela Rome com partes de teste. Eles foram executados pela primeira vez na demonstração local de 2026-10-05. Em 2026-10-25, um token de teste da Canton, TKB (o token de teste de referência distribuído pela Splice), foi registrado no gateway, e sua versão encapsulada, wTKB, existe na Ostia em `0x294d3049874526910a69f6b61da14d10a8b1b3af`. Desde 2026-11-08, você pode depositar e sacar Canton Coin por conta própria na página [Bridge](https://docs.rome.builders/pt-br/canton-zk-evm/bridge.md) do explorador; consulte [Ativo na DevNet](#live-on-devnet) abaixo.

Desde 2026-10-29, o gateway também oferece suporte a ativos Canton bidirecionais: um ERC-20 pode ter um gêmeo na Canton, e a Canton Coin pode ir para a Ostia e voltar. Consulte [Gêmeos Canton de tokens ERC-20](#canton-twins-of-erc-20-tokens) e [Canton Coin](#canton-coin).

A maioria dos links desta página aponta para a versão `v0.1.0`; o link para o README do gateway aponta para a ramificação principal. Atualmente, a DevNet executa o código da ramificação principal do repositório com o pacote Daml 0.5.0, e as etapas seguem as mesmas regras. [Status](https://docs.rome.builders/pt-br/canton-zk-evm/status.md) indica o commit. Para saber o que você pode criar usando as etapas, consulte [Desenvolver com Canton](https://docs.rome.builders/pt-br/canton-zk-evm/build-with-canton.md). Leia o [README completo do gateway](https://github.com/rome-protocol/canton-zk-evm/blob/main/gateway/README.md) e a [interface Daml](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/daml/README.md).

| Etapa     | Chamada ao gateway               | Ação EVM                                             | Ação Canton em `Advance`                                                |
| --------- | -------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------- |
| Depósito  | `claim(id, token, amount)`       | Emite tokens encapsulados para quem fez a chamada.   | Executa a alocação do depositante para o gateway.                       |
| Saque     | `withdraw(token, amount, party)` | Queima os tokens encapsulados de quem fez a chamada. | Transfere o token Canton sob custódia do gateway para a parte indicada. |
| Pagamento | `pay(id, token, to, amount)`     | Transfere um ERC-20 de quem paga para quem recebe.   | Executa a alocação especificada pelos termos de pagamento acordados.    |

## Ativo na DevNet

Um depósito, um pagamento e um saque foram executados duas vezes na DevNet em 2026-10-25:

| Execução                                                 | Depósito                                       | Pagamento                                                                                                           | Saque                                         |
| -------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Primeira, das 08:08 às 08:10 UTC                         | Bloco 780: 10 TKB recebidos, 10 wTKB emitidos. | Bloco 783: V pagou 1 WtROME a U (tROME encapsulado, um ERC-20 na Ostia) em troca da alocação de 10 TKB de U para V. | Bloco 784: 4 wTKB queimados, 4 TKB pagos a U. |
| Segunda, das 11:31 às 11:34 UTC, com o pacote Daml 0.2.0 | Bloco 1465.                                    | Bloco 1471.                                                                                                         | Bloco 1473.                                   |

Cada perna ficou em um bloco separado. Em cada uma, o registro do bloco e a alteração da posição foram uma única atualização do Canton. Após a segunda execução, o fornecimento de wTKB era 12, o que qualquer pessoa pode consultar no Ostia. A execução do Rome verificou que, naquele momento, a gateway mantinha 12 TKB no Canton, igual a esse fornecimento. Desde 2026-10-25, o explorer também mostra isso: a página do token wTKB tem um cartão "Lastreado no Canton" com uma custódia de 12 TKB ao lado de um fornecimento de 12 wTKB.

U e V são partes de teste que o Rome criou e executa em seu próprio participante, e o Rome realizou todas as etapas. Você pode acompanhar as pernas no explorer: acesse [`/legs`](https://ostia.devnet.romeprotocol.xyz/legs) para ver a lista ou a página de um bloco para ver as pernas que ele contém. Um saque identifica a parte do Canton para a qual foi pago. wTKB é um ERC-20 comum com 10 casas decimais, portanto seu fornecimento e seus saldos são exibidos como os de qualquer outro token (consulte [Explorer](https://docs.rome.builders/pt-br/canton-zk-evm/explorer.md#legs-and-custody)).

O Rome executa um depósito, um pagamento e um saque a cada 10 minutos, e monitora a integridade deles a cada 30 segundos.

Para depositar e sacar Canton Coin por conta própria, conecte sua carteira Canton na página [Bridge](https://docs.rome.builders/pt-br/canton-zk-evm/bridge.md) do explorer, depois que ela estiver habilitada para sua carteira. A página Bridge também bloqueia tROME e TKA para o Canton (um gateway `pay` para o cofre). Os outros pagamentos e depósitos de TKB nesta página são executados pelas partes de teste do Rome.

## Depositar um token do Canton

O depositante aloca um token do Canton para a gateway, com o operador como executor. O depositante assina um `DepositRequest` que especifica o ID do depósito, o endereço EVM autorizado a reivindicá-lo e a alocação. O ID do depósito é o SHA-256 de `deposit,<depositor's party id>,<label>`, portanto, somente o depositante pode criar um ID a partir da própria parte.

Esse endereço EVM chama `claim`. A gateway emite tokens para quem a chamou e registra a perna do depósito. O destinatário precisa de tROME para pagar o gas. O builder associa a perna à solicitação, ao token registrado e à alocação.

`Advance` executa a alocação para a custódia da gateway e confirma o bloco que emitiu os tokens wrapped. Um token wrapped tem 10 casas decimais, correspondentes às quantias do Canton. A conversão entre as duas quantias é exata, sem arredondamento.

## Sacar para uma parte do Canton

O titular chama `withdraw` com o token wrapped, a quantia e o ID completo da parte do Canton. A gateway queima os tokens wrapped e registra o destinatário na perna.

O destinatário precisa ter assinado um `WithdrawalAcceptance`. Ele permanece ativo até ser arquivado. O builder também precisa de saldo desbloqueado suficiente da gateway no instrumento registrado. Se essas condições não forem atendidas, ele exclui a transação.

`Advance` paga o destinatário por meio da fábrica de transferências do registro de tokens. A transferência no Canton e o bloco que contém a queima são confirmados juntos. O builder inclui no máximo um saque de um instrumento por bloco, conforme descrito no [README do builder](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/builder/README.md).

## Vincular um pagamento a uma alocação

O pagador no Canton aloca um token do Canton para o beneficiário no Canton. Os dois assinam os `DvpTerms` que especificam a alocação, o ID do pagamento, o token EVM, o beneficiário EVM e a quantia. O ID do pagamento é o SHA-256 do texto UTF-8 `<Canton payer's party id>,<Canton payee's party id>,<label>`, representado em hexadecimal minúsculo. Os termos rejeitam qualquer outro ID.

Um pagador EVM aprova a gateway e chama `pay` com o ID, o token, o destinatário e a quantia acordados. A gateway transfere o ERC-20 desse pagador para o beneficiário EVM e registra a perna do pagamento. Na demonstração, o pagador era controlado pelo beneficiário no Canton; o protocolo não exige essa relação. `Advance` usa os termos assinados para executar a alocação do pagador no Canton para o beneficiário no Canton. O pagamento em ERC-20 e o pagamento no Canton são confirmados juntos, portanto nenhum dos dois é final sem o outro.

Uma transferência ERC-20 comum não registra nenhuma perna. Nem mesmo uma transferência do mesmo token para o mesmo beneficiário no mesmo bloco pode substituir `pay`. O [fluxo de pagamento do design](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/docs/DESIGN.md#the-flows) explica esse vínculo.

## Tokens ERC-20 equivalentes no Canton

Um token equivalente é a forma no Canton de um ERC-20 que existe no Ostia. É um token CIP-0056, o padrão de tokens do Canton, com o ID do instrumento `erc20:<token address>`, e ele é movimentado pelo padrão de transferência do token entre partes cujos participantes validaram o ostia-twin — o que hoje significa contas dos participantes da Canton. Cada twin corresponde individualmente ao ERC-20 mantido no cofre. TKA e WtROME (tROME encapsulado) têm twins na DevNet.

**Bloqueio.** Você deposita o ERC-20 no cofre por meio de um gateway simples, usando `pay`, e informa a parte da Canton que deve receber o twin. Antes do depósito, você informa ao serviço de registro de twins o destinatário e um `ref` à sua escolha; ele responde com o ID do bloqueio, que é o SHA-256 de `lock,<receiver>,<ref>`. O bloco registra o depósito no cofre e, na mesma transação da Canton, emite a mesma quantidade de twins para o destinatário. A oferta de twins passa, então, a ser igual ao que o cofre mantém.

**Resgate.** O titular assina uma solicitação de resgate na Canton e, em seguida, `release` é chamado no cofre com o mesmo `ref`. O cofre envia o ERC-20 para o endereço EVM indicado na solicitação, e o twin é queimado no mesmo bloco. A Canton liquida uma liberação somente quando há uma solicitação de resgate correspondente.

Pelas regras da cadeia, um twin só é emitido em `Advance`, mediante comprovação de um depósito em um cofre registrado; atualmente, o administrador do twin — a parte do gateway — também pode emitir e queimar tokens por conta própria. [Modelo de confiança e limitações](https://docs.rome.builders/pt-br/canton-zk-evm/trust-model.md#what-the-twins-trust) explica em que isso se baseia.

| Etapa    | Onde ocorre                                                       | Ação Canton em `Advance`           |
| -------- | ----------------------------------------------------------------- | ---------------------------------- |
| Bloqueio | Um gateway `pay` para o cofre.                                    | Emitir o twin para o destinatário. |
| Resgate  | `release` no cofre, mediante a solicitação assinada pelo titular. | Queimar o twin do titular.         |

Em 2026-10-29, um bloqueio de 5 TKA destinado a uma parte da Canton entrou no bloco 28389, e a parte recebeu 5 twins. Ela enviou 2 twins para uma segunda parte na Canton, e o resgate desses 2 entrou no bloco 28392. Depois disso, a oferta de twins e o saldo do cofre eram ambos 3. A página [`/twins`](https://ostia.devnet.romeprotocol.xyz/twins) do explorador mostra a oferta de cada twin ao lado do saldo do cofre (consulte [Explorador](https://docs.rome.builders/pt-br/canton-zk-evm/explorer.md#twins-and-canton-assets)).

Um bloqueio só é criado para um destinatário que tenha aceitado receber twins. Uma parte assina uma única vez para confirmar que os aceita, e o builder só cria um bloqueio para uma parte que tenha feito isso. Ao conectar uma carteira da Canton na página [Ponte](https://docs.rome.builders/pt-br/canton-zk-evm/bridge.md) e aceitar a participação ao optar por ela, você pode executar todo o ciclo com uma parte sua.

## Canton Coin

A Canton Coin chega à Ostia pelo mesmo depósito de gateway usado para qualquer token da Canton. O token encapsulado CC (`0x4db3dea7c13116961fd3e438542ccfcca61a7547`, 10 casas decimais; registros anteriores o chamam de wCC) é registrado na factory indicada pelo proxy de varredura do validador. Uma parte aloca Canton Coin ao gateway e assina uma solicitação de depósito identificada; o destinatário reivindica CC na Ostia, e um saque devolve a Canton Coin. A Canton Coin requer uma entrada adicional: um contexto de escolha fornecido pelo proxy de varredura, que o builder busca antes de comprovar o bloco.

Em 2026-10-29, uma parte depositou 5 Canton Coin no bloco 28473, ficando com 15; o gateway ficou com 5, e a oferta de CC passou a ser 5. O saque no bloco 28474 reverteu os três valores: 20, 0 e 0. A DevNet não cobrou taxas por essas transferências.

## O que a prova garante

Cada etapa registra seu tipo, ID, token, conta, quantidade e, quando aplicável, a parte da Canton. O gateway calcula o hash das etapas na ordem em que aparecem. `Advance` verifica se as etapas anexadas produzem o hash presente no estado comprovado do gateway. Se uma etapa estiver faltando, for extra, estiver fora de ordem ou tiver sido alterada, a transação falhará. A verificação também abrange blocos sem etapas.

A comprovação do bloco não reserva a alocação da Canton. O remetente ainda pode retirar a alocação antes da liquidação. Se isso acontecer após a comprovação, a Canton rejeitará `Advance` e o reth retorna ao último bloco confirmado. O mesmo bloco comprovado não pode ser reenviado com sua perna removida. A próxima construção omite o pagamento, conforme demonstrado em [execução 4](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md#results).

## Limites de tokens e custódia

Quem detém os tokens Canton e quais comportamentos dos tokens não são cobertos pelo gateway estão descritos em [Modelo de confiança e limites](https://docs.rome.builders/pt-br/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/pt-br/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.
