> ## 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.

# Architecture

> Technical overview of Stoffel VM's register-based architecture with separate clear and secret value handling.

Stoffel VM is a register based virtual machine with two sets of registers. Clear registers for manipulating non-secret values. Secret registers are used for manipulating secret values.

<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 and secret registers, runtime stores, and MPC protocol hooks." width="1200" height="675" data-path="images/diagrams/vm-execution-model.svg" />

<img src="https://mintcdn.com/stoffellabs/WsJVEVCX73RSUEma/images/campaign/stoffel-stack.png?fit=max&auto=format&n=WsJVEVCX73RSUEma&q=85&s=9ad9008238577cc8c9f85582081b8647" alt="Campaign-style Stoffel stack diagram showing how applications, SDKs, Stoffel language and CLI, VM bytecode, and the privacy backend layer together." width="1800" height="1125" data-path="images/campaign/stoffel-stack.png" />

## Technical Overview

### [Virtual Machine Architecture](./subsections/virtualmachine)

* What type of VM is stoffel
* Clear vs Secret values

### [Instruction Set](./subsections/instructionset)

* Complete reference of supported VM instructions
* Opcode specifications and behavior
* Optimization opportunities

### [Builtin Types](./subsections/builtintypes)

* Overview of core data types (numbers, strings, arrays, etc.)
* Type conversion and manipulation
* Memory representation and optimization

### [Activation Records](./subsections/activationrecords)

* Call stack management and function invocation
* Local variable scoping and lifetime
* Optimizing stack frame allocation

### [VM Functions](./subsections/vmfunctions)

* Virtual machine architecture overview
* Execution model and stack management
* Error handling

### [Closures Overview](./subsections/closures)

* Lexical scoping and variable capture
* Implementation details and memory management

### [Foreign Function Interface](./subsections/foreignfunctioninterface)

* Integrating with external libraries and systems
* Data marshalling and type conversion
* Performance considerations for FFI calls

### [Builtin Methods](./subsections/builtinmethods)

* Standard library functions and utilities
* Common operations for each data type

### [Runtime Hooks](./subsections/runtimehooks)

* Extension points for monitoring and customization
* Performance profiling and instrumentation
* Debugging facilities

## Why a Register Machine?

The choice of a register-based architecture over a stack-based design was driven by several key factors:

1. **Parallelization Opportunities**
   * Register machines allow for easier identification of independent instructions
   * Multiple instructions can be executed in parallel, reducing overall execution time
   * Better suited for modern hardware architectures

2. **Communication Efficiency**
   * Reduced number of memory access operations
   * Fewer rounds of communication in Multi-Party Computation (MPC) contexts
   * More efficient instruction encoding

3. **Optimization Potential**
   * Direct access to operands enables better optimization strategies
   * Easier to implement specialized instructions
   * More straightforward analysis of data flow

## Why dedicated clear and secret registers

1. **Implicit reveal and hide**
   * Having dedicated registers for secret and clear values allows us to implicitly reveal and hide values as they're moved between registers.
   * Separation of registers allows for optimizations to be applied specifically to clear or secret operations.
   * Avoids having to track the type of the virtual register during runtime as values may become secret shared or reveal through the course of execution.