A blockchain-native application is economic activity whose settlement, custody and rules are on-chain by construction, rather than a conventional business with a token attached to the side of it. That sounds like a different kind of engineering. It is less different than it sounds.

Every component of the stack you build today has a counterpart. The counterpart does the same job with one change: what used to be trusted is now proved. Apogee exists to make that change cheap enough to be the default.

The shift in one sentence#

In a conventional application the server is the authority: it holds the data, applies the rules and reports the result. In a blockchain-native application the chain holds a commitment to the data, the rules are a program anyone can name by its digest, and a result is accepted only with a proof that this program produced it.

The operator does not disappear. Someone still runs the program, stores the data and answers requests. What disappears is the need to believe them.

Layer by layer#

The middle column is what a blockchain-native application is made of. Apogee supplies the machinery underneath it: the RISC-V machine, the circuits, the commitments, the recursion and the verifier contract. None of that appears in your program.

What does not change#

• You still write ordinary Rust. Structs, enums, traits, iterators, Vec, BTreeMap, and any crate that builds without std. There is no circuit language to learn.
• You still test on your laptop. The usual layout puts the application logic in a no_std library that runs on the host, under cargo test, exactly as it runs in the guest. See Writing a guest.
• You still reason about state, requests and responses. The shapes are the same; only their guarantees change.
• Deterministic code stays deterministic. Good backend code already avoids hidden inputs. The VM makes that absolute.

What does change#

• No ambient world. A guest has no clock, no randomness, no network and no files. Everything it knows arrives as public input or as advice, and a request for host data is a call no proof admits.
• Every instruction has a price. Each executed instruction becomes a proved row. Copies, allocations and dead loops cost proving time, so the old discipline of counting cycles comes back.
• Supplied data is checked, not trusted. Advice is chosen by the prover. A guest checks it against something the proof binds before anything derived from it is published.
• Outputs are small and public. The journal holds at most 16,380 bytes. A large result is published as a digest.
• Nothing is hidden. Apogee v1.0.0 proofs are succinct, not zero-knowledge. A guest must not hold secrets.

A ledger, built both ways#

A deposit into an account balance: the smallest state change worth proving.

The conventional version#

BEGIN;
SELECT balance FROM accounts WHERE id = $1 FOR UPDATE;    -- read
UPDATE accounts SET balance = balance + $2 WHERE id = $1;  -- write
COMMIT;                                                     -- make it durable

Users trust the operator to have run exactly this, against the real table, and to report the result honestly.

The blockchain-native version#

The accounts live in a binary Merkle tree whose leaves are keccak256(account ‖ balance). A contract stores the root. The guest receives the old root and the request as public input, receives the account's balance and Merkle path as advice, checks the path, and publishes the old and new roots.

#![no_std]
#![no_main]

guest_sdk::entry!(main);

const DEPTH: usize = 20; // room for 2^20 accounts

/// A leaf commits to one account's balance.
fn leaf(account: &[u8; 20], balance: u64) -> [u8; 32] {
    let mut bytes = [0u8; 28];
    bytes[..20].copy_from_slice(account);
    bytes[20..].copy_from_slice(&balance.to_le_bytes());
    guest_sdk::keccak256(&bytes)
}

/// Fold a leaf up its Merkle path; bit `level` of `index` says whether the
/// node is a right child at that level.
fn root_of(mut node: [u8; 32], index: u32, path: &[[u8; 32]; DEPTH]) -> [u8; 32] {
    let mut pair = [0u8; 64];
    for (level, sibling) in path.iter().enumerate() {
        let (left, right) = if (index >> level) & 1 == 0 { (&node, sibling) } else { (sibling, &node) };
        pair[..32].copy_from_slice(left);
        pair[32..].copy_from_slice(right);
        node = guest_sdk::keccak256(&pair);
    }
    node
}

/// Public input: old_root (32) ‖ account (20) ‖ amount (8, LE)
/// Advice:       balance (8, LE) ‖ index (4, LE) ‖ path (DEPTH × 32)
/// Journal:      old_root ‖ new_root ‖ account ‖ amount
fn main() {
    let input = guest_sdk::public_input();
    let advice = guest_sdk::advice();
    if input.len() != 60 || advice.len() != 12 + 32 * DEPTH {
        guest_sdk::exit(1);
    }
    let old_root: [u8; 32] = input[..32].try_into().unwrap();
    let account: [u8; 20] = input[32..52].try_into().unwrap();
    let amount = u64::from_le_bytes(input[52..60].try_into().unwrap());

    let balance = u64::from_le_bytes(advice[..8].try_into().unwrap());
    let index = u32::from_le_bytes(advice[8..12].try_into().unwrap());
    let mut path = [[0u8; 32]; DEPTH];
    for (i, sibling) in path.iter_mut().enumerate() {
        sibling.copy_from_slice(&advice[12 + 32 * i..12 + 32 * (i + 1)]);
    }

    // The query: the balance the prover supplied is the one the root commits to.
    if root_of(leaf(&account, balance), index, &path) != old_root {
        guest_sdk::exit(2);
    }
    // The write: the same path with the new leaf gives the new root.
    let Some(new_balance) = balance.checked_add(amount) else { guest_sdk::exit(3) };
    let new_root = root_of(leaf(&account, new_balance), index, &path);

    // The commit: publish the transition for the contract to apply.
    guest_sdk::commit(&old_root);
    guest_sdk::commit(&new_root);
    guest_sdk::commit(&account);
    guest_sdk::commit(&amount.to_le_bytes());
}

Read it against the SQL. SELECT … FOR UPDATE became a Merkle path checked against the root. UPDATE became a new leaf on the same path. COMMIT became four calls to commit, which write the journal the proof will bind. The balance came from the prover, and that is fine: a balance the root does not commit to fails the check and the run exits 2.

The contract that owns the root accepts a transition only with a proof that this program produced it and exited 0:

interface IApogeeVerifier {
    function verify(bytes calldata input, bytes calldata output, uint256 exitStatus,
                    uint256[10] calldata proof, uint256[] calldata points) external view returns (bool);
}

contract Ledger {
    IApogeeVerifier public immutable verifier;
    bytes32 public root;

    constructor(IApogeeVerifier v, bytes32 genesis) { verifier = v; root = genesis; }

    function apply(bytes calldata input, bytes calldata journal,
                   uint256[10] calldata proof, uint256[] calldata points) external {
        require(verifier.verify(input, journal, 0, proof, points), "proof");
        require(bytes32(journal[0:32]) == root, "stale root");
        root = bytes32(journal[32:64]);
    }
}

The model in three lines#

1. The chain holds a root.
2. The guest proves the transition.
3. The contract moves the root.

Everything else, from the shards and circuits to the recursion and the decider, is Apogee's. That is the abstraction: a program, its input and its output, and a proof that ties them together.

Next#

In one paragraph#

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. It carries that proof through a recursion tree to one Groth16 proof that an Ethereum contract checks. Every circuit is a layered GKR circuit over BN254's scalar field, every committed column is opened with Mercury, and every challenge comes from a Poseidon2 transcript. The fields, curve, pairing, MSM, hash, polynomial commitment, GKR prover and Groth16 are all implemented in the repository. Its reference workload is Ethereum block validation.

The facts#

Measured#

All figures are block 257,510 of glamsterdam-devnet-8, run through the stateless validator guest: 60 transactions, 101.5 Mgas, 198M cycles. Sources: the specification's recursion §10 and streaming §1.

What a verifier must hold#

Two values, taken from a channel the prover does not control:

• The program identity, one field element. Against an identity supplied by the prover, a proof shows only that some program ran.
• The SRS digest of the ceremony. A key built over a known τ is refused only by this comparison.

The verifying key itself may come from anyone: loading it recomputes both values from its own contents and holds its circuits to the verifier's registry. The security model has the full list of assumptions.

Where v1.0.0 stops#

• Not zero-knowledge. No blinding in Mercury, GKR or the decider.
• Advice is unbound. A guest checks it against something a proof binds.
• Traps are not provable. A misaligned access, an access outside mapped memory, ebreak, or a pc with no instruction ends the run with no proof.
• sc.w always succeeds. The one deviation from RV32IMAC: there is no reservation state.
• Delegations are a fixed set of six. EVM MULMOD with an arbitrary modulus, MODEXP and BLS12-381 run as ordinary instructions.
• Proving is memory-bound. The measured block peaked at 174 GiB; memory follows the shards in flight, not the length of the run.
• The decider key is per root shape, and only as trustworthy as its ceremony. The development key is forgeable.

Who builds it#

Apogee VM is the flagship of G Web3's research program toward blockchain-native application environments: one optimized environment per economic application, each settling to Ethereum with a validity proof. The program's position is set out in the thesis; where the next version goes is Quantum Leap.

A guest is the program Apogee proves: a no_std Rust binary compiled for riscv32imac-unknown-none-elf, with an entry point, three memory regions for its inputs and outputs, and nothing else. The host is everything around it: the code that supplies the input, asks Apogee for a proof and hands that proof to whoever checks it. You write both. Apogee supplies the machine, the circuits and the verifier.

This section is written for two readers at once: an engineer at a keyboard and the model they work with. Every page states its rules plainly, and the AI Companion condenses all of them into one file you can hand to an assistant before it writes a line.

The model#

A proof says one thing: the program with this identity, started over its image with this public input and some advice of the prover's choosing, ran to EXIT with this status, having written this journal. Everything you build sits on that sentence.

The workflow#

The Quickstart walks the whole loop once with a guest of three lines.

The rules that matter most#

Each is explained, with what goes wrong and what to do instead, in the guest programming guide.

• usize and every pointer are 32 bits. Overflowing usize panics in the guest alone, x as usize truncates silently, and anything whose layout or hash depends on a length differs between host and guest.
• The allocator never frees. It bumps a pointer up from __heap_start, so what runs a guest out of memory is the total it allocates over the run, not its peak. Reuse buffers and size them with with_capacity.
• Atomics work, and you should not write them. The machine has one hart, so the A extension is there for compatibility with code that already uses it. New guest code has nothing to synchronize.
• There is no world outside. No files, no clock, no randomness, no network. A guest knows its public input, its advice, and what it computes.
• Advice is the prover's choice. Check it against something the proof binds before anything derived from it reaches the journal.
• The journal is small. 16,380 bytes at most. Publish a digest of anything that grows.
• Overflow checks stay on in release. They are part of what the program computes, so the guest profile pins them.
• Every executed instruction is a proved row. Proving cost follows cycle count, so build --release and count cycles before you optimize anything else.

Where to start#

This page walks the whole loop once with the smallest guest that does something: it reads its public input and publishes it as its journal. Every output below was produced by running these exact commands on Apogee v1.0.0.

[package]
name = "hello"
version.workspace = true
edition.workspace = true
publish.workspace = true

[dependencies]
guest-sdk.workspace = true

#![no_std]
#![no_main]

guest_sdk::entry!(main);

fn main() {
    // The public input is memory: a slice, with no ecall and no cursor.
    guest_sdk::commit(guest_sdk::public_input());
}

members = ["fib", "echo", … , "recursion", "hello"]

cd guests/hello
cargo build --release --target riscv32imac-unknown-none-elf
cd ../..

printf 'hello, apogee' > /tmp/hello.in
cargo run --release -p profiler -- elf guests/target/riscv32imac-unknown-none-elf/release/hello --input /tmp/hello.in

workload
  label                        hello
  guest                        hello
  guest cycles                 114
  exit status                  0
  journal bytes                13

cycles by family
  ADD_SUB_LUI_AUIPC            64
  JUMP_BRANCH_SLT              21
  MEM_WORD                     3
  MEM_SUBWORD                  26

cargo run --release -p artifact-dump -- tables \
    guests/target/riscv32imac-unknown-none-elf/release/hello \
    --ptau assets/ptau/ppot_0080_24.ptau

program identity  9ead85cee880df30daa8eba657316215107a075640a64ccf2424a054b758b802

VmConfig
--------
  id  family              height     live rows  columns
   0  ADD_SUB_LUI_AUIPC     4194304         33  pc next_pc rs1 rs2 rd imm extra_mask
   1  JUMP_BRANCH_SLT       4194304         12  pc next_pc rs1 rs2 rd imm extra_mask
   4  MEM_WORD              4194304          3  pc next_pc rs1 rs2 rd imm extra_mask
   5  MEM_SUBWORD           4194304          3  pc next_pc rs1 rs2 rd imm extra_mask
   7  INIT_TEARDOWN         4194304          0  none: claims no pc
   8  ZERO_WINDOWS          4194304          0  none: claims no pc
  12  PUBLIC_INPUT             4096          0  none: claims no pc
  13  PUBLIC_OUTPUT            4096          0  none: claims no pc
  14  ADVICE_WINDOWS        4194304          0  none: claims no pc

use constants::family;
use emulator::GuestIo;
use program::ProgramParams;
use srs::Srs;

fn main() {
    let elf = std::fs::read("guests/target/riscv32imac-unknown-none-elf/release/hello")
        .expect("build the guest with --release first");

    // Small heights for a small program: the seven instruction families at
    // their 2^20 floor, the three RAM-window families at 2^16. Every choice of
    // heights is its own program identity.
    let mut params = ProgramParams::defaults();
    for f in 0..7 {
        params.heights[f] = 1 << 20;
    }
    for f in [family::INIT_TEARDOWN, family::ZERO_WINDOWS, family::ADVICE_WINDOWS] {
        params.heights[f as usize] = 1 << 16;
    }

    // As many ceremony powers as the tallest family has rows: 2^20 here.
    let ptau = std::path::Path::new("assets/ptau/ppot_0080_24.ptau");
    let srs = Srs::from_ptau(ptau, 20).expect("the ceremony file reads");
    let setup = host::setup(&elf, &params, srs).expect("the program registers");

    let io = GuestIo { input: b"hello, apogee".to_vec(), advice: Vec::new() };
    let proven = host::prove(&setup, &io, 2).expect("the run proves"); // two shards in flight
    host::verify(&setup.vk, &proven.block).expect("the block verifies");

    assert_eq!(proven.exit_code, 0);
    assert_eq!(proven.journal, b"hello, apogee");
    let id: String = setup.vk.identity.to_bytes().iter().map(|b| format!("{b:02x}")).collect();
    println!("identity  {id}");
    println!("cycles    {}", proven.cycles);
    println!("shards    {}", proven.report.shards);
    println!("journal   {:?}", core::str::from_utf8(&proven.journal).unwrap());
}

