# Beispiel-Gastprogramme

> Die Gastprogramme im Repository, jedes ein ausgearbeitetes Beispiel für einen Teil des Guest-SDK oder der Maschine. Wo Sie das Muster finden, das Sie brauchen.

Der Workspace `guests/` enthält jedes Gastprogramm (Guest), das das Repository baut und testet. Jedes existiert, um etwas zu erproben, und das macht sie zur besten Referenz für das Muster, das Sie gerade schreiben wollen. Alle bauen mit `cargo build --target riscv32imac-unknown-none-elf` aus ihrem eigenen Verzeichnis.

## Hier beginnen

| Gastprogramm | Zeigt |
| --- | --- |
| `public-io` | die drei Speicherbereiche auf einmal: Hilfsdaten (Advice), gegen die öffentliche Eingabe geprüft, bevor irgendetwas festgeschrieben wird. Das I/O-Modell in einem kleinen Programm |
| `fib` | das kleinste SDK-Gastprogramm: ein `u32` hinein, ein `u32` heraus, umlaufende Arithmetik |
| `echo`, `heap` | den Allokator: Hilfsdaten durch Heap-Puffer kopiert, `Vec` und `Box` immer wieder über den Bump-Allokator angelegt und verworfen |

## Anwendungsmuster

| Gastprogramm | Zeigt |
| --- | --- |
| `amm`, `orderbook` | 128- und 256-Bit-Ganzzahlen ohne Heap; `BTreeMap`, Sortieren und eine als Hilfsdaten gelieferte Sortierreihenfolge, die geprüft statt berechnet wird |
| `vault`, `recursion-ops` | `crates/field` und `crates/transcript` in einem Gastprogramm, die an `FR_ARITH` und `POSEIDON2` delegieren, ohne dass ein Shim benannt wird |
| `revm-block` | Ethereum-Blöcke auf revm: die Binaries `revm-block` (ein aufgezeichneter Mini-Block) und `revm-block-stateless` (der zustandslose Validator) |

## Delegationen

| Gastprogramm | Zeigt |
| --- | --- |
| `keccak-test`, `sha256-ops`, `mod-mul-ops`, `ec-ops` | `KECCAK_F`, `SHA256_COMP`, `MOD_MUL` und `EC_ADD`, jeweils im Gastprogramm gegen unabhängige Werte geprüft |
| `keccak-unused`, `recursion-unused` | gelinkte, nie aufgerufene Shims: Die Familien sind deklariert und beweisen null Shards |

## Die Maschine selbst

| Gastprogramm | Zeigt |
| --- | --- |
| `atomics` | jeden Befehl der A-Erweiterung, so wie `core::sync::atomic` ihn erzeugt. Ein einziger Hart bedeutet, dass jeder ein gewöhnliches Read-Modify-Write ist; das Gastprogramm existiert, um die Familie zu testen, nicht um die Praxis zu empfehlen |
| `opcodes` | jeden Befehl von RV32IMAC |
| `rvc-dense` | die Expansion komprimierter Befehle: eine Sequenz, komprimiert und unkomprimiert assembliert |
| `addsub`, `control`, `alu`, `mem`, `shards` | handgeschriebenes Assembly mit eigenem `_start` und ohne SDK, das mit seinem Ergebnis endet. `shards` füllt zwei `2^20`-Shards |
| `recursion` | die Verifier-Programme des Rekursionsbaums, die Binaries `leaf` und `node` |

## Das kleinste nützliche Gastprogramm

`fib` liest ein `u32`, macht so viele Fibonacci-Schritte mit umlaufender Arithmetik und schreibt das Ergebnis fest:

```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());
}
```

Eine zu kurze Eingabe ist ein Fehler und kein Fall für einen Standardwert: Ein Gastprogramm, das mit einem teilweise gefüllten Puffer weitermacht, beweist eine Aussage über Nullen. Die Addition läuft absichtlich um; ein `n` über 47, jenseits des letzten Glieds, das in 32 Bit passt, ist also eine gewöhnliche Eingabe mit einer gewöhnlichen Antwort und kein fehlgeschlagener Lauf. Und es gibt keine Hilfsdaten, weil `f_n` einen Verifier beim Prüfen genauso viel kostet wie beim Berechnen: Eine als Hilfsdaten gelieferte Antwort müsste neu berechnet werden, damit man ihr glauben kann.