Implement Goldilocks example

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace] 
-members = [ "latticefold", "cyclotomic-rings"]
+members = [ "latticefold", "cyclotomic-rings", "latticefold-examples"]
 resolver = "2"
 
 [workspace.package]
@@ -19,7 +19,7 @@ lattirust-ring = { git = "ssh://[email protected]/NethermindEth/lattirust.git", bra
 num-bigint = { version = "0.4.5", default-features = false }
 rand = { version = "0.8.5", default-features = false }
 thiserror = { version = "2.0.3", default-features = false }
-
+cyclotomic-rings = { path = "cyclotomic-rings", default-features = false }
 [workspace.metadata.docs.rs]
 # To build locally, use 
 # RUSTDOCFLAGS="--html-in-header docs-header.html" cargo doc --no-deps --document-private-items --open

README.md

@@ -33,6 +33,10 @@ Available packages:
 - `latticefold`: main crate, contains the non-interactive folding scheme implementation, together with the Ajtai commitment scheme, R1CS/CCS structures, Fiat-Shamir transcript machinery, etc.
 - `cyclotomic-rings`: contains the trait definition of a ring suitable to be used in the LatticeFold protocol, a few ready-to-use rings and short challenge set machinery.
 
+## Examples
+
+Check [latticefold-examples/README.md](examples/README.md) for examples.
+
 ## Frontends
 
 Currently, the only way to define a circuit to be folded is by specifying it as a [rank-1 constraint system (R1CS)](https://github.com/NethermindEth/latticefold/blob/main/latticefold/src/arith/r1cs.rs) or a [customizable constraint system (CCS)](https://github.com/NethermindEth/latticefold/blob/main/latticefold/src/arith.rs).

latticefold-examples/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "examples"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+ark-ff = { workspace = true }
+ark-serialize = { workspace = true }
+ark-std = { workspace = true }
+latticefold = { path = "../latticefold", default-features = false }
+cyclotomic-rings = { workspace = true }
+lattirust-linear-algebra = { workspace = true }
+lattirust-poly = { workspace = true }
+lattirust-ring = { workspace = true }
+
+[dev-dependencies]
+humansize = "2.1.3"

latticefold-examples/README.md

@@ -0,0 +1,87 @@
+# Examples README
+
+This file explains how to use the examples in this repository. Examples demonstrate functionality and can be customized using environment variables. Instructions are provided for Linux/MacOS (bash/zsh) and Windows (PowerShell).
+
+## Implemented examples
+* goldilocks
+
+## Customization with Environment Variables
+
+The examples in this repository support customization via environment variables. You can modify the following parameters to tailor the behavior of the examples:
+
+- **`DECOMPOSITION_B`**: Sets the value of `B` in `DecompositionParams`.
+    - Default: `32768` (equivalent to `1 << 15`)
+- **`DECOMPOSITION_L`**: Sets the value of `L` in `DecompositionParams`.
+    - Default: `5`
+- **`DECOMPOSITION_B_SMALL`**: Sets the value of `B_SMALL` in `DecompositionParams`.
+    - Default: `2`
+- **`DECOMPOSITION_K`**: Sets the value of `K` in `DecompositionParams`.
+    - Default: `15`
+- **`DECOMPOSITION_C`**: Sets the value of `C`, controlling challenge set parameters.
+    - Default: `4`
+- **`DECOMPOSITION_WIT_LEN`**: Sets the witness length.
+    - Default: `4`
+
+These parameters influence the behavior and output of the examples.
+
+## Setting Environment Variables
+
+### Linux/MacOS (bash/zsh)
+
+1. Open a terminal.
+2. Export the desired environment variables before running the examples. For example:
+
+   ```bash
+   export DECOMPOSITION_B=65536
+   export DECOMPOSITION_L=6
+   export DECOMPOSITION_B_SMALL=3
+   export DECOMPOSITION_K=16
+   export DECOMPOSITION_C=5
+   export DECOMPOSITION_WIT_LEN=5
+
+   cargo run --example <example_name>
+   ```
+
+3. Replace `<example_name>` with the name of the example you want to run.
+
+### Windows (PowerShell)
+
+1. Open PowerShell.
+2. Set the desired environment variables before running the examples. For example:
+
+   ```powershell
+   $env:DECOMPOSITION_B=65536
+   $env:DECOMPOSITION_L=6
+   $env:DECOMPOSITION_B_SMALL=3
+   $env:DECOMPOSITION_K=16
+   $env:DECOMPOSITION_C=5
+   $env:DECOMPOSITION_WIT_LEN=5
+
+   cargo run --example <example_name>
+   ```
+
+3. Replace `<example_name>` with the name of the example you want to run.
+
+## Example Output
+
+When you modify environment variables, the generated parameters are automatically updated in the example's output. This allows for testing different configurations and validating results under various conditions.
+
+## Default Values
+
+If no environment variables are specified, the examples will run with the following defaults:
+
+- `DECOMPOSITION_B`: `32768`
+- `DECOMPOSITION_L`: `5`
+- `DECOMPOSITION_B_SMALL`: `2`
+- `DECOMPOSITION_K`: `15`
+- `DECOMPOSITION_C`: `4`
+- `DECOMPOSITION_WIT_LEN`: `4`
+
+## Notes
+
+- Ensure you rebuild the examples after modifying environment variables to see the changes.
+  ```bash
+  cargo clean && cargo run --example <example_name>
+  ```
+
+- For detailed instructions on each example, refer to the example's source code or inline comments.

latticefold-examples/build.rs

@@ -0,0 +1,48 @@
+use std::fs;
+use std::path::Path;
+
+fn main() -> Result<(), String> {
+    let out_dir = std::env::var("OUT_DIR").unwrap();
+
+    let dest_path = Path::new(&out_dir).join("generated.rs");
+
+    let generated_code = format!(
+        r#"
+        // This file was automatically generated by build.rs script.
+        // It can be used in examples with include! macro:
+        //     include!(concat!(env!("OUT_DIR"), "/generated.rs"));
+        //
+        // Check examples/README.md file how to use environment variables to modify the file
+
+        use latticefold::decomposition_parameters::DecompositionParams;
+
+        #[derive(Clone)]
+        pub struct ExampleDP {{}}
+
+        impl DecompositionParams for ExampleDP {{
+            const B: u128 = {}; // Default: 1 << 15
+            const L: usize = {}; // Default: 5
+            const B_SMALL: usize = {}; // Default = 2
+            const K: usize = {}; // Default = 15
+        }}
+
+        const C: usize = {}; // Default = 4
+        const WIT_LEN: usize = {}; // Default = 4
+        const W: usize = WIT_LEN * ExampleDP::L;
+
+        "#,
+        std::env::var("PARAM_B").unwrap_or("1 << 15".to_string()),
+        std::env::var("PARAM_L").unwrap_or("5".to_string()),
+        std::env::var("PARAM_B_SMALL").unwrap_or("2".to_string()),
+        std::env::var("PARAM_K").unwrap_or("15".to_string()),
+        std::env::var("PARAM_C").unwrap_or("4".to_string()),
+        std::env::var("PARAM_WIT_LEN").unwrap_or("4".to_string()),
+    );
+
+    fs::write(&dest_path, generated_code).unwrap();
+
+    // Optionally tell Cargo when to rerun the build script
+    println!("cargo:rerun-if-changed=build.rs");
+
+    Ok(())
+}