> 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 it locally

Run the checks, the rehearsal without a GPU and the local Ostia demo on a GPU.

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. The GPU demo proves blocks. The rehearsal uses a stand-in proof and needs no GPU.

This page describes commit `a84e84e439a5cc669c0ae61facf7c8c995d9d564`. Read the full [network guide](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/network/README.md) and [demo guide](https://github.com/rome-protocol/canton-zk-evm/blob/a84e84e439a5cc669c0ae61facf7c8c995d9d564/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/a84e84e439a5cc669c0ae61facf7c8c995d9d564/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 [Prover host](/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/a84e84e439a5cc669c0ae61facf7c8c995d9d564/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/a84e84e439a5cc669c0ae61facf7c8c995d9d564/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 [Explorer](/canton-zk-evm/explorer.md) and the full demo guide.


---

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