chore(docs): Brillig opcodes (#7722)

Co-authored-by: Tom French <15848336+TomAFrench@users.noreply.github.com>

Author: vezenovm

acvm-repo/brillig/src/black_box.rs

@@ -7,27 +7,13 @@ use serde::{Deserialize, Serialize};
 #[cfg_attr(feature = "arb", derive(proptest_derive::Arbitrary))]
 pub enum BlackBoxOp {
     /// Encrypts a message using AES128.
-    AES128Encrypt {
-        inputs: HeapVector,
-        iv: HeapArray,
-        key: HeapArray,
-        outputs: HeapVector,
-    },
+    AES128Encrypt { inputs: HeapVector, iv: HeapArray, key: HeapArray, outputs: HeapVector },
     /// Calculates the Blake2s hash of the inputs.
-    Blake2s {
-        message: HeapVector,
-        output: HeapArray,
-    },
+    Blake2s { message: HeapVector, output: HeapArray },
     /// Calculates the Blake3 hash of the inputs.
-    Blake3 {
-        message: HeapVector,
-        output: HeapArray,
-    },
+    Blake3 { message: HeapVector, output: HeapArray },
     /// Keccak Permutation function of 1600 width
-    Keccakf1600 {
-        input: HeapArray,
-        output: HeapArray,
-    },
+    Keccakf1600 { input: HeapArray, output: HeapArray },
     /// Verifies a ECDSA signature over the secp256k1 curve.
     EcdsaSecp256k1 {
         hashed_msg: HeapVector,
@@ -44,13 +30,8 @@ pub enum BlackBoxOp {
         signature: HeapArray,
         result: MemoryAddress,
     },
-
     /// Performs multi scalar multiplication over the embedded curve.
-    MultiScalarMul {
-        points: HeapVector,
-        scalars: HeapVector,
-        outputs: HeapArray,
-    },
+    MultiScalarMul { points: HeapVector, scalars: HeapVector, outputs: HeapArray },
     /// Performs addition over the embedded curve.
     EmbeddedCurveAdd {
         input1_x: MemoryAddress,
@@ -61,45 +42,32 @@ pub enum BlackBoxOp {
         input2_infinite: MemoryAddress,
         result: HeapArray,
     },
-    BigIntAdd {
-        lhs: MemoryAddress,
-        rhs: MemoryAddress,
-        output: MemoryAddress,
-    },
-    BigIntSub {
-        lhs: MemoryAddress,
-        rhs: MemoryAddress,
-        output: MemoryAddress,
-    },
-    BigIntMul {
-        lhs: MemoryAddress,
-        rhs: MemoryAddress,
-        output: MemoryAddress,
-    },
-    BigIntDiv {
-        lhs: MemoryAddress,
-        rhs: MemoryAddress,
-        output: MemoryAddress,
-    },
-    BigIntFromLeBytes {
-        inputs: HeapVector,
-        modulus: HeapVector,
-        output: MemoryAddress,
-    },
-    BigIntToLeBytes {
-        input: MemoryAddress,
-        output: HeapVector,
-    },
-    Poseidon2Permutation {
-        message: HeapVector,
-        output: HeapArray,
-        len: MemoryAddress,
-    },
-    Sha256Compression {
-        input: HeapArray,
-        hash_values: HeapArray,
-        output: HeapArray,
-    },
+    /// BigInt addition
+    BigIntAdd { lhs: MemoryAddress, rhs: MemoryAddress, output: MemoryAddress },
+    /// BigInt subtraction
+    BigIntSub { lhs: MemoryAddress, rhs: MemoryAddress, output: MemoryAddress },
+    /// BigInt multiplication
+    BigIntMul { lhs: MemoryAddress, rhs: MemoryAddress, output: MemoryAddress },
+    /// BigInt division
+    BigIntDiv { lhs: MemoryAddress, rhs: MemoryAddress, output: MemoryAddress },
+    /// BigInt from le bytes
+    BigIntFromLeBytes { inputs: HeapVector, modulus: HeapVector, output: MemoryAddress },
+    /// BigInt to le bytes
+    BigIntToLeBytes { input: MemoryAddress, output: HeapVector },
+    /// Applies the Poseidon2 permutation function to the given state,
+    /// outputting the permuted state.
+    Poseidon2Permutation { message: HeapVector, output: HeapArray, len: MemoryAddress },
+    /// Applies the SHA-256 compression function to the input message
+    Sha256Compression { input: HeapArray, hash_values: HeapArray, output: HeapArray },
+    /// Returns a decomposition in `num_limbs` limbs of the given input over the given radix.
+    ///
+    /// - The value stored in `radix` must be in the range [2, 256]
+    /// - `num_limbs` must be at least one if the value stored in `input` is not zero.
+    /// - The value stored in `output_bits` must have a `bit_size` of one.
+    ///   That value specifies whether we should decompose into bits. The value stored in
+    ///   the `radix` address must be two if the value stored in `output_bits` is equal to one.
+    ///
+    /// Native to the Brillig VM and not supported as an ACIR black box function.
     ToRadix {
         input: MemoryAddress,
         radix: MemoryAddress,

acvm-repo/brillig/src/opcodes.rs

@@ -4,14 +4,19 @@ use serde::{Deserialize, Serialize};
 
 pub type Label = usize;
 
+/// Represents an address in the VM's memory.
+/// Supports both direct and relative addressing.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
 #[cfg_attr(feature = "arb", derive(proptest_derive::Arbitrary))]
 pub enum MemoryAddress {
+    /// Specifies an exact index in the VM's memory
     Direct(usize),
+    /// Specifies an index relative to the stack pointer.
+    ///
+    /// It is resolved as the current stack pointer plus the offset stored here.
     Relative(usize),
 }
 
-/// `MemoryAddress` refers to the index in VM memory.
 impl MemoryAddress {
     pub fn direct(address: usize) -> Self {
         MemoryAddress::Direct(address)
@@ -209,7 +214,7 @@ pub enum ValueOrArray {
 pub enum BrilligOpcode<F> {
     /// Takes the fields in addresses `lhs` and `rhs`
     /// Performs the specified binary operation
-    /// and stores the value in the `result` address.
+    /// and stores the value in the `destination` address.
     BinaryFieldOp {
         destination: MemoryAddress,
         op: BinaryFieldOp,
@@ -218,7 +223,7 @@ pub enum BrilligOpcode<F> {
     },
     /// Takes the `bit_size` size integers in addresses `lhs` and `rhs`
     /// Performs the specified binary operation
-    /// and stores the value in the `result` address.
+    /// and stores the value in the `destination` address.
     BinaryIntOp {
         destination: MemoryAddress,
         op: BinaryIntOp,
@@ -236,17 +241,19 @@ pub enum BrilligOpcode<F> {
         source: MemoryAddress,
         bit_size: BitSize,
     },
+    /// Sets the program counter to the value of `location` if
+    /// the value at the `condition` address is zero.
     JumpIfNot {
         condition: MemoryAddress,
         location: Label,
     },
-    /// Sets the program counter to the value located at `destination`
+    /// Sets the program counter to the value of `location`
     /// If the value at `condition` is non-zero
     JumpIf {
         condition: MemoryAddress,
         location: Label,
     },
-    /// Sets the program counter to the label.
+    /// Sets the program counter to the value of `location`.
     Jump {
         location: Label,
     },
@@ -258,19 +265,27 @@ pub enum BrilligOpcode<F> {
     },
     /// We don't support dynamic jumps or calls
     /// See <https://github.com/ethereum/aleth/issues/3404> for reasoning
+    ///
+    /// Pushes the current program counter to the call stack as to set a return location.
+    /// Sets the program counter to the value of `location`.
     Call {
         location: Label,
     },
+    /// Stores a constant `value` with a `bit_size` in the `destination` address.
     Const {
         destination: MemoryAddress,
         bit_size: BitSize,
         value: F,
     },
+    /// Reads the address from `destination_pointer`, then stores a constant `value` with a `bit_size` at that address.
     IndirectConst {
         destination_pointer: MemoryAddress,
         bit_size: BitSize,
         value: F,
     },
+    /// Pops the top element from the call stack, which represents the return location,
+    /// and sets the program counter to that value. This operation is used to return
+    /// from a function call.
     Return,
     /// Used to get data from an outside source.
     /// Also referred to as an Oracle. However, we don't use that name as
@@ -290,6 +305,7 @@ pub enum BrilligOpcode<F> {
         /// retrieve the elements)
         input_value_types: Vec<HeapValueType>,
     },
+    /// Moves the content in the `source` address to the `destination` address.
     Mov {
         destination: MemoryAddress,
         source: MemoryAddress,
@@ -301,20 +317,26 @@ pub enum BrilligOpcode<F> {
         source_b: MemoryAddress,
         condition: MemoryAddress,
     },
+    /// Reads the `source_pointer` to obtain a memory address, then retrieves the data
+    /// stored at that address and writes it to the `destination` address.
     Load {
         destination: MemoryAddress,
         source_pointer: MemoryAddress,
     },
+    /// Reads the `destination_pointer` to obtain a memory address, then stores the value
+    /// from the `source` address at that location.
     Store {
         destination_pointer: MemoryAddress,
         source: MemoryAddress,
     },
+    /// Native functions in the VM.
+    /// These are equivalent to the black box functions in ACIR.
     BlackBox(BlackBoxOp),
-    /// Used to denote execution failure, returning data after the offset
+    /// Used to denote execution failure, halting the VM and returning data specified by a dynamically-sized vector.
     Trap {
         revert_data: HeapVector,
     },
-    /// Stop execution, returning data after the offset
+    /// Halts execution and returns data specified by a dynamically-sized vector.
     Stop {
         return_data: HeapVector,
     },

cspell.json

@@ -261,6 +261,7 @@
         "vecs",
         "Vecs",
         "vitkov",
+        "VM",
         "walkdir",
         "wasi",
         "wasmer",