> 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/zh/canton-zk-evm/run-it-locally.md).

# 运行您自己的 Ostia

运行校验、无需 GPU 的演练、在 GPU 上的本地演示、可在重启后继续运行的链，以及在现有 Canton 参与方上部署的 Ostia。

默认情况下，提供的脚本会运行本地测试网络。Canton 将状态保存在内存中，因此每次重启都会丢弃该状态并创建一个新网络。另有两种模式会保留链：持久模式（`CZE_PERSIST=1`）以及在已有的 Canton 参与方上运行 Ostia；Ostia DevNet 就是以这种方式运行的。GPU 演示会生成区块证明。演练则使用替代证明，不需要 GPU。

本页介绍发行版 `v0.1.0`。请阅读完整的 [网络指南](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md) 和 [演示指南](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md)。请在 `canton-zk-evm` 代码仓库根目录下运行以下命令。

## 所需条件

| 工作项         | 要求                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------ |
| 仓库检查        | Docker、 `bash`, `curl`, `jq`, `openssl` 以及 Python 3。Rust 测试使用 `rust-toolchain.toml`.             |
| Canton 集成测试 | Linux x86-64、Java 21 和网络访问权限。                                                                    |
| 演示演练        | Linux x86-64、Docker、Java 21、Rust，以及 Python 3.12 或更高版本。                                           |
| 资源管理器测试     | Node 22.18 或更高版本。                                                                                |
| GPU 网络与演示   | Linux x86-64、已安装驱动程序的 NVIDIA GPU、Docker、Rust、Python 3.12 或更高版本、 `jq`, `curl`, `openssl` 以及 ZisK。 |

