# Repository Map

> Where everything lives in the Apogee VM repository, what each crate is, and the page of the specification that defines it.

The Apogee VM repository is two Cargo workspaces: the root workspace for everything that runs on your host, and `guests/` for everything that runs inside the VM.

## Crates

| Path | What it is | Specified in |
| --- | --- | --- |
| `crates/constants` | every protocol constant, tag and identifier; no logic | the page that uses each |
| `crates/field`, `curve`, `poly`, `sumcheck` | `Fr`; the `Fq` tower, G1, G2, the pairing, MSM; multilinear polynomials; the zerocheck | [Primitives](https://apogee.gweb3networks.com/docs/auditors/spec/primitives) |
| `crates/transcript` | Poseidon2 and the duplex transcript | [Transcript](https://apogee.gweb3networks.com/docs/auditors/spec/transcript) |
| `crates/srs` | ceremony ingestion, the SRS archive, KZG, Groth16's phase 1 | [SRS](https://apogee.gweb3networks.com/docs/auditors/spec/srs) |
| `crates/pcs`, `pcs-verify` | Mercury and deferred verification; `pcs-verify` is verification's field side | [Mercury](https://apogee.gweb3networks.com/docs/auditors/spec/mercury) |
| `crates/loader`, `isa`, `program` | ELF to `ProgramImage`; the decoder; decoded tables, `VmConfig`, program identity | [Program and identity](https://apogee.gweb3networks.com/docs/auditors/spec/program) |
| `crates/emulator`, `trace` | the executor and its tracers; rows, memory state, column builders | [Execution trace](https://apogee.gweb3networks.com/docs/auditors/spec/execution-trace) |
| `crates/constraints` | every circuit as data: memory frames, lookup channels, the family circuits, the registries | [GKR engine](https://apogee.gweb3networks.com/docs/auditors/spec/gkr), [Memory](https://apogee.gweb3networks.com/docs/auditors/spec/memory), [Lookups](https://apogee.gweb3networks.com/docs/auditors/spec/lookup), [Circuits](https://apogee.gweb3networks.com/docs/auditors/spec/circuits) and the family pages |
| `crates/gkr-verify`, `gkr` | the GKR verifier and prover | [GKR engine](https://apogee.gweb3networks.com/docs/auditors/spec/gkr) |
| `crates/verifier-core` | statement, transcripts, verifying key, every check of a shard and a block but the opening; recursion's tapes, nodes and folding | [The proof](https://apogee.gweb3networks.com/docs/auditors/spec/proof), [Recursion](https://apogee.gweb3networks.com/docs/auditors/spec/recursion) |
| `crates/verifier` | `verify_shard`, `verify_block`, the proof archive, the `verifier` CLI | [The proof](https://apogee.gweb3networks.com/docs/auditors/spec/proof) |
| `crates/prover` | key construction, column fills, the streaming prover, the debug log | [Streaming prover](https://apogee.gweb3networks.com/docs/auditors/spec/streaming) |
| `crates/groth16` | Groth16 with bound wires and a two-phase ceremony | [Recursion §9](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s9) |
| `crates/host` | the host SDK: setup, prove, verify; the block-witness recorder; the recursion tree and decider | [Ethereum blocks](https://apogee.gweb3networks.com/docs/auditors/spec/ethereum), [Recursion](https://apogee.gweb3networks.com/docs/auditors/spec/recursion) |
| `crates/checker` | independent validators of the circuit laws, native lookup and memory evaluators, the tamper suite, the `checker` CLI | [Circuits §3](https://apogee.gweb3networks.com/docs/auditors/spec/circuits#s3) |
| `crates/guest-sdk` | the guest runtime: entry, linker script, allocator, memory regions, delegation shims | [Guest ABI](https://apogee.gweb3networks.com/docs/auditors/spec/ecall-abi), [Delegation ABI](https://apogee.gweb3networks.com/docs/auditors/spec/delegation) |
| `guests/` | test and workload guests, a workspace of their own; `vendor/` holds patched upstream crates | [Example guests](https://apogee.gweb3networks.com/docs/launch/examples) |
| `contracts/` | `ApogeeVerifier.sol` | [Recursion §9](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s9) |
| `tools/` | `kat-gen`, `bench`, `profiler`, `artifact-dump`, `test-support`; `transcript-ref` and `stateless-ref`, independent oracles outside the workspace | [Tools and CLIs](https://apogee.gweb3networks.com/docs/reference/tools) |
| `docs/` | the architecture overview, the glossary, the guest manual, the tools page and `spec/`, one page per subject | this site |

## Requirements

- The toolchain, its components and the `riscv32imac-unknown-none-elf` target are pinned in `rust-toolchain.toml`; `rustup` installs them on first use.
- Program identity, real keys and proving need the ceremony file `assets/ptau/ppot_0080_24.ptau`. The workspace tests do not.
- Proving is memory-bound: a full block peaked at 174 GiB.

## Commands

```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>
```

The suites that prove real shards are `#[ignore]`d and CI does not run them: each proves over a toy SRS of its own and needs tens of 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
```