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

# VM Architecture Details

> Detailed Stoffel VM architecture including dual register spaces for clear and secret values in MPC operations.

This section covers the detailed architectural design of Stoffel VM. For implementation details and current status, see [Stoffel VM Implementation Details](../stoffel-vm/implementation).

<img src="https://mintcdn.com/stoffellabs/WsJVEVCX73RSUEma/images/diagrams/vm-execution-model.svg?fit=max&auto=format&n=WsJVEVCX73RSUEma&q=85&s=3904911081be82c388b652e51f6e8ea5" alt="Stoffel VM execution model showing bytecode, the instruction dispatcher, clear registers, secret registers, runtime stores, and MPC protocol hooks." width="1200" height="675" data-path="images/diagrams/vm-execution-model.svg" />

## Register Architecture

Stoffel VM uses a register-based architecture with two distinct register spaces:

### Clear Registers

* Store public/non-secret values
* Direct CPU register mapping for performance
* Standard arithmetic and logical operations
* No cryptographic overhead

### Secret Registers

* Store secret-shared values for MPC
* Protocol-agnostic secret handling
* Automatic secret sharing and reconstruction
* MPC-optimized operations

## Memory Model

### Object Store

* Dynamic object allocation with reference counting
* Key-value mappings for flexible data structures
* Garbage collection integration points

### Array Store

* Contiguous memory layout for arrays
* Dynamic resizing capabilities
* Index bounds checking

### Stack Management

* Function call activation records
* Parameter passing via argument stack
* Local variable storage

## Instruction Pipeline

### Fetch-Decode-Execute Cycle

1. **Instruction Fetch**: Retrieve next instruction from program counter
2. **Decode**: Parse instruction opcode and operands
3. **Execute**: Perform operation with register/memory access
4. **Writeback**: Store result in destination register

### Hook Integration Points

* Pre-instruction hooks for debugging
* Post-instruction hooks for monitoring
* Register access hooks for MPC protocol integration
* Memory operation hooks for garbage collection

## Type System Integration

### Value Types

The VM supports a rich type system with runtime type information:

* Primitive types (integers, floats, booleans, strings)
* Complex types (objects, arrays, closures)
* Foreign objects for host language integration

### Type Safety

* Runtime type checking for operations
* Type coercion rules for mixed operations
* Error handling for type mismatches

## Closure System

### Lexical Scoping

* True lexical scoping with upvalue capture
* Closure creation with environment capture
* Upvalue sharing between closures

### Function Calls

* Dynamic function dispatch
* Parameter binding and local variable allocation
* Return value handling

## Protocol Integration

### MPC Protocol Interface

* Abstract protocol operations for secret sharing
* Reveal operations for secret-to-clear transitions
* Communication round optimization

### Clear/Secret Transitions

* Automatic hiding (clear → secret) on register moves
* Explicit revealing (secret → clear) operations
* Type preservation during transitions

This architectural design enables efficient MPC computation while maintaining the flexibility to support different protocols and optimization strategies.