cargo run --release -p host --example prove_hello

identity  606d1f1d720459cc1a078787381656b29c9fce5a9e539b36f899e62b64129c14
cycles    114
shards    7
journal   "hello, apogee"

assert_eq!(setup.vk.identity.to_bytes(), registered); // `registered` from your own channel

What just happened#

The emulator ran the 114 instructions twice. The first pass committed the memory columns of every shard and fixed the statement. The second filled each shard and proved it. There were seven shards: one for each of the four instruction families that executed, one for the memory window that holds the program's image, and one each for the public input and the journal. This guest never touched its stack, so no other window needed one; a typical program adds the stack's. Each shard was proved by its family's GKR circuit and opened with one Mercury proof, and the verifier reconciled the memory reads and writes of all seven in one equation. The architecture overview follows the same path in detail.

Next#

Apogee v1.0.0 is a Rust repository. There is nothing to install beyond rustup: the repository pins its toolchain, and the toolchain carries the guest target. Writing, building, running and profiling a guest need nothing else. Proving adds one large file and a machine with memory to match.

The toolchain#

rust-toolchain.toml at the repository root pins stable Rust 1.96.1 with rustfmt, clippy and llvm-tools, and the target riscv32imac-unknown-none-elf, whose core and alloc ship prebuilt. rustup applies it in every directory below the root and installs it on first use.

cd apogee-vm
rustup show active-toolchain     # 1.96.1, overridden by rust-toolchain.toml
cargo --version

No nightly and no unstable features are used anywhere. llvm-tools supplies the llvm-objdump and llvm-nm matching the compiler's LLVM, which the repository uses for its committed disassembly listings and which you can use to read your guest's code.

Two workspaces#

The checkout holds two Cargo workspaces, and the split matters:

Guests are kept apart because every member compiles for the guest target and links a #[panic_handler]; cargo test --workspace at the root must never reach them. The guest workspace also carries what a guest needs to be built correctly, so you never type it:

• guests/.cargo/config.toml sets the target and passes the linker -T crates/guest-sdk/link.ld, the memory map, and --no-relax, because relaxation would move addresses that the program identity binds.
• guests/Cargo.toml pins both build profiles to the same semantics, overflow checks included (Build and inspect).
• Its [patch.crates-io] routes k256, ark-ff and revm-precompile to vendored copies that call Apogee's delegations (Delegations).

The ceremony file#

Every commitment Apogee makes is under the powers of a secret τ from a public ceremony: the PSE perpetual powers of tau, contribution 80. One file serves every use:

assets/ptau/ppot_0080_24.ptau        19.3 GB, 2^24 powers; assets/ptau/ is gitignored

You need it to compute a program identity, to build real keys and to prove. You do not need it to build, run or profile a guest, or to run the workspace tests, which prove over toy setups of their own.

Files from PSE's ceremony are cut from one transcript, so any file of power 24 or more serves. Hermez's powersOfTau28_hez_final_*.ptau is a different ceremony with a different τ: the reader ingests it as readily, and every commitment, key and identity over it comes out different. To confirm you hold the right ceremony, its [τ]_1, as the hex of its canonical encoding x ‖ y, is:

9bbb31bedc304e081e2aada4b56c2217e0e94ee16874e3517d14bef5dcec3a16
317ff1589e53513fa333591b318e8f1e55ef7c37d92beb6d9a61d770a2f39506

The specification's SRS page states exactly what the reader checks and what it takes on trust.

The machine#

Building and running are laptop work. Proving is memory-bound, and its memory follows the shards being proved at once, not the length of the run.

The proving page explains how heights and the number of shards in flight trade memory against time: Prove and verify.

Check your checkout#

What CI runs, all of it without the ceremony file:

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
(cd guests && cargo clippy --bins -- -D warnings)

The suites that prove real shards are #[ignore]d, because each needs tens of GiB. Run one by name when you want to see a proof made and refused on your own machine:

cargo test --release -p prover --test acceptance -- --include-ignored --test-threads=1

Next: write a guest, or run the whole loop once in the Quickstart.

The crate#

In v1.0.0 a guest is a binary crate in the repository's guests/ workspace. The workspace supplies the target, the linker flags, the pinned profiles and the vendored crates, so a guest's own manifest stays short:

[package]
name = "my-app"
version.workspace = true
edition.workspace = true
publish.workspace = true

[dependencies]
guest-sdk.workspace = true

#![no_std]
#![no_main]

extern crate alloc; // Vec, Box, String, BTreeMap, over the SDK's allocator

use alloc::vec::Vec;

guest_sdk::entry!(main);

fn main() {
    let input = guest_sdk::public_input();
    let mut out = Vec::with_capacity(input.len());
    out.extend(input.iter().rev());
    guest_sdk::commit(&out);
}

Add "my-app" to members in guests/Cargo.toml, and build from the guest's own directory: cargo build --release --target riscv32imac-unknown-none-elf.

What runs underneath you#

The guest SDK is the entire runtime. It is small enough to state in full:

• Start. _start sits at 0x0001_0000, the first byte of .text. It points sp at the top of RAM, zeroes .bss byte by byte, and calls main. entry!(f) exports that main as a wrapper around your function, which takes no arguments and returns ().
• Exit. Returning from main is exit(0). guest_sdk::exit(code) ends the run with any status. A nonzero status is a failed execution, and a failed execution is still provable: the statement carries the status, and a verifier reads it.
• Panic. The panic handler exits with status 101 and writes nothing. There is no diagnostic stream. A panicking guest has still published whatever it committed before the panic.
• Heap. A bump allocator grows up from __heap_start, just above .bss. It never frees. See the heap.
• System calls. The only ecalls a guest makes are EXIT and the delegation calls the SDK makes for you. Input, advice and output are memory, read and written with ordinary loads and stores.

The memory map#

The whole 32-bit address space, as a guest sees it:

Code is static. Each pc's instruction comes from the program's decoded tables, never from RAM, so a store into .text changes what a later load reads but not what executes.

The heap#

The allocator bumps a pointer and dealloc does nothing. That is the right design for a short program whose every cycle costs proving time, and it changes how you write Rust:

• What runs you out of memory is the total you allocate, not your peak. A loop that builds and drops a Vec each iteration consumes fresh heap every time.
• Reuse buffers. Hoist allocations out of loops, clear() and refill instead of reallocating, and size growing collections with with_capacity so they do not reallocate and copy as they grow.
• The ceiling is exit 71. An allocation that would end above 0x7F80_0000, or above the live stack pointer, exits with status 71 rather than return null or overwrite the stack.

// Allocates a fresh Vec per record: total heap grows with the record count.
for record in records {
    let fields: Vec<&[u8]> = record.split(|b| *b == b',').collect();
    handle(&fields);
}

// One buffer, reused: total heap is the largest record's field count.
let mut fields: Vec<&[u8]> = Vec::with_capacity(16);
for record in records {
    fields.clear();
    fields.extend(record.split(|b| *b == b','));
    handle(&fields);
}

The stack has its 8 MiB reserve, and deep recursion inside it is fine. What nothing detects is a stack that grows past the reserve after the heap has filled the space below it: heap blocks would then change under a deep call chain. Keep recursion bounded, or make it iterative.

Dependencies#

Any crate that builds for riscv32imac-unknown-none-elf without std will do. In practice:

• Turn off default features (default-features = false) and enable alloc where a crate offers it.
• A crate that pulls in getrandom, a clock or std::collections::HashMap with its random seed has nothing to draw on. Such a call answers -ENOSYS and leaves the run unprovable. Prefer BTreeMap, or a hash map with a fixed, deterministic hasher.
• Floating point compiles to integer software routines, because the target has no F or D extension. It is correct and deterministic, and costs many instructions per operation. Integer or fixed-point arithmetic is cheaper.
• Hashing and elliptic-curve arithmetic have dedicated circuits. Use the SDK's functions or the vendored crates so your dependencies reach them: Delegations.

Test it on the host first#

A guest prints nothing, so debugging happens on the host. The layout that makes this easy keeps the program in a #![no_std] library from bytes to bytes, keeps main.rs down to moving bytes in and out of the regions, and makes the SDK a dependency of the guest target only:

[package]
name = "my-app"
version.workspace = true
edition.workspace = true
publish.workspace = true

[target.'cfg(target_arch = "riscv32")'.dependencies]
guest-sdk.workspace = true

#![no_std]
extern crate alloc;
use alloc::vec::Vec;

/// The whole application: public input and advice in, journal out.
pub fn run(input: &[u8], advice: &[u8]) -> Result<Vec<u8>, i32> {
    let _ = advice;
    let mut out = Vec::with_capacity(input.len());
    out.extend(input.iter().rev());
    Ok(out)
}

#![no_std]
#![no_main]

guest_sdk::entry!(main);

fn main() {
    match my_app::run(guest_sdk::public_input(), &[]) {
        Ok(journal) => guest_sdk::commit(&journal),
        Err(code) => guest_sdk::exit(code),
    }
}

Host code then depends on the library by path, as crates/emulator depends on guests/revm-block, runs my_app::run natively, and compares the result with the journal the emulator produces for the same input (Run and profile). Your logic gets unit tests, a debugger and println! on the host, and the guest binary stays a thin shell around code you have already tested.

Assembly and the instruction set#

The decoder accepts exactly the 59 instructions of RV32IMA, and compressed (C) instructions, which are expanded at load. Inline assembly is fine within that set. Anything outside it, such as a CSR access, fence.i, a floating-point or an RV64 encoding, makes the whole program refuse to register, even if it is never reached: derivation reports Not all opcodes supported: pc=…. An ebreak, a jump to a halfword with no instruction, or a misaligned halfword or word access ends the run with no proof.

Atomic instructions decode and prove, with one deviation: sc.w always succeeds, because the machine keeps no reservation state. The guest programming guide explains why new guest code should not use atomics at all.

Next#

An Apogee guest has no file descriptors, no streams and no I/O syscall. Its inputs and outputs are three regions of memory, read and written with ordinary loads and stores, and the proof binds two of them.

The three regions#

let input: &[u8] = guest_sdk::public_input(); // a slice over the input window, no copy
let data: &[u8] = guest_sdk::advice();        // a slice over the advice region
guest_sdk::commit(b"result");                  // appends to the journal

• public_input() and advice() return slices over memory; nothing is copied. read_input(buf) copies min(buf.len(), input.len()) bytes and returns the count, so it may return short.
• commit appends and keeps a length word, which is what makes the proof bind an exact byte string rather than a zero-padded window. It exits with status 70 rather than overflow the window.
• advice() on a run given no advice is a fatal OutOfBounds, not an empty slice: a run with no advice has no advice region at all, and pays nothing for one.

What "bound" means#

The statement a proof establishes carries the public input bytes, the journal bytes and the exit status. The proof shows that the input window held exactly the statement's input before the guest's first access, and that the journal window held exactly the statement's output when the guest exited. That rests on the memory argument, not on anything the guest does: there is no hash the guest must compute and no convention it must follow.

Advice is different. The advice region's initial contents are whatever the prover wrote there, and nothing ties them to the program identity, the statement or any gate. A proof says that some advice exists under which the program, given this input, published this journal. That is exactly as strong as the guest's own checks on the advice.

The pattern: commit, supply, check#

A guest with a large input takes the bulk as advice, which the public input commits to, and checks one against the other before anything derived from the advice reaches the journal:

fn main() {
    let want = guest_sdk::public_input(); // 32 bytes: keccak256 of the advice
    let data = guest_sdk::advice();       // the prover's bytes, bound by nothing
    if guest_sdk::keccak256(data).as_slice() != want {
        guest_sdk::exit(1); // refused before anything derived from it is committed
    }
    let sum = data.iter().fold(0u32, |s, b| s.wrapping_add(u32::from(*b)));
    guest_sdk::commit(&sum.to_le_bytes()); // the journal: what the proof publishes
}

The check need not be a hash of the whole advice. It can be a Merkle path checked against a root the input carries, as in the ledger example, or a signature over the data, or a constraint the result itself satisfies, such as a claimed sorted order that the guest verifies in one pass instead of sorting. What matters is that the thing it is checked against is bound.

Structured data#

Encode structured inputs with a no_std serializer such as postcard over serde with the alloc feature, which is what the repository's own Ethereum guest uses for its block witness. Two habits keep a format honest:

• Use fixed-width integers. u32 and u64, never usize, whose width differs between your host and the guest.
• Insist on one encoding per value when it matters. A deserializer that accepts trailing bytes or non-minimal varints admits two byte strings for one value. Where uniqueness matters, decode, re-encode and compare, as the Ethereum guest's BlockWitness::decode does.

Outputs that grow#

The journal holds 16,380 bytes. An output that grows with the work, such as one record per transaction, has no fixed bound and will eventually exit 70. Publish a digest instead: hash the records as you produce them and commit the 32-byte result, then let whoever needs the records recompute them natively and compare. The repository's stateless Ethereum validator publishes a 43-byte journal for a whole block this way.

