# 仓库地图

> 远地虚拟机代码仓库中各部分的位置、每个 crate 的作用，以及定义它的规范页面。

远地虚拟机的代码仓库由两个 Cargo 工作空间组成：根工作空间包含在你的宿主机（host）上运行的一切，`guests/` 包含在虚拟机内运行的一切。

## Crate 一览

| 路径 | 说明 | 规范出处 |
| --- | --- | --- |
| `crates/constants` | 所有协议常量、标签和标识符；不含逻辑 | 使用各常量的页面 |
| `crates/field`、`curve`、`poly`、`sumcheck` | `Fr`；`Fq` 扩域塔、G1、G2、配对、MSM；多线性多项式；零校验（zerocheck） | [原语](https://apogee.gweb3networks.com/docs/auditors/spec/primitives) |
| `crates/transcript` | Poseidon2 与双工 transcript | [Transcript](https://apogee.gweb3networks.com/docs/auditors/spec/transcript) |
| `crates/srs` | 仪式文件导入、SRS 归档、KZG、Groth16 的第一阶段 | [SRS](https://apogee.gweb3networks.com/docs/auditors/spec/srs) |
| `crates/pcs`、`pcs-verify` | Mercury 与延迟验证；`pcs-verify` 是验证中的域运算部分 | [Mercury](https://apogee.gweb3networks.com/docs/auditors/spec/mercury) |
| `crates/loader`、`isa`、`program` | 从 ELF 到 `ProgramImage`；解码器；解码表、`VmConfig`、程序身份 | [程序与身份](https://apogee.gweb3networks.com/docs/auditors/spec/program) |
| `crates/emulator`、`trace` | 执行器及其追踪器；行、内存状态、列构建器 | [执行轨迹](https://apogee.gweb3networks.com/docs/auditors/spec/execution-trace) |
| `crates/constraints` | 以数据形式表示的全部电路：内存帧、查找通道、各电路族的电路、注册表 | [GKR 引擎](https://apogee.gweb3networks.com/docs/auditors/spec/gkr)、[内存](https://apogee.gweb3networks.com/docs/auditors/spec/memory)、[查找](https://apogee.gweb3networks.com/docs/auditors/spec/lookup)、[电路](https://apogee.gweb3networks.com/docs/auditors/spec/circuits)以及各电路族页面 |
| `crates/gkr-verify`、`gkr` | GKR 验证者与证明者 | [GKR 引擎](https://apogee.gweb3networks.com/docs/auditors/spec/gkr) |
| `crates/verifier-core` | 陈述、transcript、验证密钥，以及除打开之外对分片和块（block）的全部检查；递归的 tape、节点与折叠 | [证明](https://apogee.gweb3networks.com/docs/auditors/spec/proof)、[递归](https://apogee.gweb3networks.com/docs/auditors/spec/recursion) |
| `crates/verifier` | `verify_shard`、`verify_block`、证明归档、`verifier` CLI | [证明](https://apogee.gweb3networks.com/docs/auditors/spec/proof) |
| `crates/prover` | 密钥构造、列填充、流式证明者、调试日志 | [流式证明者](https://apogee.gweb3networks.com/docs/auditors/spec/streaming) |
| `crates/groth16` | 带绑定线和两阶段仪式的 Groth16 | [递归 §9](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s9) |
| `crates/host` | 宿主程序 SDK：设置、证明、验证；区块见证记录器；递归树与判定器 | [以太坊区块](https://apogee.gweb3networks.com/docs/auditors/spec/ethereum)、[递归](https://apogee.gweb3networks.com/docs/auditors/spec/recursion) |
| `crates/checker` | 电路法则的独立校验器、原生查找与内存求值器、篡改测试套件、`checker` CLI | [电路 §3](https://apogee.gweb3networks.com/docs/auditors/spec/circuits#s3) |
| `crates/guest-sdk` | 客户程序（guest）运行时：入口、链接脚本、分配器、内存区域、委托 shim | [客户程序 ABI](https://apogee.gweb3networks.com/docs/auditors/spec/ecall-abi)、[委托 ABI](https://apogee.gweb3networks.com/docs/auditors/spec/delegation) |
| `guests/` | 用于测试和工作负载的客户程序，自成一个工作空间；`vendor/` 存放打过补丁的上游 crate | [示例客户程序](https://apogee.gweb3networks.com/docs/launch/examples) |
| `contracts/` | `ApogeeVerifier.sol` | [递归 §9](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s9) |
| `tools/` | `kat-gen`、`bench`、`profiler`、`artifact-dump`、`test-support`；`transcript-ref` 与 `stateless-ref`，即工作空间之外的独立参照（oracle） | [工具与 CLI](https://apogee.gweb3networks.com/docs/reference/tools) |
| `docs/` | 架构概述、术语表、客户程序手册、工具页面，以及 `spec/`（每个主题一页） | 本站 |

## 环境要求

- 工具链、其组件以及 `riscv32imac-unknown-none-elf` 目标都固定在 `rust-toolchain.toml` 中；`rustup` 会在首次使用时安装它们。
- 计算程序身份、生成真实密钥和执行证明都需要仪式文件 `assets/ptau/ppot_0080_24.ptau`。工作空间的测试不需要。
- 证明受内存限制：一个完整区块的内存峰值达到 174 GiB。

## 常用命令

```sh
# What CI runs
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo run -p kat-gen && git diff --exit-code     # committed fixtures regenerate identically

# Guests: their own workspace and target
(cd guests && cargo clippy --bins -- -D warnings)
(cd guests/fib && cargo build --target riscv32imac-unknown-none-elf)   # --release for proving

# Prove and verify a block, then recurse and decide
cargo run --release -p bench -- prove mini-block --out <dir>
cargo run --release -p verifier -- block <stem>.vk  <stem>.public <stem>.block
cargo run --release -p bench -- recurse <dir>/<stem> --out <out>
```

证明真实分片的测试套件都标记了 `#[ignore]`，CI 不运行它们：每个套件都在自己的玩具 SRS 上做证明，需要数十 GiB 内存。

```sh
cargo test --release -p prover --test <suite> -- --include-ignored --test-threads=1
#   acceptance, control, alu, mem, fills, block, streaming, keccak, recursion, public_io, revm
cargo test --release -p host --test prove -- --include-ignored --test-threads=1     # a mainnet mini-block
cargo test --release -p checker --test tamper -- --include-ignored --test-threads=1 # every tamper twin
```