# Exemples de programmes invités

> Les programmes invités du dépôt, chacun un exemple concret d’une partie du SDK des programmes invités ou de la machine. Où chercher le motif dont vous avez besoin.

L’espace de travail `guests/` contient tous les programmes invités que le dépôt compile et teste. Chacun existe pour mettre quelque chose à l’épreuve, ce qui en fait la meilleure référence pour le motif que vous vous apprêtez à écrire. Tous se compilent avec `cargo build --target riscv32imac-unknown-none-elf` à partir de leur propre répertoire.

## Commencez ici

| Programme invité | Montre |
| --- | --- |
| `public-io` | les trois régions à la fois : des données auxiliaires (*advice*) vérifiées par rapport à l’entrée publique avant que quoi que ce soit ne soit consigné. Le modèle d’E/S en un seul petit programme |
| `fib` | le plus petit programme invité qui utilise le SDK : un `u32` en entrée, un `u32` en sortie, une arithmétique à rebouclage |
| `echo`, `heap` | l’allocateur : des données auxiliaires copiées dans des tampons du tas, des `Vec` et des `Box` créés puis abandonnés en série dans l’allocateur linéaire |

## Motifs applicatifs

| Programme invité | Montre |
| --- | --- |
| `amm`, `orderbook` | des entiers de 128 et 256 bits sans tas; `BTreeMap`, le tri, et un ordre trié fourni en données auxiliaires et vérifié plutôt que calculé |
| `vault`, `recursion-ops` | `crates/field` et `crates/transcript` dans un programme invité, qui délèguent à `FR_ARITH` et `POSEIDON2` sans nommer de shim |
| `revm-block` | des blocs Ethereum sur revm : les binaires `revm-block` (un mini-bloc enregistré) et `revm-block-stateless` (le validateur sans état) |

## Délégations

| Programme invité | Montre |
| --- | --- |
| `keccak-test`, `sha256-ops`, `mod-mul-ops`, `ec-ops` | `KECCAK_F`, `SHA256_COMP`, `MOD_MUL` et `EC_ADD`, chacune vérifiée dans le programme invité par rapport à des valeurs indépendantes |
| `keccak-unused`, `recursion-unused` | des shims liés et jamais appelés : les familles sont déclarées et prouvent zéro shard |

## La machine elle-même

| Programme invité | Montre |
| --- | --- |
| `atomics` | chaque instruction de l’extension A telle que l’émet `core::sync::atomic`. Avec un seul hart, chacune est une simple lecture-modification-écriture; ce programme existe pour tester la famille, pas pour recommander la pratique |
| `opcodes` | chaque instruction RV32IMAC |
| `rvc-dense` | le développement des instructions compressées : une même séquence assemblée avec et sans compression |
| `addsub`, `control`, `alu`, `mem`, `shards` | de l’assembleur écrit à la main, avec son propre `_start` et sans SDK, qui se termine avec son résultat. `shards` remplit deux shards de `2^20` |
| `recursion` | les programmes vérificateurs de l’arbre de récursion, binaires `leaf` et `node` |

## Le plus petit programme invité utile

`fib` lit un `u32`, effectue autant d’étapes de Fibonacci avec une arithmétique à rebouclage, et consigne le résultat :

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

Une entrée trop courte est une erreur, et non une invitation à compléter par défaut : un programme invité qui poursuit avec un tampon partiellement rempli prouve un énoncé sur des zéros. L’addition reboucle à dessein, si bien qu’un `n` supérieur à 47, au-delà du dernier terme qui tient sur 32 bits, est une entrée ordinaire avec une réponse ordinaire plutôt qu’une exécution en échec. Et il n’y a pas de données auxiliaires, parce que `f_n` coûte autant à un vérificateur à vérifier qu’à calculer : une réponse fournie en données auxiliaires devrait être recalculée pour être crue.