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

# Run your own Ostia

Run the checks, the rehearsal without a GPU, the local demo on a GPU, a chain that survives restarts and Ostia on an existing Canton participant.

By default the supplied scripts run a local test network. Canton holds its state in memory, so each restart discards that state and creates a new network. Two other modes keep a chain: persistent mode (`CZE_PERSIST=1`) and Ostia on a Canton participant you already have, which is how Ostia DevNet runs. The GPU demo proves blocks. The rehearsal uses a stand-in proof and needs no GPU.

This page describes release `v0.1.0`. Read the full [network guide](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md) and [demo guide](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md). Run the commands below from the `canton-zk-evm` repository root.

## What you need

| Work                     | Requirements                                                                                                                 |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Repository checks        | Docker, `bash`, `curl`, `jq`, `openssl` and Python 3. Rust tests use `rust-toolchain.toml`.                                  |
| Canton integration tests | Linux x86-64, Java 21 and network access.                                                                                    |
| Demo rehearsal           | Linux x86-64, Docker, Java 21, Rust and Python 3.12 or newer.                                                                |
| Explorer tests           | Node 22.18 or newer.                                                                                                         |
| GPU network and demo     | Linux x86-64, an NVIDIA GPU with its driver installed, Docker, Rust, Python 3.12 or newer, `jq`, `curl`, `openssl` and ZisK. |

