# Architecture

> Apogee VM end to end. What a proof states, the path from a guest binary to a contract call, how the large components fit together, and the design decisions that shape them.

Apogee proves executions of RV32IMAC programs. This section describes the system at the level of its large components: what each one does, why it is built the way it is, and how it hands off to the next. The [Auditors](https://apogee.gweb3networks.com/docs/auditors) section holds the same system at the level of every column and gate.

## What a proof states

A verifier holds three things it does not take from the prover's word:

- the **program identity**, one field element digesting the program's instruction tables, its initial memory image, its entry pc and its configuration;
- the **SRS digest** of the ceremony a verifying key must carry;
- a **verifying key**, which may come from anyone, because loading it recomputes the identity and the SRS digest from its own contents and holds its circuits to the verifier's registry.

The proof's statement carries the public input, the public output (the **journal**), the exit status, and the record of the execution's shape: shard counts, memory windows, the final registers and pc, and every shard's memory commitments and roots. A proof that verifies establishes that the program of that identity, started at its entry pc over its image, with the public input in its input window and some advice of the prover's choosing, executes instruction by instruction to `EXIT` with that status, having written that journal. Nothing is claimed of the advice, and nothing is hidden: no commitment or proof is blinded.

## From a binary to a contract call

> Figure: The four stages. The program is fixed before anything runs; the execution is cut into shards; each shard is proved on its own except for the memory argument, which closes once over all of them; settlement compresses the block for a contract.

1. **The program.** The loader reads the ELF into a `ProgramImage`, expanding compressed instructions in place. The decoder routes each instruction to one of seven instruction families and builds every family's decoded table, a row per halfword of code, then commits to all of it as the program identity. [Programs and identity](https://apogee.gweb3networks.com/docs/architecture/program).
2. **Execution.** The emulator runs the guest on one hart. A cycle is one row of the family that owns its instruction, recording timestamped reads and writes of the pc, the registers and RAM. Hashing and big-integer arithmetic are delegated: an `ecall` names a frame in RAM, and a row of a delegation family does the work on it. [Execution, families and shards](https://apogee.gweb3networks.com/docs/architecture/execution).
3. **Shards.** A family's rows are cut into shards of the family's height, a power of two between `2^8` and `2^22`. The memory an execution touches is covered by shards of the window families, which give each word its initial and final values. A shard is the unit of proving; a block is hundreds.
4. **A shard's proof.** Its columns are committed with [Mercury](https://apogee.gweb3networks.com/docs/architecture/mercury). The family's circuit is run backward by the [GKR engine](https://apogee.gweb3networks.com/docs/architecture/gkr) from its outputs to those columns, a sumcheck per layer, and every column is opened at the one point that pass ends on, in one batched opening.
5. **The block.** A `BlockProof` is the statement and its shard proofs. Verification runs the global transcript once, each shard's checks, and once the [memory reconciliation](https://apogee.gweb3networks.com/docs/architecture/memory-lookups) over every shard's roots.
6. **Recursion and settlement.** Verifier programs, proved by Apogee itself, verify runs of shards and fold their deferred pairings. A tree of them ends in a root, a Groth16 circuit re-verifies the root, and `ApogeeVerifier.sol` checks that proof and the folded pairing. [Recursion and settlement](https://apogee.gweb3networks.com/docs/architecture/recursion).

The prover executes the guest twice: once to commit every shard's memory columns, which fixes the statement and its challenges, and once to prove each shard as it fills. Its memory is bounded by the shards in flight, not by the length of the execution. [The streaming prover](https://apogee.gweb3networks.com/docs/architecture/streaming).

## The decisions that shape it

**One field, one curve.** Everything is over BN254's scalar field: the circuits, the transcript, the commitments and the recursion. That is what lets a node of the recursion tree verify base shards in its own arithmetic, and what lets the tree end in a Groth16 proof Ethereum checks with its pairing precompile.

**Layered GKR circuits instead of committed constraint tables.** A family's circuit is a stack of degree-2 gate layers above its committed columns. Only the bottom layer is committed; every layer above it is proved by sumcheck in a single backward pass and never committed. The pass ends with every committed column claimed at one point, so a shard needs exactly one opening. [The GKR engine](https://apogee.gweb3networks.com/docs/architecture/gkr) explains why this is the engine's central economy.

**A constant-size opening.** Mercury opens a multilinear commitment with eight curve points and six field elements, 704 bytes, whatever the polynomial's size and however many columns share the point. Its checks have the shape `e(A, [1]_2) = e(B, [x]_2)`, which recursion can fold instead of pairing.

**One memory argument for the whole execution.** Every access, in every shard of every family, is a tuple in one read/write multiset, and the verifier reconciles the products once per statement. The pc is a cell of that multiset, so ordering, continuity and cycle uniqueness across shards need no other argument and no shard needs to chain to its neighbour.

**Delegations as families, not instructions.** An expensive function gets its own circuit family, invoked by an `ecall` over a frame of RAM and paired one to one with its request through the same multiset. The instruction circuits stay small, and a guest pays for a delegation only if it calls it.

**Streaming instead of materializing.** The trace at about 300 bytes a cycle would be the largest object in the system, so it never exists. The prover executes twice and holds only the shards being worked.

**No borrowed cryptography.** Fields, curve, pairing, MSM, hash, polynomial commitment, GKR and Groth16 are implemented in the repository and specified page by page. arkworks, Plonky3 and zkhash appear only as test oracles.

## How soundness composes

Each shard's GKR pass and opening tie its circuit's outputs to committed columns. On top of that, these arguments span the execution:

| Claim | Carried by |
| --- | --- |
| Every row obeys its instruction | the family circuit's enforcing gates, zero on every row |
| A row's instruction is the program's at its pc | a lookup of the row's pc and fields in the family's decoded table, which the identity commits |
| Every read returns the last write | one multiset over all shards; the verifier multiplies every shard's read and write roots against boundary factors for the registers and the pc |
| The rows are one path from the entry pc to the exit, in program order | the pc is a cell of that multiset, written at least four timestamps after it is read |
| A value is a byte, a word, a sign, an XOR | LogUp channels over range, byte and generic tables |
| The public input and the journal are the claimed bytes | the two public windows' initial and final columns, held to the bytes' multilinear extensions |
| A delegated computation is the function's | invocation rows that read and write the frame through the same multiset, paired one to one with their `ecall` |

Challenges come from a Poseidon2 duplex transcript. The global transcript absorbs the whole statement, every shard's memory commitments included, before the memory challenges exist; each shard's transcript is seeded from its final state. The [soundness map](https://apogee.gweb3networks.com/docs/auditors/soundness-map) carries each row down to the sections that prove it.

## The code, by layer

| Layer | Crates | Role |
| --- | --- | --- |
| Arithmetic | `field`, `curve`, `poly`, `sumcheck` | `Fr`; the `Fq` tower, G1, G2, the pairing, MSM; multilinear polynomials; the zerocheck |
| Fiat–Shamir and setup | `transcript`, `srs` | Poseidon2 and the duplex transcript; ceremony ingestion, KZG, Groth16's phase 1 |
| Commitments | `pcs`, `pcs-verify` | Mercury and its deferred verification |
| The program | `loader`, `isa`, `program` | ELF to image, the decoder, decoded tables, `VmConfig` and identity |
| Execution | `emulator`, `trace` | the executor and its tracers; rows, memory state, column builders |
| Circuits | `constraints`, `gkr-verify`, `gkr` | every circuit as data; the GKR verifier and prover |
| Proof and verification | `verifier-core`, `verifier`, `prover` | statement, transcripts, keys, every check; the streaming prover |
| Settlement | `host`, `groth16`, `contracts/` | the host SDK, the recursion tree and decider; `ApogeeVerifier.sol` |
| Assurance | `checker`, `tools/` | independent validators, the tamper suite, benchmarks, profilers, oracles |

The verifier is the only trusted party: the prover validates nothing, and a wrong input costs an honest prover a proof that fails. [The security model](https://apogee.gweb3networks.com/docs/architecture/security) lists exactly which crates soundness rests on.