Skip to content

Commit

Permalink
chore(book): cleanup examples (#1173)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jonathanpwang
jonathanpwang authored Jan 6, 2025
1 parent eec611e commit 4ec47bc
Show file tree
Hide file tree
Showing 16 changed files with 127 additions and 355 deletions.
1 change: 0 additions & 1 deletion book/src/SUMMARY.md
View file
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
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
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
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
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

0 comments on commit 4ec47bc

Please sign in to comment.