For a proof checked on Ethereum, keep both public values a fixed length. The deployed verifier contract is built for one input length and one output length, and refuses anything else (Settle on-chain).

The exit status#

Nothing is published at exit beyond what was committed, and a run that panics or exits nonzero has a valid proof of what it did. So a verifier reads the exit status before it reads the journal. On-chain, the verifier contract takes the expected status as an argument, and an application passes 0. The SDK's own statuses:

Choose your own failure codes outside these, as the ledger example does with 1, 2 and 3.

What the proof does not say#

• Nothing orders the journal's writes, and nothing forces a guest to read its input. The proof binds the windows' contents, not the accesses that produced them.
• Advice is writable. A store into the advice region is an ordinary store. It is still unbound either way.
• The journal is the window's whole final contents. commit maintains that form. A guest that writes the window directly must keep it: a length of at most 16,380, that many bytes, then zeros.

The specification states all of this precisely: Public values and advice.

Some computations are far cheaper to prove with a circuit built for them than as a stream of RISC-V instructions. Apogee calls these delegations. A delegation is a circuit family that proves one function of a frame of words in RAM, invoked by an ecall, and the guest SDK makes those calls for you behind ordinary functions. You never write an ecall yourself.

What you call, and what it reaches#

The functions are bit-identical to their software definitions. keccak256 is Ethereum's Keccak, not SHA3-256. sha256 is FIPS 180-4. ec_add uses the complete formula of Renes, Costello and Batina (2015, Algorithm 7), so doubling, P + (−P), the identity and any Z need no special case.

use guest_sdk::{ec_mul, keccak256, recursion::SECP256K1_GROUPS, ProjectivePoint};

let digest: [u8; 32] = keccak256(b"blockchain-native");

// A point is homogeneous projective (x = X/Z, y = Y/Z), each coordinate eight
// little-endian u32 limbs below the field modulus. The scalar is eight limbs too.
fn times(p: &ProjectivePoint, k: &[u32; 8]) -> ProjectivePoint {
    ec_mul(&SECP256K1_GROUPS, p, k).expect("EC_ADD is implemented on Apogee")
}

Library code reaches them too#

The guest workspace patches three crates so that the code inside them calls delegations on the guest target, with upstream's code as the fallback path:

A guest that depends on these crates gets the patched copies automatically through guests/Cargo.toml's [patch.crates-io]. Unpatched, k256's field multiply and square alone were 44% of a mainnet block's cycles. secp256k1 signature recovery is ordinary k256 code, which the patches turn into delegated arithmetic.

What a delegation costs#

A delegation family is part of a program only if the program links one of its shims, and a call costs shards of that family's height:

• Linked and never called: nothing. The family is declared and proves zero shards.
• Called once: a whole shard. A shard costs its full height whatever its occupancy.
• Called a lot: very little per call. A shard's proof grows only by one sumcheck round per variable as its height grows.

The price is memory more than time: a 2^18 KECCAK_F shard's forward pass holds about 42 GiB of field elements, and two of them in flight set the measured Ethereum block's peak.

Rules on operands#

• Operands below their modulus. A MOD_MUL or EC_ADD operand at or above the modulus its selector names has no proof: the executor refuses the frame as a fatal DelegationFrame. The vendored k256 reduces its lazily reduced field elements before calling.
• Points are not checked for you. EC_ADD proves the formula's arithmetic. Whether a point lies on the curve is the calling code's question, and a guest that takes points from advice must ask it.
• Multi-call operations are one SDK function each. A keccak permutation is 24 calls on one frame, a SHA-256 compression 16, a point addition 3. Each call proves its own step, and nothing refuses a wrong order: it computes something else. Use keccak256, sha256 and ec_add, which issue the calls in order, rather than the raw shims.
• Exit 72 means a delegation answered something its shim refuses. On Apogee's own executor this does not happen for a well-formed frame.

What is not delegated#

• The EVM's MULMOD with an arbitrary modulus, MODEXP, BLS12-381, and every primitive outside the table above run as instructions.
• No signature scheme or pairing is delegated as a whole. secp256k1 recovery is k256 over MOD_MUL and EC_ADD; a BN254 pairing is ark-bn254 over MOD_MUL.
• A delegation is an operation's core. Padding, sponges, block loops and a scalar multiplication's ladder are guest code, proved as instructions.

Signature schemes for guests are on the v2.0.0 roadmap.

Is a new delegation worth it?#

The cycle profiler prices the obvious candidates in every report, as a ceiling on the cycles a delegation could remove:

removable = max(0, cycles − calls·(4 + 2·frame_words))

cycles is the category's share of the run, calls the entries into the candidate's functions, and 4 + 2·frame_words the shim a delegation would leave behind: the frame's stores, the ecall and the result's loads. It charges nothing for the new family's shards, so treat it as an upper bound. Run and profile shows a report.

The specification of each delegation, column by column, is under Delegation circuits.

Build#

From the guest's directory, with no flag but the target:

cd guests/my-app
cargo build --release --target riscv32imac-unknown-none-elf     # .../release/my-app
cargo build --target riscv32imac-unknown-none-elf               # .../debug/my-app

The ELF lands in the guest workspace's one target directory, guests/target/riscv32imac-unknown-none-elf/. guests/.cargo/config.toml adds two linker arguments that you never type:

• -T crates/guest-sdk/link.ld, the memory map, which also defines the symbols the startup code and the allocator use.
• --no-relax. Linker relaxation rewrites instruction sequences and shifts every later address, and the program identity binds those addresses.

There is no runner: nothing outside Apogee maps a guest's regions, so cargo run has nothing to run it with. You run a guest through the emulator (Run and profile).

Profiles#

guests/Cargo.toml pins both profiles to one semantics. They differ only in optimization and in dependencies' debug assertions:

Cargo's default release profile turns overflow checks off, and in a guest that is not a performance setting. It changes the statement: u32::MAX + 1 would commit 00000000 and exit 0 where the dev build panics with exit 101. So the workspace keeps the checks on in both profiles. A dependency's debug assertion checks that crate's own invariant, and a correct dependency computes the same without it, so release turns those off and keeps the cycles: 6.8% of the stateless Ethereum guest's run.

Prove the release build. Every executed instruction is a proved row, opt-level = 3 removes a quarter to over half of a guest's image, and each family's code must fit its decoded table: the Ethereum guest's debug image needs 2^22-row tables, its release image 2^20. The identity you publish is the release image's.

Reproducibility#

Two clean builds on one machine produce identical ELFs. Builds on two machines generally do not: the ELF embeds absolute paths in panic-location strings, the toolchain's core sources, crates/guest-sdk and the cargo registry, while the guest's own files appear relative to guests/. A build elsewhere is another image with another identity.

So what you register and hand on is a build's ELF, not a recipe. Keep the ELF you proved, and let anyone who wants to check the identity recompute it from that ELF, the parameters and the ceremony file.

Export the image#

cargo run -p artifact-dump -- guests/target/riscv32imac-unknown-none-elf/release/my-app --out artifacts

This writes artifacts/my-app.img, the loaded ProgramImage in its wire form (postcard, no header), and artifacts/my-app.img.txt, a report rendered from the image read back through the validating reader. It prints the entry point, the segment and instruction counts, and the artifact's size and SHA-256. If the read-back differs, or the loader refuses the ELF, it writes nothing.

The .img is the program's static description, for keeping and diffing; nothing downstream needs it, since the setup and the tools take the ELF. Its SHA-256 pins bytes. It is not the program identity.

Read the report#

A compressed instruction keeps its address and its two bytes; len alone says whether the next pc is pc + 2 or pc + 4. For mnemonics, use the tables view below or the pinned disassembler:

