# Repository-Übersicht

> Wo im Repository von Apogee VM was liegt, was jedes Crate ist und welche Seite der Spezifikation es definiert.

Das Repository von Apogee VM besteht aus zwei Cargo-Workspaces: dem Root-Workspace für alles, was auf Ihrem Host läuft, und `guests/` für alles, was in der VM läuft.

## Crates

| Pfad | Was es ist | Spezifiziert in |
| --- | --- | --- |
| `crates/constants` | jede Protokollkonstante, jedes Tag und jeder Bezeichner; keine Logik | die Seite, die sie jeweils verwendet |
| `crates/field`, `curve`, `poly`, `sumcheck` | `Fr`; der `Fq`-Turm, G1, G2, das Pairing, MSM; multilineare Polynome; der Zerocheck | [Primitive](https://apogee.gweb3networks.com/docs/auditors/spec/primitives) |
| `crates/transcript` | Poseidon2 und das Duplex-Transkript | [Transkript](https://apogee.gweb3networks.com/docs/auditors/spec/transcript) |
| `crates/srs` | Einlesen der Zeremonie, das SRS-Archiv, KZG, Phase 1 von Groth16 | [SRS](https://apogee.gweb3networks.com/docs/auditors/spec/srs) |
| `crates/pcs`, `pcs-verify` | Mercury und aufgeschobene Verifikation; `pcs-verify` ist die Körperseite der Verifikation | [Mercury](https://apogee.gweb3networks.com/docs/auditors/spec/mercury) |
| `crates/loader`, `isa`, `program` | ELF zu `ProgramImage`; der Decoder; dekodierte Tabellen, `VmConfig`, Programmidentität | [Programm und Identität](https://apogee.gweb3networks.com/docs/auditors/spec/program) |
| `crates/emulator`, `trace` | der Executor und seine Tracer; Zeilen, Speicherzustand, Spalten-Builder | [Ausführungs-Trace](https://apogee.gweb3networks.com/docs/auditors/spec/execution-trace) |
| `crates/constraints` | jeder Schaltkreis als Daten: Speicher-Frames, Lookup-Kanäle, die Familienschaltkreise, die Registries | [GKR-Engine](https://apogee.gweb3networks.com/docs/auditors/spec/gkr), [Speicherargument](https://apogee.gweb3networks.com/docs/auditors/spec/memory), [Lookups](https://apogee.gweb3networks.com/docs/auditors/spec/lookup), [Schaltkreise](https://apogee.gweb3networks.com/docs/auditors/spec/circuits) und die Familienseiten |
| `crates/gkr-verify`, `gkr` | der GKR-Verifier und der GKR-Prover | [GKR-Engine](https://apogee.gweb3networks.com/docs/auditors/spec/gkr) |
| `crates/verifier-core` | Aussage, Transkripte, Verifikationsschlüssel, jede Prüfung eines Shards und eines Blocks außer der Öffnung; Tapes, Knoten und Falten der Rekursion | [Der Beweis](https://apogee.gweb3networks.com/docs/auditors/spec/proof), [Rekursion](https://apogee.gweb3networks.com/docs/auditors/spec/recursion) |
| `crates/verifier` | `verify_shard`, `verify_block`, das Beweisarchiv, die CLI `verifier` | [Der Beweis](https://apogee.gweb3networks.com/docs/auditors/spec/proof) |
| `crates/prover` | Schlüsselkonstruktion, Befüllen der Spalten, der Streaming-Prover, das Debug-Log | [Streaming-Prover](https://apogee.gweb3networks.com/docs/auditors/spec/streaming) |
| `crates/groth16` | Groth16 mit gebundenen Wires und einer zweiphasigen Zeremonie | [Rekursion §9](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s9) |
| `crates/host` | das Host-SDK: Setup, Beweisen, Verifizieren; der Recorder für Block-Witnesses; Rekursionsbaum und Decider | [Ethereum-Blöcke](https://apogee.gweb3networks.com/docs/auditors/spec/ethereum), [Rekursion](https://apogee.gweb3networks.com/docs/auditors/spec/recursion) |
| `crates/checker` | unabhängige Validatoren der Schaltkreisgesetze, native Evaluatoren für Lookups und Speicher, die Manipulations-Suite, die CLI `checker` | [Schaltkreise §3](https://apogee.gweb3networks.com/docs/auditors/spec/circuits#s3) |
| `crates/guest-sdk` | die Laufzeit der Gastprogramme (Guests): Einsprung, Linker-Skript, Allokator, Speicherbereiche, Delegations-Shims | [Gastprogramm-ABI](https://apogee.gweb3networks.com/docs/auditors/spec/ecall-abi), [Delegations-ABI](https://apogee.gweb3networks.com/docs/auditors/spec/delegation) |
| `guests/` | Gastprogramme für Tests und Arbeitslasten, ein eigener Workspace; `vendor/` enthält gepatchte Upstream-Crates | [Beispiel-Gastprogramme](https://apogee.gweb3networks.com/docs/launch/examples) |
| `contracts/` | `ApogeeVerifier.sol` | [Rekursion §9](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s9) |
| `tools/` | `kat-gen`, `bench`, `profiler`, `artifact-dump`, `test-support`; `transcript-ref` und `stateless-ref`, unabhängige Orakel außerhalb des Workspace | [Werkzeuge und CLIs](https://apogee.gweb3networks.com/docs/reference/tools) |
| `docs/` | die Architekturübersicht, das Glossar, das Handbuch für Gastprogramme, die Werkzeugseite und `spec/`, eine Seite pro Thema | diese Website |

## Voraussetzungen

- Die Toolchain, ihre Komponenten und das Target `riscv32imac-unknown-none-elf` sind in `rust-toolchain.toml` festgelegt; `rustup` installiert sie bei der ersten Verwendung.
- Programmidentität, echte Schlüssel und Beweiserzeugung benötigen die Zeremoniedatei `assets/ptau/ppot_0080_24.ptau`. Die Workspace-Tests nicht.
- Die Beweiserzeugung ist speichergebunden: Ein vollständiger Block erreichte eine Spitze von 174 GiB.

## Befehle

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

Die Suiten, die echte Shards beweisen, sind mit `#[ignore]` markiert, und die CI führt sie nicht aus: Jede beweist über einem eigenen Spielzeug-SRS und braucht Dutzende 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
```