instruction: better organization for the execution

Author: tcoratger

crates/leanVm/src/bytecode/instruction.rs

@@ -0,0 +1,81 @@
+use crate::{
+    bytecode::{
+        operand::{MemOrConstant, MemOrFp},
+        operation::Operation,
+    },
+    context::run_context::RunContext,
+    errors::{math::MathError, vm::VirtualMachineError},
+    memory::{manager::MemoryManager, val::MemoryValue},
+};
+
+/// Performs a basic arithmetic computation: `res = arg_a op arg_b`.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct ComputationInstruction {
+    /// The arithmetic operation to perform (`Add` or `Mul`).
+    pub operation: Operation,
+    /// The first operand of the computation.
+    pub arg_a: MemOrConstant,
+    /// The second operand of the computation.
+    pub arg_b: MemOrFp,
+    /// The memory location or constant that the result must be equal to.
+    pub res: MemOrConstant,
+}
+
+impl ComputationInstruction {
+    /// Executes a computation instruction (`res = arg_a op arg_b`), handling deduction and assertion.
+    ///
+    /// This function implements the core logic for `ADD` and `MUL` instructions. It follows
+    /// a "constraint satisfaction" model:
+    ///
+    /// 1.  **Deduction:** If exactly one of the three operands (`res`, `arg_a`, `arg_b`) is unknown
+    ///     (i.e., its memory cell is uninitialized), the function computes its value from the other
+    ///     two and writes it to memory.
+    /// 2.  **Assertion:** If all three operands are already known, the function computes `arg_a op arg_b`
+    ///     and asserts that it equals the value of `res`.
+    pub fn execute(
+        &self,
+        run_context: &RunContext,
+        memory_manager: &mut MemoryManager,
+    ) -> Result<(), VirtualMachineError> {
+        let val_a = run_context.value_from_mem_or_constant(&self.arg_a, memory_manager);
+        let val_b = run_context.value_from_mem_or_fp(&self.arg_b, memory_manager);
+        let val_res = run_context.value_from_mem_or_constant(&self.res, memory_manager);
+
+        match (val_a, val_b, val_res) {
+            // Case 1: a OP b = c — compute c
+            (Ok(MemoryValue::Int(a)), Ok(MemoryValue::Int(b)), Ok(MemoryValue::Address(addr))) => {
+                let c = self.operation.compute(a, b);
+                memory_manager.memory.insert(addr, c)?;
+            }
+            // Case 2: a OP b = c — recover b
+            (Ok(MemoryValue::Int(a)), Ok(MemoryValue::Address(addr)), Ok(MemoryValue::Int(c))) => {
+                let b = self
+                    .operation
+                    .inverse_compute(c, a)
+                    .ok_or(MathError::DivisionByZero)?;
+                memory_manager.memory.insert(addr, b)?;
+            }
+            // Case 3: a OP b = c — recover a
+            (Ok(MemoryValue::Address(addr)), Ok(MemoryValue::Int(b)), Ok(MemoryValue::Int(c))) => {
+                let a = self
+                    .operation
+                    .inverse_compute(c, b)
+                    .ok_or(MathError::DivisionByZero)?;
+                memory_manager.memory.insert(addr, a)?;
+            }
+            // Case 4: a OP b = c — assert equality
+            (Ok(MemoryValue::Int(a)), Ok(MemoryValue::Int(b)), Ok(MemoryValue::Int(c))) => {
+                let computed = self.operation.compute(a, b);
+                if computed != c {
+                    return Err(VirtualMachineError::AssertEqFailed {
+                        computed: computed.into(),
+                        expected: c.into(),
+                    });
+                }
+            }
+            _ => return Err(VirtualMachineError::TooManyUnknownOperands),
+        }
+
+        Ok(())
+    }
+}

crates/leanVm/src/bytecode/instruction/computation.rs

