# Example Guests

> The guests in the repository, each a worked example of one part of the guest SDK or the machine. Where to look for the pattern you need.

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

| Guest | Shows |
| --- | --- |
| `public-io` | the three regions at once: advice checked against the public input before anything is committed. The I/O model in one small program |
| `fib` | the smallest SDK guest: a `u32` in, a `u32` out, wrapping arithmetic |
| `echo`, `heap` | the allocator: advice copied through heap buffers, `Vec` and `Box` churned through the bump allocator |

## Application patterns

| Guest | Shows |
| --- | --- |
| `amm`, `orderbook` | 128- and 256-bit integers with no heap; `BTreeMap`, sorting, and a sorted order supplied as advice and checked rather than computed |
| `vault`, `recursion-ops` | `crates/field` and `crates/transcript` in a guest, delegating to `FR_ARITH` and `POSEIDON2` with no shim named |
| `revm-block` | Ethereum blocks on revm: binaries `revm-block` (a recorded mini-block) and `revm-block-stateless` (the stateless validator) |

## Delegations

| Guest | Shows |
| --- | --- |
| `keccak-test`, `sha256-ops`, `mod-mul-ops`, `ec-ops` | `KECCAK_F`, `SHA256_COMP`, `MOD_MUL` and `EC_ADD`, each checked inside the guest against independent values |
| `keccak-unused`, `recursion-unused` | shims linked and never called: the families are declared and prove zero shards |

## The machine itself

| Guest | Shows |
| --- | --- |
| `atomics` | every A-extension instruction as `core::sync::atomic` emits it. One hart means each is a plain read-modify-write; it exists to test the family, not to recommend the practice |
| `opcodes` | every RV32IMAC instruction |
| `rvc-dense` | compressed-instruction expansion: one sequence assembled compressed and not |
| `addsub`, `control`, `alu`, `mem`, `shards` | hand-written assembly with its own `_start` and no SDK, exiting with its result. `shards` fills two `2^20` shards |
| `recursion` | the recursion tree's verifier programs, binaries `leaf` and `node` |

## The smallest useful guest

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

```rust title="guests/fib/src/main.rs"
#![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.