moving more acir docs to code declaration and more structure documented

Author: vezenovm

acvm-repo/acir/README.md

@@ -1,110 +1,5 @@
 # ACIR documentation (draft)
 
-## Abstract
-
-This document describes the purpose of ACIR, what it is and how ACIR programs
-can be used by compilers and proving systems. It is intended to be a reference
-documentation for ACIR.
-
-## Introduction
-
-The purpose of ACIR is to make the link between a generic proving system, such
-as Aztec's Barretenberg, and a frontend, such as Noir, which describes user
-specific computations.
-
-More precisely, Noir is a programming language for zero-knowledge proofs (ZKP)
-which allows users to write programs in an intuitive way using a high-level
-language close to Rust syntax. Noir is able to generate a proof of execution of
-a Noir program, using an external proving system. However, proving systems use
-specific low-level constrain-based languages. Similarly, frontends have their
-own internal representation in order to represent user programs.
-
-The goal of ACIR is to provide a generic open-source intermediate
-representation close to proving system 'languages', but agnostic to a specific
-proving system, that can be used both by proving system as well as a target for
-frontends. So, at the end of the day, an ACIR program is just another
-representation of a program, dedicated to proving systems.
-
-## Abstract Circuit Intermediate Representation
-ACIR stands for abstract circuit intermediate representation:
-- **abstract circuit**: circuits are a simple computation model where basic
-    computation units, named gates, are connected with wires. Data flows
-    through the wires while gates compute output wires based on their input.
-    More formally, they are directed acyclic graphs (DAG) where the vertices
-    are the gates and the edges are the wires. Due to the immutability nature
-    of the wires (their value does not change during an execution), they are
-    well suited for describing computations for ZKPs. Furthermore, we do not
-    lose any expressiveness when using a circuit as it is well known that any
-    bounded computation can be translated into an arithmetic circuit (i.e a
-    circuit with only addition and multiplication gates).
-The term abstract here simply means that we do not refer to an actual physical
-circuit (such as an electronic circuit). Furthermore, we will not exactly use
-the circuit model, but another model even better suited to ZKPs, the constraint
-model (see below).
-- **intermediate representation**: The ACIR representation is intermediate
-because it lies between a frontend and its proving system. ACIR bytecode makes
-the link between noir compiler output and the proving system backend input.
-
-## The constraint model
-
-The first step for generating a proof that a specific program was executed, is
-to execute this program. Since the proving system is going to handle ACIR
-programs, we need in fact to execute an ACIR program, using the user-supplied
-inputs.
-
-In ACIR terminology, the gates are called opcodes and the wires are called
-partial witnesses. However, instead of connecting the opcodes together through
-wires, we create constraints: an opcode constraints together a set of wires.
-This constraint model trivially supersedes the circuit model. For instance, an
-addition gate `output_wire = input_wire_1 + input_wire_2` can be expressed with
-the following arithmetic constraint:
-`output_wire - (input_wire_1 + input_wire_2) = 0`
-
-
-## Solving
-
-Because of these constraints, executing an ACIR program is called solving the
-witnesses. From the witnesses representing the inputs of the program, whose
-values are supplied by the user, we find out what the other witnesses should be
-by executing/solving the constraints one-by-one in the order they were defined.
-
-For instance, if `input_wire_1` and `input_wire_2` values are supplied as `3` and
-`8`, then we can solve the opcode
-`output_wire - (input_wire_1 + input_wire_2) = 0` by saying that `output_wire` is
-`11`.
-
-In summary, the workflow is the following:
-1. user program -> (compilation) ACIR, a list of opcodes which constrain
-    (partial) witnesses
-2. user inputs + ACIR -> (execution/solving) assign values to all the
-    (partial) witnesses
-3. witness assignment + ACIR -> (proving system) proof
-
-Although the ordering of opcode does not matter in theory, since a system of
-equations is not dependent on its ordering, in practice it matters a lot for the
-solving (i.e the performance of the execution). ACIR opcodes **must be ordered**
-so that each opcode can be resolved one after the other.
-
-The values of the witnesses lie in the scalar field of the proving system. We
-will refer to it as `FieldElement` or ACIR field. The proving system needs the
-values of all the partial witnesses and all the constraints in order to generate
-a proof.
-
-*Remark*: The value of a partial witness is unique and fixed throughout a program
-    execution, although in some rare cases, multiple values are possible for a
-    same execution and witness (when there are several valid solutions to the
-    constraints). Having multiple possible values for a witness may indicate that
-    the circuit is not safe.
-
-*Remark*: Why do we use the term partial witnesses? It is because the proving
-    system may create other constraints and witnesses (especially with
-    `BlackBoxFuncCall`, see below). A proof refers to a full witness assignments
-    and their constraints. ACIR opcodes and their partial witnesses are still an
-    intermediate representation before getting the full list of constraints and
-    witnesses. For the sake of simplicity, we will refer to witness instead of
-    partial witness from now on.
-
-
 ## ACIR Reference
 
 We assume here that the proving system is Barretenberg. Some parameters may

