Tracking PR for v0.2 release

.github/workflows/book.yml

@@ -3,7 +3,7 @@ name: AirScript book
 on:
   push:
     branches:
-      - main
+      - next
 
 jobs:
   deploy:

.gitignore

@@ -2,6 +2,9 @@
 # will have compiled files and executables
 /target/
 
+# Remove system config files generated by mac os
+**/.DS_Store
+
 # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
 # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
 Cargo.lock

CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.2.0 (2023-02-22)
+
+- Added support for named constants (scalars, vectors, and matrices).
+- Added support for intermediate variables in `boundary_constraints` and `integrity_constraints` sections (scalars, vectors, and matrices).
+- Added support for binding identifier names to groups of trace columns (in addition to single columns, which were already supported).
+- Added the `$main` and `$aux` built-ins for accessing columns in the execution trace by index.
+- [BREAKING] Replaced the `$rand` built-in for accessing random values with an explicit `random_values` declaration section, enabling use of a custom identifier for the random values array.
+- Added support for binding identifiers to specific random values or groups of random values.
+- Made significant changes to the IR, including:
+  - Moved the boundary constraints into the algebraic constraint graph.
+  - Made the trace reference more general to support additional trace segments in the future.
+  - Added analysis to differentiate between validity and transition constraints.
+  - Added the `Sub` operation and removed the `Neg` operation.
+- [FIX] Fixed a bug in the Winterfell codegen output for auxiliary transition constraints.
+- Improved the Winterfell codegen by consolidating code generation for boundary and transition constraints and removing redundant parentheses.
+
+## 0.1.0 (2022-11-10)
+
+- Initial release of AirScript, including a minimal but complete implementation of the AirScript compiler for an initial basic set of language features.

README.md