@@ -0,0 +1,79 @@
+use crate::{
+    bytecode::operand::MemOrFpOrConstant,
+    context::run_context::RunContext,
+    errors::{memory::MemoryError, vm::VirtualMachineError},
+    memory::{address::MemoryAddress, manager::MemoryManager, val::MemoryValue},
+};
+
+/// Performs a double-dereference memory access: `res = m[m[fp + shift_0] + shift_1]`.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct DerefInstruction {
+    /// The offset from `fp` for the first memory access, which yields a pointer.
+    pub shift_0: usize,
+    /// The offset added to the pointer from the first access to get the final address.
+    pub shift_1: usize,
+    /// The value that the result of the double dereference must be equal to.
+    pub res: MemOrFpOrConstant,
+}
+
+impl DerefInstruction {
+    /// Executes the `DEREF` instruction: `res = m[m[fp + shift_0] + shift_1]`.
+    ///
+    /// It operates using a constraint satisfaction model with two primary modes:
+    ///
+    /// 1.  **Deduction of `res`**: If the `res` operand points to an unwritten memory
+    ///     location, this function performs the double-dereference to find the final
+    ///     value and writes it into `res`'s location.
+    ///
+    /// 2.  **Constraint of `m[...]`**: If `res` holds a known value, that value is
+    ///     written to the final dereferenced address. The underlying memory model
+    ///     ensures this write is consistent, effectively asserting that
+    ///     `m[m[...]]` must equal the known `res` value.
+    pub fn execute(
+        &self,
+        run_context: &RunContext,
+        memory_manager: &mut MemoryManager,
+    ) -> Result<(), VirtualMachineError> {
+        // Resolve the `res` operand first to determine which execution path to take.
+        //
+        // This will either be
+        // - a known `Int`,
+        // - an `Address` to an unwritten cell.
+        let res_lookup_result =
+            run_context.value_from_mem_or_fp_or_constant(&self.res, memory_manager)?;
+
+        // Calculate the address of the first-level pointer, `fp + shift_0`.
+        let ptr_shift_0_addr = (run_context.fp + self.shift_0)?;
+
+        // Read the pointer from memory. It must be a `MemoryAddress` type.
+        let ptr: MemoryAddress = memory_manager.memory.get_as(ptr_shift_0_addr)?;
+
+        // Calculate the final, second-level address: `ptr + shift_1`.
+        let ptr_shift_1_addr = (ptr + self.shift_1)?;
+
+        // Branch execution based on whether `res` was a known value or an unwritten address.
+        match res_lookup_result {
+            // Case 1: `res` is an unwritten memory location.
+            //
+            // We deduce its value by reading from the final address.
+            MemoryValue::Address(addr) => {
+                // Read the value from the final dereferenced address `m[ptr + shift_1]`.
+                let value = memory_manager
+                    .get(ptr_shift_1_addr)
+                    .ok_or(MemoryError::UninitializedMemory(ptr_shift_1_addr))?;
+
+                // Write the deduced value into `res`'s memory location.
+                memory_manager.memory.insert(addr, value)?;
+            }
+            // Case 2: `res` is a known integer value.
+            //
+            // We use this value to constrain the memory at the final address.
+            MemoryValue::Int(value) => {
+                // Write the known `res` value to the final dereferenced address.
+                memory_manager.memory.insert(ptr_shift_1_addr, value)?;
+            }
+        }
+
+        Ok(())
+    }
+}

crates/leanVm/src/bytecode/instruction/deref.rs

@@ -0,0 +1,74 @@
+use p3_field::BasedVectorSpace;
+
+use crate::{
+    constant::{DIMENSION, EF, F},
+    context::run_context::RunContext,
+    errors::vm::VirtualMachineError,
+    memory::{address::MemoryAddress, manager::MemoryManager},
+};
+
+/// Degree-8 extension field multiplication of 2 elements -> 1 result.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct ExtensionMulInstruction {
+    /// An array of three offsets from `fp`. These point to the start of the 8-cell memory blocks
+    /// for the two input extension field elements and the resulting output element.
+    args: [usize; 3],
+}
+
+impl ExtensionMulInstruction {
+    /// Executes the `ExtensionMul` instruction.
+    ///
+    /// Multiplies two extension field elements stored in memory and writes the result back.
+    ///
+    /// ## Memory Layout
+    /// The instruction takes three argument offsets `[a, b, c]` from the frame pointer `fp`:
+    ///
+    /// - `fp + a`: address of a pointer to the first operand
+    /// - `fp + b`: address of a pointer to the second operand
+    /// - `fp + c`: address of a pointer to the output location
+    ///
+    /// The multiplication is:
+    ///
+    /// ```text
+    /// m_vec[ptr_out] = EF::from(m_vec[ptr_lhs]) * EF::from(m_vec[ptr_rhs])
+    /// ```
+    ///
+    /// where `ptr_lhs`, `ptr_rhs`, and `ptr_out` are memory addresses stored at `fp + args[0..=2]`.
+    pub fn execute(
+        &self,
+        run_context: &RunContext,
+        memory_manager: &mut MemoryManager,
+    ) -> Result<(), VirtualMachineError> {
+        // Get the frame pointer.
+        let fp = run_context.fp;
+
+        // Read the memory addresses where the operands and result will reside.
+        let ptr_lhs: MemoryAddress = memory_manager.memory.get_as((fp + self.args[0])?)?;
+        let ptr_rhs: MemoryAddress = memory_manager.memory.get_as((fp + self.args[1])?)?;
+        let ptr_out: MemoryAddress = memory_manager.memory.get_as((fp + self.args[2])?)?;
+
+        // Load the `[F; EF::DIMENSION]` input arrays from memory and convert them into EF elements.
+        let lhs = EF::from_basis_coefficients_slice(
+            &memory_manager
+                .memory
+                .get_array_as::<F, DIMENSION>(ptr_lhs)?,
+        )
+        .unwrap();
+
+        let rhs = EF::from_basis_coefficients_slice(
+            &memory_manager
+                .memory
+                .get_array_as::<F, DIMENSION>(ptr_rhs)?,
+        )
+        .unwrap();
+
+        // Perform the field multiplication in the extension field.
+        let product = lhs * rhs;
+
+        // Write the result converted back into `[F; EF::DIMENSION]` to memory.
+        let result_coeffs: &[F] = product.as_basis_coefficients_slice();
+        memory_manager.load_data(ptr_out, result_coeffs)?;
+
+        Ok(())
+    }
+}

crates/leanVm/src/bytecode/instruction/extension_mul.rs

@@ -0,0 +1,12 @@
+use crate::bytecode::operand::{MemOrConstant, MemOrFp};
+
+/// Conditional jump: `JumpUnlessZero`. Jumps if `condition != 0`.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct JumpIfNotZeroInstruction {
+    /// The value to check. The jump is taken if this value is not zero.
+    pub condition: MemOrConstant,
+    /// The destination `pc` for the jump.
+    pub dest: MemOrConstant,
+    /// The new value for the frame pointer (`fp`) after the instruction.
+    pub updated_fp: MemOrFp,
+}