"$(rustc --print sysroot)"/lib/rustlib/*/bin/llvm-objdump \
    --disassemble --no-print-imm-hex -M no-aliases <elf>

The not code halfwords#

A report may show a line such as ---- not code: 0x00010f9a .. 0x00010f9c, 1 halfword ----. That is ordinary compiler output. LLVM proved a match's default arm unreachable, rustc lowered the unreachable block to unimp, and with the C extension that is c.unimp, the all-zero halfword, RVC's defined-illegal encoding. The loader records it as a non-instruction and moves on. No pc reaches it; one that did would stop the run with NotAnInstruction.

What the VM will prove#

cargo run --release -p artifact-dump -- tables <elf> --ptau assets/ptau/ppot_0080_24.ptau

This prints, at the default parameters, the VmConfig the image derives: each family's height, its live rows and decoded columns. Then it prints each instruction's pc, next_pc, family, mnemonic and fields. With --ptau and the ceremony file it also prints the program identity, the value a verifier registers. The Quickstart shows a real one.

The identity is one field element. It binds every instruction with its pc, length, operands and kind, every file-backed byte of the image (.text, .rodata, .data), the entry point, the family set, every height, the code-size ceiling and the code version. It does not bind the symbol table, .bss, or anything an execution chooses. One ELF at two settings of the heights has two identities.

Derivation refuses, naming the pc or the size:

Check a build#

Build into a fresh target directory, export again, and compare:

cd guests/my-app
CARGO_TARGET_DIR=/tmp/fresh cargo build --release --target riscv32imac-unknown-none-elf
cd ../..
cargo run -p artifact-dump -- /tmp/fresh/riscv32imac-unknown-none-elf/release/my-app --out /tmp/again
cmp artifacts/my-app.img /tmp/again/my-app.img
diff artifacts/my-app.img.txt /tmp/again/my-app.img.txt     # differs only in the `source ELF` line

Running a guest costs almost nothing; proving it costs in proportion to the cycles it runs. So run first, compare against your host build, and look at the cycle profile before you prove anything.

From Rust: the emulator#

emulator::run executes a loaded image over a public input and advice, in host code, with no proof:

let elf = std::fs::read(elf_path)?;
let image = loader::load_elf(&elf).expect("the ELF loads");
let io = emulator::GuestIo { input: b"hi".to_vec(), advice: Vec::new() };
let run = emulator::run(&image, &io).expect("no fatal error");

assert_eq!(run.exit_code, 0);
assert_eq!(run.io.output, my_app::run(b"hi", &[]).unwrap()); // the host build agrees
println!("{} cycles", run.cycle_count);

run returns an Execution: the final registers, the exit status, the cycle count and the public values. A nonzero exit status is an execution, not an error, and comes back as exit_code. A fatal executor error, such as OutOfBounds, Misaligned or NotAnInstruction, comes back as an EmuError, and such a run has no proof (Troubleshooting).

The emulator is a pure function of the image and the input: no clock, no randomness, no threads. The same input gives the same execution, cycle for cycle, which is also what lets the prover execute twice and cut identical shards.

From the command line: the profiler#

cargo run --release -p profiler -- elf <elf> [--input <file>] [--advice <file>] [--top <n>] [--json <path>]

It runs the guest over the given files at the smallest table height its code fits, and prints a report. Its numbers are counts of executed cycles, the same on any machine.

workload
  label                        hello
  guest cycles                 114
  exit status                  0
  journal bytes                13

cycles by semantic workload
  core runtime                             94   82.46%
  unattributed                             20   17.54%

cycles by family
  ADD_SUB_LUI_AUIPC            64
  JUMP_BRANCH_SLT              21
  MEM_WORD                     3
  MEM_SUBWORD                  26

top functions
            94   82.46%          1 calls        94.0 c/call  guest_sdk::commit  [core runtime]
             8    7.02%          1 calls         8.0 c/call  main  [unattributed]

How to read it:

• Cycles by family is what you pay for. Each family with rows costs at least one shard of its height, and more cycles in a family means more shards of it.
• Top functions charges each function for its own cycles, including everything the compiler inlined into it, but not its callees. Calls are counted at the function's first instruction.
• Cycles by semantic workload groups functions into fourteen categories by name, such as hashing, signatures and the core runtime. The unattributed share and the mnemonic mix are the checks on that attribution, since no symbol table can mislabel them.
• Accelerator candidates price the delegations a future version could add, as a ceiling: see Delegations.

The profiler has two more verbs, for the Ethereum workload: block <stem> runs the revm guest over a recorded fixture, and record <number|latest> records a block from ETH_RPC_URL and runs it.

Make it cheaper#

The order that usually pays:

1. Build --release. Optimization removes a quarter to over half of a guest's instructions.
2. Delegate hashing and curve arithmetic. Use guest_sdk::keccak256, sha256, ec_add and the vendored k256 and ark-ff, instead of compiling a software implementation into the guest.
3. Stop allocating in loops. Each allocation is instructions, and with a bump allocator it is also memory you never get back (the heap).
4. Check instead of compute. If a result is expensive to find and cheap to verify, such as a sorted order, a square root or a path through a tree, let the prover supply it as advice and have the guest verify it.
5. Avoid floating point. It compiles to software routines; integer and fixed-point arithmetic are far cheaper.

Then measure again. Cycle counts are exact and repeatable, so every change shows up as a number.

The three calls#

let params = program::ProgramParams::defaults();
let ptau = std::path::Path::new("assets/ptau/ppot_0080_24.ptau");
let srs = srs::Srs::from_ptau(ptau, 22).expect("ceremony");

let setup = host::setup(&elf, &params, srs).expect("registers");          // once per program
let proven = host::prove(&setup, &io, 4).expect("proves");                // at most 4 shards in flight
host::verify(&setup.vk, &proven.block).expect("verifies");

assert_eq!(setup.vk.identity.to_bytes(), registered); // from your own channel, never the proof
assert_eq!(proven.exit_code, 0);

• host::setup loads the ELF, decodes it into its family tables and VmConfig, commits the setup columns under the ceremony, and builds the verifying key. Its cost is per program and per choice of heights, not per run.
• host::prove executes the guest twice and proves every shard (below). It returns a Proven: the BlockProof, the exit code, the cycle count, the journal and a report of the run.
• host::verify checks the block against the key, using the statement the block carries. It compares neither the identity nor the SRS digest with anything, so that comparison is yours.

The Quickstart runs exactly this code over a small guest, with its real output.

What a verifier must hold for itself#

Two values come from a channel the prover does not control:

1. The program identity. Against an identity the prover supplied, a proof shows only that some program ran. A verifier registers the identity of the release it trusts and compares it with the key's.
2. The SRS digest of the ceremony. A key loads under whatever digest its own points give. One built over a known τ could open anything, and is refused only by comparing its digest with the ceremony's.

The verifying key itself may come from anyone, including the prover: loading it recomputes the identity and the SRS digest from its own contents and holds its circuits to the verifier's own registry. Then read the statement: the exit status first, then the journal.

Heights#

Each family has a height, the number of rows in one of its shards, chosen from 2^8, 2^12, 2^16, 2^18, 2^20, 2^22. Heights are part of the program, not of a run: every height is bound into the identity.

A family with rows costs at least one whole shard of its height, so a short run wastes less at smaller heights, and a long one needs fewer shards at larger heights. A decoded table must also be tall enough to reach the family's last instruction: 2^20 reaches 1.9375 MiB of code and 2^22 reaches 7.9375 MiB. The Ethereum guest proves at 2^20 for every family whose height is a choice.

use constants::family;

let mut params = program::ProgramParams::defaults();
for f in 0..7 {
    params.heights[f] = 1 << 20;
}
for f in [family::INIT_TEARDOWN, family::ZERO_WINDOWS, family::ADVICE_WINDOWS] {
    params.heights[f as usize] = 1 << 16; // window 0 is then 256 KiB: the image must fit in it
}

The ceremony must supply as many powers as the tallest family has rows, and at least 2^18 for the generic lookup table: Srs::from_ptau(path, k) with 2^k at least the largest height.

Shards in flight#

The third argument of host::prove is max_in_flight, the number of shards proved at once. It is the one knob that trades memory for time:

• Memory follows the shards in flight, not the cycle count. Each shard in flight holds its rows, its forward pass and its proof as it grows. A 2^20 shard of the widest instruction family holds about 8.4 GiB in its forward pass; a 2^18 KECCAK_F shard about 42 GiB.
• Time follows how many shards run side by side, up to the cores you have. Within a shard, the work runs on all cores.
• The proof does not depend on it. The block is byte-identical at 1 and 8 in flight.

Start low on a laptop, two or four, and raise it on a server until memory, not cores, is the limit. bench prove defaults to 8.

The two passes#

host::prove streams. It never holds the whole execution trace, which at about 300 bytes a cycle would be the largest object in the system.

1. Pass 1 executes the guest and, as each shard fills, commits its memory columns, keeps the commitments and drops the rows. At the exit it builds the statement and draws the challenges every shard shares.
2. Pass 2 executes again. The emulator is deterministic, so it cuts the same shards. Each is filled, proved and dropped as it arrives, and only its proof is kept.

That is why proving takes two executions' time and memory bounded by the shards in flight. The streaming prover explains it in depth.

Keep the proof#

host::proof_archive::write_proof(dir, stem, vk, block) writes four files, each its type's plain bytes:

<stem>.vk         the verifying key
<stem>.identity   the key's identity, 64 lowercase hex digits and a newline
<stem>.public     the statement: input, journal, exit status, the execution's record
<stem>.block      the block proof

read_proof(dir, stem) reads them back. The .identity file records what the run claimed; a verifier still compares against its own copy. The verifier command-line tool checks an archive:

cargo run --release -p verifier -- block <stem>.vk <identity-hex> <stem>.public <stem>.block

It exits 0 when everything verifies, 1 naming the first refusal, and 2 on a usage error or a malformed identity. It compares the identity you pass with the key's, and takes the SRS digest from the key file.

When a proof fails#

An honest prover never produces a proof that fails, so a failure means an input it should not have accepted, or a bug. Rebuild with the prover's debug log on and rerun:

cargo run --release -p bench --features prover/debug-info -- prove ...
APOGEE_DEBUG=detail <the same run> 2>&1 | tee run.log
grep -E 'FAIL|NOT CANONICAL|UNBALANCED|OVER the|NAMES NO|DISAGREES|NOT LOOPING|ABORTED' run.log

The log names the shard that died, and self_check FAILED names the first gate a row breaks, with every operand's value. Tools lists every marker. The log exists only in builds with the debug-info feature and changes no proof byte.

Next: Settle on-chain.

A base proof is a block of shard proofs, each a GKR proof with its commitments: megabytes of data and hundreds of curve points, which no contract can check. Settlement compresses it in three stages, each run with bench from the repository root.

1. The recursion tree#

A node is Apogee proving a verifier program. A leaf verifies a run of consecutive base shards; an internal node verifies two to four child proofs; the root covers every base shard. Each node also folds every Mercury check its shards and children defer into one pair of points, so the whole tree comes down to a single pairing claim at the top.

# the base proof as an archive: host::proof_archive::write_proof from your host
# program, or `bench prove ... --out <dir>` for the Ethereum guests
cargo run --release -p bench -- recurse <dir>/<stem> --out <out> --in-flight 4

recurse writes the two recursion programs' keys, builds the leaf and node binaries over them, fixes a plan before anything is proved (<out>/tree.txt: leaves of at most --leaf 64 base shards, then nodes of at most --fan-in 4 children), and proves node by node. Each node is its own process, which verifies its inputs natively before proving, so a bad input is refused by name. A stopped run resumes: proofs already in <out> are kept, and a run whose plan or programs differ is refused.

Base proving is untouched by any of this. A leaf verifies base shards exactly as they are.

2. The decider#

The root is still a GKR proof and some hundreds of points. The decider is a Groth16 circuit that verifies the root as a node would, and folds nothing. Instead it binds, as wires whose values the contract supplies, the two recursion programs' identities, the base statement's exit status, its public input and journal byte by byte, and each point the root owes a pairing to, with its scalar. The Groth16 proof carries one commitment to all of those wires, and the contract checks it against the values it holds.

A Groth16 key needs a ceremony. Phase 1 is the same powers-of-tau file the tree's commitments are under. Phase 2 is the circuit's own and runs in two rounds of contributions:

cargo run --release -p bench -- ceremony <out> init          # once per root shape
cargo run --release -p bench -- ceremony <out> contribute    # round 1: alpha and beta, each contributor in turn
cargo run --release -p bench -- ceremony <out> seal
cargo run --release -p bench -- ceremony <out> contribute    # round 2: gamma, delta and eta
cargo run --release -p bench -- ceremony <out> key
cargo run --release -p bench -- decide <out>                 # the Groth16 proof, checked natively and in an EVM

Each contribution multiplies a trapdoor by a factor only its contributor knew, and records it with a Schnorr proof, so any state can be verified against the circuit and the ceremony file alone. A trapdoor is unknown while one contributor to it was honest. The order of the rounds is part of soundness: alpha and beta are finished before anything is divided by delta or eta.

decide writes decision.constructor and decision.calldata: the deployment arguments and the call, as hex.

3. The contract#

contracts/ApogeeVerifier.sol has one entry point:

function verify(
    bytes calldata input,        // the base program's public input
    bytes calldata output,       // its journal
    uint256 exitStatus,          // the status you require, normally 0
    uint256[10] calldata proof,  // Groth16 A, B, C and the bound wires' commitment D
    uint256[] calldata points    // x, y and scalar of each point, side [1]_2's then side [x]_2's
) external view returns (bool);

It rebuilds the bound values from the calldata, checks the Groth16 pairing equation, folds each side's points with ecMul and ecAdd, which also holds every point to the curve, and checks the folded claim e(A, [1]_2) = e(B, [x]_2). An application contract calls it and then acts on the journal: see the ledger sketch.

What one deployment fixes#

The constructor takes the Groth16 key, the ceremony's two G2 points, the leaf and node programs' identities, the number of points on each side, and the byte lengths of the public input and the journal. So one deployed verifier serves:

• One base program. Its identity is a constant of the leaf program's image, which the leaf's identity binds.
• One root shape. The decider's circuit depends on the root's program, its shard counts and the public values' lengths, so a key and its ceremony are per shape.
• Fixed-length public values. verify refuses an input or journal of any other length. Design guests whose on-chain public values have a fixed size, such as a fixed record or a 32-byte digest.

The contract pays about 9,000 gas a point, because the circuit folds none of them.

Measured#

Block 257,510, with the tree on a 32-CPU, 247 GiB machine and the ceremony and decider on an 18-core laptop:

The specification of all of it is Recursion and decider.

Most of writing a guest is writing Rust. This page is about the rest: the places where a bare-metal, single-hart, proved machine behaves differently from the host you are used to. Each rule says what to do, why, and what goes wrong otherwise. The AI Companion carries the same rules in a form you can hand to a model.

Types and memory#

usize is 32 bits, and so is every pointer#

The guest target is riscv32imac: usize, isize and every pointer are 32 bits wide, while your host's are 64.

• Overflowing a usize panics on the guest and not on the host.
• x as usize from a u64 truncates silently on the guest.
• size_of::<T>(), struct layout, and core::hash of anything holding a length or pointer differ between the two builds.

Do: use explicit u32 and u64 in anything you commit, hash, serialize or compare with a host computation. Convert with usize::try_from(x) where a value may not fit, so it fails loudly on both builds. Don't: commit usize, hash a structure containing one, or derive a layout-dependent encoding.

let n = u64::from_le_bytes(input[..8].try_into().unwrap());
let len = usize::try_from(n).expect("length fits the guest"); // not `n as usize`

The allocator never frees#

The heap is a bump allocator: alloc moves a pointer up, dealloc does nothing, and memory comes back only when the program exits. So what runs a guest out of memory is the total it allocates over the run, not its peak. When an allocation would end above the stack's reserve, or above the live stack pointer, the guest exits with status 71.

Do:

• Allocate once and reuse: hoist buffers out of loops and clear() them instead of building new ones.
• Size collections up front with Vec::with_capacity, String::with_capacity, so they do not reallocate and copy as they grow. A Vec grown one push at a time to n elements also leaves its earlier, smaller buffers behind.
• Prefer borrowing (&[u8], &str) to cloning, and iterators to intermediate collections.
• Process large advice in place: advice() is already a slice over memory, so there is nothing to copy.

Don't: collect() into a new Vec inside a hot loop, clone values you only read, or rebuild a map per request when one map can be cleared and refilled.

// Total heap grows with the number of requests:
for req in requests {
    let parts: Vec<u32> = req.chunks(4).map(|c| u32::from_le_bytes(c.try_into().unwrap())).collect();
    process(&parts);
}

// Total heap is one buffer:
let mut parts: Vec<u32> = Vec::with_capacity(MAX_PARTS);
for req in requests {
    parts.clear();
    parts.extend(req.chunks(4).map(|c| u32::from_le_bytes(c.try_into().unwrap())));
    process(&parts);
}

The stack has 8 MiB, and nothing guards its far edge#

The stack grows down from 0x8000_0000 and has an 8 MiB reserve that no heap block may enter. Deep recursion within it is fine. What nothing detects is a stack that grows past its reserve after the heap has filled the space below it: heap blocks then change under a deep call chain, silently. Do: keep recursion depth bounded and predictable, or write deep traversals iteratively with an explicit work list. Don't: recurse to a depth set by untrusted input.

Aligned accesses only#

A halfword or word access through a misaligned pointer is fatal, never split, and the run has no proof. Safe Rust never produces one. Don't cast a byte pointer to *const u32 and dereference it; read with u32::from_le_bytes, which compiles to byte loads, or with ptr::read_unaligned.

Null is a hole#

Addresses below 0x8000 belong to nothing, so a null or small wild pointer is a fatal OutOfBounds rather than a read of garbage. It surfaces as a run with no proof, never as a wrong answer.

Concurrency#

Atomics: supported, and not for new guest code#

What to know if atomics reach your guest through a dependency:

• On one hart an atomic is just a read-modify-write. fetch_add is an amoadd.w that adds; nothing can interleave with it.
• sc.w always succeeds. The machine keeps no reservation state, so a store-conditional stores and writes 0 to rd. The lr.w/sc.w retry loop that compiled code uses for compare_exchange is unaffected, because first-time success is legal on any hart. Code that relies on sc.w failing without a valid reservation does not get that failure here. This is the one place Apogee deviates from RV32IMAC.
• fence does nothing, and memory orderings (aq, rl, SeqCst) order nothing on one hart.
• They cost a circuit family. An atomic adds the ATOMICS family to the program, which then proves at least one shard of it.

Do: use plain variables, Cell and RefCell for state in new guest code. Don't: add AtomicU32, Mutex-like spin locks or Arc to a guest that has no second thread to share them with.

Inputs and outputs#

Check advice before anything derived from it reaches the journal#

Advice is memory the prover filled, and nothing binds it. Check it against something the proof does bind, such as a hash or a Merkle root in the public input, a signature, or a property of the result, before committing anything that depends on it. Committing a function of unchecked advice publishes a value the prover chose. See the pattern.

Keep public values small, and fixed-size for on-chain use#

The input and the journal hold at most 16,380 bytes each. commit exits 70 rather than overflow. Large inputs belong in advice behind a commitment, and growing outputs behind a digest. A verifier contract is built for one input length and one journal length, so a guest settled on Ethereum should publish a fixed-size journal.

Decide what failure looks like#

A guest that exits nonzero, or panics, still has a valid proof of what it did, and a verifier reads the status before the journal. Give each refusal its own exit code outside the SDK's (70, 71, 72 and 101), and commit nothing derived from unchecked data before the checks that can refuse it.

No world outside#

A guest has no clock, no randomness, no network, no files and no environment. A library call that asks the host for any of them answers -ENOSYS and leaves the run unprovable. Seed HashMap deterministically or use BTreeMap; derive randomness from the input when an algorithm needs it; pass time in as input.

Cost#

Every executed instruction is a proved row#

Proving cost follows the cycle count, family by family. Build --release, measure with the profiler, and treat cycles the way embedded programmers treat bytes.

Delegate what has a circuit#

keccak256, sha256, elliptic-curve addition and multiplication, Poseidon2, BN254 field arithmetic and 256-bit modular multiplication have dedicated circuits. Reach them through guest_sdk and the vendored k256, ark-ff and revm-precompile, not a software implementation compiled into the guest. See Delegations.

Verify instead of compute#

When a result is expensive to find and cheap to check, let the prover find it and pass it as advice, and have the guest check it: a sorted order, a factorization, an inverse, a path through a tree, a search result.

Avoid floating point#

The target has no F or D extension, so f32 and f64 compile to integer software routines. They are correct and deterministic, and each operation costs many instructions. Use integers or fixed point.

Heights cost whole shards#

A family with rows costs at least one shard of its height, however few rows it fills. A program that touches a family once pays for a whole shard; the families your code uses, and the heights you choose, set the floor of every proof. See Heights.

Code and identity#

The instruction stream is the image#

Code is static: each pc's instruction comes from the decoded tables built at load, never from RAM. A store into .text changes data, not behaviour, and a jump to a halfword with no instruction ends the run with no proof. There is no JIT and no self-modifying code.

One illegal word anywhere refuses the program#

The decoder takes all of .text, reachable or not. A CSR access, fence.i, a floating-point or an RV64 encoding in inline assembly, or data assembled into .text, makes derivation refuse the whole program. ebreak decodes but has no proof.

Overflow checks are part of the program#

The guest profiles keep overflow-checks on in release, because turning them off changes what a guest computes: u32::MAX + 1 would wrap and exit 0 instead of panicking. Use wrapping_*, checked_* and saturating_* where you mean them.

A build is an identity#

The identity binds every byte of code and data, the entry point and every height. Rebuilding on another machine produces another identity, because the ELF embeds absolute paths. Register and ship the ELF you proved, not the command that made it.

Checklist#

Before you prove:

• cargo build --release for riscv32imac-unknown-none-elf, and the profiler's cycle report reviewed
• no usize in anything committed, hashed or serialized
• no allocation inside hot loops; growing collections sized with with_capacity
• no atomics, locks or Arc in guest code of your own
• every use of advice checked against something the proof binds, before any commit that depends on it
• journal bounded, and fixed-size if it settles on-chain
• hashing and curve arithmetic routed through delegations
• distinct exit codes for each refusal
• the host build and the emulator agree on the journal for your test inputs
• the program identity recorded from the ELF you will ship

A guest can stop short of a verified proof at six points. Find the symptom, then the row.

The run exits with a status you did not expect#

The run finished and is provable; the guest chose to fail. The SDK's own statuses:

Any other status is your own exit(code).

The run stops with a fatal error#

The emulator returns an EmuError and there is no exit status and no proof:

The ELF is refused#

artifact-dump, host::setup and the tools refuse an ELF the loader cannot take, with a LoaderError:

The program does not register#

The ELF loads but the program cannot be decoded into a configuration:

A key also fails to build if a family the program uses is set below its floor, 2^20 for an instruction family and 2^16 for the RAM window families, since no circuit exists there.

The prover fails#

An honest prover proving what the emulator executed does not fail, so a failure points at an input it should not have accepted or at a bug. Two cases account for most:

• A call with no proof. A system call outside EXIT and the delegations, which a library made for host data, answers -ENOSYS and the run continues, but the prover's fill refuses that row and names the cycle. Find the dependency that asks for randomness or time.
• Out of memory. The process is killed while shards are in flight. Lower the third argument of host::prove, or lower heights.

For anything else, rebuild with the prover's debug log and rerun:

cargo run --release -p bench --features prover/debug-info -- prove ...
APOGEE_DEBUG=detail <the run> 2>&1 | tee run.log
grep -c 'begin h=' run.log; grep -c 'gkr done' run.log     # unequal: a shard died
grep 'begin h=' run.log | tail -1                           # which one
grep -E 'FAIL|NOT CANONICAL|UNBALANCED|OVER the|NAMES NO|DISAGREES|NOT LOOPING|ABORTED' run.log

self_check FAILED names the row's first failing gate and every operand's value. The debug log lists every marker.

Verification fails#

verify_shard and verify_block return a VerifyError whose class says what broke:

If you built the proof with Apogee's own prover from an execution the emulator accepted, a verification failure means the verifier and the prover disagree about the program: check that you load the key the proof was made under, at the same heights, over the same ceremony.

Identity mismatch#

The identity you computed differs from the one you expected:

• Another machine's build. The ELF embeds absolute paths, so a rebuild elsewhere is another image. Compare against the ELF that was proved, not a fresh build.
• Other heights. Every height is bound into the identity. artifact-dump tables reports the identity at the default heights; your setup may use others.
• Another ceremony. A Hermez powers-of-tau file is a different τ, so every commitment differs. Check the file's [τ]_1 against the ceremony's.

The guests/ workspace holds every guest the repository builds and tests. Each one exists to exercise something, which makes them the best reference for the pattern you are about to write. All of them build with cargo build --target riscv32imac-unknown-none-elf from their own directory.

Start here#

Application patterns#

Delegations#

The machine itself#

The smallest useful guest#

fib reads one u32, takes that many Fibonacci steps with wrapping arithmetic, and commits the result:

#![no_std]
#![no_main]

guest_sdk::entry!(main);

fn main() {
    let mut n = [0u8; 4];
    assert_eq!(
        guest_sdk::read_input(&mut n),
        4,
        "fib: the public input is one u32"
    );
    let n = u32::from_le_bytes(n);

    let mut a: u32 = 0;
    let mut b: u32 = 1;
    for _ in 0..n {
        let next = a.wrapping_add(b);
        a = b;
        b = next;
    }
    guest_sdk::commit(&a.to_le_bytes());
}

A short input is a fault, not a default: a guest that proceeds on a partly filled buffer proves a statement about zeroes. The addition wraps on purpose, so an n above 47, past the last term that fits in 32 bits, is an ordinary input with an ordinary answer rather than a failed run. And there is no advice, because f_n costs a verifier as much to check as to compute: an advised answer would have to be recomputed to be believed.

crates/guest-sdk is a guest's entire runtime: the startup code, the entry macro, the allocator, the panic handler and the ecall shims. It compiles only for riscv32imac-unknown-none-elf.

Entry#

guest_sdk::entry!(main);

Exports the main symbol the startup code calls, as a wrapper calling your function, which takes no arguments and returns (). Your function keeps its own name and may itself be called main. Returning from it is exit(0).

The regions#

Hashing#

Elliptic curves#

pub type ProjectivePoint = [[u32; 8]; 3];

A point in homogeneous projective coordinates, x = X/Z and y = Y/Z, each coordinate eight little-endian 32-bit limbs below the curve's field modulus. It is not Jacobian: arkworks' Projective is, so a caller converting from it maps (X·Z, Y·Z², Z) in and (X·Z, Y, Z³) out. The identity is (0 : 1 : 0).

The formula proves arithmetic, not curve membership: check points taken from advice yourself.

Raw delegation shims#

guest_sdk::recursion holds the shims over word-aligned frame types. Each frame type is #[repr(C, align(4))], so its alignment is the type's and not wherever the code generator put a local. A base-format shim returns false on exactly -ENOSYS; any other nonzero answer exits 72.

Each shim reads its ecall number from its family's declaration record, a 12-byte static in its own linker section. Linking a shim declares the family; a declared family that is never called proves zero shards.

Runtime behaviour#

Transparent delegation#

Two library crates of the repository delegate on the guest target without naming the SDK, through a target-only dependency on it:

• field::Fr: addition, Montgomery multiplication (*, square, pow and the conversions) and nonzero inverse call FR_ARITH. A guest using Fr arithmetic declares that family.
• transcript::poseidon2_permute calls POSEIDON2.

The vendored k256, ark-ff and revm-precompile do the same for secp256k1, BN254 and the EVM precompiles: Delegations.

The specification of the ABI underneath all of this is Guest ABI.

Much of the code written against Apogee will be drafted by a model. A model that has never seen Apogee will write a plausible guest that uses std, allocates in every loop, reaches for an atomic counter, trusts its advice and commits a usize. The AI Companion is a single Markdown file that front-loads everything that prevents those mistakes: what a guest is, the hard rules, the SDK's complete public surface with exact signatures, patterns to copy, the errors and their fixes, and a review checklist.

How to use it#

• In a chat: attach the file, or paste it as the first message, before you describe what you want built.
• In a coding agent: save it at the root of your project under the name your tool reads by convention, such as AGENTS.md or CLAUDE.md, or add it to the tool's project rules. The agent then reads it at the start of every session.
• For review: ask the model to check a guest against section 8 of the file, the review checklist, line by line.

The file states its rules as MUST and MUST NOT, with the reason beside each, because models follow constraints that are explicit and explained more reliably than conventions they are expected to infer.

What it contains#

The rules it insists on#

The companion repeats this manual's rules, and three of them deserve to be called out because models get them wrong most often:

• Pointers and usize are 32 bits. A model trained mostly on 64-bit code serializes usize without a second thought. The guest and the host then disagree on the bytes.
• The heap never frees. Idiomatic Rust allocates freely because a real allocator gives memory back. Here every allocation is permanent for the rest of the run, so the companion asks for reuse and with_capacity everywhere.
• Atomics compile, and do not belong in new guest code. They are supported for compatibility with existing libraries. On a single hart they synchronize nothing, and they add a circuit family to the proof.

For agents reading these docs directly#

• /llms.txt indexes every page of this site in Markdown, for models that read the web.
• /docs/llms-full.txt is the whole English documentation, specification included, in one file.
• Every page has a View as Markdown link and a Copy as Markdown button, under its title and in the right-hand column.

English is the canonical language of the documentation, and the companion is published in English for every locale: it is the language models follow most reliably, and the one the specification is written in.

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

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.
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.
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. The family's circuit is run backward by the GKR engine 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 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.

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.

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

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 carries each row down to the sections that prove it.

The code, by layer#

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 lists exactly which crates soundness rests on.

Before anything executes, Apogee turns the guest binary into a fixed description of the program: its image, its instructions sorted into circuit families, the configuration it will be proved under, and one field element that commits to all of it. Every step is a pure function of its input.

Loading#

The loader accepts a static 32-bit little-endian RISC-V executable whose loadable segments lie inside guest RAM at even addresses, pairwise disjoint, at least one executable. It reads a program header's type, offsets, sizes and executable bit, and nothing else: the VM has no pages and no permissions, and all of RAM is addressable whatever the segments declare.

It then sweeps each executable segment halfword by halfword. A halfword ending in binary 11 begins a 4-byte instruction; the zero halfword is a non-instruction (LLVM pads unreachable blocks with it); anything else is a compressed instruction, expanded to its 32-bit form in place. Addresses are never compacted: a c.addi at 0x1002 stays there and occupies two bytes, so every linker-resolved address holds, and an instruction's length is the only record of whether the next pc is pc + 2 or pc + 4.

A desynchronized sweep cannot make a wrong instruction provable. A slot is a function of the bytes at its own pc, so every instruction slot is what a hart fetching there would decode. Data that shifts the sweep off the true boundaries can only lose true instruction starts, whose pcs then have no table row, or meet an unclaimed encoding and refuse the whole image.

Decoding and routing#

The decoder takes 32-bit words only and accepts exactly the 59 instructions of RV32IMA: 40 of the base set, 8 of M, 11 of A. Everything else, from RV64 encodings and floating point to CSRs and fence.i, is a decode error, and one undecodable word anywhere in executable code refuses the program, reachable or not. Each instruction is routed to exactly one of seven instruction families:

The grouping follows what the circuits share. One comparison gadget settles signed and unsigned order for every branch and slt kind; one product identity serves all four multiplies and the division; a shift either way is one product with a looked-up power of two.

Decoded tables#

Each instruction family gets a decoded table: its setup columns, where row i is pc 2i, one row per halfword of the address space the table reaches. A live row holds one of the family's instructions as a tuple pc, next_pc, rs1, rs2, rd, imm, extra_mask, where the mask is one bit naming the mnemonic. Every other row is padding, −1 in every field, so no live row is ever the padding row and an all-zero row is never a claimable instruction at pc 0.

Every cycle's row looks itself up in its family's table by its pc. That lookup is what binds an execution to the program: a row's instruction is the program's instruction at that pc, and a pc with no live row in any table cannot be executed provably. Code is static as a result. A store into .text changes what a later load reads, never what executes.

The configuration#

A program's static shape is its VmConfig: the families it uses, each with a height, and a ceiling on its code size. Nothing chooses the family set; it is derived:

• an instruction family is present when the image holds one of its instructions;
• the five window families, which initialize and tear down memory, are always present;
• a delegation family is present when the image declares it, through a 12-byte record that linking its shim leaves among the image's bytes.

A family's height is the number of rows in one of its shards, chosen from 2^8, 2^12, 2^16, 2^18, 2^20, 2^22. Every height is an even power of two because a Mercury opening needs one. Heights are a parameter of the program, not of a run, and each choice of heights is its own program.

Program identity#

The program identity is one element of Fr: a Poseidon2 digest of the code version, the VmConfig, the entry pc, and every family's setup commitments, which are Mercury commitments to the decoded tables and to the image's initial memory words.

It binds every instruction the sweep found, with its pc, length, operands and kind, and that no other pc holds one; every file-backed byte of the image, which includes the delegation declarations; the entry pc; the family set, every height, the code-size ceiling and the code version. It does not bind the ceremony or the generic lookup table, which the SRS digest covers; the circuits, which a key's load holds to the verifier's registry; anything an execution chooses; or anything of the ELF the loader does not read, such as the symbol table.

Computing it needs the ceremony's powers, to commit. Checking it needs only the commitments, which a verifying key carries: loading a key recomputes the identity from them, and every shard's opening checks its setup columns against the same points. That is what ties the tables a proof reads to the identity a verifier registered.

The specification: Program and identity.

The machine#

The emulator runs RV32IMAC on one hart over a ProgramImage, with no interrupts and no privilege levels. A run is a pure function of the image and its input, with no clock, randomness or threads, so two runs cut identical shards. It differs from a hosted RV32IMAC at three points: sc.w always succeeds, a misaligned halfword or word access is fatal rather than split, and the instruction stream is the image decoded at load.

Every other way a run can stop short of EXIT, such as an access outside the mapped regions, ebreak, or a jump to a halfword with no instruction, is a fatal error with no trace. Such a run has no proof. A nonzero exit status is not an error: it is an execution like any other, and provable.

The clock and the query#

Cycle c occupies the four timestamps 4c + Δ, one per slot Δ ∈ {0, 1, 2, 3}. Every instruction is one cycle and nothing else is: a delegation invocation rides the cycle that requested it. Cycles are numbered from 1, because timestamp 0 is every address's initial write. The clock is 38 bits, so an execution runs at most 2^36 − 1 cycles.

Every memory access is a query: a read of a value last written at some earlier timestamp, and a write at this one. A query that only reads writes back what it read. Slot 0 of every cycle is the pc query, which reads pc and writes next_pc. Then come the instruction's register and memory queries at fixed slots:

Addresses live in spaces: the 32 registers, RAM by 4-aligned word, the pc, one anchor space per delegation type, and the recursion format's field cells. x0 is an ordinary register in the trace and a constant in the machine: every query at it reads and writes 0.

Twenty-three families#

A family is a circuit and the rows it proves. There are four kinds:

Every cycle goes to the one execution family whose decoded table claims its pc. Families interleave in time: ADD_SUB_LUI_AUIPC may own cycles 1 and 3 and JUMP_BRANCH_SLT cycle 2. Nothing needs them to be contiguous, because the memory argument orders every row by its pc write.

The window families exist because the memory argument needs every address an execution touches to have exactly one initial value and one final value. INIT_TEARDOWN covers RAM window 0 and starts it with the program's image; ZERO_WINDOWS covers every other window of ordinary RAM the run touched and starts it at zero; the public pair covers the input and journal windows; ADVICE_WINDOWS covers the advice region, starting it with the prover's bytes.

Shards#

A family's rows, in the order they appear, are cut into shards of the family's height. The last is padded with zero rows, which the circuits are built to accept. A shard costs its full height whatever its occupancy, so the families a program touches and the heights it chooses set the floor of every proof.

A shard is proved on its own, by its family's circuit, except for the memory argument: each shard's circuit outputs the product of its read tuples and of its write tuples, and the verifier reconciles those products across every shard of the statement once. That is the only thing that joins shards. There is no per-shard chaining of the pc and no shared boundary between neighbours.

The shard proof sizes at the default heights run from about 12.5 KB for a public window to 665 KB for a POSEIDON2 shard; an instruction family's is 64 to 77 KB. Performance has the table.

The specification: Execution trace, Circuits and registry.

Every shard in Apogee is proved the same way: by its family's circuit, written as a stack of layers, run backward by the GKR engine from the circuit's outputs to its committed columns. This page is about why that engine sits at the centre of the system, and why the family of proof systems it belongs to is where the frontier of proving is moving.

The idea#

The classical way to prove a computation is to lay it out as a table, commit to every column, the intermediate values included, and prove that a set of constraints vanishes over the table. Commitments are the expensive part: every committed column costs a multi-scalar multiplication or a Merkle tree, and an opening at each point the constraint argument asks about.

GKR, after Goldwasser, Kalai and Rothblum, changes what has to be committed. The computation is a layered circuit. Only the bottom layer, the inputs, is committed. Every layer above it is defined by gates over the layer below, and the prover never commits to it. Instead, a claim about the top layer is reduced to a claim about the layer beneath it by one sumcheck, then to the next, until the claims land on the committed inputs, all at a single random point. One opening settles them.

What that buys a zkVM:

• Intermediate values cost no commitment. A family circuit can compute hundreds of inner columns, product trees and fraction trees, and none of them is ever committed. Only its trace columns are.
• One opening point per shard. The backward pass ends with every committed column claimed at the same point. A shard needs exactly one batched opening, 704 bytes, however many columns it has.
• Prover work is field arithmetic. Each layer's sumcheck is linear in the layer's size, over Fr, with no commitment, transform or hash per layer.
• Arguments compose inside the circuit. The memory argument's grand products and the lookups' LogUp sums are just more layers of the same circuit, reduced in the same pass.

A family circuit, layer by layer#

The bottom layer is the shard's committed columns, in three kinds that differ in when they are bound: M, the memory columns, committed in the statement's global transcript before any memory challenge exists; W, the witness columns, committed in the shard's own transcript; and S, the setup columns, bound by the program identity or by the ceremony. Beside them sit virtual tables: closed forms such as the row index or the 16-bit range, which the verifier evaluates at any point and which are never committed.

Above layer 0 every family circuit has the same anatomy:

1. Gate list 0 computes, row by row, the memory leaves (each query's read and write tuples), the lookup fractions (one (numerator, denominator) pair per lookup, plus the table's), and every enforcing gate: the family's constraints, each a polynomial that must vanish on every row.
2. Row-wise lists combine sibling leaves: a product tree multiplies tuples, a fraction tree adds fractions as (n_a·d_b + n_b·d_a, d_a·d_b), until each row holds one node per tree.
3. Halving lists, one per variable of the shard's height, combine the rows pairwise: the first half with the second. After n of them the circuit reaches a top with no variables: the shard's read root, its write root, and each lookup channel's final numerator and denominator.

So one circuit proves the family's constraints, computes its contribution to the memory argument, and sums its lookups, in one pass. Every gate has degree at most 2, so every round polynomial of every sumcheck is a cubic.

The backward pass#

The prover materializes every layer once, upward. The proof then runs downward, and its transcript schedule is the same for every circuit:

1. The outputs are absorbed first, so the prover is committed to the roots before any challenge exists.
2. For each transition from layer k + 1 down to layer k, a challenge λ batches every claim on layer k + 1, together with every enforcing gate of the list, into one sum. A sumcheck reduces that sum to an evaluation at a random point ρ, one cubic message per variable.
3. The prover states the values of layer k's columns at ρ. For a halving list it states both children, and a further challenge τ merges them into one claim per column.
4. At layer 0 every committed column has one claim, all at the same point u.

The shard's single Mercury opening proves those claims against the commitments: the memory columns' from the statement, the witness columns' from the shard proof, the setup columns' from the verifying key. Virtual tables are evaluated by the verifier itself.

Enforcing gates ride along for free. An enforcing gate claims 0 everywhere, so it joins the batch of the transition it sits in, and a violated gate makes the batched sum nonzero with overwhelming probability. A single LayerInconsistency error covers a wrong descending claim and a violated gate alike; a batched sum cannot tell them apart, and the proof spends nothing on telling them apart.

Why it is sound#

Each challenge is drawn after everything it protects:

• the output point after the outputs, so a prover cannot pick tables that agree with the truth only where it will be checked;
• λ after the claims and the point, so a false claim or a violated gate survives only at a root of a nonzero polynomial in λ;
• each sumcheck challenge after its round's cubic, so a wrong cubic agrees with the true one with probability at most 3/|Fr|;
• τ after both children's values.

Summed over every transition of a registered circuit at its default height, the soundness error stays under 2^14/|Fr|, with Fiat–Shamir over the Poseidon2 transcript in the random-oracle model.

Circuits as data#

A circuit is not code. It is a CircuitArtifact: its committed columns by name, its virtual tables, its gate lists with seven gate shapes, a flat list of the same relations, its lookups and its padding row, serialized canonically. Four laws hold every artifact to a consistent form: every operand is readable where it is read, every list's width is derived from its gates, the top layer is exactly the outputs, and the layered gates and the flat relations are one constraint set. They run once, where an artifact is built or a key is loaded, never per proof.

Two consequences matter to anyone evaluating the system:

• A verifying key carries its circuits, and the verifier holds them to its own registry. The program identity binds the program; the registry binds the circuits that prove it.
• The circuits can be checked by a second implementation. The checker crate re-implements the laws, the lookup rules and the padding contract without sharing the constructors' code, and evaluates gates only through the one gate kernel both sides use as the semantic authority.

The cost#

The engine trades commitments for memory. The forward pass holds every inner layer as field elements: about 8.4 GiB for a 2^20 shard of the widest instruction family, and 42 GiB for a 2^18 KECCAK_F shard, whose circuit computes 5,490 inner columns. That is why proving is memory-bound, why heights are a tuning parameter, and why the streaming prover bounds memory by the shards in flight. Proof size grows only by one sumcheck round per variable per layer: a KECCAK_F shard's proof is 381,100 bytes at 2^18 against 373,276 at 2^16, for four times the work.

The specification: The GKR engine, and every family's own page under Auditors.

Every column Apogee commits is a multilinear polynomial, a table of 2^n evaluations over the boolean cube. Every one of them is committed and opened with Mercury (Eagen and Gabizon, ePrint 2025/385), finished by the batched KZG opening of BDFG20 (Boneh, Drake, Fisch and Gabizon, ePrint 2020/081). The specification pins what the papers leave open and adds two things: a batch of many columns at one point, and a deferred form that the recursion tree folds.

The commitment#

A Mercury commitment is exactly the KZG commitment of the evaluation table read as coefficients: one multi-scalar multiplication over the first n powers of the ceremony's τ, one G1 point, 64 bytes. There is no second scheme behind it. Two properties follow and the rest of the system uses both:

• It is linear. The commitment of Σ ρ^i·f_i is Σ ρ^i·cm_i, which is what lets many columns share one opening.
• Zero coefficients add nothing. A column extended by zero rows keeps its commitment, so the generic lookup table's three commitments serve every height that holds the table, and they are a constant of the ceremony.

Columns are committed at their integer width: a bit, byte, halfword or word column goes through an MSM over u32 scalars, recoded from 32 bits instead of 254, which keeps committing a trace cheap.

The opening#

Mercury splits an opening point u of s = 2t variables into halves, folds the polynomial by a challenge α, and proves the two inner products that remain with a symmetrized witness, finishing with one batched KZG opening at three points. The proof is eight G1 points and six field elements: 704 bytes, for every size. Hence one requirement: the number of variables must be even, which is why every height on the menu is an even power of two.

The verifier does O(t) field operations, MSMs of ten and two points, and one pairing check of two pairs. Both relations it checks are written as e(A, [1]_2) = e(B, [x]_2), so both G2 arguments are constants of the setup and the verifier does no G2 arithmetic at all. That shape is also what lets recursion postpone the pairing instead of computing it.

A shard's columns, one opening#

The GKR pass ends with every committed column of a shard claimed at the same point u. So nothing needs a claim-merging sumcheck: the opening batches all of them. A challenge ρ, drawn after every commitment and every claimed value, weights column i by ρ^i; the prover opens Σ ρ^i·f_i once, and the verifier forms Σ ρ^i·cm_i by a k-point MSM. A false claim survives with probability at most (k − 1)/|Fr|.

The columns in the batch come from three places, in a fixed order that is part of what is proved: the memory columns' commitments from the statement, the witness columns' from the shard proof, and the setup columns' from the verifying key. Taking the setup commitments from the key is what makes the opening bind the decoded tables and the image the program identity commits.

Deferred verification#

A deferred check runs everything but the pairing and keeps the relation's terms as twelve (side, scalar, point) entries. Recursion uses exactly this: each node of the tree computes a shard's twelve scalars in its own arithmetic, weights them by fresh challenges, and adds them into one running pair of points (A, B). Every shard's opening in the whole tree folds into one claim e(A, [1]_2) = e(B, [x]_2), which only the contract on Ethereum finally checks. Recursion and settlement shows the fold.

Measured#

On an 18-core Apple M5 Pro:

Security#

Knowledge soundness holds in the algebraic group model under q-DLOG, with Fiat–Shamir over the Poseidon2 transcript in the random-oracle model, and an SRS whose τ nobody knows. The statistical terms, Schwartz–Zippel over the challenges, stay below 2^−220 for every instance in use, so the security level is BN254's, about 100 bits. Nothing is hiding and nothing is blinded: Apogee v1.0.0 is not zero-knowledge.

The SRS is the PSE perpetual powers of tau, contribution 80, sound while one contributor was honest. Its file is decoded and every point checked to lie on its curve and in the right subgroup; nothing proves that a file is that ceremony's, which is why a verifier compares the SRS digest with the ceremony's from its own channel.

The specification: Mercury, The structured reference string.

A family's gates constrain one row at a time. Everything that crosses rows, shards or families, such as what a register holds, what a load returns, which instruction a row executes and whether a value fits in 32 bits, is carried by two arguments that live inside the same GKR circuits.

The memory argument#

Every memory access becomes a field element, a tuple:

T(AS, ADDR, TS, VAL) = γ + AS + α_addr·ADDR + α_ts·TS + α_val·VAL

over the address space, the address, the timestamp and the value, with four challenges drawn once per statement. A query contributes its read tuple to one side and its write tuple to the other. Each shard's circuit outputs two numbers, the product of its read tuples and the product of its write tuples. The verifier then checks one equation over the whole statement:

∏ read roots · R_b  =  ∏ write roots · W_b          over every shard of every family

W_b and R_b are the initial and final tuples of the 32 registers and the pc, which have no rows of their own: the verifier multiplies them in from 64 boundary scalars the statement carries. RAM gets its initial and final values from the window families' shards, which hold one word per row: the program's image in window 0, zeros in every other window the run touched, the statement's input in the public input window, the prover's bytes in advice.

If the equation holds, the multisets are equal with overwhelming probability. Equal multisets mean every read returns the last write before it: each read is matched to exactly one write, a read must strictly follow the write it consumes, and every address has exactly one initial write.

Order for free#

The pc is a memory cell like any other, at address 0 of its own space. Every row reads the pc and writes the next one, and its circuit holds the write at least four timestamps after the read. So the pc's history is one path through every live row of every family, from the entry point to the exit row. That single path gives:

• program order, since rows are ordered by their pc writes;
• continuity across shards and families, since every row's pc read consumes some row's pc write;
• no cycle proved twice, since no write can be consumed twice.

No shard chains to its neighbour, and none needs to. A shard's claimed time window binds nothing; it is checked only for shape.

What must come first#

The memory challenges are drawn once per statement, at the end of the global transcript, after everything a tuple can read is fixed: every shard's memory commitments, the program identity (which fixes the entry pc and the image), the ceremony digest, the shard counts and the window list, the digest of the public input and journal, and last the 64 boundary scalars. A value chosen after the challenges could be solved for; the order of the transcript is what forbids it. For the same reason a memory tuple may read only memory, setup and virtual columns, never a witness column, which is committed in the shard's own transcript after the challenges. The circuit constructors refuse any artifact that breaks this.

Lookups#

A lookup says that a tuple of a row's values is a row of some table. Apogee proves every lookup of a shard with LogUp: one identity per table, or channel,

Σ_rows Σ_lookups 1/(E(y) + g)  −  Σ_rows mult(y)/(T(y) + g)  =  0

summed by a fraction tree inside the family's own GKR circuit and checked at its root: numerator zero, denominator nonzero. The multiplicity column needs no constraint at all: a tuple in no table row leaves a pole the multiplicities cannot cancel.

Three of the tables are virtual: closed forms of the row index that the verifier evaluates itself, which cost no commitment. The generic table is committed once by the ceremony's powers and covered by the SRS digest.

The decoder lookup#

Every execution family makes one lookup per live row into its own decoded table, keyed by the pc the row read from memory. That single lookup binds the cycle to the program: the row's operands, immediate and instruction kind are the program's at that pc, and its kind bits are one-hot because every live row of the table holds a one-hot mask and every padding row holds −1, which no sum of kind bits reaches. A row at a pc where the program has no instruction finds no table row at all.

Keys must be bounded#

A channel proves membership of a table and nothing more. Several sub-tables share the generic table under disjoint key ranges, so an unbounded key could land in the wrong sub-table and prove a false AND. Every family therefore bounds each key it looks up, with a range lookup under the same selector, and the circuit constructors check that a bound written through a scaling factor also carries a direct bound. The specification states the attack this prevents for every family.

How it adds up#

Together with each family's gates, these two arguments give the statement its meaning: each row obeys its instruction, the instruction is the program's, every read sees the last write, the rows form one path from the entry to the exit, every value is the integer it claims to be, and the public windows hold the statement's bytes. The soundness map carries each claim to the sections that prove it.

The specification: The memory argument, Lookups.

Hashing and big-integer arithmetic dominate real workloads: in a mainnet Ethereum block, secp256k1's field multiplication and squaring alone were 44% of the cycles before they were delegated. Proving them instruction by instruction is possible and slow. A delegation gives such a function a circuit family of its own, invoked from the guest, so the instruction circuits stay small and a program pays only for the delegations it calls.

The call#

A delegation is invoked, never decoded. The guest writes a frame of 32-bit words in RAM and issues an ecall with the delegation's number in a7 and the frame's base address in a0. The ecall is one row of the ADD_SUB_LUI_AUIPC family, the request. The work is one row of the delegation's own family, the invocation, which reads every frame word and writes every frame word back, the results among them, at the requesting cycle. An invocation owns no cycle; it rides the one that asked for it.

Frames are word-aligned and lie wholly in ordinary RAM, so no frame overlaps a public window or advice, and the frame's reads and writes are ordinary memory queries. What a delegation computed is therefore bound exactly as any store is: through the one memory multiset.

The anchor#

Requests and invocations must pair one to one: otherwise many requests could close against one invocation and leave calls unexecuted, or an unrequested invocation could rewrite a frame. They pair through the same memory multiset, in an anchor space that belongs to the delegation type alone and that no instruction can reach:

Three gates on the request side fix its read at timestamp 0 and value 0 and make it write 0 to a0. Then the tuples stamped 0 are exactly the requests' reads and the invocations' answers, so there are as many invocations as requests over the same bases; and since no two requests share a cycle, each invocation's read is exactly one request's write. Every invocation sits at its request's base and cycle. No gate in a delegation circuit had to know about requests at all.

Many calls, one operation#

An operation too wide for one row is several invocations on one frame, a frame word naming the step: a keccak-f[1600] permutation is 24 round calls, a SHA-256 compression 16 calls of four rounds, a complete point addition three calls. No gate joins two rows. Each call proves its step on the frame as it finds it, its reads lying on each word's single memory history, so it reads the previous step's writes. That every step runs, in order, is the calling code's to ensure, and the calling code is guest code proved as instructions. The SDK issues each multi-call operation from one function, so a guest never orders the steps by hand.

Declared statically#

The instruction sweep cannot see a call, because the number is a run-time value of a7. So each shim in the SDK leaves a 12-byte declaration record in its own linker section, kept only if the shim is reachable. The program derivation scans the image for records, and a declared family joins the configuration, bound by the identity through the image bytes. A family linked but never called proves zero shards; a called number whose family the program never declared has no proof.

The six circuits#

A few constructions recur across them. A one-code rule decodes a frame word naming one of k cases into boolean selectors with exactly one set, because codes add: without it, selectors 1 and 3 answer a request for 4. A canonicity chain proves a 256-bit value is below a modulus through borrows over 32-bit limbs. And every written word is bounded below 2^32, so that RAM stays words, which every instruction family relies on.

The economics#

A delegation family's height sets how many calls one shard holds, and a shard costs its height whatever its occupancy:

For a family with many calls, the fatter shard is the cheaper one: a KECCAK_F proof barely grows from 2^16 to 2^18. The price is memory. A 2^18 KECCAK_F shard's forward pass is 42 GiB, and two of them in flight set the measured block's peak.

What is delegated, and what is not#

Library code reaches the delegations through patched copies of k256, ark-ff and revm-precompile: secp256k1 recovery becomes k256 code over MOD_MUL and EC_ADD, and a BN254 pairing becomes ark-bn254 code over MOD_MUL. The EVM's MULMOD with an arbitrary modulus, MODEXP, BLS12-381 and every whole signature scheme run as instructions. Dedicated signature support for guests is part of the v2.0.0 trajectory.

The specification: Delegation ABI, Delegation circuits.

A full Ethereum block is about 200 million cycles. Its trace, every row of every family and every memory event, would be about 300 bytes a cycle: tens of gigabytes before a single column is committed. Apogee's prover never builds it. It executes the guest twice and holds only the shards it is working on.

Two passes#

Pass 1 executes the guest and, as each shard fills, commits its memory columns, keeps the commitments and drops the rows. At the exit it derives everything else the statement needs from the final memory state: the register and pc boundary, the list of memory windows the run touched, and the window families' shards. Then it runs the global transcript, which absorbs the statement, every memory commitment included, and draws the memory challenges and the digest every shard is seeded from.

Pass 2 executes again. The emulator is a pure function of its input, so it cuts the same shards, and pass 2 asserts that its cycle profile, window list and boundary are pass 1's. Each shard gets every committed column and is proved: its transcript, its GKR pass, its opening. The memory columns are not recommitted: the opening takes their commitments from the statement and their values from pass 2, so columns that differed between the passes would give an opening the verifier refuses.

The order is forced by soundness. The memory challenges must follow every value a memory tuple can read, so every shard's memory columns are committed before any shard can be proved.

The pipeline#

A fixed number of workers, max_in_flight, share one lock around the executor. Under the lock a worker hands back its finished shard and claims the next: a filled shard if one is waiting, and otherwise it steps the executor itself until a buffer fills. Outside the lock it builds the shard's columns, proves it and drops it.

• The executor never runs ahead of demand. At most one filled, unclaimed shard per family waits, as rows.
• Within a shard, the work is data-parallel across every core. A worker blocked in that work does not take a second shard.
• The block does not depend on the schedule. A shard's proof is a function of the global state and its own columns; proofs are placed by statement position. The bytes are identical at 1 and at 8 shards in flight.
• Failures are deterministic. The failure returned is the earliest in fill order, at any worker count.

What it costs#

Memory is a partial buffer per family, the last-access tables, the shards being worked and the output. A shard's working set is dominated by its forward pass, every inner GKR layer as field elements: 8.4 GiB for a 2^20 SHIFT_BITWISE shard, 42 GiB for a 2^18 KECCAK_F one. So max_in_flight bounds how many of those coincide, and heights set how large each is.

Measured on block 257,510 (60 transactions, 101.5 Mgas, 198M cycles, 207 shards) on 32 vCPUs and 247.7 GiB, twelve shards in flight:

The peak came from one delegation family's height, not from the twelve shards in flight. That is the lever: a block with fewer Keccak calls, or Keccak at a lower height, peaks lower.

The specification: The streaming prover.

A base proof of an Ethereum block is 207 shard proofs: 14.5 MB, each shard a GKR proof with its commitments and a Mercury opening that ends in a pairing check. A contract can check none of that directly. Recursion compresses it, and the way it does is the most consequential design choice after the GKR engine itself.

The base proof is untouched#

The first decision is what recursion does not do. No base key, statement or proof changes to make recursion possible: a leaf verifies base shards exactly as a native verifier would. Everything recursion needs is added above the base proof, never inside it. A block can be verified natively, recursed, or both, from the same bytes.

Apogee proves its own verifier#

A node of the tree is Apogee proving a verifier program. A leaf verifies a run of consecutive base shards, from from to to; an internal node verifies two to four children, each a whole proof of a leaf or node program; the root covers every base shard. Every node is proved by the same streaming prover as a base block.

Running the Rust verifier as RISC-V instructions would work, and measured 3.0 billion cycles for one block's 207 shards: fifteen times the block itself. So nodes run in a recursion format instead.

The recursion format#

A statement is in the recursion format exactly when its program declares field families. The format adds one address space and four coprocessor families on it, all invoked through the ordinary delegation ABI, and changes nothing else:

Two further changes make a recursion shard cheaper to verify by its parent. Its memory and witness columns are committed as stacks of up to 2^24 evaluations, so a parent folds a handful of points instead of hundreds. And a recursion request writes its frame base advanced past the frame, so frames laid back to back replay as back-to-back ecalls, one row a call.

Tapes#

A shard's checks have a fixed shape for its family and height. So the host compiles them, once, into a tape: a straight-line list of coprocessor calls over absolute cells, in which nothing branches on a value. A shard's tape is the native verifier's steps for that shard, call for call: the shard transcript, the GKR backward pass, the lookup and root checks, and the Mercury opening's twelve scalars. Every check is an assert-equal.

Each recursion program's tapes, fold templates and constants are built at compile time by the verifier crate itself and placed in the program's read-only data. The program identity therefore binds every tape the program replays: proving that a node ran its program is proving that it ran exactly these checks.

A transcript chained across the tree#

The base statement's global transcript is one sponge over the whole statement. The tree splits it without changing it. The node holding shard 0 runs the prefix, through the public input digest; every node absorbs its own shards' memory commitments, continuing from the state its predecessor left; the node holding the last shard runs the suffix and draws the memory challenges every node had taken as claims. A node's journal records the chain's state at both ends of its range, and a parent holds its children's states to meet.

A node also holds its children to one another: exit status 0, one base statement (its shape, digest, challenges, input and journal digest, exit status and shard count), adjacent shard ranges, chain states that meet, time windows in order across the seam, and the identities of the recursion programs. A node that holds a whole statement makes the memory argument.

Folding the pairings#

No node computes a pairing. Each shard's Mercury check is deferred as twelve (side, scalar, point) entries; after the shard's tape, the node's own transcript absorbs the shard transcript's final state and draws weights, and every entry is added, weighted, into one running pair of points (A, B) representing the claim e(A, [1]_2) = e(B, [x]_2). The batch check that ties a shard's combined commitment to its columns is folded beside it. Points every shard of a family shares, such as [1]_1 and the setup commitments, accumulate one scalar each and enter once. A child's (A, B) enters under a weight drawn after its whole journal.

Each side is one multi-scalar multiplication on FQ_OP, run as a static template: Pippenger with 8-bit digits over GLV halves, every point held to the curve, every step fixed in advance. A point costs about 400 FQ_OP calls.

At the root, the tree's whole content has collapsed: every base shard verified, the transcript run end to end, the memory argument made, and every opening folded into one pairing claim. What remains is that claim and two program identities.

The decider#

The root is still a GKR proof and some hundreds of points, which a contract cannot check. The decider is a Groth16 circuit that runs the node procedure over one child, the root, through a driver that writes rank-1 constraints instead of coprocessor calls, and holds the root's journal to the whole range of base shards. It folds nothing: each point the root owes the final pairing, with its scalar, becomes a bound wire, a value the verifier holds, committed in the proof under a fifth trapdoor rather than passed as a public input. So are the two identities, the base exit status, and the base public input and journal, byte by byte.

Apogee's Groth16 differs from the textbook in three ways: the bound-wire commitment, no blinding, and a proving key over the Lagrange basis that the powers-of-tau ceremony already publishes. Its key comes from a two-phase ceremony: phase 1 is the same ceremony file the commitments are under; phase 2 is the circuit's own, with contributions to α and β finished before any to γ, δ and η, an order that is itself part of soundness.

ApogeeVerifier.sol rebuilds the bound values from calldata, checks the Groth16 equation, folds both sides' points with ecMul and ecAdd, which also holds every point to the curve, and checks the one remaining pairing. Its constructor fixes the key, the ceremony's two G2 points and the two recursion programs' identities. A deployment serves one base program, one root shape and fixed public-value lengths.

Measured#

Block 257,510, tree on a 32-CPU machine, ceremony and decider on an 18-core laptop:

The specification: Recursion and decider. Running it yourself: Settle on-chain.

Apogee proves arbitrary RV32IMAC programs. Its reference workload, the one it is measured and tuned on, is the hardest common one: validating an Ethereum block inside the VM with revm, the Rust EVM. One library, revm_block, compiles both for the guest and for the host, and two binaries prove two different statements.

Two binaries, two statements#

The stateless validator is the one that proves blocks. It implements verify_stateless_new_payload from Ethereum's execution specifications: it decodes the request, checks the ancestor headers and the header rules against the parent, recovers every sender, executes every transaction against a pre-state held to the parent's state root by hashes, applies withdrawals and requests, and recomputes the receipts root, bloom, gas, requests hash, block access list and post-state root. The witness needs no binding of its own: the published root fixes the payload, and the witness is held to it by hashes, so a wrong witness cannot make an invalid payload valid. A verdict of false means only that this input did not validate.

Forks and conformance#

The validator names the fork by the input's schema id, with no activation schedule compiled in: Osaka, BPO1, BPO2 and Amsterdam. All 67,251 pairs of the tests-zkevm v21.0.1 release match natively, and CI holds the library to a committed subset of 34 cases covering every rule the release reaches, in both input layouts.

Delegations in practice#

Both binaries declare KECCAK_F, SHA256_COMP, MOD_MUL and EC_ADD. Keccak reaches its circuit through alloy-primitives' native-keccak hook. SHA-256, secp256k1 and BN254 reach theirs through patched copies of revm-precompile, k256 and ark-ff, each with upstream's code as its fallback path. Every sender is recovered in the guest under EIP-2's rules, with k256 arithmetic that the patches route to MOD_MUL and EC_ADD.

The binaries are built --release and proved with every family whose height is a choice at 2^20: the stateless binary's .text is about 1.96 MB, 96.6% of what a 2^20 table reaches.

The measured block#

Block 257,510 of glamsterdam-devnet-8, through revm-block-stateless: 60 transactions, 101.5 Mgas, 198 million cycles, cut into 207 shards. The base proof took 2,481 s on a 32-vCPU, 247.7 GiB machine and peaked at 174 GiB, recursion added about 2,620 s, and the contract accepted the result for 3,620,026 gas. Performance breaks each stage down.

What a block proof does not do#

• The validator takes its input from an external witness producer. eth_getProof returns the trie nodes on each key's path, but a deletion that collapses a branch needs a sibling node that is on no changed key's path. The repository's recorder therefore cannot produce stateless inputs; they come from a tests-zkevm release or the zkEVM benchmark's datasets.
• The mini-block binary proves an execution over a recorded pre-state, usually a block's first few transactions, and makes no state-root claim. Its journal grows by a record per transaction and outgrows the public window, which is why full blocks go through the stateless validator.

The specification: Ethereum blocks.

What a proof establishes#

A proof that verifies establishes that the program of a given 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 a given status, having written a given journal. Nothing is claimed of the advice. Nothing is hidden.

Assumptions#

BN254 gives about 100 bits of security. The statistical error of every protocol layer, from the sumchecks and the batched opening to the memory and lookup arguments, is far below that: under 2^14/|Fr| for a circuit's whole GKR pass, below 2^−190 for every lookup channel, below 2^−220 for every Mercury instance.

What a verifier must hold for itself#

Two values, from a channel the prover does not control:

• The program identity. Against a prover-supplied identity a proof shows only that some program ran.
• The ceremony's SRS digest. A key loads under whatever digest its own points give, so a key built over a known τ is refused only by this comparison.

The verifying key itself may come from anyone. Loading it recomputes the identity and the SRS digest from its own contents and holds its circuits to the verifier's registry: the identity binds the program, the registry binds the circuits. The verifier command-line tool compares the identity only, taking the SRS digest from the key; host::verify compares neither, and leaves its caller to check the statement's input, journal and exit status too.

Trusted code#

Soundness is the verifier's alone. It rests on 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 also trusts loader, isa and program. The last step to the chain adds the recursion programs, groth16, the decider's circuit and the contract.

The prover, the emulator, the trace builders and the proving half of the host SDK are untrusted. The prover validates nothing; a wrong input costs an honest prover a proof that fails, and a cheating prover runs none of this code anyway.

Not constant-time, not zero-knowledge#

Nothing in the code is constant-time: reductions, exponentiations, point additions and scalar ladders branch on their operands. That is harmless here because no proof is zero-knowledge, so proving keeps nothing secret. The one secret the code handles is a decider ceremony contributor's factor, which goes through the same variable-time ladder; run contributions on a machine you control.

Limits of v1.0.0#

Where the next version moves this#

Every assumption above that involves BN254, from q-DLOG and the pairing to Groth16, falls to a large enough quantum computer. The v2.0.0 trajectory is a proving core whose soundness rests on lattice problems instead.

For an auditor's view of the same model, crate by crate and argument by argument: Audit guide, Soundness map.

All end-to-end figures are block 257,510 of glamsterdam-devnet-8, proved through the stateless validator guest: 60 transactions, 101.5 Mgas, 198 million cycles. Each figure comes from the specification's measurements.

End to end#

The base proof, pass by pass#

The peak was set by one delegation family's height, not by the number of shards in flight.

A small guest#

The Quickstart's guest, 114 cycles in four instruction families, proved at 2^20 instruction heights and 2^16 window heights with two shards in flight: 7 shards, 52 s and 18 GB peak on an 18-core, 48 GiB laptop, almost all of it the two 2^20 shards being worked. The floor of a proof is set by its families and heights, not by its cycle count.

Each family's shard#

At the default heights. A shard's proof size is fixed by its circuit's shape and height; its proving cost follows its height times its circuit's width, however many rows are live.

A height changes only the number of halving lists and sumcheck rounds, not the gates: ADD_SUB_LUI_AUIPC at 2^20 has 298 inner columns and a 57,196-byte proof against 314 and 64,764 at 2^22.

Forward-pass memory#

The GKR prover holds every inner layer as field elements, 32 bytes a cell. Representative working sets:

Mercury#

On an 18-core Apple M5 Pro:

Reading these numbers#

Proving is memory-bound, and its memory follows the shards in flight and their heights, never the length of the execution. Time follows the cycle count family by family. The on-chain cost follows the number of points the root owes the final pairing, at about 9,000 gas a point. Cycle counts themselves are exact and machine-independent, so the cycle profiler is the right first tool for estimating any of the rest.

Version 1.0.0 settles the question of whether the architecture holds at full scale: a whole Ethereum block, from a Rust guest to a contract that says true. Version 2.0.0 changes what that architecture rests on and whom it serves. Its proving core moves to mathematics a quantum computer does not break, and its developer surface grows from a repository into a system that deploys applications.

The four initiatives#

The trajectory#

What carries over#

The leap is in the foundations, not in the model a builder writes against:

• The guest. Rust, RISC-V, three memory regions, an identity, a journal. Programs written for v1.0.0 keep their shape.
• The GKR engine. Layered circuits and sumcheck are defined over any field. The engine that funnels a circuit to one point is the part of Apogee that moves to the new field most directly.
• The arguments. One memory multiset over the whole execution, and LogUp channels, carry over as constructions; their tables and range arguments are re-derived for the new field's size.
• The discipline. Specification first, every layer checked against an independent oracle, every forgery class held by a tamper twin.

Why now#

A validity proof is only as quantum-safe as the system that produces it. A proof over BN254 rests on pairings and discrete logarithms, so a large enough quantum computer could forge one without touching anything the guest computed. Blockchain-native applications are meant to hold value for decades. The foundation they settle on has to outlast the machines that will one day break today's curves, and the time to move it is before those machines exist.

Read the initiatives: Post-quantum proving · Signatures for guests · The Deployment System.

What breaks, and where#

Every cryptographic assumption under Apogee v1.0.0 involves BN254. Mercury and KZG are sound under q-DLOG in the algebraic group model; the recursion tree folds pairing checks; the decider is Groth16. Shor's algorithm solves discrete logarithms on a quantum computer of sufficient size, and with them every one of these assumptions. The guest's computation would still be what it was; the proof that it ran correctly would no longer mean anything.

The commitment is where the dependence is concentrated. Every column of every shard is committed with it, every opening ends in its pairing, and recursion exists to fold those pairings. Replace the commitment, and the rest of the proving core has nothing left that depends on a discrete logarithm.

QL-01 · Lattice commitments#

A lattice commitment is a linear map, t = A·s mod q, applied to a vector s with small entries. It is binding as long as nobody can find a short vector the matrix sends to zero: Module-SIS, the assumption family under ML-DSA and ML-KEM, NIST's post-quantum standards, with worst-case reductions and decades of cryptanalysis behind it.

It keeps what made KZG so useful to Apogee and that hash-based commitments give up: it is homomorphic. Commitments to many chunks combine under challenge coefficients, and the combination opens by a single vector. Batching a shard's columns, deferring checks and folding them up a tree are linear operations, and linear operations survive the move. Merkle paths cannot be combined at all.

The price is a constraint with no analogue elsewhere: the commitment binds only short vectors, every combination makes the vector longer, and the prover must show it is still short enough. The schemes of the last two years differ mainly in how they pay that price, and they have moved fast. For polynomials of 2^30 coefficients, the published Module-SIS schemes give evaluation proofs of 53 to 72 KB, and verification fell from 2.8 seconds in 2024 to 8 to 16 milliseconds in 2026. The expository Lattice-Based Polynomial Commitment Schemes surveys them scheme by scheme and reads the numbers against the hash-based side.

QL-02 · Re-fielding#

The lattice schemes do not live in BN254's world. The leading constructions work over small prime moduli, with evaluation points drawn from an extension field to keep soundness, which fits a small-field proof system and does not fit a 254-bit one. So the commitment's move brings the field with it: v2.0.0 re-fields the arithmetization, moving every circuit from BN254's scalar field to a small field matched to the commitment.

The move pays for itself:

• Every layer gets cheaper. A GKR prover spends its time in field arithmetic, and a multiplication in a small field is a fraction of one in a 254-bit field. The engine's central economy, that intermediate layers are never committed, compounds with cheaper arithmetic on every layer that remains.
• Commitments get cheaper. Committing a trace column is a linear map over small digits, paid per nonzero entry, rather than a multi-scalar multiplication over a curve.
• The engine carries over. GKR and sumcheck are defined over any field. Challenges move to an extension field; the backward pass, the layer model and the arguments built on it keep their structure.

What has to be rebuilt is everything that assumed a large field: word-level values that fit one BN254 element with room to spare, range arguments and carries sized against a 254-bit modulus, canonicity chains, and the recursion format's field cells. Each is re-derived for the new field and specified as v1.0.0's were, with its own oracle and tamper twins.

Settlement#

Ethereum's verification precompiles today are pairing-based. How a post-quantum proving core settles on that chain, and what of the final step can rest on lattices, is part of the same programme of work, and will be specified with the same care as the core before it ships.

Back to the mission brief.

Almost every blockchain-native application asks the same question on every request: did the right key authorize this? In v1.0.0 a guest answers it with code. secp256k1 recovery is k256 running over the delegated MOD_MUL and EC_ADD circuits, which makes Ethereum's own signatures affordable, and anything else is ordinary instructions. QL-03 makes signature verification a first-class guest operation.

The schemes#

A signature scheme is cheap to prove, or not, almost entirely because of its verification algorithm: what arithmetic it does, in which field, and which hash it calls. The signer never runs inside the proof. Four designs cover the space:

All four verifiers are compute-and-compare, with no secrets and no branching on secrets, which is what makes each of them provable. The expository ZK-Friendly Signature Schemes works through each with a toy example and compares their in-circuit costs.

What decides the cost#

Two levers move every number:

• The field the prover runs over. A scheme is native when its arithmetic is the circuit's arithmetic. Which scheme is cheapest therefore follows the re-fielding of QL-02, and the selection is made with it.
• The hash. The post-quantum verifiers are dominated by their standard hash, not by their algebra. Replacing it with an arithmetic hash leaves the standard, and is the variant the zk-oriented constructions choose; keeping it is what interoperability with existing keys requires. Both have a place, and the guest decides.

For builders#

The aim is a guest that verifies an authorization the way it computes a hash today: one call, delegated to a circuit, no cryptography in the application's own code. That opens the patterns blockchain-native applications are built on: accounts whose keys are not the chain's, multi-party approval inside the state-transition function, session keys, and identities that stay valid after the curves they were born on have fallen.

Back to the mission brief.

Version 1.0.0 gives a builder a repository, its tools and this manual. Everything between a proved guest and a live application, from keys and ceremonies to verifier contracts, bridges and operations, is still the builder's to assemble. The Apogee Blockchain-Native Deployment System is the second half of the leap: a portal and a toolchain that turn a guest program into a running blockchain-native environment, and keep it running.

The modules#