book: add sha2 summary section (#1149)

* book: add sha2 summary section

* tmp: cargo.lock

* chore: lint

.github/workflows/lints.yml

@@ -41,7 +41,7 @@ jobs:
       - name: Run fmt, clippy for guest
         run: |
           # Find all directories named "programs" and include additional static paths
-          for crate_path in $(find . -type d -name "programs" -exec find {} -mindepth 0 -maxdepth 0 -type d \;) benchmarks/programs/* examples/*; do
+          for crate_path in $(find . -type d -name "programs" -exec find {} -mindepth 0 -maxdepth 0 -type d \;) examples/*; do
             # Check if Cargo.toml exists in the directory
             if [ -f "$crate_path/Cargo.toml" ]; then
               echo "Running cargo fmt, clippy for $crate_path"
@@ -59,4 +59,4 @@ jobs:
             else
               echo "Skipping $crate_path as it does not contain a Cargo.toml"
             fi
-          done
+          done

book/src/SUMMARY.md

@@ -20,6 +20,7 @@
 
 - [Overview](./custom-extensions/overview.md)
 - [Keccak](./custom-extensions/keccak.md)
+- [SHA-256](./custom-extensions/sha256.md)
 - [Big Integer](./custom-extensions/bigint.md)
 - [Algebra (Modular Arithmetic)](./custom-extensions/algebra.md)
 - [Elliptic Curve Cryptography](./custom-extensions/ecc.md)

book/src/custom-extensions/algebra.md

@@ -1,6 +1,6 @@
-# OpenVM Algebra
+# Algebra (Modular Arithmetic)
 
-The OpenVM Algebra extension provides tools to create and manipulate modular arithmetic structures and their complex extensions. For example, if \\(p\\) is prime, OpenVM Algebra can handle modular arithmetic in \\(\mathbb{F}_p\\)​ and its quadratic extension fields \\(\mathbb{F}_p[x]/(x^2 + 1)\\).
+The OpenVM Algebra extension provides tools to create and manipulate modular arithmetic structures and their complex extensions. For example, if \\(p\\) is prime, OpenVM Algebra can handle modular arithmetic in \\(\mathbb{F}\_p\\)​ and its quadratic extension fields \\(\mathbb{F}\_p[x]/(x^2 + 1)\\).
 
 The functional part is provided by the `openvm-algebra-guest` crate, which is a guest library that can be used in any OpenVM program. The macros for creating corresponding structs are in the `openvm-algebra-moduli-setup` and `openvm-algebra-complex-macros` crates.
 
@@ -53,7 +53,7 @@ This step enumerates the declared moduli (e.g., `0` for the first one, `1` for t
 
 ## Complex field extension
 
-Complex extensions, such as \\(\mathbb{F}_p[x]/(x^2 + 1)\\), are defined similarly using `complex_declare!` and `complex_init!`:
+Complex extensions, such as \\(\mathbb{F}\_p[x]/(x^2 + 1)\\), are defined similarly using `complex_declare!` and `complex_init!`:
 
 1. **Declare**:
 

book/src/custom-extensions/bigint.md

@@ -1,10 +1,10 @@
-# OpenVM BigInt
+# Big Integers
 
 The OpenVM BigInt extension (aka `Int256`) provides two structs: `U256` and `I256`. These structs can be used to perform 256 bit arithmetic operations. The functional part is provided by the `openvm-bigint-guest` crate, which is a guest library that can be used in any OpenVM program.
 
 ## `U256`
 
-The `U256` struct is a 256-bit unsigned integer type. 
+The `U256` struct is a 256-bit unsigned integer type.
 
 ### Constants
 
@@ -162,7 +162,7 @@ To be able to import the `I256` struct, add the following to your `Cargo.toml` f
 openvm-bigint-guest = { git = "https://github.com/openvm-org/openvm.git" }
 ```
 
-## External Functions
+## External Linking
 
 The Bigint Guest extension provides another way to use the native implementation. It provides external functions that are meant to be linked to other external libraries. The external libraries can use these functions as a hook for the 256 bit integer native implementations. Enabled only when the `target_os = "zkvm"`. All of the functions are defined as `unsafe extern "C" fn`. Also, note that you must enable the feature `export-intrinsics` to make them globally linkable.
 

book/src/custom-extensions/ecc.md

@@ -1,4 +1,4 @@
-# OpenVM ECC
+# Elliptic Curve Cryptography
 
 The OpenVM Elliptic Curve Cryptography Extension provides support for elliptic curve operations through the `openvm-ecc-guest` crate.
 

book/src/custom-extensions/keccak.md

@@ -1,6 +1,6 @@
-# OpenVM Keccak256
+# Keccak256
 
-The OpenVm Keccak256 extension provides tools for using the Keccak-256 hash function.
+The OpenVM Keccak256 extension provides tools for using the Keccak-256 hash function.
 The functional part is provided by the `openvm-keccak-guest` crate, which is a guest library that can be used in any OpenVM program.
 
 ## Functions for guest code
@@ -41,9 +41,9 @@ openvm-keccak256-guest = { git = "https://github.com/openvm-org/openvm.git" }
 hex = { version = "0.4.3", default-features = false, features = ["alloc"] }
 ```
 
-## Native Keccak256
+## External Linking
 
-Keccak guest extension also provides another way to use the native Keccak-256 implementation. It provides a function that is meant to be linked to other external libraries. The external libraries can use this function as a hook for the Keccak-256 native implementation. Enabled only when the target is `zkvm`.
+The keccak guest extension also provides another way to use the keccak-256 intrinsic implementation. It provides a function that is meant to be linked to other external libraries. The external libraries can use this function as a hook for the keccak-256 intrinsic. This is enabled only when the target is `zkvm`.
 
 - `native_keccak256(input: *const u8, len: usize, output: *mut u8)`: This function has `C` ABI. It takes in a pointer to the input, the length of the input, and a pointer to the output buffer.
 

book/src/custom-extensions/overview.md

@@ -5,12 +5,13 @@ You can seamlessly integrate certain performance-optimized extensions maintained
 In this chapter, we will explain how to use the following existing extensions:
 
 - [`openvm-keccak-guest`](./keccak.md) - Keccak256 hash function.
+- [`openvm-sha256-guest`](./sha256.md) - SHA2-256 hash function.
 - [`openvm-bigint-guest`](./bigint.md) - Big integer arithmetic for 256-bit signed and unsigned integers.
 - [`openvm-algebra-guest`](./algebra.md) - Modular arithmetic and complex field extensions.
 - [`openvm-ecc-guest`](./ecc.md) - Elliptic curve cryptography.
 - [`openvm-pairing-guest`](./pairing.md) - Elliptic curve optimal Ate pairings.
 
-Some extensions such as `openvm-keccak-guest` and `openvm-bigint-guest` can be enabled without specifying any additional configuration.
+Some extensions such as `openvm-keccak-guest`, `openvm-sha256-guest`, and `openvm-bigint-guest` can be enabled without specifying any additional configuration.
 
 On the other hand certain arithmetic operations, particularly modular arithmetic, can be optimized significantly when the modulus is known at compile time. This approach requires a framework to inform the compiler about all the moduli and associated arithmetic structures we intend to use. To achieve this, three steps are involved:
 
@@ -34,6 +35,7 @@ The template `openvm.toml` file is as follows:
 [app_vm_config.rv32m]
 [app_vm_config.io]
 [app_vm_config.keccak]
+[app_vm_config.sha256]
 [app_vm_config.native]
 [app_vm_config.bigint]
 [app_vm_config.modular]
@@ -55,4 +57,4 @@ b = "<b_2>"
 ```
 
 `rv32i`, `io`, and `rv32m` need to be always included if you make an `openvm.toml` file while the rest are optional and should be included if you want to use the corresponding extension.
-All moduli and scalars must be provided in decimal format. Currently  `pairing` supports only pre-defined `Bls12_381` and `Bn254` curves. To add more `ecc` curves you need to add more `[[app_vm_config.ecc.supported_curves]]` entries.
+All moduli and scalars must be provided in decimal format. Currently `pairing` supports only pre-defined `Bls12_381` and `Bn254` curves. To add more `ecc` curves you need to add more `[[app_vm_config.ecc.supported_curves]]` entries.

book/src/custom-extensions/sha256.md

@@ -1,14 +1,14 @@
-# OpenVM Sha256
+# SHA-256
 
-The OpenVm Sha256 extension provides tools for using the Sha256 hash function. Refer [here][https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf] for more details on the Sha256.
+The OpenVM SHA-256 extension provides tools for using the SHA-256 hash function. Refer [here](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) for more details on SHA-256.
 The functional part is provided by the `openvm-sha256-guest` crate, which is a guest library that can be used in any OpenVM program.
 
 ## Functions for guest code
 
-The OpenVM Sha256 Guest extension provides two functions for using in your guest code:
+The OpenVM SHA-256Guest extension provides two functions for using in your guest code:
 
-- `sha256(input: &[u8]) -> [u8; 32]`: Computes the Sha256 hash of the input data and returns it as an array of 32 bytes.
-- `set_sha256(input: &[u8], output: &mut [u8; 32])`: Sets the output to the Sha256 hash of the input data into the provided output buffer.
+- `sha256(input: &[u8]) -> [u8; 32]`: Computes the SHA-256 hash of the input data and returns it as an array of 32 bytes.
+- `set_sha256(input: &[u8], output: &mut [u8; 32])`: Sets the output to the SHA-256 hash of the input data into the provided output buffer.
 
 See the full example [here](https://github.com/openvm-org/openvm/blob/main/examples/sha256).
 
@@ -48,9 +48,9 @@ openvm-sha256-guest = { git = "https://github.com/openvm-org/openvm.git" }
 hex = { version = "0.4.3", default-features = false, features = ["alloc"] }
 ```
 
-## Native Sha256
+## External Linking
 
-Keccak guest extension also provides another way to use the native Sha256 implementation. It provides a function that is meant to be linked to other external libraries. The external libraries can use this function as a hook for the Sha256 native implementation. Enabled only when the target is `zkvm`.
+The SHA-256 guest extension also provides another way to use the intrinsic SHA-256 implementation. It provides a function that is meant to be linked to other external libraries. The external libraries can use this function as a hook for the SHA-256 intrinsic. This is enabled only when the target is `zkvm`.
 
 - `zkvm_sha256_impl(input: *const u8, len: usize, output: *mut u8)`: This function has `C` ABI. It takes in a pointer to the input, the length of the input, and a pointer to the output buffer.
 
@@ -71,7 +71,7 @@ fn sha256(input: &[u8]) -> [u8; 32] {
         output
     }
     #[cfg(not(target_os = "zkvm"))] {
-        // Regular Sha256 implementation
+        // Regular SHA-256 implementation
     }
 }
 ```

examples/algebra/src/main.rs

@@ -1,7 +1,7 @@
 #![cfg_attr(not(feature = "std"), no_main)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
-use openvm_algebra_guest::{moduli_setup::*, DivUnsafe, IntMod};
+use openvm_algebra_guest::{moduli_setup::*, IntMod};
 
 openvm::entry!(main);
 
@@ -41,5 +41,6 @@ pub fn main() {
     let b = Complex2::new(Mod2::ZERO, Mod2::from_u32(1000000006)); // b = -i in the corresponding field
     assert_eq!(a.clone() * &a * &a * &a * &a, a); // a^5 = a
     assert_eq!(b.clone() * &b * &b * &b * &b, b); // b^5 = b
-                                                  // Note that these assertions would fail, have we provided the `mod_idx` parameters wrongly.
+
+    // Note that the above assertions would fail, had we provided the `mod_idx` parameters wrongly.
 }