acvm-repo/acir/src/circuit/brillig.rs

@@ -1,3 +1,5 @@
+//! [Brillig][brillig] structures for integration within an ACIR circuit.
+
 use super::opcodes::BlockId;
 use crate::native_types::{Expression, Witness};
 use brillig::Opcode as BrilligOpcode;

acvm-repo/acir/src/circuit/mod.rs

@@ -1,3 +1,5 @@
+//! The Abstract Circuit Intermediate Representation (ACIR)
+
 pub mod black_box_functions;
 pub mod brillig;
 pub mod opcodes;
@@ -39,7 +41,7 @@ pub enum ExpressionWidth {
     },
 }
 
-/// A program represented by multiple ACIR circuits. The execution trace of these
+/// A program represented by multiple ACIR [circuit][Circuit]'s. The execution trace of these
 /// circuits is dictated by construction of the [crate::native_types::WitnessStack].
 #[derive(Clone, PartialEq, Eq, Serialize, Deserialize, Default, Hash)]
 #[cfg_attr(feature = "arb", derive(proptest_derive::Arbitrary))]
@@ -48,13 +50,20 @@ pub struct Program<F: AcirField> {
     pub unconstrained_functions: Vec<BrilligBytecode<F>>,
 }
 
+/// Representation of a single ACIR circuit. The execution trace of this structure
+/// is dictated by the construction of a [crate::native_types::WitnessMap]
 #[derive(Clone, PartialEq, Eq, Serialize, Deserialize, Default, Hash)]
 #[cfg_attr(feature = "arb", derive(proptest_derive::Arbitrary))]
 pub struct Circuit<F: AcirField> {
-    // current_witness_index is the highest witness index in the circuit. The next witness to be added to this circuit
-    // will take on this value. (The value is cached here as an optimization.)
+    /// current_witness_index is the highest witness index in the circuit. The next witness to be added to this circuit
+    /// will take on this value. (The value is cached here as an optimization.)
     pub current_witness_index: u32,
+    /// The circuit opcodes representing the relationship between witness values.
+    ///
+    /// The opcodes should be further converted into a backend-specific circuit representation.
+    /// When initial witness inputs are provided, these opcodes can also be used for generating an execution trace.
     pub opcodes: Vec<Opcode<F>>,
+    /// Maximum width of the [expression][Expression]'s which will be constrained
     pub expression_width: ExpressionWidth,
 
     /// The set of private inputs to the circuit.
@@ -76,20 +85,32 @@ pub struct Circuit<F: AcirField> {
     pub assert_messages: Vec<(OpcodeLocation, AssertionPayload<F>)>,
 }
 
+/// Enumeration of either an [expression][Expression] or a [memory identifier][BlockId].
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Hash)]
 #[cfg_attr(feature = "arb", derive(proptest_derive::Arbitrary))]
 pub enum ExpressionOrMemory<F> {
     Expression(Expression<F>),
     Memory(BlockId),
 }
 
+/// Payload tied to an assertion failure.
+/// This data allows users to specify feedback upon a constraint not being satisfied in the circuit.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Hash)]
 #[cfg_attr(feature = "arb", derive(proptest_derive::Arbitrary))]
 pub struct AssertionPayload<F> {
+    /// Selector that maps a hash of either a constant string or an internal compiler error type
+    /// to an ABI type. The ABI type should then be used to appropriately resolve the payload data.
     pub error_selector: u64,
+    /// The dynamic payload data.
+    ///
+    /// Upon fetching the appropriate ABI type from the `error_selector`, the values
+    /// in this payload can be decoded into the given ABI type.
+    /// The payload is expected to be empty in the case of a constant string
+    /// as the string can be contained entirely within the error type and ABI type.
     pub payload: Vec<ExpressionOrMemory<F>>,
 }
 
