> 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/run-it-locally.md).

# Execute seu próprio Ostia

Execute as verificações, o ensaio sem GPU, a demo local com GPU, uma chain que sobrevive a reinicializações e a Ostia em um participante Canton já existente.

Por padrão, os scripts fornecidos executam uma rede de teste local. O Canton mantém o estado na memória; portanto, cada reinicialização descarta esse estado e cria uma nova rede. Dois outros modos mantêm uma cadeia: o modo persistente (`CZE_PERSIST=1`) e o Ostia em um participante Canton que você já tenha, que é como a Ostia DevNet funciona. A demonstração com GPU comprova blocos. O ensaio usa uma prova substituta e não requer GPU.

Esta página descreve a versão `v0.1.0`. Leia o [guia completo da rede](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md) e o [guia da demonstração](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md). Execute os comandos abaixo a partir da raiz do repositório `canton-zk-evm` .

## O que você precisa

| Atividade                      | Requisitos                                                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Verificações do repositório    | Docker, `bash`, `curl`, `jq`, `openssl` e Python 3. Os testes do Rust usam `rust-toolchain.toml`.                               |
| Testes de integração do Canton | Linux x86-64, Java 21 e acesso à rede.                                                                                          |
| Ensaio da demonstração         | Linux x86-64, Docker, Java 21, Rust e Python 3.12 ou mais recente.                                                              |
| Testes do Explorer             | Node 22.18 ou mais recente.                                                                                                     |
| Rede e demonstração com GPU    | Linux x86-64, uma GPU NVIDIA com o driver instalado, Docker, Rust, Python 3.12 ou mais recente, `jq`, `curl`, `openssl` e ZisK. |

