-
Notifications
You must be signed in to change notification settings - Fork 223
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore(docs): docs for v0.19.0 (#3442)
Co-authored-by: signorecello <github@zepedro.me> Co-authored-by: Savio <72797635+Savio-Sou@users.noreply.github.com>
- Loading branch information
1 parent
f097941
commit 244116a
Showing
55 changed files
with
5,379 additions
and
0 deletions.
There are no files selected for viewing
48 changes: 48 additions & 0 deletions
48
docs/versioned_docs/version-v0.19.0/examples/merkle-proof.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,48 @@ | ||
--- | ||
title: Merkle Proof Membership | ||
description: | ||
Learn how to use merkle membership proof in Noir to prove that a given leaf is a member of a | ||
merkle tree with a specified root, at a given index. | ||
keywords: | ||
[merkle proof, merkle membership proof, Noir, rust, hash function, Pedersen, sha256, merkle tree] | ||
--- | ||
|
||
Let's walk through an example of a merkle membership proof in Noir that proves that a given leaf is | ||
in a merkle tree. | ||
|
||
```rust | ||
use dep::std; | ||
|
||
fn main(message : [Field; 62], index : Field, hashpath : [Field; 40], root : Field) { | ||
let leaf = std::hash::hash_to_field(message); | ||
let merkle_root = std::merkle::compute_merkle_root(leaf, index, hashpath); | ||
assert(merkle_root == root); | ||
} | ||
|
||
``` | ||
|
||
The message is hashed using `hash_to_field`. The specific hash function that is being used is chosen | ||
by the backend. The only requirement is that this hash function can heuristically be used as a | ||
random oracle. If only collision resistance is needed, then one can call `std::hash::pedersen_hash` | ||
instead. | ||
|
||
```rust | ||
let leaf = std::hash::hash_to_field(message); | ||
``` | ||
|
||
The leaf is then passed to a compute_merkle_root function with the root, index and hashpath. The returned root can then be asserted to be the same as the provided root. | ||
|
||
```rust | ||
let merkle_root = std::merkle::compute_merkle_root(leaf, index, hashpath); | ||
assert (merkle_root == root); | ||
``` | ||
|
||
> **Note:** It is possible to re-implement the merkle tree implementation without standard library. | ||
> However, for most usecases, it is enough. In general, the standard library will always opt to be | ||
> as conservative as possible, while striking a balance with efficiency. | ||
An example, the merkle membership proof, only requires a hash function that has collision | ||
resistance, hence a hash function like Pedersen is allowed, which in most cases is more efficient | ||
than the even more conservative sha256. | ||
|
||
[View an example on the starter repo](https://github.com/noir-lang/noir-examples/blob/3ea09545cabfa464124ec2f3ea8e60c608abe6df/stealthdrop/circuits/src/main.nr#L20) |
249 changes: 249 additions & 0 deletions
249
docs/versioned_docs/version-v0.19.0/getting_started/00_nargo_installation.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,249 @@ | ||
--- | ||
title: Nargo Installation | ||
description: | ||
nargo is a command line tool for interacting with Noir programs (e.g. compiling, proving, | ||
verifying and more). Learn how to install and use Nargo for your projects with this comprehensive | ||
guide. | ||
keywords: [Nargo, command line tool, Noir programs, installation guide, how to use Nargo] | ||
--- | ||
|
||
`nargo` is a command line tool for interacting with Noir programs (e.g. compiling, proving, | ||
verifying and more). | ||
|
||
Alternatively, the interactions can also be performed in [NoirJS](../noir_js/noir_js.md). | ||
|
||
### UltraPlonk | ||
|
||
Nargo versions <0.5.0 of `aztec_backend` and `aztec_wasm_backend` are based on the TurboPlonk | ||
version of Aztec Backend, which lacks efficient implementations of useful primitives (e.g. Keccak256 in 18k constraints, ECDSA verification in 36k constraints) that the UltraPlonk version offers. | ||
|
||
## Installation | ||
|
||
There are four approaches for installing Nargo: | ||
|
||
- [Option 1: Noirup](#option-1-noirup) | ||
- [Option 2: Binaries](#option-2-binaries) | ||
- [Option 3: Compile from Source](#option-3-compile-from-source) | ||
- [Option 4: WSL for Windows](#option-4-wsl-for-windows) | ||
|
||
Optionally you can also install [Noir VS Code extension] for syntax highlighting. | ||
|
||
### Option 1: Noirup | ||
|
||
If you're on OSX or Linux, the easiest way to start using Noir and Nargo is via noirup. Just open a | ||
terminal and run: | ||
|
||
```bash | ||
curl -L https://raw.githubusercontent.com/noir-lang/noirup/main/install | bash | ||
``` | ||
|
||
Close the terminal, open another one, and run | ||
|
||
```bash | ||
noirup | ||
``` | ||
|
||
Done, you should have the latest version working. You can check with `nargo --version`. | ||
|
||
You can also install nightlies, specific versions | ||
or branches, check out the [noirup repository](https://github.com/noir-lang/noirup) for more | ||
information. | ||
|
||
#### GitHub Actions | ||
|
||
You can use `noirup` with GitHub Actions for CI/CD and automated testing. It is as simple as | ||
installing `noirup` and running tests in your GitHub Action `yml` file. | ||
|
||
See the | ||
[config file](https://github.com/TomAFrench/noir-hashes/blob/master/.github/workflows/noir.yml) in | ||
this repo containing hash functions in Noir for an example. | ||
|
||
#### Nightly versions | ||
|
||
To install the nightly version of Noir (updated daily) run: | ||
|
||
```bash | ||
noirup -n | ||
``` | ||
|
||
### Option 2: Binaries | ||
|
||
See [GitHub Releases](https://github.com/noir-lang/noir/releases) for the latest and previous | ||
platform specific binaries. | ||
|
||
#### Step 1 | ||
|
||
Paste and run the following in the terminal to extract and install the binary: | ||
|
||
> **macOS / Linux:** If you are prompted with `Permission denied` when running commands, prepend | ||
> `sudo` and re-run it. | ||
##### macOS (Apple Silicon) | ||
|
||
```bash | ||
mkdir -p $HOME/.nargo/bin && \ | ||
curl -o $HOME/.nargo/bin/nargo-aarch64-apple-darwin.tar.gz -L https://github.com/noir-lang/noir/releases/download/v0.6.0/nargo-aarch64-apple-darwin.tar.gz && \ | ||
tar -xvf $HOME/.nargo/bin/nargo-aarch64-apple-darwin.tar.gz -C $HOME/.nargo/bin/ && \ | ||
echo '\nexport PATH=$PATH:$HOME/.nargo/bin' >> ~/.zshrc && \ | ||
source ~/.zshrc | ||
``` | ||
|
||
##### macOS (Intel) | ||
|
||
```bash | ||
mkdir -p $HOME/.nargo/bin && \ | ||
curl -o $HOME/.nargo/bin/nargo-x86_64-apple-darwin.tar.gz -L https://github.com/noir-lang/noir/releases/download/v0.6.0/nargo-x86_64-apple-darwin.tar.gz && \ | ||
tar -xvf $HOME/.nargo/bin/nargo-x86_64-apple-darwin.tar.gz -C $HOME/.nargo/bin/ && \ | ||
echo '\nexport PATH=$PATH:$HOME/.nargo/bin' >> ~/.zshrc && \ | ||
source ~/.zshrc | ||
``` | ||
|
||
##### Linux (Bash) | ||
|
||
```bash | ||
mkdir -p $HOME/.nargo/bin && \ | ||
curl -o $HOME/.nargo/bin/nargo-x86_64-unknown-linux-gnu.tar.gz -L https://github.com/noir-lang/noir/releases/download/v0.6.0/nargo-x86_64-unknown-linux-gnu.tar.gz && \ | ||
tar -xvf $HOME/.nargo/bin/nargo-x86_64-unknown-linux-gnu.tar.gz -C $HOME/.nargo/bin/ && \ | ||
echo -e '\nexport PATH=$PATH:$HOME/.nargo/bin' >> ~/.bashrc && \ | ||
source ~/.bashrc | ||
``` | ||
|
||
#### Step 2 | ||
|
||
Check if the installation was successful by running `nargo --help`. | ||
|
||
> **macOS:** If you are prompted with an OS alert, right-click and open the _nargo_ executable from | ||
> Finder. Close the new terminal popped up and `nargo` should now be accessible. | ||
For a successful installation, you should see something similar to the following after running the | ||
command: | ||
|
||
```sh | ||
$ nargo --help | ||
|
||
Noir's package manager | ||
Usage: nargo <COMMAND> | ||
Commands: | ||
check Checks the constraint system for errors | ||
codegen-verifier Generates a Solidity verifier smart contract for the program | ||
compile Compile the program and its secret execution trace into ACIR format | ||
new Create a new binary project | ||
execute Executes a circuit to calculate its return value | ||
prove Create proof for this program. The proof is returned as a hex encoded string | ||
verify Given a proof and a program, verify whether the proof is valid | ||
test Run the tests for this program | ||
gates Counts the occurrences of different gates in circuit | ||
help Print this message or the help of the given subcommand(s) | ||
``` | ||
### Option 3: Compile from Source | ||
Due to the large number of native dependencies, Noir projects uses [Nix](https://nixos.org/) and [direnv](https://direnv.net/) to streamline the development experience. It helps mitigating ssues commonly associated with dependency management, such as conflicts between required package versions for different projects (often referred to as "dependency hell"). | ||
Combined with direnv, which automatically sets or unsets environment variables based on the directory, it further simplifies the development process by seamlessly integrating with the developer's shell, facilitating an efficient and reliable workflow for managing and deploying Noir projects with multiple dependencies. | ||
|
||
#### Setting up your environment | ||
|
||
For the best experience, please follow these instructions to setup your environment: | ||
|
||
1. Install Nix following [their guide](https://nixos.org/download.html) for your operating system. | ||
2. Create the file `~/.config/nix/nix.conf` with the contents: | ||
|
||
```ini | ||
experimental-features = nix-command | ||
extra-experimental-features = flakes | ||
``` | ||
|
||
3. Install direnv into your Nix profile by running: | ||
|
||
```sh | ||
nix profile install nixpkgs#direnv | ||
``` | ||
|
||
4. Add direnv to your shell following [their guide](https://direnv.net/docs/hook.html). | ||
1. For bash or zshell, add `eval "$(direnv hook bash)"` or `eval "$(direnv hook zsh)"` to your ~/.bashrc or ~/.zshrc file, respectively. | ||
5. Restart your shell. | ||
|
||
#### Shell & editor experience | ||
|
||
Now that your environment is set up, you can get to work on the project. | ||
|
||
1. Clone the repository, such as: | ||
|
||
```sh | ||
git clone git@github.com:noir-lang/noir | ||
``` | ||
|
||
> Replacing `noir` with whichever repository you want to work on. | ||
|
||
2. Navigate to the directory: | ||
|
||
```sh | ||
cd noir | ||
``` | ||
|
||
> Replacing `noir` with whichever repository you cloned. | ||
|
||
3. You should see a **direnv error** because projects aren't allowed by default. Make sure you've reviewed and trust our `.envrc` file, then you need to run: | ||
|
||
```sh | ||
direnv allow | ||
``` | ||
|
||
4. Now, wait awhile for all the native dependencies to be built. This will take some time and direnv will warn you that it is taking a long time, but we just need to let it run. | ||
|
||
5. Once you are presented with your prompt again, you can start your editor within the project directory (we recommend [VSCode](https://code.visualstudio.com/)): | ||
|
||
```sh | ||
code . | ||
``` | ||
|
||
6. (Recommended) When launching VSCode for the first time, you should be prompted to install our recommended plugins. We highly recommend installing these for the best development experience. | ||
|
||
#### Building and testing | ||
|
||
Assuming you are using `direnv` to populate your environment, building and testing the project can be done | ||
with the typical `cargo build`, `cargo test`, and `cargo clippy` commands. You'll notice that the `cargo` version matches the version we specify in `rust-toolchain.toml`, which is 1.71.1 at the time of this writing. | ||
If you want to build the entire project in an isolated sandbox, you can use Nix commands: | ||
1. `nix build .` (or `nix build . -L` for verbose output) to build the project in a Nix sandbox. | ||
2. `nix flake check` (or `nix flake check -L` for verbose output) to run clippy and tests in a Nix sandbox. | ||
#### Without `direnv` | ||
If you have hesitations with using direnv, you can launch a subshell with `nix develop` and then launch your editor from within the subshell. However, if VSCode was already launched in the project directory, the environment won't be updated. | ||
|
||
Advanced: If you aren't using direnv nor launching your editor within the subshell, you can try to install Barretenberg and other global dependencies the package needs. This is an advanced workflow and likely won't receive support! | ||
|
||
### Option 4: WSL (for Windows) | ||
|
||
The default backend for Noir (Barretenberg) doesn't provide Windows binaries at this time. For that reason, Noir cannot be installed nativerly. However, it is available by using Windows Subsystem for Linux (WSL). | ||
Step 1: Follow the instructions [here](https://learn.microsoft.com/en-us/windows/wsl/install) to install and run WSL. | ||
step 2: Follow the [Noirup instructions](#option-1-noirup). | ||
## Uninstalling Nargo | ||
### Noirup | ||
If you installed Noir with `noirup`, you can uninstall Noir by removing the files in `~/.nargo`, `~/nargo` and `~/noir_cache`. | ||
```bash | ||
rm -r ~/.nargo | ||
rm -r ~/nargo | ||
rm -r ~/noir_cache | ||
``` | ||
### Nix | ||
If you installed Noir with Nix or from source, you can remove the binary located at `~/.nix-profile/bin/nargo`. | ||
```bash | ||
rm ~/.nix-profile/bin/nargo | ||
``` | ||
[noir vs code extension]: https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir |
Oops, something went wrong.