+/// Value for differentiating error types. Used internally by an [AssertionPayload].
 #[derive(Debug, Copy, PartialEq, Eq, Hash, Clone, PartialOrd, Ord)]
 pub struct ErrorSelector(u64);
 
@@ -123,12 +144,19 @@ impl<'de> Deserialize<'de> for ErrorSelector {
     }
 }
 
+/// A dynamic assertion payload whose data has been resolved.
+/// This is instantiated upon hitting an assertion failure.
 #[derive(Clone, PartialEq, Eq, Debug, Serialize, Deserialize)]
 pub struct RawAssertionPayload<F> {
+    /// Selector to the respective ABI type the data in this payload represents
     pub selector: ErrorSelector,
+    /// Resolved data that represents some ABI type.
+    /// To be decoded in the final step of error resolution.
     pub data: Vec<F>,
 }
 
+/// Enumeration of allowed assertion payloads.
+/// These can either be static strings or dynamic payloads.
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub enum ResolvedAssertionPayload<F> {
     String(String),
@@ -156,6 +184,8 @@ pub enum OpcodeLocation {
     Brillig { acir_index: usize, brillig_index: usize },
 }
 
+/// Index of Brillig opcode within a list of Brillig opcodes.
+/// To be used by callers for resolving debug information.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
 pub struct BrilligOpcodeLocation(pub usize);
 

acvm-repo/acir/src/circuit/opcodes.rs

@@ -1,3 +1,6 @@
+//! ACIR opcodes
+//!
+//! This module defines the core set opcodes used in ACIR.
 use super::brillig::{BrilligFunctionId, BrilligInputs, BrilligOutputs};
 
 pub mod function_id;
@@ -29,6 +32,9 @@ impl BlockType {
     }
 }
 
+/// Defines an operation within an ACIR circuit
+///
+/// Expects a type parameter `F` which implements [AcirField].
 #[allow(clippy::large_enum_variant)]
 #[derive(Clone, PartialEq, Eq, Serialize, Deserialize, Hash)]
 #[cfg_attr(feature = "arb", derive(proptest_derive::Arbitrary))]

acvm-repo/acir/src/circuit/opcodes/memory_operation.rs

@@ -2,6 +2,7 @@ use crate::native_types::{Expression, Witness};
 use acir_field::AcirField;
 use serde::{Deserialize, Serialize};
 
+/// Identifier for a block of memory
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Hash, Copy, Default)]
 #[cfg_attr(feature = "arb", derive(proptest_derive::Arbitrary))]
 pub struct BlockId(pub u32);

acvm-repo/acir/src/lib.rs

