From b651ed19867282a1ac2f61ff5ba2d2a8e885a404 Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Wed, 16 Oct 2024 04:30:17 +0000 Subject: [PATCH 01/17] GITBOOK-21: No subject --- docs/gitbook/README.md | 4 +- docs/gitbook/SUMMARY.md | 6 ++- .../README.md} | 2 +- .../using-python-garaga-cli.md | 2 + .../using-rust.md | 2 + .../using-typescript.md | 2 + docs/gitbook/installation/README.md | 5 +- docs/gitbook/installation/developer-setup.md | 18 ++++--- docs/gitbook/installation/npm-package.md | 51 +++++++++---------- docs/gitbook/installation/rust-crate.md | 6 +++ 10 files changed, 61 insertions(+), 37 deletions(-) rename docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/{generating-calldata-from-a-proof-and-using-your-deployed-contract.md => generating-calldata-from-a-proof-and-using-your-deployed-contract/README.md} (97%) create mode 100644 docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-python-garaga-cli.md create mode 100644 docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-rust.md create mode 100644 docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-typescript.md create mode 100644 docs/gitbook/installation/rust-crate.md diff --git a/docs/gitbook/README.md b/docs/gitbook/README.md index c5afc0b2..ed3e7207 100644 --- a/docs/gitbook/README.md +++ b/docs/gitbook/README.md @@ -1,6 +1,8 @@ # Garaga documentation Welcome to Garaga's documentation ! \ - +\ +\ +Essentially, Garaga consists of Repository link : [https://github.com/keep-starknet-strange/garaga](https://github.com/keep-starknet-strange/garaga) diff --git a/docs/gitbook/SUMMARY.md b/docs/gitbook/SUMMARY.md index f942f857..4a6767f4 100644 --- a/docs/gitbook/SUMMARY.md +++ b/docs/gitbook/SUMMARY.md @@ -4,12 +4,16 @@ * [Installation](installation/README.md) * [Developer setup](installation/developer-setup.md) * [Python package](installation/python-package.md) + * [Rust Crate](installation/rust-crate.md) * [Npm package](installation/npm-package.md) * [Using garaga libraries in your Cairo project](using-garaga-libraries-in-your-cairo-project/README.md) * [EC (Multi)-Scalar Multiplication](using-garaga-libraries-in-your-cairo-project/ec-multi-scalar-multiplication.md) * [Deploy your SNARK verifier on Starknet](deploy-your-snark-verifier-on-starknet/README.md) * [Groth16](deploy-your-snark-verifier-on-starknet/groth16/README.md) * [Generate and deploy your verifier contract](deploy-your-snark-verifier-on-starknet/groth16/generate-and-deploy-your-verifier-contract.md) - * [Generating calldata from a proof and using your deployed contract](deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract.md) + * [Generating calldata from a proof and using your deployed contract](deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/README.md) + * [Using Python/Garaga CLI](deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-python-garaga-cli.md) + * [Using Rust](deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-rust.md) + * [Using Typescript](deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-typescript.md) * [Noir](deploy-your-snark-verifier-on-starknet/noir.md) * [Support](support.md) diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/README.md similarity index 97% rename from docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract.md rename to docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/README.md index 15b04604..1b4ea05d 100644 --- a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract.md +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/README.md @@ -37,7 +37,7 @@ To do this, use the garaga `verify-onchain` command. ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` -As for the verifying key, both Snarkjs and Gnark `proof.json` and `public.json` are supported out of the box. See the example in the [generate-and-deploy-your-verifier-contract.md](generate-and-deploy-your-verifier-contract.md "mention") for Gnark export. +As for the verifying key, both Snarkjs and Gnark `proof.json` and `public.json` are supported out of the box. See the example in the [generate-and-deploy-your-verifier-contract.md](../generate-and-deploy-your-verifier-contract.md "mention") for Gnark export. Alternatively, the `--public-inputs` parameter can be omitted if your proof include everything at once, as below. diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-python-garaga-cli.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-python-garaga-cli.md new file mode 100644 index 00000000..79faac59 --- /dev/null +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-python-garaga-cli.md @@ -0,0 +1,2 @@ +# Using Python/Garaga CLI + diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-rust.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-rust.md new file mode 100644 index 00000000..0b321543 --- /dev/null +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-rust.md @@ -0,0 +1,2 @@ +# Using Rust + diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-typescript.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-typescript.md new file mode 100644 index 00000000..1d59eee7 --- /dev/null +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-typescript.md @@ -0,0 +1,2 @@ +# Using Typescript + diff --git a/docs/gitbook/installation/README.md b/docs/gitbook/installation/README.md index d01869ee..e75c2712 100644 --- a/docs/gitbook/installation/README.md +++ b/docs/gitbook/installation/README.md @@ -6,5 +6,6 @@ icon: gear You can use garaga in different ways, for different use cases. \ \- The [developer-setup.md](developer-setup.md "mention") allows you to contribute to garaga and use the Garaga CLI.\ -\- The [python-package.md](python-package.md "mention")is the easiest way to generate SNARKS verifiers, deploy them to Starknet, and call you contract from the command line, using the Garaga CLI.\ -\- The [npm-package.md](npm-package.md "mention") (soon available) provides tooling to dApps developers to convert proofs to calldata and interact with browser wallets. +\- The [python-package.md](python-package.md "mention")is the way to generate Cairo SNARKS verifiers, deploy them to Starknet, and call your contract from the command line, using the Garaga CLI.\ +\- The [rust-crate.md](rust-crate.md "mention") \ +\- The [npm-package.md](npm-package.md "mention") (essentially wasm code generated from the Rust crate) provides tooling to dApps developers to convert proofs to calldata and interact with browser wallets. diff --git a/docs/gitbook/installation/developer-setup.md b/docs/gitbook/installation/developer-setup.md index 4904407f..7338aed0 100644 --- a/docs/gitbook/installation/developer-setup.md +++ b/docs/gitbook/installation/developer-setup.md @@ -4,10 +4,16 @@ icon: wrench # Developer setup -To work with Garaga, you need the following dependencies : +To work with Garaga, you need the following dependencies : + +* Python 3.10. The command `python3.10` should be available and working in your terminal. +* [Scarb](https://docs.swmansion.com/scarb/download.html) v2.8.2. +* [Rust](https://www.rust-lang.org/tools/install) + + * Python 3.10. The command `python3.10` should be available and working in your terminal. -* [Scarb](https://docs.swmansion.com/scarb/download.html) v2.8.2. +* [Scarb](https://docs.swmansion.com/scarb/download.html) with the version specified in [https://github.com/keep-starknet-strange/garaga/blob/main/src/.tool-versions](https://github.com/keep-starknet-strange/garaga/blob/main/src/.tool-versions) * [Rust](https://www.rust-lang.org/tools/install) Simply clone the [repository](https://github.com/keep-starknet-strange/garaga) : @@ -18,22 +24,22 @@ Using git: git clone https://github.com/keep-starknet-strange/garaga.git ``` -Using [github cli ](https://cli.github.com/) : +Using [github cli ](https://cli.github.com/): ```bash gh repo clone keep-starknet-strange/garaga ``` -After that, go into the root of the directory and run the command : +After that, go into the root of the directory and run the command : ```bash make setup ``` -Pay attention to any message indicating failure. Contact us on Garaga telegram if you have any trouble at this point. +Pay attention to any message indicating failure. Contact us on Garaga telegram if you have any trouble at this point. If everything succeeded, you're good to go! {% hint style="info" %} -Make sure to activate the virtual environment created with this setup, using `source/venv/bin/activate` +Make sure to activate the virtual environment created with this setup, using `source/venv/bin/activate` {% endhint %} diff --git a/docs/gitbook/installation/npm-package.md b/docs/gitbook/installation/npm-package.md index e823d343..a783ea1c 100644 --- a/docs/gitbook/installation/npm-package.md +++ b/docs/gitbook/installation/npm-package.md @@ -1,3 +1,7 @@ +--- +icon: js +--- + # Npm package ## Installation via NPM Registry (recommended) @@ -5,7 +9,7 @@ The easiest way to install Garaga is via your prefered Node.js package manager, such as `npm` or `yarn`. 1. Open your terminal or command prompt. -2. Run the following command: +2. Run the following command: ```bash npm i -S garaga @@ -22,13 +26,12 @@ The easiest way to install Garaga is via your prefered Node.js package manager, The package can be build directly from source code by cloning the garaga repository. Make sure you have both [Rust](https://www.rust-lang.org/tools/install) and [Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed in you machine. 1. Open your terminal or command prompt. -2. Install `wasm-pack` by running: +2. Install `wasm-pack` by running: ```bash cargo install wasm-pack ``` - -3. Run the following commands: +3. Run the following commands: ```bash git clone https://github.com/keep-starknet-strange/garaga.git @@ -37,9 +40,8 @@ The package can be build directly from source code by cloning the garaga reposit npm run build npm pack ``` - 4. The .tgz file with the package contents will be available in the current folder. -5. Install the .tgz file in your project +5. Install the .tgz file in your project ```bash npm i -S @@ -48,16 +50,15 @@ The package can be build directly from source code by cloning the garaga reposit For reproducible builds, one can use instead docker compose. Make sure [docker](https://docs.docker.com/engine/install/) is installed in you machine. 1. Open your terminal or command prompt. -2. Run the following commands: +2. Run the following commands: ```bash git clone https://github.com/keep-starknet-strange/garaga.git cd tools/npm/garaga_ts docker compose up --build ``` - 3. The .tgz file with the package contents will be available in the current folder. -4. Install the .tgz file in your project +4. Install the .tgz file in your project ```bash npm i -S @@ -74,51 +75,49 @@ Changes to the TypeScript library should only be made to files under the `node` Onces changes are in place they can be made permanent into the repository by committing the contents of both folders. Here is the bulk of the process: 1. Open your terminal or command prompt. -2. Use `git` to clone the repository: +2. Use `git` to clone the repository: ```bash git clone https://github.com/keep-starknet-strange/garaga.git cd tools/npm/garaga_ts npm ci ``` - -3. If you make TypeScript only changes, you can quickly rebuild the package using the `build:node` NPM script: +3. If you make TypeScript only changes, you can quickly rebuild the package using the `build:node` NPM script: ```bash npm run build:node npm pack ``` - -4. If instead you make Rust changes, it is necessary to generate the WASM interoperability code using the `build` NPM script: +4. If instead you make Rust changes, it is necessary to generate the WASM interoperability code using the `build` NPM script: ```bash npm run build npm pack ``` - -5. However, before commiting changes, it is necessary to generate the WASM interoperability code in a reproducible manner using docker: +5. However, before commiting changes, it is necessary to generate the WASM interoperability code in a reproducible manner using docker: ```bash docker compose up --build git commit . ``` + ### How `wasm-pack` is used to achieve interoperability Internaly the `build` NPM script uses `wasm-pack` to produce the WASM interoperability code. This is achieved by running - ```bash - cd tools/garaga_rs && wasm-pack build --target web --out-dir ../npm/garaga_ts/src/wasm/pkg --release --no-default-features - cd tools/npm/garaga_ts && node patch.wasm.cjs - ``` +```` +```bash +cd tools/garaga_rs && wasm-pack build --target web --out-dir ../npm/garaga_ts/src/wasm/pkg --release --no-default-features +cd tools/npm/garaga_ts && node patch.wasm.cjs +``` +```` + Let's unpack it. -In the Rust source folder we run `wasm-pack` in `--target web` mode. This generates TypeScript code targeting web pages. -The `--release` option is required to minimize the size of the WASM module. -And the `--no-default-features` disables the need to build non WASM features of garaga_rs. +In the Rust source folder we run `wasm-pack` in `--target web` mode. This generates TypeScript code targeting web pages. The `--release` option is required to minimize the size of the WASM module. And the `--no-default-features` disables the need to build non WASM features of garaga\_rs. -Once the `wasm-pack` is done, the code is generated under the folder `src/wasm/pkg` of garaga_ts that houses the TypeScript source code. +Once the `wasm-pack` is done, the code is generated under the folder `src/wasm/pkg` of garaga\_ts that houses the TypeScript source code. -We then run a custom script `patch.wasm.cjs` which makes minimal changes to the code generated by wasm-pack to facilitate seamless support of the WASM module in both the browser and Node.js. -Basically it converts the WASM module to a [Base64](https://en.wikipedia.org/wiki/Base64) string that can be loaded in a portable way in both environments, amongst other minor tweaks. +We then run a custom script `patch.wasm.cjs` which makes minimal changes to the code generated by wasm-pack to facilitate seamless support of the WASM module in both the browser and Node.js. Basically it converts the WASM module to a [Base64](https://en.wikipedia.org/wiki/Base64) string that can be loaded in a portable way in both environments, amongst other minor tweaks. (It is important to note that the use of a custom script is only required so long `wasm-pack` itself does not provide a more portable/universal target mode.) diff --git a/docs/gitbook/installation/rust-crate.md b/docs/gitbook/installation/rust-crate.md new file mode 100644 index 00000000..b8189e83 --- /dev/null +++ b/docs/gitbook/installation/rust-crate.md @@ -0,0 +1,6 @@ +--- +icon: crab +--- + +# Rust Crate + From e380eb6881559290132d933c20201f9401a9ea61 Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Thu, 17 Oct 2024 12:09:02 +0000 Subject: [PATCH 02/17] GITBOOK-22: No subject --- docs/gitbook/README.md | 2 - docs/gitbook/SUMMARY.md | 14 +- ...erate-and-deploy-your-verifier-contract.md | 2 +- .../README.md} | 14 +- .../garaga-rs-crate/README.md | 6 + .../rust-greater-than-python-bindings.md | 2 + .../rust-greater-than-wasm-bidings.md | 6 + .../working-with-auto-generated-cairo-code.md | 276 ++++++++++++++++++ docs/gitbook/installation/README.md | 2 +- docs/gitbook/installation/python-package.md | 2 +- docs/gitbook/installation/rust-crate.md | 2 +- .../maintained-smart-contracts/README.md | 8 + .../maintained-smart-contracts/drand.md | 7 + .../maintained-smart-contracts/risczero.md | 7 + .../gitbook/maintained-smart-contracts/sp1.md | 7 + docs/gitbook/updating-these-docs.md | 9 + .../ec-signatures.md | 7 + 17 files changed, 358 insertions(+), 15 deletions(-) rename docs/gitbook/{installation/developer-setup.md => developer-setup-and-guides/README.md} (83%) create mode 100644 docs/gitbook/developer-setup-and-guides/garaga-rs-crate/README.md create mode 100644 docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-python-bindings.md create mode 100644 docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-wasm-bidings.md create mode 100644 docs/gitbook/developer-setup-and-guides/working-with-auto-generated-cairo-code.md create mode 100644 docs/gitbook/maintained-smart-contracts/README.md create mode 100644 docs/gitbook/maintained-smart-contracts/drand.md create mode 100644 docs/gitbook/maintained-smart-contracts/risczero.md create mode 100644 docs/gitbook/maintained-smart-contracts/sp1.md create mode 100644 docs/gitbook/updating-these-docs.md create mode 100644 docs/gitbook/using-garaga-libraries-in-your-cairo-project/ec-signatures.md diff --git a/docs/gitbook/README.md b/docs/gitbook/README.md index ed3e7207..1bc3d613 100644 --- a/docs/gitbook/README.md +++ b/docs/gitbook/README.md @@ -3,6 +3,4 @@ Welcome to Garaga's documentation ! \ \ \ -Essentially, Garaga consists of - Repository link : [https://github.com/keep-starknet-strange/garaga](https://github.com/keep-starknet-strange/garaga) diff --git a/docs/gitbook/SUMMARY.md b/docs/gitbook/SUMMARY.md index 4a6767f4..759c6dd4 100644 --- a/docs/gitbook/SUMMARY.md +++ b/docs/gitbook/SUMMARY.md @@ -2,13 +2,18 @@ * [Garaga documentation](README.md) * [Installation](installation/README.md) - * [Developer setup](installation/developer-setup.md) * [Python package](installation/python-package.md) * [Rust Crate](installation/rust-crate.md) * [Npm package](installation/npm-package.md) +* [Developer setup & guides](developer-setup-and-guides/README.md) + * [Working with auto-generated Cairo Code](developer-setup-and-guides/working-with-auto-generated-cairo-code.md) + * [garaga-rs crate](developer-setup-and-guides/garaga-rs-crate/README.md) + * [Rust -> Python bindings](developer-setup-and-guides/garaga-rs-crate/rust-greater-than-python-bindings.md) + * [Rust -> Wasm bidings](developer-setup-and-guides/garaga-rs-crate/rust-greater-than-wasm-bidings.md) * [Using garaga libraries in your Cairo project](using-garaga-libraries-in-your-cairo-project/README.md) * [EC (Multi)-Scalar Multiplication](using-garaga-libraries-in-your-cairo-project/ec-multi-scalar-multiplication.md) -* [Deploy your SNARK verifier on Starknet](deploy-your-snark-verifier-on-starknet/README.md) + * [EC-Signatures](using-garaga-libraries-in-your-cairo-project/ec-signatures.md) +* [Deploy your own SNARK verifier on Starknet](deploy-your-snark-verifier-on-starknet/README.md) * [Groth16](deploy-your-snark-verifier-on-starknet/groth16/README.md) * [Generate and deploy your verifier contract](deploy-your-snark-verifier-on-starknet/groth16/generate-and-deploy-your-verifier-contract.md) * [Generating calldata from a proof and using your deployed contract](deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/README.md) @@ -16,4 +21,9 @@ * [Using Rust](deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-rust.md) * [Using Typescript](deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-typescript.md) * [Noir](deploy-your-snark-verifier-on-starknet/noir.md) +* [Maintained Smart Contracts](maintained-smart-contracts/README.md) + * [RiscZero](maintained-smart-contracts/risczero.md) + * [SP1](maintained-smart-contracts/sp1.md) + * [Drand](maintained-smart-contracts/drand.md) * [Support](support.md) +* [Updating these docs](updating-these-docs.md) diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generate-and-deploy-your-verifier-contract.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generate-and-deploy-your-verifier-contract.md index 3b53702e..54793eb7 100644 --- a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generate-and-deploy-your-verifier-contract.md +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generate-and-deploy-your-verifier-contract.md @@ -113,7 +113,7 @@ func SaveToJSON(filePath string, v interface{}) error { ## Generate the Smart contract code \ -Using the [developer-setup.md](../../installation/developer-setup.md "mention") or the [python-package.md](../../installation/python-package.md "mention"), you should now have access to the Garaga CLI from your terminal, using the command `garaga` +Using the [developer-setup-and-guides](../../developer-setup-and-guides/ "mention") or the [python-package.md](../../installation/python-package.md "mention"), you should now have access to the Garaga CLI from your terminal, using the command `garaga` ```bash garaga diff --git a/docs/gitbook/installation/developer-setup.md b/docs/gitbook/developer-setup-and-guides/README.md similarity index 83% rename from docs/gitbook/installation/developer-setup.md rename to docs/gitbook/developer-setup-and-guides/README.md index 7338aed0..fcf06c0b 100644 --- a/docs/gitbook/installation/developer-setup.md +++ b/docs/gitbook/developer-setup-and-guides/README.md @@ -2,15 +2,11 @@ icon: wrench --- -# Developer setup +# Developer setup & guides -To work with Garaga, you need the following dependencies : - -* Python 3.10. The command `python3.10` should be available and working in your terminal. -* [Scarb](https://docs.swmansion.com/scarb/download.html) v2.8.2. -* [Rust](https://www.rust-lang.org/tools/install) +### Installation - +To work with Garaga, you need the following dependencies : * Python 3.10. The command `python3.10` should be available and working in your terminal. * [Scarb](https://docs.swmansion.com/scarb/download.html) with the version specified in [https://github.com/keep-starknet-strange/garaga/blob/main/src/.tool-versions](https://github.com/keep-starknet-strange/garaga/blob/main/src/.tool-versions) @@ -43,3 +39,7 @@ If everything succeeded, you're good to go! {% hint style="info" %} Make sure to activate the virtual environment created with this setup, using `source/venv/bin/activate` {% endhint %} + + + +### diff --git a/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/README.md b/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/README.md new file mode 100644 index 00000000..feee5eac --- /dev/null +++ b/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/README.md @@ -0,0 +1,6 @@ +--- +icon: crab +--- + +# garaga-rs crate + diff --git a/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-python-bindings.md b/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-python-bindings.md new file mode 100644 index 00000000..cedad8bd --- /dev/null +++ b/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-python-bindings.md @@ -0,0 +1,2 @@ +# Rust -> Python bindings + diff --git a/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-wasm-bidings.md b/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-wasm-bidings.md new file mode 100644 index 00000000..cedc69d7 --- /dev/null +++ b/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-wasm-bidings.md @@ -0,0 +1,6 @@ +--- +description: Explains how to add a bind +--- + +# Rust -> Wasm bidings + diff --git a/docs/gitbook/developer-setup-and-guides/working-with-auto-generated-cairo-code.md b/docs/gitbook/developer-setup-and-guides/working-with-auto-generated-cairo-code.md new file mode 100644 index 00000000..56e55a3f --- /dev/null +++ b/docs/gitbook/developer-setup-and-guides/working-with-auto-generated-cairo-code.md @@ -0,0 +1,276 @@ +--- +icon: wand-sparkles +--- + +# Working with auto-generated Cairo Code + +### Developer workflow + +If working with the python - auto generated cairo code, the main script to work with is `make rewrite` \ + + +{% code title="tools/make/rewrite.sh" %} +```bash +rm -rf src/src/tests/* +rm -rf src/src/circuits/* +rm -rf src/contracts/groth16_example_bls12_381/* +rm -rf src/contracts/groth16_example_bn254/* +rm -rf src/contracts/risc0_verifier_bn254/* + +set -e # Exit immediately if a command exits with a non-zero status + +python hydra/garaga/precompiled_circuits/all_circuits.py || { echo "Error in all_circuits.py"; exit 1; } +python hydra/garaga/starknet/tests_and_calldata_generators/test_writer.py || { echo "Error in test_writer.py"; exit 1; } +python hydra/garaga/starknet/groth16_contract_generator/generator.py || { echo "Error in generator.py"; exit 1; } +python hydra/garaga/starknet/groth16_contract_generator/generator_risc0.py || { echo "Error in generator_risc0.py"; exit 1; } +``` +{% endcode %} + +\ +As you can see this will : + +* Rewrite all the auto-generated cairo code in `src/src/circuits/` (with the `all_circuits.py` script) +* Rewrite all the auto-generated cairo tests in `src/src/tests/` (with the `test_writer.py` script) +* Rewrite the Groth16 verifiers smart contract templates examples in `src/contracts/` (with the `generator.py` and `generator_risc0.py` scripts) + + + +## Creating auto-generated circuits. + +While it's relatively easy to write Cairo circuits yourself if their size is small, it starts to be quite time consuming if you need to build a large amount of them, parametrize them, and the circuits themselves are quite large. + +{% hint style="info" %} +Examples of small hand-made small circuits can be found in [https://github.com/keep-starknet-strange/garaga/blob/main/src/src/basic\_field\_ops.cairo](https://github.com/keep-starknet-strange/garaga/blob/main/src/src/basic\_field\_ops.cairo) +{% endhint %} + +\ +If you want to write a new auto-generated circuit to `src/src/circuits`, you can define them with python code, and register them to the `all_circuits.py` file. \ +\ +Below we show a basic tutorial for a non-parametrized circuit. + +### Simple isolated example + +
import garaga.modulo_circuit_structs as structs
+from garaga.definitions import CurveID, get_base_field
+from garaga.modulo_circuit import PyFelt, ModuloCircuit
+
+
+curve_id = CurveID.BN254 # BN254
+field = get_base_field(curve_id) # Use with field(int) or field.random(). 
+
+COMPILATION_MODE = 1 # 1 for Cairo, 0 for CairoZero. 
+
+circuit = ModuloCircuit(
+    name=f"dummy_{curve_id.name.lower()},
+    curve_id.value,
+    generic_circuit=False,
+    compilation_mode=COMPILATION_MODE,
+)
+# All "structs" expect a name (replicated in the signature) and a list of elements.
+x, y = circuit.write_struct(structs.u384Span("xy", [field.random(), field.random()]))
+# All "structs" written with write_struct will be expected in the Cairo
+# function signature of the given type.
+z = circuit.write_struct(structs.u384("z", [field(42)]))
+
+# With this configuration,
+# the signature will be fn(xy: Span<u384>, z:u384).
+# More structs and arbitrary ones are supported as well.
+
+# To write constants, use set_or_get_constant.
+one = circuit.set_or_get_constant(1)
+
+# Here happens the core circuit logic.
+# The core operations are add, sub, mul, inv.
+# However, more high level methods are available that translate to
+# a sequence of the core operations (ex: div <=> inv then mul)
+a = circuit.add(x, y)
+b = circuit.sub(a, one)
+c = circuit.mul(b, z)
+d = circuit.inv(c)
+f = circuit.div(d, z)
+
+# Define the output of the function using structs as well.
+circuit.extend_struct_output(structs.u384Span("abc", [a, b, c]))
+circuit.extend_struct_output(structs.u384("f", [f]))
+
+# Compile and print the compiled cairo circuit : 
+header = compilation_mode_to_file_header(1) # Cairo 1
+compiled_code, function_name = circuit.compile_circuit()
+# Note: some imports are unused in the header, 
+# we should make the compiler aware of the structs used ;)
+print(header) 
+print(compiled_code)
+
+ +To obtain the corresponding Cairo code, you can do it like this + +The obtained Cairo code will be + +```rust +use core::circuit::{ + RangeCheck96, AddMod, MulMod, u384, u96, CircuitElement, CircuitInput, circuit_add, circuit_sub, + circuit_mul, circuit_inverse, EvalCircuitResult, EvalCircuitTrait, CircuitOutputsTrait, + CircuitModulus, AddInputResultTrait, CircuitInputs, CircuitDefinition, + CircuitData, CircuitInputAccumulator +}; +use garaga::core::circuit::AddInputResultTrait2; +use core::circuit::CircuitElement as CE; +use core::circuit::CircuitInput as CI; +use garaga::definitions::{get_a, get_b, get_p, get_g, get_min_one, G1Point, G2Point, E12D, u288, E12DMulQuotient, G1G2Pair, BNProcessedPair, BLSProcessedPair, MillerLoopResultScalingFactor, G2Line, get_BLS12_381_modulus,get_BN254_modulus}; +use garaga::ec_ops::{SlopeInterceptOutput, FunctionFeltEvaluations, FunctionFelt}; +use core::option::Option; + + +#[inline(always)] +fn run_dummy_bn254_circuit(xy: Span, z: u384) -> (Span, u384) { + // CONSTANT stack + let in0 = CE::> {}; // 0x1 + + // INPUT stack + let (in1, in2, in3) = (CE::> {}, CE::> {}, CE::> {}); + let t0 = circuit_add(in1, in2); + let t1 = circuit_sub(t0, in0); + let t2 = circuit_mul(t1, in3); + let t3 = circuit_inverse(t2); + let t4 = circuit_inverse(in3); + let t5 = circuit_mul(t3, t4); + + let modulus = get_BN254_modulus(); // BN254 prime field modulus + + let mut circuit_inputs = (t0, t1, t2, t5,).new_inputs(); + // Prefill constants: + circuit_inputs = circuit_inputs.next_2([0x1, 0x0, 0x0, 0x0]); // in0 + // Fill inputs: + let mut xy = xy; + while let Option::Some(val) = xy.pop_front() { + circuit_inputs = circuit_inputs.next_2(*val); + }; + // in1 - in2 + circuit_inputs = circuit_inputs.next_2(z); // in3 + + let outputs = circuit_inputs.done_2().eval(modulus).unwrap(); + let abc: Span = array![ + outputs.get_output(t0), outputs.get_output(t1), outputs.get_output(t2) + ] + .span(); + let f: u384 = outputs.get_output(t5); + return (abc, f); +} +``` + +Note that the compiler will adapt the signature of the Cairo function depending on the `generic_circuit` parameter, and retrieve the corresponding modulus inside the function code. + +{% code title="https://github.com/keep-starknet-strange/garaga/blob/584cad66d067aa6c04447fe06a00c7be99bc2445/hydra/garaga/modulo_circuit.py#L1068-L1071" %} +```python +if self.generic_circuit: + code = f"#[inline(always)]\nfn {function_name}({signature_input}, curve_index:usize)->{signature_output} {{\n" +else: + code = f"#[inline(always)]\nfn {function_name}({signature_input})->{signature_output} {{\n" +``` +{% endcode %} + +### Using parameterization (docs in progress :construction:) + +#### The base class + +Currently, the way we deal with parameterization is encapsulating the earlier `ModuloCircuit` class into a [BaseModuloCircuit](https://github.com/keep-starknet-strange/garaga/blob/584cad66d067aa6c04447fe06a00c7be99bc2445/hydra/garaga/precompiled\_circuits/compilable\_circuits/base.py#L12C7-L12C25) class, and adding keyword arguments to the class deriving it. + +```python +class BaseModuloCircuit(ABC): + """ + Base class for all modulo circuits that will be compiled to Cairo code. + Parameters: + - name: str, the name of the circuit + - curve_id: int, the id of the curve + - auto_run: bool, whether to run the circuit automatically at initialization. + When compiling, this flag must be set to true so the ModuloCircuit class inside the + ".circuit" member of this class holds the necessary metadata + about the operations that will be compiled. + For CairoZero, this flag will be set to False in the Python hint, so that + BaseModuloCircuit.run_circuit() can be called on a segment parsed from the + CairoZero VM. + - compilation mode: 0 (CairoZero) or 1 (Cairo) + """ + + def __init__( + self, + name: str, + curve_id: int, + auto_run: bool = True, + compilation_mode: int = 0, +``` + +All Cairo function must inherit from the base abstract class \ +The abstract methods to implement are : \ + + +* `build_input` + + ```python + def build_input(self) -> list[PyFelt]: + """ + This method is used to create the necessary inputs that will be written to the ModuloCircuit. + It works in pair with the _run_circuit_inner function, where the _run_circuit_inner will use the output of + the build_input function to "deserialize" the list of elements and "write" them to the ModuloCircuit class. + """ + ``` +* `_run_circuit_inner` + + ```python + def _run_circuit_inner(self, input: list[PyFelt]) -> ModuloCircuit: + """ + This method is responsible for + - deserializing the input list of elements, + - creating a ModuloCircuit class (or class that derives from ModuloCircuit) + - "writing" the inputs to the ModuloCircuit class to obtain ModuloCircuitElements + - using the methods add, sub, mul, inv (or higher level methods) of the ModuloCircuit class + to define the list of operations on the given inputs. + - Returning the ModuloCircuit class in a state where the circuit has been run, and therefore holding + the metadata so that its instructions can be compiled to Cairo code. + + """ + ``` + + + +At initialization, you must choose a name for the circuit. \ +Pay attention to the parameter `generic_circuit` passed to the `ModuloCircuit` class inside `_run_circuit_inner` + +
import garaga.modulo_circuit_structs as structs
+from garaga.definitions import CurveID
+from garaga.precompiled_circuits.compilable_circuits.base import BaseModuloCircuit
+from garaga.modulo_circuit import PyFelt, ModuloCircuit
+
+class FixedExpCircuit(BaseModuloCircuit):
+    def __init__(
+        self, curve_id: int, auto_run: bool = True, compilation_mode: int = 1, n:int=1
+        
+    ) -> None:
+        super().__init__(
+            name=f"fixed_exp_circuit_{CurveID(curve_id).name.lower()}_{n}",
+            curve_id=curve_id,
+            auto_run=auto_run,
+            compilation_mode=compilation_mode,
+        )
+        self.n = n
+
+    def build_input(self) -> list[PyFelt]:
+        return [self.field.random()]
+
+    def _run_circuit_inner(self, input: list[PyFelt]) -> ModuloCircuit:
+        circuit = ModuloCircuit(
+            self.name,
+            self.curve_id,
+            generic_circuit=True,
+            compilation_mode=self.compilation_mode,
+        )
+
+        z = circuit.write_struct(structs.u384("z", [input[2]]), WriteOps.INPUT)
+        res = z
+        for i in range(n):
+            res = circuit.mul(res, z)
+        circuit.extend_struct_output(structs.u384("res", [res]))
+
+        return circuit
+
+
diff --git a/docs/gitbook/installation/README.md b/docs/gitbook/installation/README.md index e75c2712..a2cd73a2 100644 --- a/docs/gitbook/installation/README.md +++ b/docs/gitbook/installation/README.md @@ -5,7 +5,7 @@ icon: gear # Installation You can use garaga in different ways, for different use cases. \ -\- The [developer-setup.md](developer-setup.md "mention") allows you to contribute to garaga and use the Garaga CLI.\ +\- The [developer-setup-and-guides](../developer-setup-and-guides/ "mention") explains how to setup a dev environment for contributing to garaga and as well as some tutorials.\ \- The [python-package.md](python-package.md "mention")is the way to generate Cairo SNARKS verifiers, deploy them to Starknet, and call your contract from the command line, using the Garaga CLI.\ \- The [rust-crate.md](rust-crate.md "mention") \ \- The [npm-package.md](npm-package.md "mention") (essentially wasm code generated from the Rust crate) provides tooling to dApps developers to convert proofs to calldata and interact with browser wallets. diff --git a/docs/gitbook/installation/python-package.md b/docs/gitbook/installation/python-package.md index 8963f448..4c5d063d 100644 --- a/docs/gitbook/installation/python-package.md +++ b/docs/gitbook/installation/python-package.md @@ -1,5 +1,5 @@ --- -icon: snake +icon: python --- # Python package diff --git a/docs/gitbook/installation/rust-crate.md b/docs/gitbook/installation/rust-crate.md index b8189e83..c14ab964 100644 --- a/docs/gitbook/installation/rust-crate.md +++ b/docs/gitbook/installation/rust-crate.md @@ -1,5 +1,5 @@ --- -icon: crab +icon: rust --- # Rust Crate diff --git a/docs/gitbook/maintained-smart-contracts/README.md b/docs/gitbook/maintained-smart-contracts/README.md new file mode 100644 index 00000000..f369302f --- /dev/null +++ b/docs/gitbook/maintained-smart-contracts/README.md @@ -0,0 +1,8 @@ +--- +icon: file-lock +--- + +# Maintained Smart Contracts + +We deployed & maintain Smart Contracts for the community. + diff --git a/docs/gitbook/maintained-smart-contracts/drand.md b/docs/gitbook/maintained-smart-contracts/drand.md new file mode 100644 index 00000000..afe08727 --- /dev/null +++ b/docs/gitbook/maintained-smart-contracts/drand.md @@ -0,0 +1,7 @@ +--- +icon: dice +--- + +# Drand + +Deployment & Docs soon. diff --git a/docs/gitbook/maintained-smart-contracts/risczero.md b/docs/gitbook/maintained-smart-contracts/risczero.md new file mode 100644 index 00000000..a0b4717d --- /dev/null +++ b/docs/gitbook/maintained-smart-contracts/risczero.md @@ -0,0 +1,7 @@ +--- +icon: microchip +--- + +# RiscZero + +Docs incoming. diff --git a/docs/gitbook/maintained-smart-contracts/sp1.md b/docs/gitbook/maintained-smart-contracts/sp1.md new file mode 100644 index 00000000..933ba70e --- /dev/null +++ b/docs/gitbook/maintained-smart-contracts/sp1.md @@ -0,0 +1,7 @@ +--- +icon: microchip +--- + +# SP1 + +Soon. diff --git a/docs/gitbook/updating-these-docs.md b/docs/gitbook/updating-these-docs.md new file mode 100644 index 00000000..8c6a7d7b --- /dev/null +++ b/docs/gitbook/updating-these-docs.md @@ -0,0 +1,9 @@ +--- +icon: file-doc +--- + +# Updating these docs + +Simply PR to the `docs` branch of the repo to the files in the `docs/gitbook` folder[https://github.com/keep-starknet-strange/garaga/tree/docs/docs/gitbook](https://github.com/keep-starknet-strange/garaga/tree/docs/docs/gitbook)\ +\ +When merged, the gitbook website will be updated automatically. diff --git a/docs/gitbook/using-garaga-libraries-in-your-cairo-project/ec-signatures.md b/docs/gitbook/using-garaga-libraries-in-your-cairo-project/ec-signatures.md new file mode 100644 index 00000000..beae9a89 --- /dev/null +++ b/docs/gitbook/using-garaga-libraries-in-your-cairo-project/ec-signatures.md @@ -0,0 +1,7 @@ +--- +icon: pen-field +--- + +# EC-Signatures + +ECDSA & Schnorr soon. From d5a7495cfcc13a4c97d206e2bb79d17c49222e14 Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Fri, 18 Oct 2024 03:51:47 +0000 Subject: [PATCH 03/17] GITBOOK-24: No subject --- .../groth16/generate-and-deploy-your-verifier-contract.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generate-and-deploy-your-verifier-contract.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generate-and-deploy-your-verifier-contract.md index 54793eb7..6f0ae30c 100644 --- a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generate-and-deploy-your-verifier-contract.md +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generate-and-deploy-your-verifier-contract.md @@ -4,12 +4,6 @@ icon: file-lock # Generate and deploy your verifier contract - - -{% hint style="info" %} -Only Starknet Sepolia is supported. Starknet Mainnet will be supported on version 0.13.2 -{% endhint %} - ## Prepare your Groth16 verifying key {% hint style="info" %} From 89b7a6d05ffe0f684cd20023b7765b41eb03e1d5 Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Sun, 3 Nov 2024 09:28:22 +0000 Subject: [PATCH 04/17] GITBOOK-25: No subject --- .../maintained-smart-contracts/README.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/gitbook/maintained-smart-contracts/README.md b/docs/gitbook/maintained-smart-contracts/README.md index f369302f..ef2c6c91 100644 --- a/docs/gitbook/maintained-smart-contracts/README.md +++ b/docs/gitbook/maintained-smart-contracts/README.md @@ -4,5 +4,22 @@ icon: file-lock # Maintained Smart Contracts -We deployed & maintain Smart Contracts for the community. +We declare & maintain Smart Contracts for the community. +\ +Those contracts: + +* Are _declared_ both Starknet Sepolia and Mainnet. +* Those contracts are re-deployed at each release, so their code correspond to the release commit. +* The source code is always available in the main garaga repository under `src/contracts` +* The contracts are only declared and not deployed, their expected usage is through [library syscalls.](https://book.cairo-lang.org/ch15-03-executing-code-from-another-class.html#library-calls), their usage is done through their class hashes. \ + \ + + + + +| Contract | Class hash | Description | +| ----------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| Universal ECIP | `0x70c1d1c709c75e3cf51d79d19cf7c84a0d4521f3a2b8bf7bff5cb45ee0dd289` | A contract allowing to compute elliptic curve multi scalar multiplication for all supported curve identifiers | +| RiscZero Verifier | `0x189d559773d197f7a4d0af561294e5d224455acddb541aa83f4262c8a25d56c` | A verifier for RiscZero Groth16-wrapped proofs. | +| Drand Quicknet Verifier | `0x5dc6c40dc3937670c0f644424d10ce90270193f3385bf6f4360f52402647c1b` | A contract to verify Drand signatures and use timelock encryption utilities (soon). | From fcbe91b171058b37cea4c52878ce5ffe5eb935cb Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Sun, 3 Nov 2024 09:30:37 +0000 Subject: [PATCH 05/17] GITBOOK-26: No subject --- docs/gitbook/maintained-smart-contracts/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/gitbook/maintained-smart-contracts/README.md b/docs/gitbook/maintained-smart-contracts/README.md index ef2c6c91..ea69da9a 100644 --- a/docs/gitbook/maintained-smart-contracts/README.md +++ b/docs/gitbook/maintained-smart-contracts/README.md @@ -18,8 +18,8 @@ Those contracts: -| Contract | Class hash | Description | -| ----------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| Universal ECIP | `0x70c1d1c709c75e3cf51d79d19cf7c84a0d4521f3a2b8bf7bff5cb45ee0dd289` | A contract allowing to compute elliptic curve multi scalar multiplication for all supported curve identifiers | -| RiscZero Verifier | `0x189d559773d197f7a4d0af561294e5d224455acddb541aa83f4262c8a25d56c` | A verifier for RiscZero Groth16-wrapped proofs. | -| Drand Quicknet Verifier | `0x5dc6c40dc3937670c0f644424d10ce90270193f3385bf6f4360f52402647c1b` | A contract to verify Drand signatures and use timelock encryption utilities (soon). | +| Contract | Class hash | Description | +| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| [Universal ECIP](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/universal\_ecip) | `0x70c1d1c709c75e3cf51d79d19cf7c84a0d4521f3a2b8bf7bff5cb45ee0dd289` | A contract allowing to compute elliptic curve multi scalar multiplication for all supported curve identifiers | +| [RiscZero Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/risc0\_verifier\_bn254) | `0x189d559773d197f7a4d0af561294e5d224455acddb541aa83f4262c8a25d56c` | A verifier for RiscZero Groth16-wrapped proofs. | +| [Drand Quicknet Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/drand\_quicknet) | `0x5dc6c40dc3937670c0f644424d10ce90270193f3385bf6f4360f52402647c1b` | A contract to verify Drand signatures and use timelock encryption utilities (soon). | From 6a87a6b9ce67eeb754e75293afd153dde7c7e597 Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Sun, 3 Nov 2024 09:43:35 +0000 Subject: [PATCH 06/17] GITBOOK-28: No subject --- .../rust-greater-than-python-bindings.md | 3 + .../rust-greater-than-wasm-bidings.md | 65 +++++++++++++++++-- docs/gitbook/installation/npm-package.md | 57 ---------------- docs/gitbook/installation/python-package.md | 4 ++ docs/gitbook/installation/rust-crate.md | 20 ++++++ 5 files changed, 88 insertions(+), 61 deletions(-) diff --git a/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-python-bindings.md b/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-python-bindings.md index cedad8bd..6697eac3 100644 --- a/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-python-bindings.md +++ b/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-python-bindings.md @@ -1,2 +1,5 @@ # Rust -> Python bindings +## Adding a binding + +TODO. diff --git a/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-wasm-bidings.md b/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-wasm-bidings.md index cedc69d7..f4b6a771 100644 --- a/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-wasm-bidings.md +++ b/docs/gitbook/developer-setup-and-guides/garaga-rs-crate/rust-greater-than-wasm-bidings.md @@ -1,6 +1,63 @@ ---- -description: Explains how to add a bind ---- - # Rust -> Wasm bidings +## Adding bindings + +TODO. + +## Development notes + +The Garaga NPM package is a mixed package. It is implemented in TypeScript but also reuses Rust code targeted to WebAssembly (WASM) with the help of [`wasm-pack`](https://rustwasm.github.io/wasm-pack/). + +The `src` folder is organized into two subfolders: `node` which contains the implementation in TypeScript; and `wasm` which has the interoperabilty code produced by `wasm-pack`. + +Changes to the TypeScript library should only be made to files under the `node` subfolder. Changes to the Rust implementation requires regenerating files under the `wasm` subfolder. + +Onces changes are in place they can be made permanent into the repository by committing the contents of both folders. Here is the bulk of the process: + +1. Open your terminal or command prompt. +2. Use `git` to clone the repository: + + ```bash + git clone https://github.com/keep-starknet-strange/garaga.git + cd tools/npm/garaga_ts + npm ci + ``` +3. If you make TypeScript only changes, you can quickly rebuild the package using the `build:node` NPM script: + + ```bash + npm run build:node + npm pack + ``` +4. If instead you make Rust changes, it is necessary to generate the WASM interoperability code using the `build` NPM script: + + ```bash + npm run build + npm pack + ``` +5. However, before commiting changes, it is necessary to generate the WASM interoperability code in a reproducible manner using docker: + + ```bash + docker compose up --build + git commit . + ``` + +### How `wasm-pack` is used to achieve interoperability + +Internaly the `build` NPM script uses `wasm-pack` to produce the WASM interoperability code. This is achieved by running + +```` +```bash +cd tools/garaga_rs && wasm-pack build --target web --out-dir ../npm/garaga_ts/src/wasm/pkg --release --no-default-features +cd tools/npm/garaga_ts && node patch.wasm.cjs +``` +```` + +Let's unpack it. + +In the Rust source folder we run `wasm-pack` in `--target web` mode. This generates TypeScript code targeting web pages. The `--release` option is required to minimize the size of the WASM module. And the `--no-default-features` disables the need to build non WASM features of garaga\_rs. + +Once the `wasm-pack` is done, the code is generated under the folder `src/wasm/pkg` of garaga\_ts that houses the TypeScript source code. + +We then run a custom script `patch.wasm.cjs` which makes minimal changes to the code generated by wasm-pack to facilitate seamless support of the WASM module in both the browser and Node.js. Basically it converts the WASM module to a [Base64](https://en.wikipedia.org/wiki/Base64) string that can be loaded in a portable way in both environments, amongst other minor tweaks. + +(It is important to note that the use of a custom script is only required so long `wasm-pack` itself does not provide a more portable/universal target mode.) diff --git a/docs/gitbook/installation/npm-package.md b/docs/gitbook/installation/npm-package.md index a783ea1c..9df2ff37 100644 --- a/docs/gitbook/installation/npm-package.md +++ b/docs/gitbook/installation/npm-package.md @@ -64,60 +64,3 @@ For reproducible builds, one can use instead docker compose. Make sure [docker]( npm i -S ``` -## Development notes - -The Garaga NPM package is a mixed package. It is implemented in TypeScript but also reuses Rust code targeted to WebAssembly (WASM) with the help of [`wasm-pack`](https://rustwasm.github.io/wasm-pack/). - -The `src` folder is organized into two subfolders: `node` which contains the implementation in TypeScript; and `wasm` which has the interoperabilty code produced by `wasm-pack`. - -Changes to the TypeScript library should only be made to files under the `node` subfolder. Changes to the Rust implementation requires regenerating files under the `wasm` subfolder. - -Onces changes are in place they can be made permanent into the repository by committing the contents of both folders. Here is the bulk of the process: - -1. Open your terminal or command prompt. -2. Use `git` to clone the repository: - - ```bash - git clone https://github.com/keep-starknet-strange/garaga.git - cd tools/npm/garaga_ts - npm ci - ``` -3. If you make TypeScript only changes, you can quickly rebuild the package using the `build:node` NPM script: - - ```bash - npm run build:node - npm pack - ``` -4. If instead you make Rust changes, it is necessary to generate the WASM interoperability code using the `build` NPM script: - - ```bash - npm run build - npm pack - ``` -5. However, before commiting changes, it is necessary to generate the WASM interoperability code in a reproducible manner using docker: - - ```bash - docker compose up --build - git commit . - ``` - -### How `wasm-pack` is used to achieve interoperability - -Internaly the `build` NPM script uses `wasm-pack` to produce the WASM interoperability code. This is achieved by running - -```` -```bash -cd tools/garaga_rs && wasm-pack build --target web --out-dir ../npm/garaga_ts/src/wasm/pkg --release --no-default-features -cd tools/npm/garaga_ts && node patch.wasm.cjs -``` -```` - -Let's unpack it. - -In the Rust source folder we run `wasm-pack` in `--target web` mode. This generates TypeScript code targeting web pages. The `--release` option is required to minimize the size of the WASM module. And the `--no-default-features` disables the need to build non WASM features of garaga\_rs. - -Once the `wasm-pack` is done, the code is generated under the folder `src/wasm/pkg` of garaga\_ts that houses the TypeScript source code. - -We then run a custom script `patch.wasm.cjs` which makes minimal changes to the code generated by wasm-pack to facilitate seamless support of the WASM module in both the browser and Node.js. Basically it converts the WASM module to a [Base64](https://en.wikipedia.org/wiki/Base64) string that can be loaded in a portable way in both environments, amongst other minor tweaks. - -(It is important to note that the use of a custom script is only required so long `wasm-pack` itself does not provide a more portable/universal target mode.) diff --git a/docs/gitbook/installation/python-package.md b/docs/gitbook/installation/python-package.md index 4c5d063d..a5693089 100644 --- a/docs/gitbook/installation/python-package.md +++ b/docs/gitbook/installation/python-package.md @@ -4,6 +4,10 @@ icon: python # Python package +{% hint style="info" %} +PyPi link : [https://pypi.org/project/garaga/](https://pypi.org/project/garaga/) +{% endhint %} + The easiest way to install Garaga is via `pip`, which will fetch and install the pre-built binary wheels for your platform. 1. Open your terminal or command prompt. diff --git a/docs/gitbook/installation/rust-crate.md b/docs/gitbook/installation/rust-crate.md index c14ab964..714372c1 100644 --- a/docs/gitbook/installation/rust-crate.md +++ b/docs/gitbook/installation/rust-crate.md @@ -4,3 +4,23 @@ icon: rust # Rust Crate +To use the [`garaga_rs`](https://github.com/keep-starknet-strange/garaga/tree/main/tools/garaga\_rs) crate in your project, add the following to your `Cargo.toml` + + + +``` +[dependencies] +garaga_rs = { git = "https://github.com/keep-starknet-strange/garaga.git"} + +``` + +It is recommended to use the latest [release tag](https://github.com/keep-starknet-strange/garaga/releases) of the form `vX.Y.Z` (example `v0.14.0`) to be in sync with the latest declared [maintained-smart-contracts](../maintained-smart-contracts/ "mention"). + +``` +[dependencies] +garaga_rs = { git = "https://github.com/keep-starknet-strange/garaga.git", tag = "v0.14.0" } + +``` + + + From 7ea782db2119f22632b62ff38b807bd630d434b5 Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Sun, 3 Nov 2024 09:46:09 +0000 Subject: [PATCH 07/17] GITBOOK-29: No subject --- docs/gitbook/maintained-smart-contracts/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/gitbook/maintained-smart-contracts/README.md b/docs/gitbook/maintained-smart-contracts/README.md index ea69da9a..a2ae48a1 100644 --- a/docs/gitbook/maintained-smart-contracts/README.md +++ b/docs/gitbook/maintained-smart-contracts/README.md @@ -4,7 +4,7 @@ icon: file-lock # Maintained Smart Contracts -We declare & maintain Smart Contracts for the community. +We declare & maintain Smart Contracts for the community so they can be used as library calls. \ Those contracts: @@ -22,4 +22,5 @@ Those contracts: | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | [Universal ECIP](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/universal\_ecip) | `0x70c1d1c709c75e3cf51d79d19cf7c84a0d4521f3a2b8bf7bff5cb45ee0dd289` | A contract allowing to compute elliptic curve multi scalar multiplication for all supported curve identifiers | | [RiscZero Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/risc0\_verifier\_bn254) | `0x189d559773d197f7a4d0af561294e5d224455acddb541aa83f4262c8a25d56c` | A verifier for RiscZero Groth16-wrapped proofs. | -| [Drand Quicknet Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/drand\_quicknet) | `0x5dc6c40dc3937670c0f644424d10ce90270193f3385bf6f4360f52402647c1b` | A contract to verify Drand signatures and use timelock encryption utilities (soon). | +| [Drand Quicknet Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/drand\_quicknet) | `0x5dc6c40dc3937670c0f644424d10ce90270193f3385bf6f4360f52402647c1b` | A contract to verify Drand signatures. Soon with timelock encryption utilities. | + From 01e9003ee57889782c076c8b98e84107b9b6d3d0 Mon Sep 17 00:00:00 2001 From: Tekkac Date: Mon, 4 Nov 2024 15:45:51 +0100 Subject: [PATCH 08/17] =?UTF-8?q?=F0=9F=93=9D=20add=20calldata=20method=20?= =?UTF-8?q?docs=20(#253)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../using-python-garaga-cli.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-python-garaga-cli.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-python-garaga-cli.md index 79faac59..3acec108 100644 --- a/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-python-garaga-cli.md +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/groth16/generating-calldata-from-a-proof-and-using-your-deployed-contract/using-python-garaga-cli.md @@ -1,2 +1,34 @@ # Using Python/Garaga CLI +Using the `garaga calldata` command from the CLI, you can generate the calldata needed to verify a proof for the `verify_groth16_proof_[curve_name]`. + +First, ensure that: + - Your circuit is compiled and the verification key `verification_key.json` is created + - The public input file `public.json` and the associated proof `proof.json` are created + +The call the following command by replacing the parameters with your data: + +```bash +garaga calldata --system groth16 --vk verification_key.json --proof proof.json --public-inputs public.json +2789 41983001825546257095993508953 3045291465937026073442547681 1840582864647114302 0 69020349870260156176548317333 16784567729677911275297018120 1865382613176499468 0 51545988015561248414407597558 44248521764831362261757723052 8850086 ... +``` + +## `starkli` usage + +Using the command option `--format starkli`, +you can directly pipe the generated calldata to `starkli` to invoke a transaction on your deployed contract. + +The proof must be the last parameter of your contract's method. + +```bash +garaga calldata --system groth16 --vk verification_key.json --proof proof.json --public-inputs public.json --format starkli | xargs starkli invoke --keystore-password $KEYSTORE_PASSWORD --watch $YOUR_CONTRACT your_verify_method YOUR_PARAMETERS +``` + +## Cairo code usage + +Use the command option `--format array` to generate calldata in array format to be used in your smart-contract tests. + +```bash +garaga calldata --system groth16 --vk verification_key.json --proof proof.json --public-inputs public.json --format array +[2789, 41983001825546257095993508953, 3045291465937026073442547681, 1840582864647114302, 0, 69020349870260156176548317333, 16784567729677911275297018120, 1865382613176499468, 0, 51545988015561248414407597558, 44248521764831362261757723052, 88500861247646845, 0, ... ] +``` \ No newline at end of file From 8ac667d5ca9f4f565615564c5b36a593e5775c89 Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Mon, 9 Dec 2024 08:46:50 +0000 Subject: [PATCH 09/17] GITBOOK-32: No subject --- .../noir.md | 102 +++++++++++++++++- 1 file changed, 101 insertions(+), 1 deletion(-) diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md index d193e775..712e9b41 100644 --- a/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md @@ -4,4 +4,104 @@ icon: octopus # Noir -Soon +## Requirements + +* Noir 0.36.0 (install with \`noirup --version 0.36.0\`) +* Barretenberg 0.61.0 (install with \`bbup --version 0.61.0\`) + +To install `noirup` and `bbup`, follow the [quickstart guide from aztec ](https://noir-lang.org/docs/getting_started/quick_start): + +We recall the installations commands here: + +```bash +curl -L noirup.dev | bash +``` + +```bash +curl -L bbup.dev | bash +``` + +## Generate a Starknet smart contract for your Noir program + +First, we'll create a new Noir project and compile it. + +```bash +nargo init hello +cd hello +nargo build +``` + +This will create a json file in `hello/target/hello.json` + +Now you can generate the corresponding verifying key using barretenberg : + +```bash +bb write_vk_ultra_keccak_honk -b target/hello.json -o target/vk.bin +``` + +Finally, you can generate a smart contract from the verifying key using the garaga CLI + +```bash +garaga gen --system ultra_keccak_honk --vk target/vk.bin +``` + +This will create a smart contract folder with the following structure. + +``` +Generating Smart Contract project for ProofSystem.UltraKeccakHonk using vk.bin... +Done! +Smart Contract project created: +/noir/hello/my_project/ +├── .tools-versions +├── Scarb.toml +└── src/ + ├── honk_verifier.cairo + ├── honk_verifier_circuits.cairo + ├── honk_verifier_constants.cairo + └── lib.cairo +``` + +The main function of interest is located in `honk_verifier.cairo` + +The contract interface will be + +```rust +#[starknet::interface] +trait IUltraKeccakHonkVerifier { + fn verify_ultra_keccak_honk_proof( + self: @TContractState, full_proof_with_hints: Span, + ) -> Option>; +} + +``` + + + +In order to interact with the endpoint, you need to generate the `full_proof_with_hints`array. + +To do so, you need a specific proof for your program. But first, Noir requires you to specify the inputs of your program in `hello/Prover.toml` + +```toml +// The "hello" program simply prove that x!=y, with x being private and y public. +x = "1" +y = "2" +``` + +You can now generate a proof with barretenberg, after running the program : + +```bash +nargo execute witness +bb prove_ultra_keccak_honk -b target/hello.json -w target/witness.gz -o target/proof.bin +``` + +Finally, you can obtain the `full_proof_with_hints` array using the garaga CLI : + +```bash +garaga calldata --system ultra_keccak_honk --vk vk.bin --proof proof.bin --format array +``` + + + +{% hint style="info" %} +Using `garaga calldata`with the `--format array` lets you paste this array in cairo code for unit tests by doing let proof:Array\ = \[ ... ] ; . The `--format starkli` has a formatting which is composable with starkli in the command line and also preprends the length of the array so that it can be deserialized by starknet. +{% endhint %} From 66b39f677575d15b49a7d8163cac972da41e724a Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Mon, 9 Dec 2024 09:18:16 +0000 Subject: [PATCH 10/17] GITBOOK-33: No subject --- docs/gitbook/maintained-smart-contracts/README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/gitbook/maintained-smart-contracts/README.md b/docs/gitbook/maintained-smart-contracts/README.md index a2ae48a1..de5e53a1 100644 --- a/docs/gitbook/maintained-smart-contracts/README.md +++ b/docs/gitbook/maintained-smart-contracts/README.md @@ -16,11 +16,13 @@ Those contracts: \ +### Class hash for Garaga v0.15.0. + +| Contract | Class hash | Description | +| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| [Universal ECIP](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/universal_ecip) | `0xc4b7aa28a27b5fb8d7d43928b2a3ee960cf5b4e06cb9ae1ee3f102400b1700` | A contract allowing to compute elliptic curve multi scalar multiplication for all supported curve identifiers | +| [RiscZero Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/risc0_verifier_bn254) | `0x17f652cddd526fbe4f9c9b0380985adbc5ea5ce82d6d06170a355a0540d4979` | A verifier for RiscZero Groth16-wrapped proofs. | +| [Drand Quicknet Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/drand_quicknet) | `0x381e2dda664bb383a95b49bf83f04eef1a656aca8ab2e66c9499fa9a8079624` | A contract to verify Drand signatures. Soon with timelock encryption utilities. | -| Contract | Class hash | Description | -| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| [Universal ECIP](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/universal\_ecip) | `0x70c1d1c709c75e3cf51d79d19cf7c84a0d4521f3a2b8bf7bff5cb45ee0dd289` | A contract allowing to compute elliptic curve multi scalar multiplication for all supported curve identifiers | -| [RiscZero Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/risc0\_verifier\_bn254) | `0x189d559773d197f7a4d0af561294e5d224455acddb541aa83f4262c8a25d56c` | A verifier for RiscZero Groth16-wrapped proofs. | -| [Drand Quicknet Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/drand\_quicknet) | `0x5dc6c40dc3937670c0f644424d10ce90270193f3385bf6f4360f52402647c1b` | A contract to verify Drand signatures. Soon with timelock encryption utilities. | From 12d5373cebd57bceb059de7a8eef15b723c95664 Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Mon, 9 Dec 2024 10:58:13 +0000 Subject: [PATCH 11/17] GITBOOK-34: No subject --- docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md index 712e9b41..3cc4693a 100644 --- a/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md @@ -8,6 +8,7 @@ icon: octopus * Noir 0.36.0 (install with \`noirup --version 0.36.0\`) * Barretenberg 0.61.0 (install with \`bbup --version 0.61.0\`) +* Garaga CLI [python-package.md](../installation/python-package.md "mention") To install `noirup` and `bbup`, follow the [quickstart guide from aztec ](https://noir-lang.org/docs/getting_started/quick_start): From 0e184f6948753186241527f86d5939b9bd89c2dc Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Wed, 11 Dec 2024 06:37:42 +0000 Subject: [PATCH 12/17] GITBOOK-35: No subject --- docs/gitbook/maintained-smart-contracts/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/gitbook/maintained-smart-contracts/README.md b/docs/gitbook/maintained-smart-contracts/README.md index de5e53a1..3b219666 100644 --- a/docs/gitbook/maintained-smart-contracts/README.md +++ b/docs/gitbook/maintained-smart-contracts/README.md @@ -16,12 +16,12 @@ Those contracts: \ -### Class hash for Garaga v0.15.0. +### Class hash for Garaga v0.15.1. | Contract | Class hash | Description | | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | [Universal ECIP](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/universal_ecip) | `0xc4b7aa28a27b5fb8d7d43928b2a3ee960cf5b4e06cb9ae1ee3f102400b1700` | A contract allowing to compute elliptic curve multi scalar multiplication for all supported curve identifiers | -| [RiscZero Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/risc0_verifier_bn254) | `0x17f652cddd526fbe4f9c9b0380985adbc5ea5ce82d6d06170a355a0540d4979` | A verifier for RiscZero Groth16-wrapped proofs. | +| [RiscZero Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/risc0_verifier_bn254) | `0x34fda7d39c28c2fb0d8e876f1c51a38f9fa395023c3749a0ee793611baa6095` | A verifier for RiscZero Groth16-wrapped proofs. | | [Drand Quicknet Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/drand_quicknet) | `0x381e2dda664bb383a95b49bf83f04eef1a656aca8ab2e66c9499fa9a8079624` | A contract to verify Drand signatures. Soon with timelock encryption utilities. | From b52f81a3a5be84e7174a6e28b9f0b986f4bc2093 Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Mon, 16 Dec 2024 15:13:17 +0000 Subject: [PATCH 13/17] GITBOOK-36: No subject --- docs/gitbook/maintained-smart-contracts/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/gitbook/maintained-smart-contracts/README.md b/docs/gitbook/maintained-smart-contracts/README.md index 3b219666..f81e8311 100644 --- a/docs/gitbook/maintained-smart-contracts/README.md +++ b/docs/gitbook/maintained-smart-contracts/README.md @@ -16,13 +16,13 @@ Those contracts: \ -### Class hash for Garaga v0.15.1. +### Class hash for Garaga v0.15.3. -| Contract | Class hash | Description | -| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| [Universal ECIP](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/universal_ecip) | `0xc4b7aa28a27b5fb8d7d43928b2a3ee960cf5b4e06cb9ae1ee3f102400b1700` | A contract allowing to compute elliptic curve multi scalar multiplication for all supported curve identifiers | -| [RiscZero Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/risc0_verifier_bn254) | `0x34fda7d39c28c2fb0d8e876f1c51a38f9fa395023c3749a0ee793611baa6095` | A verifier for RiscZero Groth16-wrapped proofs. | -| [Drand Quicknet Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/drand_quicknet) | `0x381e2dda664bb383a95b49bf83f04eef1a656aca8ab2e66c9499fa9a8079624` | A contract to verify Drand signatures. Soon with timelock encryption utilities. | +| Contract | Class hash | Description | +| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| [Universal ECIP](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/universal_ecip) | `0x684d2756a4440c190a5fe54e367c0abe33aefa75084dec2fffc791b620c80e3` | A contract allowing to compute elliptic curve multi scalar multiplication for all supported curve identifiers | +| [RiscZero Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/risc0_verifier_bn254) | `0x7f3157e83dc0d636c462c77fd8f309351b4a2c710f9a23a443 05830a29b0b27` | A verifier for RiscZero Groth16-wrapped proofs. | +| [Drand Quicknet Verifier](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/drand_quicknet) | `0x42462549f0c848750e734d6bc10a040f967ee517c0b316bfd9656ab65a2eef8` | A contract to verify Drand signatures. Soon with timelock encryption utilities. | From c3a0522dae509a8dedff3626589bc51d1d77ce2b Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Mon, 23 Dec 2024 07:38:33 +0000 Subject: [PATCH 14/17] GITBOOK-31: No subject --- .../maintained-smart-contracts/risczero.md | 418 +++++++++++++++++- 1 file changed, 417 insertions(+), 1 deletion(-) diff --git a/docs/gitbook/maintained-smart-contracts/risczero.md b/docs/gitbook/maintained-smart-contracts/risczero.md index a0b4717d..b202a786 100644 --- a/docs/gitbook/maintained-smart-contracts/risczero.md +++ b/docs/gitbook/maintained-smart-contracts/risczero.md @@ -4,4 +4,420 @@ icon: microchip # RiscZero -Docs incoming. +RiscZero is a Zero-Knowledge Proof system designed to enable efficient and scalable construction of computational proofs based on the RISC-V architecture. It is Groth16-based and works over the BN254 elliptic curve. + +Garaga provides the tools and makes it possible to verify such proofs on-chain in a Starknet/Cairo smart contract. + +A Zero-Knowledge proof is a mathematical construct that guarantees that a given value is the output of a predefined computation where some of the inputs are private and must not be disclosed. + +This is achieved in two steps: + +1- A Prover performs the computation and constructs the proof artifact. The proof artifact contains the computational journal which is, in simple terms, the list of public inputs and the output value. The proof artifact attests the integrity of the computation, which means the prover ran the computation properly and the output value registered in the journal corresponds to the result of such computation given the public inputs, also registered in the jornal, an some undisclosed private inputs. Here the Verifier is a RiscZero user-defined program that implements the desired computation and is augmented to produce the desired proof artifact. + +2- Given the proof artifact, a Verifier must check its integrity before processing the output as valid. Here the Verifier is a Starknet smart contract written in Cairo and Garaga acts as a library to which the verification is delegated to. + +### Setting up the development environment + +Before starting development we need to install all the software prerequisites for building either or both the Prover and Verifier components. + +Below we provide general installation instructions for a Linux-based system. Depending on your setup you may already have some of the software installed, in which case you can skip the associated sections. But if you need additional help for a specific set up, please follow the links provided.\ +\ +In order to implement the Prover one needs to install the tooling required by RiscZero: + +1. Install Rust/Cargo using [`rustup`](https://rustup.rs/) (default version 1.8.3) + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y +export PATH="$HOME/.cargo/bin:$PATH" +``` + +2. Install the RiscZero tool-chain using [`rzup`](https://dev.risczero.com/api/zkvm/install) (default version 1.2.0) + +```bash +curl -L https://risczero.com/install | bash +export PATH="$HOME/.risc0/bin:$PATH" +rzup install +``` + +_Important: Make sure the RiscZero version installed matches the version supported by Garaga. For RiscZero 1.2.0 use Garaga 0.15.3. For RiscZero 1.1.3 use Garaga 0.14.0._ + +3. Install RiscZero additional/custom dependencies + +A C compiler, such as `gcc`, `pkg-config` and OpenSSL development libraries (`libssl-dev)` are necessary to build a RiscZero project. You should refer to your system documentation on how to install those. Here is a quick reference for Debian compatible systems + +```bash +sudo apt install -y gcc libssl-dev pkg-config +``` + +Optionally, if you intend to have the Prover generate the contract call data explicitly, Garaga requires that Python is available in your environment. If necessary, check their [documentation](https://docs.python.org/3/using/index.html) for installation instructions for your system. Again, here is a quick reference for Debian compatible systems + +```bash +sudo apt install -y python3 +``` + +In order to implement the Verifier one needs to install the tooling for Cairo development and Garaga: + +4. Install the Starknet/Cairo bundler tool [`scarb`](https://docs.swmansion.com/scarb/download#install-via-installation-script) (default version 2.9.2) + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | bash +export PATH="$HOME/.local/bin:$PATH" +``` + +5. Install Starknet Foundry using [`snfoundryup`](https://foundry-rs.github.io/starknet-foundry/getting-started/installation.html) (default version 1.35.1) + +```bash +curl -L https://raw.githubusercontent.com/foundry-rs/starknet-foundry/master/scripts/install.sh | bash +export PATH="$HOME/.local/bin:$PATH" +snfoundryup +``` + +### Create or configure the RiscZero project + +1. If you are setting up a new RiscZero project, run the command below, it will create a new project folder and define the Guest program name. The Guest program is the program that is compiled to and will run in the RiscZero VM. The project setup also creates a Host program that runs outside the RiscZero VM and interacts with the Guest, providing inputs and collecting outputs, to produce the ZK proof. Here we set up a sample project called `fibonacci_prover` with a Guest called `fibonacci_guest` + +``` +cargo risczero new fibonacci_prover --guest-name fibonacci_guest +``` + +If you already have a RiscZero project set up, make sure the RiscZero version configured as dependencies is consistent with the RiscZero toolchain installed in the previous steps. + +2. Next we need to modify the RiscZero Host program to output the proof artifact in the desired JSON format. Add the following dependencies to `host/Cargo.toml` + +```toml +[dependencies] +risc0-ethereum-contracts = { version = "1.2.0" } +hex = "0.4" +... +``` + +Optionally, if you intend to explicitly generate and handle the call data, also add the following dependency to `host/Cargo.toml` + +
[dependencies]
+garaga_rs = { git = "https://github.com/keep-starknet-strange/garaga.git", tag = "v0.15.3" }
+...
+
+ +Then we modify the Host program `host/src/main.rs` to generate the JSON file containing the proof artifact. We start by adding the required imports + +```rust +use risc0_zkvm::{ + compute_image_id, default_prover, ExecutorEnv, ProverOpts, VerifierContext +}; +use risc0_ethereum_contracts::encode_seal; +``` + +Optionally, if you intend to generate the call data explicitly, add the following imports + +```rust +use garaga_rs::definitions::CurveID; +use garaga_rs::calldata::full_proof_with_hints::groth16::{ + get_groth16_calldata, Groth16Proof +}; +use garaga_rs::calldata::full_proof_with_hints::groth16::risc0_utils::get_risc0_vk; +``` + +Next we need to modify the Host main function. + +If you are starting a fresh RiscZero project, you will need to setup the environment for the computation. This is basically the set of inputs that will be used by the Guest program to perform the computation. + +Below is an example for the `fibonacci_prover`. In this example, we want to compute the number at position `n` of the Fibonacci sequence. However we do not want to reveal `n`, but instead show that `n` lies in a given interval defined by a lower bound `l` and an upper bound `u`. + +```rust +let l: u32 = 3; // public lower bound for n +let u: u32 = 8; // public upper bound for n +let n: u32 = 6; // private n for which we will compute fibonacci(n) +let env = ExecutorEnv::builder() + .write(&l) + .unwrap() + .write(&u) + .unwrap() + .write(&n) + .unwrap() + .build() + .unwrap(); +``` + +Next we modify the default Prover setup to explicitly use Groth16 + +```rust +let prove_info = prover + .prove_with_ctx( + env, + &VerifierContext::default(), + FIBONACCI_GUEST_ELF, + &ProverOpts::groth16() + ) + .unwrap(); +``` + +Finally, as the last step of the Host program, we extract and print the proof artifact JSON to the standard output + +
let receipt = prove_info.receipt;
+let seal = to_bytes(encode_seal(&receipt).unwrap());
+let image_id = to_bytes(compute_image_id(&FIBONACCI_GUEST_ELF).unwrap());
+let journal = to_bytes(receipt.journal);
+println!(
+    "{{\"seal\": \"0x{}\", \"image_id\": \"0x{}\", \"journal\": \"0x{}\"}}",
+    hex::encode(&seal),
+    hex::encode(&image_id),
+    hex::encode(&journal)
+);
+
+// helper function to convert objects to array of bytes
+fn to_bytes<T: AsRef<[u8]>>(obj: T) -> Vec<u8> {
+    obj.as_ref().to_vec()
+}
+
+ +Optionally, if you also intend to handle the call data explicitly, it can be computed and output as a JSON as well. This produces a large array that encodes the full RiscZero proof wih hints + +```rust +let proof = Groth16Proof::from_risc0(seal, image_id, journal); +let calldata = get_groth16_calldata(&proof, &get_risc0_vk(), CurveID::BN254).unwrap(); +println!("[{}]", calldata.iter().skip(1).map(|v| format!("\"{}\"", v)).collect::>().join(", ")); +``` + +Now we need to set up the Guest program that performs the computation required by our use case. + +If you started a fresh RiscZero project, then you will need to write the Guest program that performs the computation. It is done by modifying the main function of the Guest source file at `methods/guest/src/main.rs` + +In our example, here is what the Guest code looks like for the `fibonacci_guest` + +```rust +// reads the public bounds and private n provided by the Host +let l: u32 = env::read(); +let u: u32 = env::read(); +let n: u32 = env::read(); + +// sanity check for the bounds +assert!(l <= n && n < u); + +// performs the computation +let fib_n: u32 = fibonacci(n); + +fn fibonacci(n: u32) -> u32 { + let mut a = 0; + let mut b = 1; + for _ in 0..n { + (a, b) = (b, a + b); + } + a +} + +// writes the public inputs and output to the journal +env::commit(&l); +env::commit(&u); +env::commit(&fib_n); +``` + +### RiscZero Proof Generation + +RiscZero provides some options when it comes to proof generation. Please refer to their [documentation](https://dev.risczero.com/api/generating-proofs/proving-options) in case you need to in depth information on that. The easiest and most convenient way is to use the provided [Bonsai](https://www.bonsai.xyz/) service, which works fine for many purposes. In that case, an API key for the service is required. + +_It is important to note that, if your computation has private inputs, you should definitely protect them from being exposed to external services like Bonsai by performing the proof generation locally._ + +Here is the command to run the Prover via Bonsai + +``` +BONSAI_API_KEY= BONSAI_API_URL= RISC0_DEV_MODE=0 \ + cargo run --release +``` + +### Developing the RiscZero Verifier smart contract + +There are different ways one can choose to develop a Cairo smart contract, we recommend using Staknet Foundry. A fresh new project can be created by issuing the following command + +```bash +snforge new fibonacci_sequencer +``` + +This will output a template for a smart contract along with the necessary tooling configuration to build and test it. In this case we are creating a contract called `fibonacci_sequencer`, that will process and update its state with a new number in the Fibonacci sequence that is guaranteed to have an index `n` in the sequence that is higher than the last one currently registered by the contract, although that exact index `n` is never revealed publicly. + +Garaga already provides a smart contract to verify RiscZero proofs. To make use of that functionality, one just has to call a predefined library function from the client smart contract. In order to do that, one needs to declare the interface of the RiscZero verifying library function in `src/lib.cairo`: + +```rust +#[starknet::interface] +trait IRisc0Groth16VerifierBN254 { + fn verify_groth16_proof_bn254( + self: @TContractState, full_proof_with_hints: Span, + ) -> Option>; +} +``` + +The `verify_groth16_proof_bn254` function takes the call data that encodes the proof with hints as a list of integers of type `felt252` and returns the journal (as a list of bytes) on proof verification success, or nothing if the verification fails. + +Here is how to verify the RiscZero proof and update the smart contract state for our Fibonacci sequencer example: + +```rust +fn submit_fibonacci_number(ref self: ContractState, full_proof_with_hints: Span) { + // sets the class hash for the RiscZero verifier already declared on-chain + // by the Garaga team + let class_hash: ClassHash = RISC_ZERO_VERIFIER_CLASS_HASH.try_into().unwrap(); + + // instantiate a library dispatcher to perform the library call + // to the RiscZero verifier class, given that verifying a proof is + // a read-only operation + let dispatcher = IRisc0Groth16VerifierBN254LibraryDispatcher { class_hash }; + + // calls the RiscZero verifier passing along the proof artifact and + // checks whether the proof is valid or not, aborting the transaction if not + let optional_journal = dispatcher.verify_groth16_proof_bn254(full_proof_with_hints); + assert(optional_journal != Option::None, 'Invalid proof'); + + // parses the public inputs and output from the journal + let journal = optional_journal.unwrap(); + let l = decode_u32_le(journal, 0); + let u = decode_u32_le(journal, 4); + let fib_n = decode_u32_le(journal, 8); + + // performs the necessary state update check, updates the state, + // and emits an event with the new fibnoacci number submitted + // the smart contract invariant guarantees that every fiboacci number + // accepted comes later in the fibonacci sequence without revealing + // its index, which is trivial for monotonic sequences like fibnacci, + // but would also work as expected also for non-monotonic ones + let b = self.lower_bound.read(); + assert(l >= b, 'Invalid lower bound'); + self.lower_bound.write(u); + self.emit(FibonnacciNumberSubmitted { n: fib_n }); + self.emit(LowerBoundUpdated { n: u }); +} +``` + +Along with the `submit_fibonacci_number` contract method, we need to define the RiscZero Verifier class hash, which can be obtained [here](./) + +```rust +use core::starknet::ClassHash; + +pub const RISC_ZERO_VERIFIER_CLASS_HASH: felt252 = + ; +``` + +The contract state which stores the current lower bound which gets updated whenever a new Fibonacci number is submitted + +```rust +#[storage] +struct Storage { + lower_bound: u32, +} +``` + +And also the helper function used to decode the journal values + +```rust +fn decode_u32_le(bytes: Span, i: usize) -> u32 { + let b0: u32 = (*bytes[i]).into(); + let b1: u32 = (*bytes[i + 1]).into(); + let b2: u32 = (*bytes[i + 2]).into(); + let b3: u32 = (*bytes[i + 3]).into(); + b0 + 256 * (b1 + 256 * (b2 + 256 * b3)) +} +``` + +For completeness, we also provide the definition of the events emitted by the operation + +```rust +#[event] +#[derive(Drop, starknet::Event)] +enum Event { + FibonnacciNumberSubmitted: FibonnacciNumberSubmitted, + LowerBoundUpdated: LowerBoundUpdated, +} + +#[derive(Drop, starknet::Event)] +struct FibonnacciNumberSubmitted { + #[key] + n: u32, +} + +#[derive(Drop, starknet::Event)] +struct LowerBoundUpdated { + #[key] + n: u32, +} +``` + +It is important to note that the `submit_fibonacci_number` function defined in this sample contract has a signature that takes a single argument: the proof artifact. This is useful because we can then submit the transaction to the blockchain directly, simply using the Garaga CLI passing along the JSON file output by the RiscZero Host program. This avoids the need to encode the proof as a customized call data. It also spares us from dealing with the transaction submission details which is handled internally by the Garaga CLI. + +This is an approach that makes sense when all the information required to validate and update the smart contract state can be extracted from the journal, exempting us from the need of passing additional parameters to the function which would deem it incompatible with the interface expected by the CLI. + +Once the Cairo smart contract is ready, it can be deployed in three steps: + +* Declare + + ```bash + sncast --profile declare --contract-name + ``` + + This will declare the smart contract class and return its hash. +* Deploy + + ```bash + sncast --profile deploy --class-hash + ``` + + This will deploy the smart contract instance and return its address. +* Verify (Optional) + + ```bash + sncast --profile verify \ + --network \ + --contract-name \ + --contract-address + ``` + + This will match the deployed code with the smart contract source code and make it available on Starknet block explorers. + +Before running any of the commands above, one has to configure foundry to add the desired profile name. That is achieved by editing the `snfoundry.toml` file. Here is a sample configuration as reference + +```toml +[sncast.sepolia] +account = "deployer" +accounts-file = "./accounts.json" +url = "https://starknet-sepolia.public.blastapi.io/rpc/v0_7" +``` + +This requires an `accounts.json` file. One such a way to generate it is using the following command + +```bash +sncast account import \ + --name deployer \ + --type \ + --address \ + --private-key +``` + +One can setup an [ArgentX](https://www.argent.xyz/) or [Braavos](https://braavos.app/) wallet, fund it, and export its private key. + +### Submitting the proof to the blockchain using the Garaga CLI + +Once the smart contract is published on the blockchain network, users can interact with it. In our case, one such interaction would be to perform a computation off-chain with RiscZero and submit it to the smart contract. + +As mentioned before, the JSON proof artifact generated by the RiscZero execution can be submitted to the blockchain using Garaga CLI: + +```bash +garaga verify-onchain \ + --system groth16 \ + --vk \ + --network \ + --contract-address \ + --endpoint \ + --proof +``` + +The RiscZero verifying key is shipped along Garaga and is located at `hydra/garaga/starknet/groth16_contract_generator/examples/vk_risc0.json`. + +In order to run the Garaga `verify-onchain` command you will need to provide a .`secrets` file in the current folder, or elsewhere using the `--env-file` option. Here is the format for the `.secrets` file + +``` +SEPOLIA_RPC_URL="https://starknet-sepolia.public.blastapi.io/rpc/v0_7" +SEPOLIA_ACCOUNT_PRIVATE_KEY= +SEPOLIA_ACCOUNT_ADDRESS= + +MAINNET_RPC_URL="https://starknet-mainnet.public.blastapi.io/rpc/v0_7" +MAINNET_ACCOUNT_PRIVATE_KEY= +MAINNET_ACCOUNT_ADDRESS= +``` + +Please make sure to provide RPC endpoints that supports version 0.7 of the Starknet JSON API From ef04733f134957e1781c92536ca15d1d6f802306 Mon Sep 17 00:00:00 2001 From: raugfer Date: Sat, 28 Dec 2024 09:32:37 +0000 Subject: [PATCH 15/17] GITBOOK-37: raugfer's Dec 27 changes --- .../maintained-smart-contracts/risczero.md | 46 +++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/gitbook/maintained-smart-contracts/risczero.md b/docs/gitbook/maintained-smart-contracts/risczero.md index b202a786..e6768729 100644 --- a/docs/gitbook/maintained-smart-contracts/risczero.md +++ b/docs/gitbook/maintained-smart-contracts/risczero.md @@ -12,7 +12,7 @@ A Zero-Knowledge proof is a mathematical construct that guarantees that a given This is achieved in two steps: -1- A Prover performs the computation and constructs the proof artifact. The proof artifact contains the computational journal which is, in simple terms, the list of public inputs and the output value. The proof artifact attests the integrity of the computation, which means the prover ran the computation properly and the output value registered in the journal corresponds to the result of such computation given the public inputs, also registered in the jornal, an some undisclosed private inputs. Here the Verifier is a RiscZero user-defined program that implements the desired computation and is augmented to produce the desired proof artifact. +1- A Prover performs the computation and constructs the proof artifact. The proof artifact contains the computational journal which is, in simple terms, the list of public inputs and the output value. The proof artifact attests the integrity of the computation, which means the prover ran the computation properly and the output value registered in the journal corresponds to the result of such computation given the public inputs, also registered in the jornal, an some undisclosed private inputs. Here the Prover is a RiscZero user-defined program that implements the desired computation and is augmented to produce the desired proof artifact. 2- Given the proof artifact, a Verifier must check its integrity before processing the output as valid. Here the Verifier is a Starknet smart contract written in Cairo and Garaga acts as a library to which the verification is delegated to. @@ -57,7 +57,7 @@ sudo apt install -y python3 In order to implement the Verifier one needs to install the tooling for Cairo development and Garaga: -4. Install the Starknet/Cairo bundler tool [`scarb`](https://docs.swmansion.com/scarb/download#install-via-installation-script) (default version 2.9.2) +4. Install the Starknet/Cairo bundler tool [`scarb`](https://docs.swmansion.com/scarb/download#install-via-installation-script) (default version 2.9.1) ```bash curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | bash @@ -74,7 +74,7 @@ snfoundryup ### Create or configure the RiscZero project -1. If you are setting up a new RiscZero project, run the command below, it will create a new project folder and define the Guest program name. The Guest program is the program that is compiled to and will run in the RiscZero VM. The project setup also creates a Host program that runs outside the RiscZero VM and interacts with the Guest, providing inputs and collecting outputs, to produce the ZK proof. Here we set up a sample project called `fibonacci_prover` with a Guest called `fibonacci_guest` +1. If you are setting up a new RiscZero project, run the command below, it will create a new project folder and define the Guest program name. The Guest program is the program that is compiled to and will run in the RiscZero VM. The project setup also creates a Host program that runs outside the RiscZero VM and interacts with the Guest, providing inputs and collecting outputs, to produce the ZK proof. Here we set up a sample project called `fibonacci_prover` with a Guest called `fibonacci_guest` (for reference, the complete RiscZero app presented here is available in [Garaga's GitHub repository](https://github.com/keep-starknet-strange/garaga/tree/main/src/contracts/risc0_sample_app)) ``` cargo risczero new fibonacci_prover --guest-name fibonacci_guest @@ -91,7 +91,7 @@ hex = "0.4" ... ``` -Optionally, if you intend to explicitly generate and handle the call data, also add the following dependency to `host/Cargo.toml` +Optionally, if you intend to explicitly generate and handle the call-data, also add the following dependency to `host/Cargo.toml`. Make sure to use a Garaga version tag that is consistent with your setup. 
[dependencies]
 garaga_rs = { git = "https://github.com/keep-starknet-strange/garaga.git", tag = "v0.15.3" }
