Skip to main content

Building Your Own VM

To build your own Virtual Machine (VM) without using standard structs, you can implement the abstract traits for zkVM directly instead. This guide outlines how to implement the core components of the VM using these abstract traits.

1. Abstract Traits and Their Purpose​

The abstract traits define the fundamental operations required for your VM, including memory management, stack operations, and register handling.

  • AbstractContext: Manages the context of your VM, which includes memory, registers, and stack state. Your machine struct should implement this trait.

  • AbstractMachine: Defines core machine operations like executing instructions and maintaining the VM's state.

  • AbstractMemoryMachine: Handles memory operations like reading and writing.

  • AbstractStackMachine: Manages stack operations such as pushing and popping values.

  • AbstractRegisterMachine: Facilitates interactions with registers, including getting and setting register values.

  • AbstractInstruction: Describes how each instruction is interpreted and executed within the VM.

2. Concrete Example: Implementing the Traits​

To demonstrate how to implement the abstract traits, we will create a custom state machine struct (MyMachine) and a custom instruction struct (MyInstruction).

Defining the Machine Struct​

pub struct MyMachine<K, V, const S: usize, const T: usize> {
    context: MyContext<K, V, S, T>,
    // Other necessary fields
}

impl<K, V, const S: usize, const T: usize> AbstractMachine<K, V> for MyMachine<K, V, S, T> 
where K: Base<S>, V: Base<T> {
    // Implement core machine methods such as running instructions
    
    /// Push the trace record to the trace
    fn track(&mut self, trace: Self::TraceRecord){
      // ...
    }

    /// Get the execution trace
    fn trace(&self) -> Vec<Self::TraceRecord>{
      // ...
    }
}

impl<K, V, const S: usize, const T: usize> AbstractContext<K, V, S, T> for MyContext<K, V, S, T> {
    // Implement context-specific methods for managing memory, registers, and stack
}

Implementing Memory Operations​

The AbstractMemoryMachine trait requires methods for reading and writing memory.

impl<K, V, const S: usize, const T: usize> AbstractMemoryMachine<K, V, S, T> for MyMachine<K, V, S, T> {
    fn read(&mut self, address: K) -> Result<CellInteraction<K, V>, Error> {
        // Implement read logic
    }

    fn write(&mut self, address: K, value: V) -> Result<CellInteraction<K, V>, Error> {
        // Implement write logic
    }
}

Implementing Stack Operations​

The AbstractStackMachine trait defines stack operations like push and pop.

impl<K, V, const S: usize, const T: usize> AbstractStackMachine<K, V, S, T> for MyMachine<K, V, S, T> {
    fn push(&mut self, value: V) -> Result<(u64, CellInteraction<K, V>), Error> {
        // Implement push logic
    }

    fn pop(&mut self) -> Result<(u64, CellInteraction<K, V>), Error> {
        // Implement pop logic
    }
}

Implementing Register Operations​

The AbstractRegisterMachine trait allows interaction with registers.

impl<K, V, const S: usize, const T: usize> AbstractRegisterMachine<K, V, S, T> for MyMachine<K, V, S, T> {
    fn set(&mut self, register: Register<K>, value: V) -> Result<CellInteraction<K, V>, Error> {
        // Set value in register
    }

    fn get(&mut self, register: Register<K>) -> Result<CellInteraction<K, V>, Error> {
        // Get value from register
    }
}

Implementing Instruction Operations​

The AbstractInstruction trait defines how each instruction is interpreted and executed. Here's how to implement it for a custom instruction struct (MyInstruction):

pub struct MyInstruction {
    // Define the structure of your instruction
}

impl<K, V> AbstractInstruction<K, V> for MyInstruction {
    fn execute(&self, machine: &mut dyn AbstractMachine<K, V>) -> Result<(), Error> {
        // Implement the logic to execute the instruction
        // E.g., update memory, stack, registers, etc.
    }
}

3. Using the Machine and Instruction Structs​

Once the machine and instruction structs are implemented, you can use them to create a VM object, execute a program, and generate & verify execution trace proofs.

Example VM Creation​

let my_vm = MyMachine::<KeyType, ValueType, 32, 32>::new(config_args);

Running a Program​

To execute a program, you provide a list of instructions to the machine and run them.

let instructions: Vec<MyInstruction> = vec![
    MyInstruction::new(/* params */),
    MyInstruction::new(/* params */),
    // Add more instructions
];

// Execute the program
for instruction in program {
    machine.exec(&instruction);
}

Generating and Verifying Proofs​

After execution, you can generate trace records and verify proofs.

let mut trace_record = vec![];
for x in machine.trace().into_iter() {
    trace_record.push(x);
}

// If build_and_test_circuit does not panic, then the trace is valid.
build_and_test_circuit(trace_record, 10);

4. Conclusion​

By implementing the abstract traits for memory, stack, registers, and instructions, you can create a custom VM tailored to your specific needs. This approach provides flexibility and control over the VM’s internals, allowing for a high degree of customization.