@@ -22,6 +22,8 @@ The project is organized into several crates as follows:
 | [Parser](parser) | Contains the parser for AirScript. The parser is used to parse the constraints written in AirScript into an AST. |
 | [IR](ir) | Contains the IR for AirScript, `AirIR`. `AirIR` is initialized with an AirScript AST, which it converts to an internal representation that can be optimized and used to generate code in multiple target languages. |
 | [Winterfell code generator](codegen/winterfell/) | Contains a code generator targeting the [Winterfell prover](https://github.com/novifinancial/winterfell) Rust library. The Winterfell code generator converts a provided AirScript `AirIR` into Rust code that represents the AIR as a new custom struct that implements Winterfell's `Air` trait. |
+| [AirScript Core](air-script-core) | Exports commonly used constants and structs used by the other crates. |
+| [AirScript](air-script) | Aggregates all components of the AirScript compiler into a single place and provides a CLI as an executable to transpile AIRs defined in AirScript to the specified target language. Also contains integration tests for AirScript. |
 
 ## References
 

air-script-core/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "air-script-core"
+version = "0.1.0"
+description="Core types for the AirScript compiler"
+authors = ["miden contributors"]
+readme="README.md"
+license = "MIT"
+repository = "https://github.com/0xPolygonMiden/air-script"
+categories = ["compilers", "cryptography"]
+keywords = ["air", "stark", "zero-knowledge", "zkp"]
+edition = "2021"
+rust-version = "1.65"
+
+[dependencies]

air-script-core/README.md

@@ -0,0 +1,14 @@
+# AirScript Core
+
+This crate contains the core components used by other crates in AirScript. These components include:
+
+- Access structures defined in [VectorAccess and MatrixAccess](./access.rs) structs
+- Constant structure defined in [Constant](./constant.rs) struct
+- Expression set defined in [Expression](./expression.rs) enum
+- Identifier structure defined in [Identifier](./identifier.rs) struct
+- Trace Access structures defined in [NamedTraceAccess and IndexedTraceAccess](./trace.rs) structs
+- Variable structure and Variable types defined in [variables.rs](./variable.rs)
+
+## License
+
+This project is [MIT licensed](../LICENSE).

air-script-core/src/access.rs

@@ -0,0 +1,80 @@
+use super::Identifier;
+
+/// [VectorAccess] is used to represent an element inside vector at the specified index.
+#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Clone)]
+pub struct VectorAccess {
+    name: Identifier,
+    idx: usize,
+}
+
+impl VectorAccess {
+    /// Creates a new [VectorAccess] instance with the specified identifier name and index.
+    pub fn new(name: Identifier, idx: usize) -> Self {
+        Self { name, idx }
+    }
+
+    /// Returns the name of the vector.
+    pub fn name(&self) -> &str {
+        self.name.name()
+    }
+
+    /// Returns the index of the vector access.
+    pub fn idx(&self) -> usize {
+        self.idx
+    }
+}
+
+/// [MatrixAccess] is used to represent an element inside a matrix at the specified row and column
+/// indices.
+#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Clone)]
+pub struct MatrixAccess {
+    name: Identifier,
+    row_idx: usize,
+    col_idx: usize,
+}
+
+impl MatrixAccess {
+    /// Creates a new [MatrixAccess] instance with the specified identifier name and indices.
+    pub fn new(name: Identifier, row_idx: usize, col_idx: usize) -> Self {
+        Self {
+            name,
+            row_idx,
+            col_idx,
+        }
+    }
+
+    /// Returns the name of the matrix.
+    pub fn name(&self) -> &str {
+        self.name.name()
+    }
+
+    /// Returns the row index of the matrix access.
+    pub fn row_idx(&self) -> usize {
+        self.row_idx
+    }
+
+    /// Returns the column index of the matrix access.
+    pub fn col_idx(&self) -> usize {
+        self.col_idx
+    }
+}
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub struct Range {
+    start: usize,
+    end: usize,
+}
+
+impl Range {
+    pub fn new(start: usize, end: usize) -> Self {
+        Self { start, end }
+    }
+
+    pub fn start(&self) -> usize {
+        self.start
+    }
+
+    pub fn end(&self) -> usize {
+        self.end
+    }
+}

air-script-core/src/constant.rs

@@ -0,0 +1,42 @@
+use super::Identifier;
+
+// CONSTANTS
+// ================================================================================================
+
+/// Stores a constant's name and value. There are three types of constants:
+/// - Scalar: 123
+/// - Vector: \[1, 2, 3\]
+/// - Matrix: \[\[1, 2, 3\], \[4, 5, 6\]\]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Constant {
+    name: Identifier,
+    value: ConstantType,
+}
+
+impl Constant {
+    /// Returns a new instance of a [Constant]
+    pub fn new(name: Identifier, value: ConstantType) -> Self {
+        Self { name, value }
+    }
+
+    /// Returns the name of the [Constant]
+    pub fn name(&self) -> &Identifier {
+        &self.name
+    }
+
+    /// Returns the value of the [Constant]
+    pub fn value(&self) -> &ConstantType {
+        &self.value
+    }
+}
+
+/// Type of constant. Constants can be of 3 types:
+/// - Scalar: 123
+/// - Vector: \[1, 2, 3\]
+/// - Matrix: \[\[1, 2, 3\], \[4, 5, 6\]\]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ConstantType {
+    Scalar(u64),
+    Vector(Vec<u64>),
+    Matrix(Vec<Vec<u64>>),
+}

air-script-core/src/expression.rs

@@ -0,0 +1,33 @@
+use super::{
+    Identifier, IndexedTraceAccess, ListComprehension, MatrixAccess, NamedTraceAccess, VectorAccess,
+};
+
+/// Arithmetic expressions for evaluation of constraints.
+#[derive(Debug, Eq, PartialEq, Clone)]
+pub enum Expression {
+    Const(u64),
+    /// Represents any named constant or variable.
+    Elem(Identifier),
+    /// Represents an element inside a constant or variable vector. [VectorAccess] contains the
+    /// name of the vector and the index of the element to access.
+    VectorAccess(VectorAccess),
+    /// Represents an element inside a constant or variable matrix. [MatrixAccess] contains the
+    /// name of the matrix and indices of the element to access.
+    MatrixAccess(MatrixAccess),
+    IndexedTraceAccess(IndexedTraceAccess),
+    NamedTraceAccess(NamedTraceAccess),
+    /// Represents a random value provided by the verifier. The first inner value is the name of
+    /// the random values array and the second is the index of this random value in that array
+    Rand(Identifier, usize),
+    Add(Box<Expression>, Box<Expression>),
+    Sub(Box<Expression>, Box<Expression>),
+    Mul(Box<Expression>, Box<Expression>),
+    Exp(Box<Expression>, Box<Expression>),
+    ListFolding(ListFoldingType),
+}
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub enum ListFoldingType {
+    Sum(ListComprehension),
+    Prod(ListComprehension),
+}