@@ -107,7 +107,7 @@ use risc0_zkvm::{
 use risc0_ethereum_contracts::encode_seal;
 ```
 
-Optionally, if you intend to generate the call data explicitly, add the following imports
+Optionally, if you intend to generate the call-data explicitly, add the following imports
 
 ```rust
 use garaga_rs::definitions::CurveID;
@@ -138,6 +138,8 @@ let env = ExecutorEnv::builder()
     .unwrap();
 ```
 
+_As a note, the sample app provided here exists only to demonstrate how to setup a ZK project using Garaga/RiscZero. It is clear that datatype `u32` is not appropriate datatype to host a secret Fibonacci number as it can be easily discovered by brute force checking all possibilities between the bounds._
+
 Next we modify the default Prover setup to explicitly use Groth16
 
 ```rust
@@ -170,7 +172,7 @@ fn to_bytes<T: AsRef<[u8]>>(obj: T) -> Vec<u8> {
 }
-Optionally, if you also intend to handle the call data explicitly, it can be computed and output as a JSON as well. This produces a large array that encodes the full RiscZero proof wih hints +Optionally, if you also intend to handle the call-data explicitly, it can be computed and output as a JSON as well. This produces a large array that encodes the full RiscZero proof wih hints ```rust let proof = Groth16Proof::from_risc0(seal, image_id, journal); @@ -250,7 +252,7 @@ The `verify_groth16_proof_bn254` function takes the call data that encodes the p Here is how to verify the RiscZero proof and update the smart contract state for our Fibonacci sequencer example: ```rust -fn submit_fibonacci_number(ref self: ContractState, full_proof_with_hints: Span) { +fn verify_and_submit_fibonacci_number(ref self: ContractState, full_proof_with_hints: Span) { // sets the class hash for the RiscZero verifier already declared on-chain // by the Garaga team let class_hash: ClassHash = RISC_ZERO_VERIFIER_CLASS_HASH.try_into().unwrap(); @@ -266,10 +268,10 @@ fn submit_fibonacci_number(ref self: ContractState, full_proof_with_hints: Span< assert(optional_journal != Option::None, 'Invalid proof'); // parses the public inputs and output from the journal - let journal = optional_journal.unwrap(); - let l = decode_u32_le(journal, 0); - let u = decode_u32_le(journal, 4); - let fib_n = decode_u32_le(journal, 8); + let mut journal = optional_journal.unwrap(); + let l = pop_front_u32_le(ref journal); + let u = pop_front_u32_le(ref journal); + let fib_n = pop_front_u32_le(ref journal); // performs the necessary state update check, updates the state, // and emits an event with the new fibnoacci number submitted @@ -285,7 +287,7 @@ fn submit_fibonacci_number(ref self: ContractState, full_proof_with_hints: Span< } ``` -Along with the `submit_fibonacci_number` contract method, we need to define the RiscZero Verifier class hash, which can be obtained [here](./) +Along with the `verify_and_submit_fibonacci_number` contract method, we need to define the RiscZero Verifier class hash, which can be obtained [here](./) ```rust use core::starknet::ClassHash; @@ -306,11 +308,12 @@ struct Storage { And also the helper function used to decode the journal values ```rust -fn decode_u32_le(bytes: Span, i: usize) -> u32 { - let b0: u32 = (*bytes[i]).into(); - let b1: u32 = (*bytes[i + 1]).into(); - let b2: u32 = (*bytes[i + 2]).into(); - let b3: u32 = (*bytes[i + 3]).into(); +fn pop_front_u32_le(ref bytes: Span) -> u32 { + let [b0, b1, b2, b3] = (*bytes.multi_pop_front::<4>().unwrap()).unbox(); + let b0: u32 = b0.into(); + let b1: u32 = b1.into(); + let b2: u32 = b2.into(); + let b3: u32 = b3.into(); b0 + 256 * (b1 + 256 * (b2 + 256 * b3)) } ``` @@ -338,9 +341,9 @@ struct LowerBoundUpdated { } ``` -It is important to note that the `submit_fibonacci_number` function defined in this sample contract has a signature that takes a single argument: the proof artifact. This is useful because we can then submit the transaction to the blockchain directly, simply using the Garaga CLI passing along the JSON file output by the RiscZero Host program. This avoids the need to encode the proof as a customized call data. It also spares us from dealing with the transaction submission details which is handled internally by the Garaga CLI. +It is important to note that the `verify_and_submit_fibonacci_number` function defined in this sample contract has a signature that takes a single argument: the proof artifact. This is useful because we can then submit the transaction to the blockchain directly, simply using the Garaga CLI passing along the JSON file output by the RiscZero Host program. This avoids the need to encode the proof as a customized call data. It also spares us from dealing with the transaction submission details which is handled internally by the Garaga CLI. -This is an approach that makes sense when all the information required to validate and update the smart contract state can be extracted from the journal, exempting us from the need of passing additional parameters to the function which would deem it incompatible with the interface expected by the CLI. +This is an approach that makes sense when all the information required to validate and update the smart contract state can be extracted from the journal, exempting us from the need of passing additional parameters to the function which would deem it incompatible with the interface expected by the CLI. The CLI also requires the contract method processing the proof (referred to as endpoint) to have the word `verify` as part of it. Once the Cairo smart contract is ready, it can be deployed in three steps: @@ -398,16 +401,13 @@ As mentioned before, the JSON proof artifact generated by the RiscZero execution ```bash garaga verify-onchain \ - --system groth16 \ - --vk \ + --system risc0_groth16 \ --network \ --contract-address \ --endpoint \ --proof ``` -The RiscZero verifying key is shipped along Garaga and is located at `hydra/garaga/starknet/groth16_contract_generator/examples/vk_risc0.json`. - In order to run the Garaga `verify-onchain` command you will need to provide a .`secrets` file in the current folder, or elsewhere using the `--env-file` option. Here is the format for the `.secrets` file ``` From a73707cad788ecd85016913199ea35edba9bec7c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Pedro=20Sousa?= Date: Tue, 7 Jan 2025 21:33:05 +0100 Subject: [PATCH 16/17] The nittiest nit in the docs (#286) --- docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md index 3cc4693a..290db0a9 100644 --- a/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md @@ -95,7 +95,7 @@ nargo execute witness bb prove_ultra_keccak_honk -b target/hello.json -w target/witness.gz -o target/proof.bin ``` -Finally, you can obtain the `full_proof_with_hints` array using the garaga CLI : +Finally, you can obtain the `full_proof_with_hints` array using the garaga CLI. From within the "target" directory: ```bash garaga calldata --system ultra_keccak_honk --vk vk.bin --proof proof.bin --format array From 9cb829ad965ed51451a3a640fcc7d4c04161bf9a Mon Sep 17 00:00:00 2001 From: feltroid Prime Date: Sat, 11 Jan 2025 11:24:50 +0000 Subject: [PATCH 17/17] GITBOOK-38: raugfer's Jan 7 changes --- .../noir.md | 86 +++++++++++++++---- 1 file changed, 71 insertions(+), 15 deletions(-) diff --git a/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md b/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md index 290db0a9..d3beff68 100644 --- a/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md +++ b/docs/gitbook/deploy-your-snark-verifier-on-starknet/noir.md @@ -10,9 +10,9 @@ icon: octopus * Barretenberg 0.61.0 (install with \`bbup --version 0.61.0\`) * Garaga CLI [python-package.md](../installation/python-package.md "mention") -To install `noirup` and `bbup`, follow the [quickstart guide from aztec ](https://noir-lang.org/docs/getting_started/quick_start): +To install `noirup` and `bbup`, follow the [quickstart guide from aztec ](https://noir-lang.org/docs/getting_started/quick_start): -We recall the installations commands here: +We recall the installations commands here: ```bash curl -L noirup.dev | bash @@ -24,7 +24,7 @@ curl -L bbup.dev | bash ## Generate a Starknet smart contract for your Noir program -First, we'll create a new Noir project and compile it. +First, we'll create a new Noir project and compile it. ```bash nargo init hello @@ -32,7 +32,7 @@ cd hello nargo build ``` -This will create a json file in `hello/target/hello.json` +This will create a json file in `hello/target/hello.json` Now you can generate the corresponding verifying key using barretenberg : @@ -46,7 +46,7 @@ Finally, you can generate a smart contract from the verifying key using the gara garaga gen --system ultra_keccak_honk --vk target/vk.bin ``` -This will create a smart contract folder with the following structure. +This will create a smart contract folder with the following structure. ``` Generating Smart Contract project for ProofSystem.UltraKeccakHonk using vk.bin... @@ -62,7 +62,7 @@ Smart Contract project created: └── lib.cairo ``` -The main function of interest is located in `honk_verifier.cairo` +The main function of interest is located in `honk_verifier.cairo` The contract interface will be @@ -76,11 +76,9 @@ trait IUltraKeccakHonkVerifier { ``` +In order to interact with the endpoint, you need to generate the `full_proof_with_hints`array. - -In order to interact with the endpoint, you need to generate the `full_proof_with_hints`array. - -To do so, you need a specific proof for your program. But first, Noir requires you to specify the inputs of your program in `hello/Prover.toml` +To do so, you need a specific proof for your program. But first, Noir requires you to specify the inputs of your program in `hello/Prover.toml` ```toml // The "hello" program simply prove that x!=y, with x being private and y public. @@ -88,21 +86,79 @@ x = "1" y = "2" ``` -You can now generate a proof with barretenberg, after running the program : +You can now generate a proof with barretenberg, after running the program : ```bash nargo execute witness bb prove_ultra_keccak_honk -b target/hello.json -w target/witness.gz -o target/proof.bin ``` -Finally, you can obtain the `full_proof_with_hints` array using the garaga CLI. From within the "target" directory: +Finally, you can obtain the `full_proof_with_hints` array using the garaga CLI. From within the "target" directory: ```bash garaga calldata --system ultra_keccak_honk --vk vk.bin --proof proof.bin --format array ``` - - {% hint style="info" %} -Using `garaga calldata`with the `--format array` lets you paste this array in cairo code for unit tests by doing let proof:Array\ = \[ ... ] ; . The `--format starkli` has a formatting which is composable with starkli in the command line and also preprends the length of the array so that it can be deserialized by starknet. +Using `garaga calldata`with the `--format array` lets you paste this array in cairo code for unit tests by doing let proof:Array\ = \[ ... ] ; . The `--format starkli` has a formatting which is composable with starkli in the command line and also preprends the length of the array so that it can be deserialized by starknet. {% endhint %} + + + +## The Ultra Starknet Flavor + +We are in the process of adding a new flavor to Noir proofs called Ultra Starknet. It contrasts with with Ultra Keccak presented in the previous section. + +The Ultra Starknet flavor replaces the Keccak hash function by [Poseidon](https://www.poseidon-hash.info/), which is a ZK-friendly hash function and therefore better suited in the context of Starknet and Cairo contracts. + +In order to provide the Ultra Starknet flavor we forked and customized the Barretenberg (`bb`) implementation. Here the steps to build the customized `bb`: + +1. Install [build dependencies](https://github.com/AztecProtocol/aztec-packages/tree/master/barretenberg#development) (assuming here a Debian-compatible system) + +```bash +sudo apt install -y cmake clang clang-16 clang-format libstdc++-12-dev ninja-build +``` + +2. Clone our fork of the Aztec Packages repository and checkout the specific branch + +```bash +git clone https://github.com/raugfer/aztec-packages.git +cd aztec-packages +git checkout ultra-starknet-honk +``` + +3. Perform the build + +```bash +cd barretenberg/cpp +cmake --preset clang16 +cmake --build --preset clang16 --target bb +``` + +4. Manually install the custom `bb` command, conveniently, under the Nargo config folder + +```bash +install build/bin/bb ~/.nargo/bin/ +mkdir ~/.nargo/lib/ +install build/src/barretenberg/crypto/poseidon/sources/lib_pos* ~/.nargo/lib/ +export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$HOME/.nargo/lib/" +``` + +Now, in order to generate a Ultra Starknet proof and verifying key using the customized Barretenberg implementation, simply issue the following commands: + +```bash +bb prove_ultra_starnet_honk -b target/hello.json -w target/witness.gz -o target/proof.bin +bb write_vk_ultra_starnet_honk -b target/hello.json -o target/vk.bin +``` + +To generate a contract using the Ultra Starknet system, use the following command, which is similar to the previous process: + +```bash +garaga gen --system ultra_starknet_honk --vk target/vk.bin +``` + +And, as with the Ultra Keccak flavor, one can obtain the `full_proof_with_hints` array using the garaga CLI : + +```bash +garaga calldata --system ultra_starknet_honk --vk vk.bin --proof proof.bin --format array +```