Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(book): cleanup examples #1173

Merged
merged 1 commit into from
Jan 6, 2025
Merged

chore(book): cleanup examples #1173

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion book/src/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
# Getting Started

- [Install](./getting-started/install.md)

- [Quickstart](./getting-started/quickstart.md)

# Writing Apps
Expand Down
48 changes: 2 additions & 46 deletions book/src/custom-extensions/algebra.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,52 +111,8 @@ The `supported_modulus` parameter is a list of moduli that the guest program wil

Here is a toy example using both the modular arithmetic and complex field extension capabilities:

```rust
#![cfg_attr(not(feature = "std"), no_main)]
#![cfg_attr(not(feature = "std"), no_std)]

use openvm_algebra_guest::{IntMod, moduli_setup::*};

openvm::entry!(main);

// This macro will create two structs, `Mod1` and `Mod2`,
// one for arithmetic modulo 998244353, and the other for arithmetic modulo 1000000007.
moduli_declare! {
Mod1 { modulus = "998244353" },
Mod2 { modulus = "1000000007" }
}

// This macro will initialize the moduli.
// Now, `Mod1` is the "zeroth" modular struct, and `Mod2` is the "first" one.
moduli_init! {
"998244353", "1000000007"
}

// This macro will create two structs, `Complex1` and `Complex2`,
// one for arithmetic in the field $\mathbb{F}_{998244353}[x]/(x^2 + 1)$,
// and the other for arithmetic in the field $\mathbb{F}_{1000000007}[x]/(x^2 + 1)$.
openvm_algebra_complex_macros::complex_declare! {
Complex1 { mod_type = Mod1 },
Complex2 { mod_type = Mod2 },
}

// The order of these structs does not matter,
// given that we specify the `mod_idx` parameters properly.
openvm_algebra_complex_macros::complex_init! {
Complex2 { mod_idx = 1 }, Complex1 { mod_idx = 0 },
}

pub fn main() {
// Since we only use an arithmetic operation with `Mod1` and not `Mod2`,
// we only need to call `setup_0()` here.
setup_0();
setup_all_complex_extensions();
let a = Complex1::new(Mod1::ZERO, Mod1::from_u32(0x3b8) * Mod1::from_u32(0x100000)); // a = -i in the corresponding field
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.
}
```rust,no_run,noplayground
{{ #include ../../../examples/algebra/src/main.rs }}
```

To have the correct imports for the above example, add the following to the `Cargo.toml` file:
Expand Down
90 changes: 6 additions & 84 deletions book/src/custom-extensions/bigint.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,49 +31,10 @@ When using the `U256` struct with `target_os = "zkvm"`, the struct utilizes effi

### Example matrix multiplication using `U256`

See the full example [here](https://github.com/openvm-org/openvm/blob/main/extensions/bigint/tests/programs/examples/book-example2.rs).
See the full example [here](https://github.com/openvm-org/openvm/blob/main/examples/u256/src/main.rs).

```rust
#![cfg_attr(not(feature = "std"), no_main)]
#![cfg_attr(not(feature = "std"), no_std)]

openvm::entry!(main);
use core::array;
use openvm_bigint_guest::U256;

const N: usize = 16;
type Matrix = [[U256; N]; N];

pub fn get_matrix(val: u8) -> Matrix {
array::from_fn(|_| array::from_fn(|_| U256::from_u8(val)))
}

pub fn mult(a: &Matrix, b: &Matrix) -> Matrix {
let mut c = get_matrix(0);
for i in 0..N {
for j in 0..N {
for k in 0..N {
c[i][j] += &a[i][k] * &b[k][j];
}
}
}
c
}

pub fn get_identity_matrix() -> Matrix {
let mut res = get_matrix(0);
for i in 0..N {
res[i][i] = U256::from_u8(1);
}
res
}

pub fn main() {
let a: Matrix = get_identity_matrix();
let b: Matrix = get_matrix(28);
let c: Matrix = mult(&a, &b);
assert_eq!(c, b);
}
```rust,no_run,noplayground
{{ #include ../../../examples/u256/src/main.rs }}
```

To be able to import the `U256` struct, add the following to your `Cargo.toml` file:
Expand Down Expand Up @@ -111,49 +72,10 @@ When using the `I256` struct with `target_os = "zkvm"`, the struct utilizes effi

### Example matrix multiplication using `I256`

See the full example [here](https://github.com/openvm-org/openvm/blob/main/extensions/bigint/tests/programs/examples/matrix-power-signed.rs).
See the full example [here](https://github.com/openvm-org/openvm/blob/main/examples/i256/src/main.rs).

```rust
#![cfg_attr(not(feature = "std"), no_main)]
#![cfg_attr(not(feature = "std"), no_std)]

openvm::entry!(main);
use core::array;
use openvm_bigint_guest::I256;

const N: usize = 16;
type Matrix = [[I256; N]; N];

pub fn get_matrix(val: i32) -> Matrix {
array::from_fn(|_| array::from_fn(|_| I256::from_i32(val)))
}

pub fn mult(a: &Matrix, b: &Matrix) -> Matrix {
let mut c = get_matrix(0);
for i in 0..N {
for j in 0..N {
for k in 0..N {
c[i][j] += &a[i][k] * &b[k][j];
}
}
}
c
}

pub fn get_identity_matrix() -> Matrix {
let mut res = get_matrix(0);
for i in 0..N {
res[i][i] = I256::from_i32(1);
}
res
}

pub fn main() {
let a: Matrix = get_identity_matrix();
let b: Matrix = get_matrix(-28);
let c: Matrix = mult(&a, &b);
assert_eq!(c, b);
}
```rust,no_run,noplayground
{{ #include ../../../examples/i256/src/main.rs }}
```

To be able to import the `I256` struct, add the following to your `Cargo.toml` file:
Expand Down
39 changes: 6 additions & 33 deletions book/src/custom-extensions/ecc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ For the basic operations provided by the `WeierstrassPoint` trait, the scalar fi

## Example program

See a working example [here](https://github.com/openvm-org/openvm/blob/main/extensions/ecc/tests/programs/examples/ec.rs).
See a working example [here](https://github.com/openvm-org/openvm/blob/main/examples/ecc/src/main.rs).

To use the ECC extension, add the following dependencies to `Cargo.toml`:

Expand All @@ -74,44 +74,17 @@ openvm-ecc-guest = { git = "https://github.com/openvm-org/openvm.git", features

One can define their own ECC structs but we will use the Secp256k1 struct from `openvm-ecc-guest` and thus the `k256` feature should be enabled.

```rust
use openvm_ecc_guest::{
k256::{Secp256k1Coord, Secp256k1Point, Secp256k1Scalar},
Group, weierstrass::WeierstrassPoint,
};

openvm_algebra_guest::moduli_setup::moduli_init! {
"0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE FFFFFC2F",
"0xFFFFFFFF FFFFFFFF FFFFFFFF FFFFFFFE BAAEDCE6 AF48A03B BFD25E8C D0364141"
}

openvm_ecc_guest::sw_setup::sw_init! {
Secp256k1Coord,
}
```rust,no_run,noplayground
{{ #include ../../../examples/ecc/src/main.rs:imports }}
{{ #include ../../../examples/ecc/src/main.rs:init }}
```

We `moduli_init!` both the coordinate and scalar field because they were declared in the `k256` module, although we will not be using the scalar field below.

With the above we can start doing elliptic curve operations like adding points:

```rust
pub fn main() {
setup_all_moduli();
setup_all_curves();
let x1 = Secp256k1Coord::from_u32(1);
let y1 = Secp256k1Coord::from_le_bytes(&hex!(
"EEA7767E580D75BC6FDD7F58D2A84C2614FB22586068DB63B346C6E60AF21842"
));
let p1 = Secp256k1Point::from_xy_nonidentity(x1, y1).unwrap();

let x2 = Secp256k1Coord::from_u32(2);
let y2 = Secp256k1Coord::from_le_bytes(&hex!(
"D1A847A8F879E0AEE32544DA5BA0B3BD1703A1F52867A5601FF6454DD8180499"
));
let p2 = Secp256k1Point::from_xy_nonidentity(x2, y2).unwrap();

let p3 = &p1 + &p2;
}
```rust,no_run,noplayground
{{ #include ../../../examples/ecc/src/main.rs:main }}
```

### Config parameters
Expand Down
25 changes: 5 additions & 20 deletions book/src/custom-extensions/keccak.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,28 +10,13 @@ The OpenVM Keccak256 Guest extension provides two functions for using in your gu
- `keccak256(input: &[u8]) -> [u8; 32]`: Computes the Keccak-256 hash of the input data and returns it as an array of 32 bytes.
- `set_keccak256(input: &[u8], output: &mut [u8; 32])`: Sets the output to the Keccak-256 hash of the input data into the provided output buffer.

See the full example [here](https://github.com/openvm-org/openvm/blob/main/extensions/keccak256/tests/programs/examples/keccak.rs).
See the full example [here](https://github.com/openvm-org/openvm/blob/main/examples/keccak/src/main.rs).

### Example:
### Example

```rust
use hex::FromHex;
use openvm_keccak256_guest::keccak256;

pub fn main() {
let test_vectors = [
("", "C5D2460186F7233C927E7DB2DCC703C0E500B653CA82273B7BFAD8045D85A470"),
("CC", "EEAD6DBFC7340A56CAEDC044696A168870549A6A7F6F56961E84A54BD9970B8A"),
];
for (input, expected_output) in test_vectors.iter() {
let input = Vec::from_hex(input).unwrap();
let expected_output = Vec::from_hex(expected_output).unwrap();
let output = keccak256(&black_box(input));
if output != *expected_output {
panic!();
}
}
}
```rust,no_run,noplayground
{{ #include ../../../examples/keccak/src/main.rs:imports }}
{{ #include ../../../examples/keccak/src/main.rs:main }}
```

To be able to import the `keccak256` function, add the following to your `Cargo.toml` file:
Expand Down
Loading