# Audit Guide

> Everything an auditor of Apogee VM v1.0.0 needs to start: the scope, the normative specification and how it is organized, the notation, the trust boundary, a reading order, and the properties most worth checking first.

This section is the complete construction of Apogee VM v1.0.0, organized for evaluation. Its core is the **normative specification**, reproduced verbatim: one page per subject, with every committed column by index and name, every gate as a polynomial, every lookup and its channel, every transcript message in order, and every byte of every wire form. Around it, this guide and the [soundness map](https://apogee.gweb3networks.com/docs/auditors/soundness-map) give an auditor a way in.

## Scope

| In scope | Where |
| --- | --- |
| The statement a proof establishes, and what a verifier must hold | [System, end to end](https://apogee.gweb3networks.com/docs/auditors/spec/architecture), [The proof](https://apogee.gweb3networks.com/docs/auditors/spec/proof) |
| The arithmetic: `Fr`, the `Fq` tower, G1 and G2, the pairing, MSM, multilinear polynomials, the sumcheck | [Primitives](https://apogee.gweb3networks.com/docs/auditors/spec/primitives) |
| Fiat–Shamir: Poseidon2, the duplex sponge, every tag | [Transcript](https://apogee.gweb3networks.com/docs/auditors/spec/transcript) |
| The setup and the commitment scheme | [Structured reference string](https://apogee.gweb3networks.com/docs/auditors/spec/srs), [Mercury](https://apogee.gweb3networks.com/docs/auditors/spec/mercury) |
| The program: loading, decoding, tables, configuration, identity | [Program and identity](https://apogee.gweb3networks.com/docs/auditors/spec/program), [Guest ABI](https://apogee.gweb3networks.com/docs/auditors/spec/ecall-abi) |
| The execution model and the trace | [Execution trace](https://apogee.gweb3networks.com/docs/auditors/spec/execution-trace), [Public values and advice](https://apogee.gweb3networks.com/docs/auditors/spec/public-values) |
| The proof system: GKR, the circuit registry, the memory argument, lookups | [GKR engine](https://apogee.gweb3networks.com/docs/auditors/spec/gkr), [Circuits](https://apogee.gweb3networks.com/docs/auditors/spec/circuits), [Memory argument](https://apogee.gweb3networks.com/docs/auditors/spec/memory), [Lookups](https://apogee.gweb3networks.com/docs/auditors/spec/lookup) |
| Every circuit family, column by column | the seven instruction families and the six delegation circuits |
| The prover's structure | [Streaming prover](https://apogee.gweb3networks.com/docs/auditors/spec/streaming) |
| Recursion, the Groth16 decider and its ceremony, the contract | [Recursion and decider](https://apogee.gweb3networks.com/docs/auditors/spec/recursion) |
| The Ethereum workload | [Ethereum blocks](https://apogee.gweb3networks.com/docs/auditors/spec/ethereum) |

The specification pages are reproduced from the Apogee VM repository's `docs/` at source revision `3571370`, with relative links turned into links on this site and every `§` reference made a link to its section. One phrase in the glossary is reworded to match the rest of this site; nothing else is changed. **Where a specification page and the code disagree, the code is right**, and the disagreement is a finding.

## How the specification reads

The pages are written to be read against the code. Each names the crate and the function that implements what it states, and source comments cite the specification back by section (`docs/spec/memory.md` §2.4). Some conventions that recur:

| Notation | Meaning |
| --- | --- |
| `M[i]`, `W[i]`, `S[i]` | committed columns of a circuit: memory columns (bound in the global transcript, before the memory challenges), witness columns (bound in the shard's own transcript), setup columns (bound by the program identity or the SRS digest) |
| `V[…]` | a virtual table: a closed form of the row index, never committed |
| `L{k}[j]`, `C{k}[j]`, `scratch[i]` | inner column `j` of layer `k`; a cached entry; a flat relation's intermediate |
| `W[8..14]` | a half-open range of column indices, `W[8]` to `W[13]` |
| `T(AS, ADDR, TS, VAL)` | a memory tuple, `γ_M + AS + α_addr·ADDR + α_ts·TS + α_val·VAL` |
| `4c + Δ` | the timestamp of slot `Δ` of cycle `c` |
| G1–G11, S1–S6 | the steps of the global and the shard transcript |
| steps 1–12, B1–B6 | the verifier's checks, in order, for a shard and a block |
| `2^n` | a power of two; heights are `2^8, 2^12, 2^16, 2^18, 2^20, 2^22` |

A gate written as an expression is held to 0. A lookup is written as its channel, selector and tuple. "Bounded" means range-checked, and a value called a **word** is an integer in `[0, 2^32)`.

## Reading order

For a first pass that builds the whole argument before descending into circuits:

1. **[System, end to end](https://apogee.gweb3networks.com/docs/auditors/spec/architecture).** The claim, the composition table, the assumptions, the limits.
2. **[The proof](https://apogee.gweb3networks.com/docs/auditors/spec/proof).** The statement, both transcripts, the verification order, the key and its loading rules.
3. **[GKR engine](https://apogee.gweb3networks.com/docs/auditors/spec/gkr).** The layer model, the artifact and its laws, the backward pass and why it is sound.
4. **[Memory argument](https://apogee.gweb3networks.com/docs/auditors/spec/memory)** and **[Lookups](https://apogee.gweb3networks.com/docs/auditors/spec/lookup).** The two arguments everything crossing a row rests on, with their construction-time rules.
5. **[Circuits](https://apogee.gweb3networks.com/docs/auditors/spec/circuits).** The registry, the shapes, and how a family circuit is assembled.
6. **The instruction families**, starting with **[`ADD_SUB_LUI_AUIPC`](https://apogee.gweb3networks.com/docs/auditors/spec/add-sub)**, which carries every `ecall` and the request side of every delegation.
7. **[Delegation ABI](https://apogee.gweb3networks.com/docs/auditors/spec/delegation)** and **[Delegation circuits](https://apogee.gweb3networks.com/docs/auditors/spec/delegation-circuits).**
8. **[Program and identity](https://apogee.gweb3networks.com/docs/auditors/spec/program)**, **[Public values](https://apogee.gweb3networks.com/docs/auditors/spec/public-values)**, **[Execution trace](https://apogee.gweb3networks.com/docs/auditors/spec/execution-trace)**.
9. **[Transcript](https://apogee.gweb3networks.com/docs/auditors/spec/transcript)**, **[SRS](https://apogee.gweb3networks.com/docs/auditors/spec/srs)**, **[Mercury](https://apogee.gweb3networks.com/docs/auditors/spec/mercury)**, **[Primitives](https://apogee.gweb3networks.com/docs/auditors/spec/primitives).**
10. **[Recursion and decider](https://apogee.gweb3networks.com/docs/auditors/spec/recursion)**, then the contract.

## The trust boundary

Soundness is the verifier's alone, and the verifier's code is a defined set of crates:

| Trusted for | Crates |
| --- | --- |
| Verifying a block | `constants`, `field`, `curve`, `transcript`, `poly`, `sumcheck`, `pcs-verify`, `pcs`, `gkr-verify`, `verifier-core`, `verifier`, and `constraints`, because the circuits are part of the statement and a missing gate is a soundness bug |
| Computing an identity from an ELF | `loader`, `isa`, `program` |
| The last step to the chain | `guests/recursion`, `groth16`, the decider's circuit, `contracts/ApogeeVerifier.sol` |
| Untrusted | `prover`, `emulator`, `trace`, the proving half of `host`: the prover validates nothing |

The assumptions are knowledge soundness of Mercury and KZG in the algebraic group model under q-DLOG, Poseidon2 as a random oracle, Groth16's own assumptions for the last step, and one honest contributor to each ceremony. Nothing is constant-time and no proof is zero-knowledge. A verifier must obtain the program identity and the ceremony's SRS digest from a channel the prover does not control.

## Where to look first

These are the properties whose failure would be a forgery, with where each is argued. The [soundness map](https://apogee.gweb3networks.com/docs/auditors/soundness-map) carries every claim of the statement the same way.

| Property | Argued in |
| --- | --- |
| Every challenge is drawn after everything it protects: the memory challenges after every `M` commitment, the window list, `io_digest` and the 64 boundary scalars; `g` and `β` after the shard's `W` commitments | [proof §2](https://apogee.gweb3networks.com/docs/auditors/spec/proof#s2), [§4](https://apogee.gweb3networks.com/docs/auditors/spec/proof#s4); [memory §6.1](https://apogee.gweb3networks.com/docs/auditors/spec/memory#s6-1) |
| No memory tuple or root reads a `W` column, which is committed after the memory challenges | [memory §8](https://apogee.gweb3networks.com/docs/auditors/spec/memory#s8) |
| A frame holds its masks only to booleanity; each family pins every mask to `m_pc` times the kinds that make the query | [memory §2.1](https://apogee.gweb3networks.com/docs/auditors/spec/memory#s2-1); each family page |
| Every key a table channel looks up is bounded by its family, and every bound written through a copower also carries a direct bound | [lookup §4](https://apogee.gweb3networks.com/docs/auditors/spec/lookup#s4), [§11](https://apogee.gweb3networks.com/docs/auditors/spec/lookup#s11); [shift-bitwise §3](https://apogee.gweb3networks.com/docs/auditors/spec/shift-bitwise#s3) |
| A selector decoded from a frame word is one-hot, since codes add | [delegation circuits §1](https://apogee.gweb3networks.com/docs/auditors/spec/delegation-circuits#s1) |
| Each delegation request pairs with exactly one invocation | [delegation §5](https://apogee.gweb3networks.com/docs/auditors/spec/delegation#s5) |
| Only the exit row can write `HALT_PC`; `next_pc` is held even where a family computes it | [memory §5](https://apogee.gweb3networks.com/docs/auditors/spec/memory#s5); [jump-branch-slt §5](https://apogee.gweb3networks.com/docs/auditors/spec/jump-branch-slt#s5) |
| One initial value per address: the window rules | [memory §3.5](https://apogee.gweb3networks.com/docs/auditors/spec/memory#s3-5), [§9](https://apogee.gweb3networks.com/docs/auditors/spec/memory#s9) |
| The input and journal windows hold the statement's bytes; the journal has no initial column | [public values §5](https://apogee.gweb3networks.com/docs/auditors/spec/public-values#s5) |
| The opening takes setup commitments from the key, binding the tables and image the identity commits | [proof §5](https://apogee.gweb3networks.com/docs/auditors/spec/proof#s5); [memory §6.2](https://apogee.gweb3networks.com/docs/auditors/spec/memory#s6-2) |
| A key's circuits are the registry's, and its SRS digest is compared with the ceremony's | [proof §3](https://apogee.gweb3networks.com/docs/auditors/spec/proof#s3), [§7](https://apogee.gweb3networks.com/docs/auditors/spec/proof#s7) |
| Recursion: tapes bound by program identity, the transcript chain, fold weights drawn after what they weight, the decider's bound wires, and the order of the ceremony's rounds | [recursion §7](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s7), [§8](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s8), [§9](https://apogee.gweb3networks.com/docs/auditors/spec/recursion#s9) |

## Reproducing

Everything CI runs needs no ceremony file. The suites that prove real shards run over a toy SRS of their own and need tens of GiB, so they are run by name:

```sh
cargo test --workspace                                   # every unit, law and row suite
cargo run -p kat-gen && git diff --exit-code             # fixtures regenerate identically
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 checker --test tamper -- --include-ignored --test-threads=1   # every tamper twin
cargo run -p checker -- laws <artifact>                  # Laws 1–4 and the lookup rules, independently
```

[Verifying the implementation](https://apogee.gweb3networks.com/docs/auditors/implementation-checks) describes what each oracle and suite establishes, and what none of them does.

## Reporting

Report findings to [admin@gweb3networks.com](mailto:admin@gweb3networks.com), with the specification section or the code path, the property at stake, and where possible a tamper twin: a forged witness, proved as an honest prover would prove it, that verifies.