# Apogee VM documentation (v1.0.0)

> Apogee VM is a RISC-V zkVM. It proves that an RV32IMAC program, named by a digest of its image, ran on a given public input to an exit status and wrote a given public output, and it carries that proof through a recursion tree to one Groth16 proof an Ethereum contract checks. Proofs are succinct, not zero-knowledge.

Arithmetization: 23 circuit families over BN254's scalar field, each a layered GKR circuit; gates checked by sumcheck, memory by one read/write multiset over the whole execution, lookups by LogUp. Commitments: Mercury, a multilinear scheme over KZG with a constant-size (704-byte) opening, on the PSE perpetual powers-of-tau ceremony. Fiat-Shamir: a Poseidon2 duplex transcript. Guests are no_std Rust built for riscv32imac-unknown-none-elf against the guest-sdk crate. The English pages are canonical; the specification pages are normative.

## The First Step

- [The First Step](https://apogee.gweb3networks.com/docs/md/index.md): Apogee VM proves that a program ran correctly and settles that proof on Ethereum. Every application can be blockchain-native; this is where it starts.
- [Blockchain Native](https://apogee.gweb3networks.com/docs/md/blockchain-native.md): A blockchain-native application is built from the same components as the one you build today, with one swap at each layer. Here is every swap, and a ledger built both ways.
- [Apogee at a Glance](https://apogee.gweb3networks.com/docs/md/at-a-glance.md): The facts on one page. What Apogee VM proves, how it proves it, what that costs, what it assumes, and where version 1.0.0 stops.

## Launch Your App

- [Launch Your App](https://apogee.gweb3networks.com/docs/md/launch.md): The builder's manual for Apogee VM. How a guest program is written, built, run, proved and settled on-chain, and the habits that keep it correct, provable and cheap.
- [Quickstart](https://apogee.gweb3networks.com/docs/md/launch/quickstart.md): From an empty crate to a verified proof. A three-line guest, built, run, inspected and proved, with the real output of every step.
- [Set Up](https://apogee.gweb3networks.com/docs/md/launch/setup.md): The toolchain the repository pins, the two workspaces it holds, the ceremony file proving needs, and the machine each step asks for.
- [Write a Guest](https://apogee.gweb3networks.com/docs/md/launch/write.md): A guest is a no_std Rust binary with an entry point and three memory regions. Crate layout, the runtime underneath you, dependencies, and the host-first layout that lets you test it like any other Rust.
- [Inputs, Advice and the Journal](https://apogee.gweb3networks.com/docs/md/launch/io.md): A guest has no I/O system calls. Its public input, the prover's advice and its journal are three regions of memory. What each holds, what the proof binds, and the pattern every guest that takes data follows.
- [Delegations](https://apogee.gweb3networks.com/docs/md/launch/delegations.md): Hashing, field and curve arithmetic have dedicated circuits. Which SDK calls reach them, what they cost, the rules on their operands, and the vendored crates that route library code to them.
- [Build and Inspect](https://apogee.gweb3networks.com/docs/md/launch/build.md): Build profiles pinned to one semantics, the ELF a build produces, the ProgramImage the loader makes of it, its report, and the program identity a verifier registers.
- [Run and Profile](https://apogee.gweb3networks.com/docs/md/launch/run.md): Run a guest in Apogee's emulator from Rust or from the command line, compare it with your host build, and find out where its cycles go before you pay to prove them.
- [Prove and Verify](https://apogee.gweb3networks.com/docs/md/launch/prove.md): Register a program, prove a run, verify the block, and keep the proof. Heights, shards in flight, the ceremony powers a proof needs, and the two values a verifier must hold for itself.
- [Settle On-Chain](https://apogee.gweb3networks.com/docs/md/launch/on-chain.md): From a base proof of hundreds of shards to one Groth16 proof that an Ethereum contract checks. The recursion tree, the decider's ceremony, the contract's interface, and what one deployment fixes.
- [Guest Programming Guide](https://apogee.gweb3networks.com/docs/md/launch/guide.md): The habits that keep a guest correct, provable and cheap. Every gotcha and preference in one place, each with the reason behind it and what to do instead.
- [Troubleshooting](https://apogee.gweb3networks.com/docs/md/launch/troubleshooting.md): Every way a guest stops short of a verified proof, by symptom. Exit statuses, fatal executor errors, refused ELFs, refused programs, failed proofs and verifier errors, with the cause and the fix.
- [Example Guests](https://apogee.gweb3networks.com/docs/md/launch/examples.md): The guests in the repository, each a worked example of one part of the guest SDK or the machine. Where to look for the pattern you need.
- [Guest SDK Reference](https://apogee.gweb3networks.com/docs/md/launch/sdk.md): Every public item of the guest-sdk crate, with its exact signature and behaviour. Only exit and the delegation shims issue an ecall; everything else is loads and stores.
- [AI Companion](https://apogee.gweb3networks.com/docs/md/launch/ai-companion.md): One file that briefs an AI model on writing Apogee guest programs. Download it, put it in front of your model, and it starts from the same rules this manual teaches.

## Architecture

- [Architecture](https://apogee.gweb3networks.com/docs/md/architecture.md): 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.
- [Programs and Identity](https://apogee.gweb3networks.com/docs/md/architecture/program.md): How a guest ELF becomes a static, verifier-known description of a program, and why one field element of identity is enough to tell a verifier which program a proof is about.
- [Execution, Families and Shards](https://apogee.gweb3networks.com/docs/md/architecture/execution.md): One hart, a 38-bit clock, every memory access as a timestamped query, 23 circuit families, and the shard as the unit of proving.
- [The GKR Engine](https://apogee.gweb3networks.com/docs/md/architecture/gkr.md): The proving engine at the centre of Apogee. Why a layered GKR circuit commits only its inputs, how one backward pass of sumchecks funnels a whole circuit to a single point, and what that buys.
- [Commitments](https://apogee.gweb3networks.com/docs/md/architecture/mercury.md): Every committed column is opened with Mercury, a multilinear commitment over KZG with a constant-size opening. What it costs, how a shard batches all its columns into one opening, and how recursion defers the pairing.
- [Memory and Lookups](https://apogee.gweb3networks.com/docs/md/architecture/memory-lookups.md): Two arguments carry everything that crosses a row. One read/write multiset over the whole execution, reconciled once, makes every read return the last write and orders every row; LogUp channels make every value a byte, a word or a table row.
- [Delegations](https://apogee.gweb3networks.com/docs/md/architecture/delegations.md): How an expensive function gets a circuit of its own without growing the instruction circuits. The call, the anchor that pairs each request with exactly one invocation, the six circuits, and their economics.
- [The Streaming Prover](https://apogee.gweb3networks.com/docs/md/architecture/streaming.md): The prover executes the guest twice and never holds the execution trace. Memory follows the shards being worked, not the length of the run, and the proof does not depend on the schedule.
- [Recursion and Settlement](https://apogee.gweb3networks.com/docs/md/architecture/recursion.md): How a base proof of hundreds of shards becomes one Groth16 proof that a contract checks. Apogee proving its own verifier, the tapes that make that cheap, the transcript chained across a tree, and pairings folded until only one is left.
- [Ethereum Blocks](https://apogee.gweb3networks.com/docs/md/architecture/ethereum.md): Apogee's reference workload. A revm guest that runs Ethereum blocks inside the VM, a stateless validator that matches every case of the zkEVM test release, and what a proof of a block says.
- [Security Model](https://apogee.gweb3networks.com/docs/md/architecture/security.md): What a proof establishes, what it assumes, what a verifier must hold for itself, which code soundness rests on, and the limits of version 1.0.0.
- [Performance](https://apogee.gweb3networks.com/docs/md/architecture/performance.md): Every measured figure for v1.0.0 with its source: the base proof of a full Ethereum block, the recursion tree, the decider and the contract, each family's shard proof, and Mercury's own costs.

## Quantum Leap

- [Quantum Leap](https://apogee.gweb3networks.com/docs/md/quantum-leap.md): Where Apogee goes next. The trajectory toward v2.0.0 — a proving core on lattices, a field chosen to match them, signatures guests can verify, and a deployment system that carries an application from repository to running chain.
- [Post-Quantum Proving](https://apogee.gweb3networks.com/docs/md/quantum-leap/post-quantum.md): Initiatives QL-01 and QL-02. A lattice commitment in place of the pairing-based one, and a field chosen to match it, so that the proving core no longer rests on discrete logarithms.
- [Signatures for Guests](https://apogee.gweb3networks.com/docs/md/quantum-leap/signatures.md): Initiative QL-03. Zk-friendly and post-quantum signature verification available to every guest as a call, so authorization inside a blockchain-native application is one line of code.
- [The Deployment System](https://apogee.gweb3networks.com/docs/md/quantum-leap/deployment-system.md): Initiative QL-04. The Apogee Blockchain-Native Deployment System, a portal and toolchain that take an application from source to a running blockchain-native environment.

## Auditors

- [Audit Guide](https://apogee.gweb3networks.com/docs/md/auditors.md): 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.
- [Soundness Map](https://apogee.gweb3networks.com/docs/md/auditors/soundness-map.md): Every claim a verified proof makes, the argument that carries it, and the exact specification sections where that argument is stated and justified.
- [Verifying the Implementation](https://apogee.gweb3networks.com/docs/md/auditors/implementation-checks.md): How the code is checked against something other than itself. Each layer's independent oracle, the second implementation of the circuit rules, the tamper twins that prove forgeries are refused, and what no check covers.
- [The system, end to end](https://apogee.gweb3networks.com/docs/md/auditors/spec/architecture.md): What a proof states, how one is made and checked, how soundness composes, what it assumes, its limits, and how the code is checked.
- [Primitives: fields, curve, pairing, polynomials, sumcheck](https://apogee.gweb3networks.com/docs/md/auditors/spec/primitives.md): BN254's scalar and base fields, G1 and G2 and their encodings, the optimal ate pairing, MSM, multilinear polynomials and the zerocheck.
- [The transcript](https://apogee.gweb3networks.com/docs/md/auditors/spec/transcript.md): The Poseidon2 permutation, the duplex sponge, typed messages, a G1 point's transcript form, and every tag.
- [The structured reference string](https://apogee.gweb3networks.com/docs/md/auditors/spec/srs.md): The powers-of-tau ceremony every commitment rests on: how its file is read, what is validated and what is presumed, KZG, and Groth16's phase 1.
- [Mercury](https://apogee.gweb3networks.com/docs/md/auditors/spec/mercury.md): The commitment every column is opened with: parameters, the opening protocol, the BDFG20 batch, k-column batching and the deferred accumulator recursion folds.
- [The program: from ELF to identity](https://apogee.gweb3networks.com/docs/md/auditors/spec/program.md): How a guest ELF becomes a ProgramImage, decoded tables, a VmConfig and one field element of program identity.
- [The guest ABI](https://apogee.gweb3networks.com/docs/md/auditors/spec/ecall-abi.md): The ecall convention, every syscall number, the guest address space and the guest SDK surface.
- [The execution trace](https://apogee.gweb3networks.com/docs/md/auditors/spec/execution-trace.md): The clock, the address spaces, a memory query, each instruction class's frame, the emulator and the trace containers.
- [Public values and advice](https://apogee.gweb3networks.com/docs/md/auditors/spec/public-values.md): How the public input and the journal are bound to a proof, and why the prover's advice is bound to nothing.
- [The GKR engine](https://apogee.gweb3networks.com/docs/md/auditors/spec/gkr.md): The layered-circuit model, the circuit artifact and its laws, and the backward pass that reduces a circuit's outputs to claims on its committed columns.
- [Circuits](https://apogee.gweb3networks.com/docs/md/auditors/spec/circuits.md): The registry with every family's shape, how a family circuit is assembled, and how the checker validates one independently.
- [The memory argument](https://apogee.gweb3networks.com/docs/md/auditors/spec/memory.md): Offline memory checking over a whole statement: the tuple, each family's memory subtree, RAM windows, the register and pc boundary, halting and binding.
- [Lookups](https://apogee.gweb3networks.com/docs/md/auditors/spec/lookup.md): One LogUp channel per table: gated keys, the denominator, fraction trees, multiplicities, the generic table and the decoder channel.
- [The proof](https://apogee.gweb3networks.com/docs/md/auditors/spec/proof.md): What a verifier checks and the formats it reads: the statement, the global and shard transcripts, the opening, verification order, the verifying key and the wire forms.
- [The ADD_SUB_LUI_AUIPC family](https://apogee.gweb3networks.com/docs/md/auditors/spec/add-sub.md): Family 0: add, sub, addi, lui, auipc, fence, and every ecall, which makes it the exit and the request side of each delegation.
- [The JUMP_BRANCH_SLT family](https://apogee.gweb3networks.com/docs/md/auditors/spec/jump-branch-slt.md): Family 1: comparisons, branches and jumps, and the is-zero and comparison gadgets other families reuse.
- [The SHIFT_BITWISE family](https://apogee.gweb3networks.com/docs/md/auditors/spec/shift-bitwise.md): Family 2: a shift either way as one product with a looked-up power of two; AND as four byte lookups, OR and XOR as linear forms over it.
- [The MUL_DIV family](https://apogee.gweb3networks.com/docs/md/auditors/spec/mul-div.md): Family 3: the M extension as one product identity, a sign rule and a range-checked gap for truncated division, and one pin for a zero divisor.
- [The memory-op families](https://apogee.gweb3networks.com/docs/md/auditors/spec/memory-ops.md): Families 4 to 6: word, sub-word and atomic memory operations, their shared addressing, the splice, and the write-side induction.
- [Delegation](https://apogee.gweb3networks.com/docs/md/auditors/spec/delegation.md): The calling convention, the registry, the frame, the anchor that pairs each request with exactly one invocation, static declaration and heights.
- [The delegation circuits](https://apogee.gweb3networks.com/docs/md/auditors/spec/delegation-circuits.md): The six base delegation circuits, KECCAK_F, POSEIDON2, FR_ARITH, MOD_MUL, SHA256_COMP and EC_ADD, frame by frame and column by column.
- [The streaming prover](https://apogee.gweb3networks.com/docs/md/auditors/spec/streaming.md): The two-pass streaming prover: what survives an execution, the shard plan, the pipeline, and the retained archived path.
- [Recursion](https://apogee.gweb3networks.com/docs/md/auditors/spec/recursion.md): From one base block proof to one Groth16 proof a contract checks: the recursion format, field memory, tapes, nodes and folding, the decider.
- [Ethereum blocks](https://apogee.gweb3networks.com/docs/md/auditors/spec/ethereum.md): The revm guest: the mini-block witness and output commitment, and the stateless validator with its forks, rules and conformance.

## Reference

- [Glossary](https://apogee.gweb3networks.com/docs/md/reference/glossary.md): The project's own vocabulary, one line a term, each linked to the section that defines it.
- [Tools](https://apogee.gweb3networks.com/docs/md/reference/tools.md): The binaries around the prover and verifier: bench, the cycle profiler, the debug log, checker, artifact-dump, the verifier CLI, kat-gen and the reference oracles.
- [Repository Map](https://apogee.gweb3networks.com/docs/md/reference/repository.md): Where everything lives in the Apogee VM repository, what each crate is, and the page of the specification that defines it.
- [Release Notes](https://apogee.gweb3networks.com/docs/md/reference/release-notes.md): Apogee VM v1.0.0, the first release. What it proves, what it ships, how it was measured and checked, and its known limits.

## Optional

- [Everything above in one file](https://apogee.gweb3networks.com/docs/llms-full.txt): every page as Markdown, specification included
- [AI Companion for guest programs](https://apogee.gweb3networks.com/docs/apogee-ai-companion.md): a front-loadable briefing for a model that writes Apogee guests