The [repository README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md#running-the-tests) lists the test prerequisites. The GPU installer uses `sudo` and `apt` on Debian or Ubuntu and needs about 100 GB of free disk. It installs system packages and changes memory-lock limits. The network's tool fetcher installs Java 21 if missing. See [Ostia prover host](https://docs.rome.builders/canton-zk-evm/prover-host.md) for the tested hardware; minimum GPU memory has not been established.

## Run the tests

Start with the quick checks from [CONTRIBUTING.md](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/CONTRIBUTING.md#building-and-testing):

```sh
tests/static.sh                  # pins, genesis and licence lines agree
tests/refuses_missing_flag.sh    # the reth launch refuses a missing or wrong flag
tests/fixtures.sh                # the recorded proof is consistent
gateway/build.sh --check         # the checked-in gateway code is what Gateway.sol compiles to (Docker)
```

The repository README also gives these checks. They need no GPU:

```sh
tests/udp_control.sh             # the UDP check fails on a container with a UDP listener (no reth)
tests/discovery.sh               # starts the pinned reth, checks it has no peers, stops it
tests/network_static.sh          # reth only through launch.sh, the Canton config, the recorded smoke result
tests/network_checks.sh          # the compiler pin check, the DAR's id, the stop on another programVK (no GPU)
tests/canton_network.sh          # the pinned Canton, the real Daml package and one Advance (Linux x86-64, Java 21, Python 3; no GPU)
gateway/tests/run.sh             # the gateway on a real reth, started with peer discovery off (Docker, curl, jq, Python 3 with the packages in demo/requirements.txt)
tests/guest-repro.sh             # the guest build runs in one fixed folder, so the source folder does not change the ELF (stand-ins for the ZisK tools; the same check on real ZisK passed on 2026-10-04, see guest/README.md)
tests/demo_static.sh             # the demo's pins, tamper switch and genesis override, and its recorded results (no GPU)
tests/demo_explorer_static.sh    # the explorer's images are pinned, and what its container is given (no Docker)
(cd explorer && npm ci && npm test)  # the explorer's tests, against fakes (Node 22.18+; CI uses EXPLORER_NODE_IMAGE in PINS)
(cd guest/rules && cargo test)   # the chain rules and their hash (needs Rust)
```

## Rehearse without a GPU

```sh
tests/demo_rehearsal.sh          # the demo and explorer with a stand-in proof (Linux x86-64, Docker, Java 21, Rust, Python 3.12+; no GPU)
```

This runs the real reth, Canton, Daml package, token standard and builder. The sidecar checks the gateway's legs against storage proofs, while a stand-in answers the proof's `verify` call. The rehearsal neither proves a block nor verifies a real zero-knowledge proof.

It also checks the explorer and faucet. The explorer's Verify check must reject the stand-in proof. The [demo README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md#the-rehearsal) describes the rehearsal's coverage.

## Start the local network on a GPU

Install ZisK with `prover/install.sh` before starting the network. Always start reth through the supplied launcher; `network/up.sh` uses it.

```sh
network/up.sh       # tools, guest build, reth, sidecars, prover, Canton, the chain
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) network/smoke.sh    # one empty block, proven and committed
network/down.sh
```

`up.sh` builds the guest and refuses a program key, ZisK root or rules hash that differs from the recorded values. The network has one synchronizer and three participants. The operator and confirmer participants each run a sidecar. The participant named users hosts the test parties and the reader.

The smoke test commits an empty block, checks the chain's head and the reader's block record, and checks that reth marked it final. State and logs go to `state/`, or `CZE_STATE_DIR` when set.

## Run the five demo cases on a GPU

Use a new local network for the 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      # optional: one empty block first
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) demo/run.sh
network/down.sh
```

The preparation script creates test keys and a funded genesis for the run. The demo runs its setup block, deposit, payment, withdrawal, allocation refusal and tampered-proof refusal. The script stops if a check fails and writes its results to `demo/results/`.

For a source export without `.git`, set `CZE_SOURCE_COMMIT` to the full hash of the commit used for the export. To include the faucet, its funded genesis must be prepared before the network starts; see [Run the explorer yourself](#run-the-explorer-yourself) below and the full demo guide.

## Keep the chain across restarts

A chain that people use has to survive a crash or a reboot. `up.sh` makes a new chain on every run unless you ask for persistent mode:

```sh
CZE_PERSIST=1 network/up.sh     # the first start: a new chain, kept
network/down.sh                 # stops everything and keeps the data
network/restart.sh              # after a reboot: the same chain comes back
network/down.sh --wipe          # stops everything and removes the chain for good
```

Canton keeps its nodes in PostgreSQL on 127.0.0.1, with a password made on the machine into a mode 0600 file. reth keeps its data in `$CZE_STATE_DIR/reth-data` and writes every block to disk as it imports it. `restart.sh` creates nothing: it starts the database, reth, the sidecars, the prover and Canton on what they kept, and moves reth to Canton's head. It stops if the databases were made by another Canton version than the one in `PINS`. Back up the databases and `reth-data` together, with the network stopped. The [network guide](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md#keeping-the-chain-across-restarts) has every case.

## Run on an existing participant

Ostia can run on a Canton participant that is there already, such as a Splice validator's on Canton Network DevNet, instead of on the local network. This is how Ostia DevNet runs. `up.sh` then starts reth, the prover and, if you ask, one sidecar, and sets the chain up on that participant. It starts no Canton and bootstraps nothing.

You need:

* The participant's JSON Ledger API (v2), as an `https` URL or an `http` URL on the same machine.
* A token file for each of four Ledger API users: `ADMIN` (uploads the package and creates the parties and users, so only `up.sh` and `setup.py` need it) and `OPERATOR`, `CONFIRMER` and `BUILDER` (the users `setup.py` creates, `ostia-operator`, `ostia-confirmer` and `ostia-builder`). Each token is HS256 with the audience `https://canton.network.global` and the user's id as `sub`. Whoever runs the participant makes them. Ostia never makes, prints or stores a token.
* A sidecar that the participant can reach and nobody else can.

Tokens are short-lived, so write each new token into the same file in place. The builder reads its file again on every call. `setup.py` and `propose.py` read each token once, so start them with fresh tokens.

First give the participant the line it needs, as one more `ADDITIONAL_CONFIG` variable of its container, and restart it:

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

With `validate-on-startup` false, the participant still starts when the sidecar is down; a block's check then fails and no block commits. Then start the chain:

```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` is required here, because the chain stays on the participant and reth must keep its blocks too. If the sidecar runs on another machine, start it there with `network/external/sidecar.sh start <sidecar address>:8085` (the address the participant reaches it on, not a public one) and run `up.sh` without `CZE_SIDECAR_LISTEN`. `up.sh` builds the guest, starts reth and the prover, and runs `external/setup.py`, which uploads the package, allocates the parties, creates the users with only their roles' rights and proposes the chain. It can run twice without harm. `restart.sh` brings the chain back and needs only the builder's token. `down.sh --wipe` does not touch the participant: the chain's contracts stay there until its operator removes them.

Three rules apply to this mode:

* **Never expose the Ledger API.** It can act as every party the participant hosts. Keep it on the machine's own address or behind a proxy that checks who calls it.
* **Keep token files at mode 0600**, and off shared machines.
* **The participant's operator sees everything.** One participant hosts every Ostia party, so the operator can read every contract and act for every party, including the gateway's custody. Its one sidecar is the only confirmer. On Ostia DevNet that operator is Rome: it runs the participant, its own Canton DevNet validator.

## Run the builder continuously

`builder.py once` makes one block. `builder.py run` keeps making them:

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

It reads the same [settings](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/builder/README.md#settings) as `once`. With the default strategy, `on_demand`, it cuts a block whenever transactions that can go in are waiting, with one block in flight at a time by default (`--max-in-flight` raises it). A quiet chain makes no blocks unless `--heartbeat-seconds N` asks for an empty block after N seconds without one; the default is no heartbeat. After two refused blocks in a row, the builder suspects a transaction and leaves it out for a cool-down.

Only one builder runs at a time; `run` and `once` take a lock and refuse to start if another holds it. A stop signal finishes the block in progress and exits. Run the builder under a service manager that restarts it, with a stop timeout longer than a proof and Canton's answer together. A restart is safe at any time: the next start goes back to Canton's head and sends the cut-off block's transactions to reth again. The builder writes `status.json` and a journal in its work folder, and the explorer reads both.

## Run the explorer yourself

The explorer runs as a container beside the chain it shows, on a Linux machine with Docker. It has its own PostgreSQL, started by `network/explorer-db.sh`, which the indexer fills from Canton's records. The faucet's funding must be in the genesis before the network starts, so `setup` comes first:

```sh
explorer/run.sh setup           # makes the faucet's key and a funded genesis
CZE_GENESIS_FILE=state/faucet/genesis.json network/up.sh
explorer/run.sh start           # then open http://127.0.0.1:8088
explorer/run.sh stop
```

`start` starts the database, applies the migrations and starts the indexer as its own container, then the explorer. With no faucet key, the faucet is off. A faucet payout is a transaction to reth, so it becomes final only when the builder runs. Starting the network or the explorer does not start the builder. Run the builder once before `explorer/run.sh start`, or run `start` again after the first builder run; until then the explorer has no builder work folder and the block lifecycle stays blank. On a network made without `CZE_PERSIST`, `stop` also deletes the explorer's database, with its faucet requests and verified contract sources. A persistent network keeps it.

A default `explorer/run.sh start` has contract verification off unless you set `EXPLORER_VERIFIER=1` (with `SOLC_LIST_URL`), and has no `/rpc` and no contract Read calls unless you set `PUBLIC_RPC=1`. The settings are listed in the header of [explorer/run.sh](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/explorer/run.sh).

On the supplied local network the Ledger API has no login. The explorer reads only as the reader party, but anyone who can reach that participant can read its other parties too, so never give the container a public address there. On an existing participant, give the explorer a mode 0600 token file for the reader user (`LEDGER_TOKEN_FILE`), the participant's `LEDGER_URL` and the `READER_PARTY`. The container still listens on 127.0.0.1; a public address needs a proxy of your own. The [explorer guide](https://github.com/rome-protocol/canton-zk-evm/blob/main/explorer/README.md#running-it) has every setting.

## Load it with a realistic mix

`load/mixed` holds the kit behind the one-hour run on [Measurements](https://docs.rome.builders/canton-zk-evm/measurements.md). It deploys tokens of several kinds, a DEX, a permissioned token and a private-transfer contract on a chain, then sends mixed traffic from 200 wallets. Its [README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/README.md) has the steps. You need Docker and an account holding about 12,000 tROME with the kit's config as shipped. On your own chain, fund it in the genesis. The DevNet faucet cannot supply that much.


---

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