> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/a16z/jolt/llms.txt
> Use this file to discover all available pages before exploring further.

# Guest and Host Architecture

> Understanding the separation between guest programs and host environments in Jolt zkVM

Jolt zkVM follows a **guest/host architecture** that separates the program being proven (guest) from the environment that generates and verifies proofs (host).

## Guest Programs

Guest programs are RISC-V binaries that execute inside the zkVM. These programs:

* Are compiled to RISC-V (RV64IMAC) instruction set
* Run in a constrained environment with limited memory
* Cannot directly perform I/O operations
* Have all execution traced and proven

### Compilation Targets

Guest code compiles to different targets depending on the mode:

```rust theme={null}
#![cfg_attr(feature = "guest", no_std)]
```

**Feature flags:**

* `guest` - Compiles for RISC-V target, runs in zkVM
* `guest-std` - Enables `std` library support in guest (uses custom allocator)
* Without guest features - Compiles for native execution

### Memory Layout

Guests have a structured memory space defined by `MemoryLayout`:

* **Program code** - Read-only executable instructions
* **Stack** - Grows downward, configurable size
* **Heap** - Dynamic allocation, configurable size
* **Input region** - Public inputs from host
* **Output region** - Results written back to host
* **Advice regions** - Trusted and untrusted advice data

```rust theme={null}
pub struct MemoryLayout {
    pub max_input_size: u64,
    pub max_output_size: u64,
    pub max_untrusted_advice_size: u64,
    pub max_trusted_advice_size: u64,
    pub stack_size: u64,
    pub heap_size: u64,
    pub program_size: u64,
    // ... derived addresses
}
```

## Host Environment

The host is the native (x86/ARM) environment that:

* Compiles guest programs to RISC-V
* Executes the guest in the tracer/emulator
* Generates zero-knowledge proofs
* Verifies proofs
* Manages memory and I/O

### Host-Only Operations

These operations only exist in the host (feature-gated with `#[cfg(not(feature = "guest"))]`):

**Program management:**

```rust theme={null}
use jolt::host::Program;

let mut program = Program::new("guest-name");
program.set_func("my_function");
program.build(&target_dir);
```

**Preprocessing:**

```rust theme={null}
let shared_preprocessing = JoltSharedPreprocessing::new(
    bytecode,
    memory_layout,
    memory_init,
    max_trace_length,
);

let prover_preprocessing = JoltProverPreprocessing::new(shared_preprocessing);
```

**Proving:**

```rust theme={null}
let (output, proof, program_io) = prove_my_function(
    program,
    preprocessing,
    public_input,
);
```

**Verification:**

```rust theme={null}
let is_valid = verify_my_function(
    public_input,
    output,
    panic_flag,
    proof,
);
```

## Communication Between Guest and Host

### Public Inputs and Outputs

Data flows through serialized memory regions:

**Host side:**

```rust theme={null}
// Inputs are serialized and placed in guest memory
io_device.inputs.append(&mut postcard::to_stdvec(&input).unwrap());

// Outputs are read after execution
let output = postcard::from_bytes::<OutputType>(&io_device.outputs).unwrap();
```

**Guest side:**

```rust theme={null}
#[jolt::provable]
fn my_function(x: u32, y: u64) -> u128 {
    // x and y are deserialized from input region
    let result = compute(x, y);
    // result is serialized to output region
    result
}
```

### Advice (Non-Deterministic Hints)

Guests can receive additional data via the advice mechanism (see [Runtime Advice](/concepts/runtime-advice)).

## Dual-Mode Execution

Many functions in Jolt support both guest and host execution:

```rust theme={null}
#[jolt::provable]
fn fibonacci(n: u32) -> u128 {
    // This code runs in BOTH environments:
    // - Native execution (testing, development)
    // - RISC-V guest (when proving)
    let mut a = 0u128;
    let mut b = 1u128;
    for _ in 1..n {
        let sum = a + b;
        a = b;
        b = sum;
    }
    b
}
```

**In host mode:** Compiles to native code, runs directly

**In guest mode:** Compiles to RISC-V, executes in zkVM

## Example: Complete Guest/Host Flow

**Guest (`guest/src/lib.rs`):**

```rust theme={null}
#![cfg_attr(feature = "guest", no_std)]

#[jolt::provable(heap_size = 32768, max_trace_length = 65536)]
fn muldiv(a: u32, b: u32, c: u32) -> u32 {
    a * b / c
}
```

**Host (`src/main.rs`):**

```rust theme={null}
use guest::*;

fn main() {
    // Compile guest to RISC-V
    let mut program = compile_muldiv("/tmp/jolt-guest");
    
    // Preprocess
    let shared = preprocess_shared_muldiv(&mut program);
    let preprocessing = preprocess_prover_muldiv(shared);
    
    // Build prover closure
    let prove = build_prover_muldiv(program, preprocessing);
    
    // Prove execution
    let (result, proof, io) = prove(10, 20, 5);
    
    println!("Result: {}", result); // 40
    println!("Proof size: {} bytes", proof.size().unwrap());
}
```

## Key Takeaways

<CardGroup cols={2}>
  <Card title="Guest = Proven" icon="shield-check">
    Guest code runs in the zkVM and every instruction is traced and proven
  </Card>

  <Card title="Host = Prover/Verifier" icon="server">
    Host code manages compilation, proof generation, and verification
  </Card>

  <Card title="Memory Isolation" icon="layer-group">
    Guests have isolated memory with explicit I/O regions
  </Card>

  <Card title="Dual Compilation" icon="code-branch">
    Same Rust code can compile for both native (host) and RISC-V (guest)
  </Card>
</CardGroup>

## Related Concepts

* [Provable Macro](/concepts/provable-macro) - Annotate functions for proving
* [Runtime Advice](/concepts/runtime-advice) - Non-deterministic hints
* [Preprocessing](/concepts/preprocessing) - One-time setup phase