该 [代码仓库 README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/README.md#running-the-tests) 列出了测试所需条件。GPU 安装程序会在 Debian 或 Ubuntu 上使用 `sudo` 和 `apt` ，并且需要约 100 GB 可用磁盘空间。它会安装系统软件包并更改内存锁定限制。若 Java 21 尚未安装，网络工具下载器会进行安装。有关经过测试的硬件，请参阅 [Ostia 证明者主机](https://docs.rome.builders/zh/canton-zk-evm/prover-host.md) ；目前尚未确定 GPU 显存的最低要求。

## 运行测试

先运行 [CONTRIBUTING.md](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/CONTRIBUTING.md#building-and-testing):

```sh
tests/static.sh                  # 固定版本、创世配置和许可证行保持一致
tests/refuses_missing_flag.sh    # reth 启动时会拒绝缺失或错误的标志
tests/fixtures.sh                # 已记录的证明保持一致
gateway/build.sh --check         # 已检入的网关代码应与 Gateway.sol 编译生成的代码一致（Docker）
```

仓库 README 也列出了这些检查。它们都不需要 GPU：

```sh
tests/udp_control.sh             # UDP 检查会在有 UDP 监听器的容器中失败（无需 reth）
tests/discovery.sh               # 启动固定版本的 reth，检查它没有对等节点，然后停止它
tests/network_static.sh          # 仅通过 launch.sh 运行 reth，并检查 Canton 配置和记录的冒烟测试结果
tests/network_checks.sh          # 编译器固定版本检查、DAR 的 ID，以及对另一个 programVK 的停止检查（无需 GPU）
tests/canton_network.sh          # 固定版本的 Canton、真实 Daml 包和一次 Advance（Linux x86-64、Java 21、Python 3；无需 GPU）
gateway/tests/run.sh             # 在真实 reth 上运行网关，并关闭对等节点发现（Docker、curl、jq、Python 3，以及 demo/requirements.txt 中的依赖包）
tests/guest-repro.sh             # guest 构建在固定目录中运行，因此源代码目录不会改变 ELF（使用 ZisK 工具的替代品；在真实 ZisK 上的同一检查已于 2026-10-04 通过，参见 guest/README.md）
tests/demo_static.sh             # 检查 demo 的固定版本、篡改开关和 genesis 覆盖项，以及记录的结果（无需 GPU）
tests/demo_explorer_static.sh    # 检查 explorer 镜像是否固定版本，以及提供给其容器的内容（无需 Docker）
(cd explorer && npm ci && npm test)  # 使用伪造对象运行 explorer 的测试（Node 22.18+；CI 使用 PINS 中的 EXPLORER_NODE_IMAGE）
(cd guest/rules && cargo test)   # 链规则及其哈希（需要 Rust）
```

## 无需 GPU 进行演练

```sh
tests/demo_rehearsal.sh          # 使用替代证明运行 demo 和 explorer（Linux x86-64、Docker、Java 21、Rust、Python 3.12+；无需 GPU）
```

此演练会运行真实的 reth、Canton、Daml 包、代币标准和构建器。sidecar 会根据存储证明检查网关各环节；同时由一个替代组件响应证明的 `verify` 调用。该演练既不会证明区块，也不会验证真实的零知识证明。

它还会检查 explorer 和 faucet。explorer 的 Verify 检查必须拒绝替代证明。 [demo README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/demo/README.md#the-rehearsal) 介绍了演练的覆盖范围。

## 在 GPU 上启动本地网络

启动网络之前，使用 `prover/install.sh` 安装 ZisK。务必通过提供的启动器启动 reth； `network/up.sh` 会使用该启动器。

```sh
network/up.sh       # 工具、guest 构建、reth、sidecar、prover、Canton、链
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) network/smoke.sh    # 一个空区块，已证明并提交
network/down.sh
```

`up.sh` 会构建 guest；如果程序密钥、ZisK 根目录或规则哈希与记录值不一致，就会拒绝运行。该网络包含一个 synchronizer 和三个参与方。operator 和 confirmer 参与方各自运行一个 sidecar。名为 users 的参与方托管测试 parties 和 reader。

冒烟测试会提交一个空区块，检查链的头部和 reader 的区块记录，并确认 reth 已将该区块标记为最终状态。状态和日志写入 `state/`；如果设置了 `CZE_STATE_DIR` ，则写入该目录。

## 在 GPU 上运行五个 demo 用例

使用新的本地网络运行 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      # 可选：先提交一个空区块
CZE_SOURCE_COMMIT=$(git rev-parse HEAD) demo/run.sh
network/down.sh
```

准备脚本会生成测试密钥和用于运行的预注资 genesis。demo 会运行设置区块、存款、付款、取款、拒绝分配以及拒绝篡改证明等用例。任何检查失败时，脚本都会停止，并将结果写入 `demo/results/`.

如果导出的源代码中没有 `.git`，请将 `CZE_SOURCE_COMMIT` 设为用于导出的提交的完整哈希。若要包含 faucet，必须在网络启动前准备好其预注资 genesis；参见 [自行运行区块浏览器](#run-the-explorer-yourself) 下方以及完整的演示指南。

## 重启后保留链

供人们使用的链必须能够在崩溃或重启后继续运行。 `up.sh` 除非启用持久化模式，否则每次运行都会创建一条新链：

```sh
CZE_PERSIST=1 network/up.sh     # 首次启动：创建一条新链并保留
network/down.sh                 # 停止所有服务并保留数据
network/restart.sh              # 重启后：恢复同一条链
network/down.sh --wipe          # 停止所有服务并永久删除该链
```

Canton 将节点数据存储在 127.0.0.1 上的 PostgreSQL 中，密码在本机生成并保存到权限为 0600 的文件中。reth 将数据存储在 `$CZE_STATE_DIR/reth-data` 并在导入每个区块时将其写入磁盘。 `restart.sh` 不会创建任何内容：它会基于已保留的数据启动数据库、reth、sidecar、证明器和 Canton，并将 reth 同步到 Canton 的最新区块。如果数据库由与 `PINS`中指定版本不同的 Canton 版本创建，脚本就会停止。请在网络停止时，一并备份数据库和 `reth-data` 。 [网络指南](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/network/README.md#keeping-the-chain-across-restarts) 涵盖了所有情况。

## 在现有参与方上运行

Ostia 可以运行在已有的 Canton 参与方上，例如 Splice 验证者在 Canton Network DevNet 上使用的参与方，而不是本地网络。这就是 Ostia DevNet 的运行方式。 `up.sh` 随后会启动 reth、证明器，并在需要时启动一个 sidecar，然后在该参与方上配置链。它不会启动 Canton，也不会执行引导初始化。

你需要：

* 参与方的 JSON Ledger API (v2)，使用 `https` URL，或使用同一台机器上的 `http` URL。
* 为四个 Ledger API 用户分别准备一个令牌文件： `ADMIN` （用于上传软件包并创建参与方和用户，因此只有 `up.sh` 和 `setup.py` 需要它）以及 `OPERATOR`, `CONFIRMER` 和 `BUILDER` （分别由用户 `setup.py` 创建为 `ostia-operator`, `ostia-confirmer` 和 `ostia-builder`）。每个令牌均采用 HS256，受众为 `https://canton.network.global` ，并将用户 ID 设为 `sub`。由运行参与方的人负责创建。Ostia 从不创建、打印或存储令牌。
* 一个参与方可以访问、其他人无法访问的 sidecar。

令牌有效期很短，因此每次生成新令牌后，都应原地写入同一个文件。构建器每次调用时都会重新读取该文件。 `setup.py` 和 `propose.py` 都会各自读取一次令牌，因此启动它们时要使用新生成的令牌。

首先，将参与方所需的配置行作为另一个 `ADDITIONAL_CONFIG` 变量传入其容器，然后重启参与方：

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

设置 `validate-on-startup` 为 false 时，即使 sidecar 已关闭，参与方仍会启动；但区块检查会失败，因此不会提交任何区块。然后启动链：

```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` 在此处是必需的，因为链运行在参与方上，reth 也必须保留其区块。如果 sidecar 在另一台机器上运行，请在该机器上使用以下命令启动它： `network/external/sidecar.sh start <sidecar address>:8085` （使用参与方访问 sidecar 时所用的地址，而不是公共地址），并运行 `up.sh` 但不要指定 `CZE_SIDECAR_LISTEN`. `up.sh` 该命令会构建执行环境、启动 reth 和证明器，并运行 `external/setup.py`，该脚本会上传软件包、分配各方、创建仅具有相应角色权限的用户，并提议启动链。重复运行不会造成问题。 `restart.sh` 会重新启动链，只需要构建器的令牌。 `down.sh --wipe` 不会影响参与方：链的合约会继续保留在参与方上，直到其运营者将其移除。

此模式适用以下三条规则：

* **绝不要将 Ledger API 暴露给外部。** 它可以代表该参与方托管的所有各方执行操作。请将其限制为仅监听本机地址，或置于会验证调用者身份的代理之后。
* **将令牌文件权限设为 0600**，并避免将其存放在共享机器上。
* **参与方的运营者可以看到所有内容。** 一个参与方托管 Ostia 的所有各方，因此其运营者可以读取所有合约，并代表所有各方执行操作，包括网关的托管资产。其唯一的 sidecar 是唯一的确认方。在 Ostia DevNet 上，该运营者是 Rome：它运行参与方，也运行自己的 Canton DevNet 验证器。

## 持续运行构建器

`builder.py once` 会生成一个区块。 `builder.py run` 则会持续生成区块：

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

它读取与 [相同的设置](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/builder/README.md#settings) ，与 `once`。使用默认策略 `on_demand`时，只要有可纳入区块的交易在等待，就会生成一个区块；默认情况下，同一时间最多只有一个区块处于处理中（`--max-in-flight` 可提高此上限）。链上没有活动时不会生成区块，除非 `--heartbeat-seconds N` 指定在 N 秒内没有生成区块时生成一个空区块；默认不启用心跳。连续两次区块被拒绝后，构建器会怀疑某笔交易有问题，并在一段冷却时间内将其排除。

同一时间只能运行一个构建器； `run` 和 `once` 都会获取锁；如果锁已被其他进程持有，就会拒绝启动。收到停止信号后，构建器会完成正在处理的区块并退出。请在能够自动重启服务的管理器下运行构建器，并将停止超时设置为长于生成证明和等待 Canton 响应所需时间之和。任何时候重启都是安全的：下次启动时，构建器会回到 Canton 的链头，并再次将被中断区块中的交易发送给 reth。构建器会在其工作目录中写入 `status.json` 和日志，浏览器会读取这两者。

## 自行运行浏览器

浏览器以容器形式运行，与其展示的链部署在同一台安装了 Docker 的 Linux 机器上。它使用独立的 PostgreSQL 数据库，由 `network/explorer-db.sh`启动，索引器会将 Canton 的记录写入其中。必须在网络启动前将水龙头的资金配置到创世状态中，因此要先运行 `setup` ：

```sh
explorer/run.sh setup           # 生成水龙头密钥和已注资的创世状态
CZE_GENESIS_FILE=state/faucet/genesis.json network/up.sh
explorer/run.sh start           # 然后打开 http://127.0.0.1:8088
explorer/run.sh stop
```

`start` 会启动数据库、应用迁移，并以独立容器启动索引器，随后启动浏览器。如果没有水龙头密钥，水龙头功能就会关闭。水龙头支付会向 reth 发送一笔交易，因此只有构建器运行后，该交易才会最终确认。启动网络或浏览器不会启动构建器。请先运行一次构建器，再运行 `explorer/run.sh start`；或者在构建器首次运行后再次运行 `start` 。在此之前，浏览器找不到构建器的工作目录，区块生命周期信息也会一直为空。对于未使用 `CZE_PERSIST`, `创建的网络，运行` stop

还会删除浏览器数据库，包括其中的水龙头请求和已验证合约源码。使用持久化网络则会保留数据库。 `默认情况下，` explorer/run.sh start `会关闭合约验证，除非设置` （同时设置 `SOLC_LIST_URL`）；也不会启用 `/rpc` 和合约读取调用，除非设置 `PUBLIC_RPC=1`。相关设置列在 [explorer/run.sh](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/explorer/run.sh).

的文件头部。在提供的本地网络中，Ledger API 无需登录。浏览器仅以读取方身份读取数据，但任何能够访问该参与方的人也能读取其其他参与方的数据，因此切勿为该容器配置可公开访问的地址。对于现有参与方，请向浏览器提供读取用户的权限为 0600 的令牌文件（`LEDGER_TOKEN_FILE`）、参与方的 `LEDGER_URL` 以及 `READER_PARTY`。容器仍仅侦听 127.0.0.1；如需使用公网地址，需要自行配置代理。 [浏览器指南](https://github.com/rome-protocol/canton-zk-evm/blob/main/explorer/README.md#running-it) 列出了所有设置。

## 使用贴近实际的混合负载运行

`load/mixed` 包含了在 [测量结果](https://docs.rome.builders/zh/canton-zk-evm/measurements.md)上进行一小时运行所需的工具包。它会在链上部署多种类型的代币、一个 DEX、一个许可型代币和一个私密转账合约，然后从 200 个钱包发送混合流量。其 [README](https://github.com/rome-protocol/canton-zk-evm/blob/v0.1.0/load/mixed/README.md) 中列出了操作步骤。你需要 Docker，以及一个持有约 12,000 tROME 的账户（使用工具包随附的配置）。如果使用自己的链，请在创世配置中为该账户注资。DevNet 水龙头无法提供这么多代币。


---

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