air-script-core/src/identifier.rs

@@ -0,0 +1,18 @@
+use std::fmt;
+
+/// [Identifier] is used to represent variable names.
+#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Clone)]
+pub struct Identifier(pub String);
+
+impl Identifier {
+    /// Returns the name of the identifier.
+    pub fn name(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for Identifier {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", &self.0)
+    }
+}

air-script-core/src/lib.rs

@@ -0,0 +1,17 @@
+mod access;
+pub use access::{MatrixAccess, Range, VectorAccess};
+
+mod constant;
+pub use constant::{Constant, ConstantType};
+
+mod expression;
+pub use expression::{Expression, ListFoldingType};
+
+mod identifier;
+pub use identifier::Identifier;
+
+mod trace;
+pub use trace::{IndexedTraceAccess, NamedTraceAccess, TraceSegment};
+
+mod variable;
+pub use variable::{Iterable, ListComprehension, Variable, VariableType};

air-script-core/src/trace.rs

@@ -0,0 +1,76 @@
+use super::Identifier;
+
+// TYPES
+// ================================================================================================
+pub type TraceSegment = u8;
+
+/// [IndexedTraceAccess] is used to represent accessing an element in the execution trace during
+/// constraint evaluation. The trace_segment specifies
+/// how many trace commitments have preceded the specified segment. `col_idx` specifies the index
+/// of the column within that trace segment, and `row_offset` specifies the offset from the current
+/// row. For example, an element in the "next" row of the "main" trace would be specified by
+/// a trace_segment of 0 and a row_offset of 1.
+#[derive(Debug, Eq, PartialEq, Clone, Copy)]
+pub struct IndexedTraceAccess {
+    trace_segment: TraceSegment,
+    col_idx: usize,
+    row_offset: usize,
+}
+
+impl IndexedTraceAccess {
+    pub fn new(trace_segment: TraceSegment, col_idx: usize, row_offset: usize) -> Self {
+        Self {
+            trace_segment,
+            col_idx,
+            row_offset,
+        }
+    }
+
+    /// Gets the trace segment of this [IndexedTraceAccess].
+    pub fn trace_segment(&self) -> TraceSegment {
+        self.trace_segment
+    }
+
+    /// Gets the column index of this [IndexedTraceAccess].
+    pub fn col_idx(&self) -> usize {
+        self.col_idx
+    }
+
+    /// Gets the row offset of this [IndexedTraceAccess].
+    pub fn row_offset(&self) -> usize {
+        self.row_offset
+    }
+}
+
+/// [NamedTraceAccess] is used to indicate a column in the trace by specifying its index within a
+/// set of trace columns with the given identifier. If the identifier refers to a single column
+/// then the index is always zero.
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub struct NamedTraceAccess {
+    name: Identifier,
+    idx: usize,
+    row_offset: usize,
+}
+
+impl NamedTraceAccess {
+    pub fn new(name: Identifier, idx: usize, row_offset: usize) -> Self {
+        Self {
+            name,
+            idx,
+            row_offset,
+        }
+    }
+
+    pub fn name(&self) -> &str {
+        self.name.name()
+    }
+
+    pub fn idx(&self) -> usize {
+        self.idx
+    }
+
+    /// Gets the row offset of this [NamedTraceAccess].
+    pub fn row_offset(&self) -> usize {
+        self.row_offset
+    }
+}