O [README do repositório](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md#running-the-tests) lista os pré-requisitos dos testes. O instalador de GPU usa `sudo` e `apt` no Debian ou Ubuntu e precisa de cerca de 100 GB de espaço livre em disco. Ele instala pacotes do sistema e altera os limites de bloqueio de memória. O utilitário de busca de ferramentas da rede instala o Java 21, se necessário. Consulte [Host do provador Ostia](https://docs.rome.builders/pt-br/canton-zk-evm/prover-host.md) para ver o hardware testado; o requisito mínimo de memória da GPU ainda não foi estabelecido.

## Execute os testes

Comece pelas verificações rápidas de [CONTRIBUTING.md](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/CONTRIBUTING.md#building-and-testing):

```sh
tests/static.sh                  # as linhas de pins, genesis e licença estão de acordo
tests/refuses_missing_flag.sh    # a inicialização do reth recusa uma flag ausente ou incorreta
tests/fixtures.sh                # a prova registrada é consistente
gateway/build.sh --check         # o código do gateway registrado no repositório é o que Gateway.sol compila (Docker)
```

O README do repositório também apresenta estas verificações. Elas não precisam de GPU:

```sh
tests/udp_control.sh             # a verificação de UDP falha em um contêiner com um listener UDP (sem reth)
tests/discovery.sh               # inicia o reth fixado, verifica se ele não tem pares e o interrompe
tests/network_static.sh          # reth somente por meio de launch.sh, a configuração do Canton e o resultado de smoke test registrado
tests/network_checks.sh          # a verificação da versão fixa do compilador, o ID do DAR e a interrupção em outro programVK (sem GPU)
tests/canton_network.sh          # o Canton fixado, o pacote Daml real e um Advance (Linux x86-64, Java 21, Python 3; sem GPU)
gateway/tests/run.sh             # o gateway em um reth real, iniciado com a descoberta de pares desativada (Docker, curl, jq, Python 3 com os pacotes de demo/requirements.txt)
tests/guest-repro.sh             # a compilação do guest é executada em uma pasta fixa, para que a pasta de origem não altere o ELF (substitutos para as ferramentas do ZisK; a mesma verificação no ZisK real passou em 2026-10-04; consulte guest/README.md)
tests/demo_static.sh             # as versões fixas do demo, a opção de adulteração e a substituição do genesis, além dos resultados registrados (sem GPU)
tests/demo_explorer_static.sh    # as imagens do explorer são fixadas, assim como o que é fornecido ao contêiner (sem Docker)
(cd explorer && npm ci && npm test)  # os testes do explorer, com dados falsos (Node 22.18+; a CI usa EXPLORER_NODE_IMAGE em PINS)
(cd guest/rules && cargo test)   # as regras da chain e seu hash (requer Rust)
```

## Faça um ensaio sem GPU

```sh
tests/demo_rehearsal.sh          # o demo e o explorer com uma prova substituta (Linux x86-64, Docker, Java 21, Rust, Python 3.12+; sem GPU)
```

Isso executa o reth, o Canton, o pacote Daml, o padrão de token e o builder reais. O sidecar verifica as etapas do gateway em relação às provas de armazenamento, enquanto um substituto responde à chamada `verify` . O ensaio não prova um bloco nem verifica uma prova real de conhecimento zero.

Ele também verifica o explorer e o faucet. A verificação Verify do explorer deve rejeitar a prova substituta. O [README do demo](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md#the-rehearsal) descreve o escopo do ensaio.

## Inicie a rede local com uma GPU

Instale o ZisK com `prover/install.sh` antes de iniciar a rede. Sempre inicie o reth pelo launcher fornecido; `network/up.sh` usa esse launcher.

```sh
network/up.sh       # ferramentas, compilação do guest, reth, sidecars, prover, Canton, a chain
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) network/smoke.sh    # um bloco vazio, provado e confirmado
network/down.sh
```

`up.sh` compila o guest e recusa uma chave de programa, uma raiz do ZisK ou um hash das regras diferente dos valores registrados. A rede tem um sincronizador e três participantes. Os participantes operator e confirmer executam, cada um, um sidecar. O participante chamado users hospeda as partes de teste e o reader.

O smoke test confirma um bloco vazio, verifica o head da chain e o registro do bloco no reader, além de verificar se o reth o marcou como final. O estado e os logs são gravados em `state/`, ou em `CZE_STATE_DIR` quando definido.

## Execute os cinco casos do demo com uma GPU

Use uma rede local nova para o demo:

```sh
demo/prepare.sh
CZE_GENESIS_FILE=$PWD/state/demo/genesis.json network/up.sh
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) network/smoke.sh      # opcional: primeiro, um bloco vazio
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) demo/run.sh
network/down.sh
```

O script de preparação cria chaves de teste e um genesis com fundos para a execução. O demo executa seu bloco de configuração, depósito, pagamento, saque, recusa de alocação e recusa de prova adulterada. O script para se uma verificação falhar e grava os resultados em `demo/results/`.

Para uma exportação do código-fonte sem `.git`, defina `CZE_SOURCE_COMMIT` com o hash completo do commit usado na exportação. Para incluir o faucet, o genesis com fundos precisa ser preparado antes do início da rede; consulte [Execute o explorador por conta própria](#run-the-explorer-yourself) abaixo e o guia completo da demonstração.

## Mantenha a cadeia entre reinicializações

Uma cadeia usada por outras pessoas precisa sobreviver a uma falha ou reinicialização. `up.sh` cria uma nova cadeia a cada execução, a menos que você solicite o modo persistente:

```sh
CZE_PERSIST=1 network/up.sh     # na primeira inicialização: cria uma nova cadeia e a mantém
network/down.sh                 # interrompe tudo e mantém os dados
network/restart.sh              # após uma reinicialização: a mesma cadeia volta
network/down.sh --wipe          # interrompe tudo e remove a cadeia permanentemente
```

O Canton mantém seus nós no PostgreSQL em 127.0.0.1, com uma senha criada na máquina e armazenada em um arquivo com modo 0600. O reth mantém seus dados em `$CZE_STATE_DIR/reth-data` e grava cada bloco em disco à medida que o importa. `restart.sh` não cria nada: inicia o banco de dados, o reth, os sidecars, o prover e o Canton com os dados que eles mantiveram, e sincroniza o reth com o head do Canton. A execução é interrompida se os bancos de dados tiverem sido criados por uma versão do Canton diferente daquela em `PINS`. Faça backup dos bancos de dados e de `reth-data` juntos, com a rede parada. O [guia da rede](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md#keeping-the-chain-across-restarts) abrange todos os casos.

## Executar em um participante existente

Ostia pode ser executado em um participante Canton que já esteja em funcionamento, como o de um validador Splice no DevNet da Canton Network, em vez de na rede local. É assim que o Ostia DevNet é executado. `up.sh` inicia então o reth, o prover e, se você solicitar, um sidecar, e configura a cadeia nesse participante. Não inicia o Canton nem faz o bootstrap de nada.

Você precisa de:

* A Ledger API JSON (v2) do participante, como uma URL `https` ou uma URL `http` na mesma máquina.
* Um arquivo de token para cada um dos quatro usuários da Ledger API: `ADMIN` (envia o pacote e cria as partes e os usuários, então apenas `up.sh` e `setup.py` precisam dele) e `OPERATOR`, `CONFIRMER` e `BUILDER` (os usuários que `setup.py` cria: `ostia-operator`, `ostia-confirmer` e `ostia-builder`). Cada token usa HS256, com o público `https://canton.network.global` e o ID do usuário como `sub`. Quem executa o participante é quem os cria. A Ostia nunca cria, imprime nem armazena um token.
* Um sidecar que o participante consegue acessar, mas mais ninguém.

Os tokens têm vida curta, então grave cada novo token no mesmo arquivo, sobrescrevendo o conteúdo. O builder lê o arquivo novamente a cada chamada. `setup.py` e `propose.py` leem cada token uma única vez; por isso, inicie-os com tokens novos.

Primeiro, forneça ao participante a linha de que ele precisa como mais uma variável `ADDITIONAL_CONFIG` do contêiner e reinicie-o:

```sh
network/external/participant-config.sh <sidecar address> 8085
# imprime: ADDITIONAL_CONFIG_ZK_EVM=canton.participants.participant.parameters.engine.extensions.canton-zk-evm { address = "<sidecar address>", port = 8085, validate-on-startup = false }
```

Com `validate-on-startup` definido como false, o participante ainda inicia quando o sidecar está indisponível; nesse caso, a verificação do bloco falha e nenhum bloco é confirmado. Em seguida, inicie a cadeia:

```sh
export CZE_CANTON=external CZE_LEDGER_URL=https://<participant's Ledger API>
export CZE_TOKEN_FILE_ADMIN=... CZE_TOKEN_FILE_OPERATOR=... \
       CZE_TOKEN_FILE_CONFIRMER=... CZE_TOKEN_FILE_BUILDER=...
CZE_PERSIST=1 CZE_SIDECAR_LISTEN=<sidecar address>:8085 network/up.sh
```

`CZE_PERSIST=1` é necessário aqui, porque a cadeia permanece no participante e o reth também precisa manter seus blocos. Se o sidecar for executado em outra máquina, inicie-o nela com `network/external/sidecar.sh start <sidecar address>:8085` (o endereço pelo qual o participante o acessa, não um endereço público) e execute `up.sh` sem `CZE_SIDECAR_LISTEN`. `up.sh` compila o guest, inicia o reth e o prover e executa `external/setup.py`, que envia o pacote, aloca as partes, cria usuários com apenas as permissões de suas respectivas funções e propõe a cadeia. Pode ser executado duas vezes sem causar problemas. `restart.sh` reativa a cadeia e precisa apenas do token do builder. `down.sh --wipe` não afeta o participante: os contratos da cadeia permanecem nele até que o operador os remova.

Este modo está sujeito a três regras:

* **Nunca exponha a Ledger API.** Ela pode agir como qualquer parte hospedada pelo participante. Mantenha-a no endereço da própria máquina ou atrás de um proxy que verifique quem a acessa.
* **Mantenha os arquivos de token com permissão 0600**, e fora de máquinas compartilhadas.
* **O operador do participante vê tudo.** Um participante hospeda todas as partes da Ostia, então o operador pode ler todos os contratos e agir em nome de todas as partes, inclusive na custódia do gateway. Seu único sidecar é o único confirmer. Na Ostia DevNet, esse operador é Roma: ela executa o participante, seu próprio validador da Canton DevNet.

## Execute o builder continuamente

`builder.py once` cria um bloco. `builder.py run` continua criando blocos:

```sh
python3 builder/builder.py run [--heartbeat-seconds N] [--status-file <path>]
```

Ele lê as mesmas [configurações](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/builder/README.md#settings) que `once`. Com a estratégia padrão, `on_demand`, ele cria um bloco sempre que há transações prontas para serem incluídas, com um bloco em andamento por vez por padrão (`--max-in-flight` aumenta esse limite). Uma cadeia sem atividade não cria blocos, a menos que `--heartbeat-seconds N` solicite um bloco vazio após N segundos sem nenhum bloco; por padrão, não há heartbeat. Depois de dois blocos recusados consecutivos, o builder suspeita de uma transação e a deixa de fora durante um período de espera.

Apenas um builder é executado por vez; `run` e `once` adquirem um bloqueio e se recusam a iniciar se outro processo já o tiver. Um sinal de parada conclui o bloco em andamento e encerra o processo. Execute o builder sob um gerenciador de serviços que o reinicie, com um tempo limite de parada superior ao tempo necessário para gerar uma prova e receber a resposta de Canton. É seguro reiniciar a qualquer momento: na próxima inicialização, o processo volta ao estado mais recente de Canton e envia novamente ao reth as transações do bloco interrompido. O builder grava `status.json` e um diário na pasta de trabalho, e o explorador lê ambos.

## Execute o explorador por conta própria

O explorador é executado em um contêiner ao lado da cadeia que exibe, em uma máquina Linux com Docker. Ele tem seu próprio PostgreSQL, iniciado por `network/explorer-db.sh`, que o indexador preenche com os registros de Canton. O financiamento do faucet precisa estar na gênese antes do início da rede, então `setup` vem primeiro:

```sh
explorer/run.sh setup           # cria a chave do faucet e uma gênese financiada
CZE_GENESIS_FILE=state/faucet/genesis.json network/up.sh
explorer/run.sh start           # depois, abra http://127.0.0.1:8088
explorer/run.sh stop
```

`start` inicia o banco de dados, aplica as migrações e inicia o indexador em seu próprio contêiner e, em seguida, inicia o explorador. Sem uma chave do faucet, o faucet fica desativado. Um pagamento do faucet é uma transação enviada ao reth, portanto só se torna final quando o builder é executado. Iniciar a rede ou o explorador não inicia o builder. Execute o builder uma vez antes de `explorer/run.sh start`, ou execute `start` novamente após a primeira execução do builder; até lá, o explorador não terá a pasta de trabalho do builder e o ciclo de vida dos blocos permanecerá em branco. Em uma rede criada sem `CZE_PERSIST`, `stop` também exclui o banco de dados do explorador, incluindo as solicitações do faucet e as fontes verificadas dos contratos. Uma rede persistente mantém esses dados.

Por padrão, `explorer/run.sh start` desativa a verificação de contratos, a menos que você defina `EXPLORER_VERIFIER=1` (com `SOLC_LIST_URL`), e não disponibiliza `/rpc` nem chamadas de leitura de contratos, a menos que você defina `PUBLIC_RPC=1`. As configurações estão listadas no cabeçalho de [explorer/run.sh](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/explorer/run.sh).

Na rede local fornecida, a Ledger API não exige login. O explorador faz leituras apenas como a parte leitora, mas qualquer pessoa que consiga acessar esse participante também pode ler os dados das outras partes; portanto, nunca exponha o contêiner a um endereço público nesse ambiente. Em um participante existente, forneça ao explorador um arquivo de token no modo 0600 para o usuário leitor (`LEDGER_TOKEN_FILE`), o `LEDGER_URL` do participante e o `READER_PARTY`. O contêiner continua escutando em 127.0.0.1; para usar um endereço público, você precisa configurar seu próprio proxy. O [guia do explorador](https://github.com/rome-protocol/canton-zk-evm/blob/main/explorer/README.md#running-it) contém todas as configurações.

## Carregue-o com uma combinação realista

`load/mixed` contém o kit usado na execução de uma hora em [Medições](https://docs.rome.builders/pt-br/canton-zk-evm/measurements.md). Ele implanta em uma cadeia tokens de vários tipos, uma DEX, um token permissionado e um contrato de transferências privadas e, em seguida, envia tráfego misto de 200 carteiras. O [README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/README.md) contém as etapas. Você precisa do Docker e de uma conta com cerca de 12.000 tROME, usando a configuração padrão do kit. Na sua própria cadeia, abasteça a conta no bloco gênese. A torneira da DevNet não consegue fornecer essa quantidade.


---

# 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/run-it-locally.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.
