You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Separates the functions exposed by guest libs into their own section in
the book.
Closes INT-4294
---------
Co-authored-by: Jonathan Wang <[email protected]>
Copy file name to clipboardExpand all lines: book/src/custom-extensions/bigint.md
-26Lines changed: 0 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,20 +29,6 @@ All of the operations can be used in 6 different ways:
29
29
30
30
When using the `U256` struct with `target_os = "zkvm"`, the struct utilizes efficient implementations of comparison operators as well as the `clone` method.
31
31
32
-
### Example matrix multiplication using `U256`
33
-
34
-
See the full example [here](https://github.com/openvm-org/openvm/blob/main/examples/u256/src/main.rs).
35
-
36
-
```rust,no_run,noplayground
37
-
{{ #include ../../../examples/u256/src/main.rs }}
38
-
```
39
-
40
-
To be able to import the `U256` struct, add the following to your `Cargo.toml` file:
The `I256` struct is a 256-bit signed integer type. The `I256` struct is very similar to the `U256` struct.
@@ -70,19 +56,7 @@ The `I256` struct implements the following constructors: `from_i8`, `from_i32`,
70
56
71
57
When using the `I256` struct with `target_os = "zkvm"`, the struct utilizes efficient implementations of comparison operators as well as the `clone` method.
72
58
73
-
### Example matrix multiplication using `I256`
74
-
75
-
See the full example [here](https://github.com/openvm-org/openvm/blob/main/examples/i256/src/main.rs).
76
-
77
-
```rust,no_run,noplayground
78
-
{{ #include ../../../examples/i256/src/main.rs }}
79
-
```
80
59
81
-
To be able to import the `I256` struct, add the following to your `Cargo.toml` file:
Copy file name to clipboardExpand all lines: book/src/custom-extensions/ecc.md
+1-49Lines changed: 1 addition & 49 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
The OpenVM Elliptic Curve Cryptography Extension provides support for elliptic curve operations through the `openvm-ecc-guest` crate.
4
4
5
-
The secp256k1 and secp256r1 curves are supported out of the box, and developers can enable arbitrary Weierstrass curves by configuring this extension with the modulus for the coordinate field and the coefficients in the curve equation.
5
+
Developers can enable arbitrary Weierstrass curves by configuring this extension with the modulus for the coordinate field and the coefficients in the curve equation. Preset configurations for the secp256k1 and secp256r1 curves are provided through the [K256](../guest-libs/k256.md) and [P256](../guest-libs/p256.md) guest libraries.
6
6
7
7
## Available traits and methods
8
8
@@ -67,51 +67,3 @@ For the basic operations provided by the `WeierstrassPoint` trait, the scalar fi
67
67
68
68
The ECC extension supports ECDSA signature verification on any elliptic curve, and pre-defined implementations are provided for the secp256k1 and secp256r1 curves.
69
69
To verify an ECDSA signature, first call the `VerifyingKey::recover_from_prehash_noverify` associated function to recover the verifying key, then call the `VerifyingKey::verify_prehashed` method on the recovered verifying key.
70
-
71
-
## Example program
72
-
73
-
See a working example [here](https://github.com/openvm-org/openvm/blob/main/examples/ecc/src/main.rs).
74
-
75
-
To use the ECC extension, add the following dependencies to `Cargo.toml`:
`moduli_init!` is called for both the coordinate and scalar field because they were declared in the `k256` module, although we will not be using the scalar field below.
90
-
91
-
With the above we can start doing elliptic curve operations like adding points:
The `supported_moduli` parameter is a list of moduli that the guest program will use. As mentioned in the [algebra extension](./algebra.md) chapter, the order of moduli in `[app_vm_config.modular]` must match the order in the `moduli_init!` macro.
114
-
115
-
The `ecc.supported_curves` parameter is a list of supported curves that the guest program will use. They must be provided in decimal format in the `.toml` file. For multiple curves create multiple `[[app_vm_config.ecc.supported_curves]]` sections. The order of curves in `[[app_vm_config.ecc.supported_curves]]` must match the order in the `sw_init!` macro.
116
-
Also, the `struct_name` field must be the name of the elliptic curve struct created by `sw_declare!`.
117
-
In this example, the `Secp256k1Point` struct is created in `openvm_ecc_guest::k256`.
hex = { version = "0.4.3", default-features = false, features = ["alloc"] }
27
-
```
28
-
29
-
## External Linking
30
-
31
-
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`.
3
+
The Keccak256 extension guest 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`.
32
4
33
5
-`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.
Copy file name to clipboardExpand all lines: book/src/custom-extensions/overview.md
+11-11Lines changed: 11 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,19 +1,17 @@
1
-
# Using Existing Extensions
1
+
# Acceleration Using Pre-Built Extensions
2
2
3
-
You can seamlessly integrate certain performance-optimized extensions maintained by the OpenVM teamto enhance your arithmetic operations and cryptographic computations.
3
+
OpenVM ships with a set of pre-built extensions maintained by the OpenVM team. Below, we highlight six of these extensions designed to accelerate common arithmetic and cryptographic operations that are notoriously expensive to execute. Some of these extensions have corresponding guest libraries which provide convenient, high-level interfaces for your guest program to interact with the extension.
4
4
5
-
In this chapter, we will explain how to use the following existing extensions:
-[`openvm-bigint-guest`](./bigint.md) - Big integer arithmetic for 256-bit signed and unsigned integers.
5
+
-[`openvm-keccak-guest`](./keccak.md) - Keccak256 hash function. See the [Keccak256 guest library](../guest-libs/keccak256.md) for usage details.
6
+
-[`openvm-sha256-guest`](./sha256.md) - SHA-256 hash function. See the [SHA-2 guest library](../guest-libs/sha2.md) for usage details.
7
+
-[`openvm-bigint-guest`](./bigint.md) - Big integer arithmetic for 256-bit signed and unsigned integers. See the [ruint guest library](../guest-libs/ruint.md) for using accelerated 256-bit integer ops in rust.
10
8
-[`openvm-algebra-guest`](./algebra.md) - Modular arithmetic and complex field extensions.
-[`openvm-pairing-guest`](./pairing.md) - Elliptic curve optimal Ate pairings.
9
+
-[`openvm-ecc-guest`](./ecc.md) - Elliptic curve cryptography. See the [k256](../guest-libs/k256.md) and [p256](../guest-libs/p256.md) guest libraries for using this extension over the respective curves.
10
+
-[`openvm-pairing-guest`](./pairing.md) - Elliptic curve optimal Ate pairings. See the [pairing guest library](../guest-libs/pairing.md) for usage details.
13
11
14
-
Some extensions such as `openvm-keccak-guest`, `openvm-sha256-guest`, and `openvm-bigint-guest` can be enabled without specifying any additional configuration.
12
+
## Optimizing Modular Arithmetic
15
13
16
-
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:
14
+
Some of these extensions—specifically `algebra`, `ecc`, and `pairing`—perform modular arithmetic, which can be significantly optimized when the modulus is known at compile time. Therefore, these extensions provide 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:
17
15
18
16
1.**Declare**: Introduce a modular arithmetic or related structure, along with its modulus and functionality. This can be done in any library or binary file.
19
17
2.**Init**: Performed exactly once in the final binary. It aggregates all previously declared structures, assigns them stable indices, and sets up linkage so that they can be referenced in generated code.
Copy file name to clipboardExpand all lines: book/src/custom-extensions/pairing.md
-96Lines changed: 0 additions & 96 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,99 +19,3 @@ This asserts that \\(e(p_0, q_0) e(p_1, q_1) = 1\\).
19
19
Naturally, this can be extended to more points by adding more elements to the arrays.
20
20
21
21
The pairing extension additionally provides field operations in \\(\mathbb{F_{p^{12}}}\\) for both BN254 and BLS12-381 curves where \\(\mathbb{F}\\) is the coordinate field.
22
-
23
-
## Guest program setup
24
-
25
-
We'll be working with an example using the BLS12-381 elliptic curve. This is in addition to the setup that needs to be done in the [Writing a Program](../writing-apps/write-program.md) section.
26
-
27
-
In the guest program, we will import the `PairingCheck` and `IntMod` traits, along with the BLS12-381 curve structs (**IMPORTANT:** this requires the `bls12_381` feature enabled in Cargo.toml for the `openvm-pairing-guest` dependency), and a few other values that we will need:
Additionally, we'll need to initialize our moduli and `Fp2` struct via the following macros. For a more in-depth description of these macros, please see the [OpenVM Algebra](./algebra.md) section.
The inputs to the pairing check are `AffinePoint`s in \\(\mathbb{F}\_p\\) and \\(\mathbb{F}\_{p^2}\\). They can be constructed via the `AffinePoint::new` function, with the inner `Fp` and `Fp2` values constructed via various `from_...` functions.
42
-
43
-
We can create a new struct to hold these `AffinePoint`s for the purpose of this guide. You may instead put them into a custom struct to serve your use case.
Most users that use the pairing extension will want to assert that a pairing is valid (the final exponentiation equals one). With the `PairingCheck` trait imported from the previous section, we have access to the `pairing_check` function on the `Bls12_381` struct. After reading in the input struct, we can use its values in the `pairing_check`:
We also have access to each of the specific functions that the pairing check utilizes for either the BN254 or BLS12-381 elliptic curves.
66
-
67
-
### Multi-Miller loop
68
-
69
-
The multi-Miller loop requires the MultiMillerLoop trait can also be run separately via:
70
-
71
-
```rust
72
-
letf=Bls12_381::multi_miller_loop(
73
-
&[p0, p1],
74
-
&[q0, q1],
75
-
);
76
-
```
77
-
78
-
## Running via CLI
79
-
80
-
### Config parameters
81
-
82
-
For the guest program to build successfully, we'll need to create an `openvm.toml` configuration file somewhere. It contains all of the necessary configuration information for enabling the OpenVM components that are used in the pairing check.
Also note that since this is a complicated computation, the `keygen` step requires quite a lot of memory. Run it with `RUST_MIN_STACK` set to a large value, e.g.
101
-
102
-
```bash
103
-
RUST_MIN_STACK=8388608 cargo openvm keygen
104
-
```
105
-
106
-
### Full example program
107
-
108
-
This [example code](https://github.com/openvm-org/openvm/blob/main/examples/pairing/src/main.rs) contains hardcoded values and no inputs as an example that can be run via the CLI.
Copy file name to clipboardExpand all lines: book/src/custom-extensions/sha256.md
+1-29Lines changed: 1 addition & 29 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,34 +1,6 @@
1
1
# SHA-256
2
2
3
-
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.
4
-
The functional part is provided by the `openvm-sha256-guest` crate, which is a guest library that can be used in any OpenVM program.
5
-
6
-
## Functions for guest code
7
-
8
-
The OpenVM SHA-256Guest extension provides two functions for using in your guest code:
9
-
10
-
-`sha256(input: &[u8]) -> [u8; 32]`: Computes the SHA-256 hash of the input data and returns it as an array of 32 bytes.
11
-
-`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.
12
-
13
-
See the full example [here](https://github.com/openvm-org/openvm/blob/main/examples/sha256/src/main.rs).
hex = { version = "0.4.3", default-features = false, features = ["alloc"] }
27
-
```
28
-
29
-
## External Linking
30
-
31
-
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`.
3
+
The SHA-256 extension guest 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`.
32
4
33
5
-`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.
0 commit comments