@@ -1,10 +1,105 @@
+//! The Abstract Circuit Intermediate Representation (ACIR)
+//!
+//! The purpose of ACIR is to make the link between a generic proving system, such
+//! as Aztec's Barretenberg, and a frontend, such as Noir, which describes user
+//! specific computations.
+//!
+//! More precisely, Noir is a programming language for zero-knowledge proofs (ZKP)
+//! which allows users to write programs in an intuitive way using a high-level
+//! language close to Rust syntax. Noir is able to generate a proof of execution of
+//! a Noir program, using an external proving system. However, proving systems use
+//! specific low-level constrain-based languages. Similarly, frontends have their
+//! own internal representation in order to represent user programs.
+//!
+//! The goal of ACIR is to provide a generic open-source intermediate
+//! representation close to proving system 'languages', but agnostic to a specific
+//! proving system, that can be used both by proving system as well as a target for
+//! frontends. So, at the end of the day, an ACIR program is just another
+//! representation of a program, dedicated to proving systems.
+//!
+//! ## Abstract Circuit Intermediate Representation
+//! ACIR stands for abstract circuit intermediate representation:
+//! - **abstract circuit**: circuits are a simple computation model where basic
+//!     computation units, named gates, are connected with wires. Data flows
+//!     through the wires while gates compute output wires based on their input.
+//!     More formally, they are directed acyclic graphs (DAG) where the vertices
+//!     are the gates and the edges are the wires. Due to the immutability nature
+//!     of the wires (their value does not change during an execution), they are
+//!     well suited for describing computations for ZKPs. Furthermore, we do not
+//!     lose any expressiveness when using a circuit as it is well known that any
+//!     bounded computation can be translated into an arithmetic circuit (i.e a
+//!     circuit with only addition and multiplication gates).
+//!     The term abstract here simply means that we do not refer to an actual physical
+//!     circuit (such as an electronic circuit). Furthermore, we will not exactly use
+//!     the circuit model, but another model even better suited to ZKPs, the constraint
+//!     model (see below).
+//! - **intermediate representation**: The ACIR representation is intermediate
+//!   because it lies between a frontend and its proving system. ACIR bytecode makes
+//!   the link between noir compiler output and the proving system backend input.
+//!
+//! ## The constraint model
+//!
+//! The first step for generating a proof that a specific program was executed, is
+//! to execute this program. Since the proving system is going to handle ACIR
+//! programs, we need in fact to execute an ACIR program, using the user-supplied
+//! inputs.
+//!
+//! In ACIR terminology, the gates are called opcodes and the wires are called
+//! partial witnesses. However, instead of connecting the opcodes together through
+//! wires, we create constraints: an opcode constraints together a set of wires.
+//! This constraint model trivially supersedes the circuit model. For instance, an
+//! addition gate `output_wire = input_wire_1 + input_wire_2` can be expressed with
+//! the following arithmetic constraint:
+//! `output_wire - (input_wire_1 + input_wire_2) = 0`
+//!
+//! ## Solving
+//!
+//! Because of these constraints, executing an ACIR program is called solving the
+//! witnesses. From the witnesses representing the inputs of the program, whose
+//! values are supplied by the user, we find out what the other witnesses should be
+//! by executing/solving the constraints one-by-one in the order they were defined.
+//!
+//! For instance, if `input_wire_1` and `input_wire_2` values are supplied as `3` and
+//! `8`, then we can solve the opcode
+//! `output_wire - (input_wire_1 + input_wire_2) = 0` by saying that `output_wire` is
+//! `11`.
+//!
+//! In summary, the workflow is the following:
+//! 1. user program -> (compilation) ACIR, a list of opcodes which constrain
+//!     (partial) witnesses
+//! 2. user inputs + ACIR -> (execution/solving) assign values to all the
+//!     (partial) witnesses
+//! 3. witness assignment + ACIR -> (proving system) proof
+//!
+//! Although the ordering of opcode does not matter in theory, since a system of
+//! equations is not dependent on its ordering, in practice it matters a lot for the
+//! solving (i.e the performance of the execution). ACIR opcodes **must be ordered**
+//! so that each opcode can be resolved one after the other.
+//!
+//! The values of the witnesses lie in the scalar field of the proving system. We
+//! will refer to it as `FieldElement` or ACIR field. The proving system needs the
+//! values of all the partial witnesses and all the constraints in order to generate
+//! a proof.
+//!
+//! _Remark_: The value of a partial witness is unique and fixed throughout a program
+//!     execution, although in some rare cases, multiple values are possible for a
+//!     same execution and witness (when there are several valid solutions to the
+//!     constraints). Having multiple possible values for a witness may indicate that
+//!     the circuit is not safe.
+//!
+//! _Remark_: Why do we use the term partial witnesses? It is because the proving
+//!     system may create other constraints and witnesses (especially with
+//!     `BlackBoxFuncCall`, see below). A proof refers to a full witness assignments
+//!     and their constraints. ACIR opcodes and their partial witnesses are still an
+//!     intermediate representation before getting the full list of constraints and
+//!     witnesses. For the sake of simplicity, we will refer to witness instead of
+//!     partial witness from now on.
+
 #![cfg_attr(not(test), forbid(unsafe_code))] // `std::env::set_var` is used in tests.
 #![warn(unreachable_pub)]
 #![warn(clippy::semicolon_if_nothing_returned)]
 #![cfg_attr(not(test), warn(unused_crate_dependencies, unused_extern_crates))]
 
-// Arbitrary Circuit Intermediate Representation
-
 pub mod circuit;
 pub mod native_types;
 mod proto;