# Carte du dépôt

> Où se trouve chaque élément dans le dépôt Apogee VM, ce qu’est chaque crate, et la page de la spécification qui la définit.

Le dépôt Apogee VM comprend deux espaces de travail Cargo : l’espace de travail racine pour tout ce qui s’exécute sur votre hôte, et `guests/` pour tout ce qui s’exécute dans la VM.

## Crates

| Chemin | Ce que c’est | Spécifié dans |
| --- | --- | --- |
| `crates/constants` | chaque constante, étiquette et identifiant du protocole; aucune logique | la page qui utilise chacun d’eux |
| `crates/field`, `curve`, `poly`, `sumcheck` | `Fr`; la tour `Fq`, G1, G2, le couplage, la MSM; les polynômes multilinéaires; le zerocheck | [Primitives](https://apogee.gweb3networks.com/docs/auditors/spec/primitives) |
| `crates/transcript` | Poseidon2 et la transcription duplex | [Transcription](https://apogee.gweb3networks.com/docs/auditors/spec/transcript) |
| `crates/srs` | l’ingestion de la cérémonie, l’archive SRS, KZG, la phase 1 de Groth16 | [SRS](https://apogee.gweb3networks.com/docs/auditors/spec/srs) |
| `crates/pcs`, `pcs-verify` | Mercury et la vérification différée; `pcs-verify` est le côté corps de la vérification | [Mercury](https://apogee.gweb3networks.com/docs/auditors/spec/mercury) |
| `crates/loader`, `isa`, `program` | de l’ELF à `ProgramImage`; le décodeur; les tables décodées, `VmConfig`, l’identité du programme | [Programme et identité](https://apogee.gweb3networks.com/docs/auditors/spec/program) |
| `crates/emulator`, `trace` | l’exécuteur et ses traceurs; les lignes, l’état de la mémoire, les constructeurs de colonnes | [Trace d’exécution](https://apogee.gweb3networks.com/docs/auditors/spec/execution-trace) |
| `crates/constraints` | chaque circuit sous forme de données : cadres mémoire, canaux de lookup, circuits des familles, registres | [Moteur GKR](https://apogee.gweb3networks.com/docs/auditors/spec/gkr), [Mémoire](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) et les pages des familles |
| `crates/gkr-verify`, `gkr` | le vérificateur et le prouveur GKR | [Moteur GKR](https://apogee.gweb3networks.com/docs/auditors/spec/gkr) |
| `crates/verifier-core` | l’énoncé, les transcriptions, la clé de vérification, toutes les vérifications d’un shard et d’un bloc sauf l’ouverture; les bandes, les nœuds et le repliement de la récursion | [La preuve](https://apogee.gweb3networks.com/docs/auditors/spec/proof), [Récursion](https://apogee.gweb3networks.com/docs/auditors/spec/recursion) |
| `crates/verifier` | `verify_shard`, `verify_block`, l’archive de preuve, la CLI `verifier` | [La preuve](https://apogee.gweb3networks.com/docs/auditors/spec/proof) |
| `crates/prover` | la construction des clés, le remplissage des colonnes, le prouveur en flux, le journal de débogage | [Prouveur en flux](https://apogee.gweb3networks.com/docs/auditors/spec/streaming) |
| `crates/groth16` | Groth16 avec fils liés et cérémonie en deux phases | [Récursion §9](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s9) |
| `crates/host` | le SDK hôte : mise en place, preuve, vérification; l’enregistreur de témoins de bloc; l’arbre de récursion et le décideur | [Blocs Ethereum](https://apogee.gweb3networks.com/docs/auditors/spec/ethereum), [Récursion](https://apogee.gweb3networks.com/docs/auditors/spec/recursion) |
| `crates/checker` | des validateurs indépendants des lois des circuits, des évaluateurs natifs des lookups et de la mémoire, la suite de falsification, la CLI `checker` | [Circuits §3](https://apogee.gweb3networks.com/docs/auditors/spec/circuits#s3) |
| `crates/guest-sdk` | l’environnement d’exécution des programmes invités : point d’entrée, script d’édition de liens, allocateur, régions mémoire, shims de délégation | [ABI du programme invité](https://apogee.gweb3networks.com/docs/auditors/spec/ecall-abi), [ABI de délégation](https://apogee.gweb3networks.com/docs/auditors/spec/delegation) |
| `guests/` | les programmes invités de test et de charge de travail, dans leur propre espace de travail; `vendor/` contient les crates amont corrigées | [Exemples de programmes invités](https://apogee.gweb3networks.com/docs/launch/examples) |
| `contracts/` | `ApogeeVerifier.sol` | [Récursion §9](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s9) |
| `tools/` | `kat-gen`, `bench`, `profiler`, `artifact-dump`, `test-support`; `transcript-ref` et `stateless-ref`, des oracles indépendants hors de l’espace de travail | [Outils et CLI](https://apogee.gweb3networks.com/docs/reference/tools) |
| `docs/` | la vue d’ensemble de l’architecture, le glossaire, le manuel des programmes invités, la page des outils et `spec/`, une page par sujet | ce site |

## Prérequis

- La chaîne d’outils, ses composants et la cible `riscv32imac-unknown-none-elf` sont fixés dans `rust-toolchain.toml`; `rustup` les installe à la première utilisation.
- L’identité du programme, les vraies clés et la génération de preuves nécessitent le fichier de cérémonie `assets/ptau/ppot_0080_24.ptau`. Les tests de l’espace de travail, non.
- La génération de preuves est limitée par la mémoire : un bloc complet a culminé à 174 GiB.

## Commandes

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

Les suites qui prouvent de vrais shards sont marquées `#[ignore]` et la CI ne les exécute pas : chacune prouve sur sa propre SRS jouet et nécessite des dizaines de 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
```