diff --git a/docs/.gitignore b/docs/.gitignore index 501e7e465ea..7ff8bd69a72 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -25,3 +25,4 @@ yarn-error.log* package-lock.json versions.json +.supermavenignore diff --git a/docs/.markdownlint.json b/docs/.markdownlint.json deleted file mode 100644 index 40896b4542f..00000000000 --- a/docs/.markdownlint.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "no-missing-space-atx": false -} diff --git a/docs/docs/getting_started.md b/docs/docs/getting_started.md new file mode 100644 index 00000000000..9c566c54b2f --- /dev/null +++ b/docs/docs/getting_started.md @@ -0,0 +1,111 @@ +--- +title: Getting Started +tags: [] +--- + +## A Quick Start with Noirenberg + +Noir is a backend-agnostic programming language for writing zero-knowledge proofs. This means you need to pair it with a proving backend. You can visit the [nargo installation](./getting_started/installation/index.md) page for details on using Noir without any particular backend. + +As an example, you can use the convenient binary [noirenberg](https://raw.githubusercontent.com/noir-lang/noirenberg/main/install.sh) script, which installs Noir along with Aztec Lab's [Barretenberg backend](https://github.com/AztecProtocol/aztec-packages/tree/master/barretenberg): + +```bash +curl -fsSL noiren.be | bash +``` + +:::info + +It's good practice to inspect what you run. This script is hosted [here](https://raw.githubusercontent.com/AztecProtocol/noirenberg/main/install.sh) and installs [`nvm`](https://github.com/nvm-sh/nvm/tree/master), [`node`](https://nodejs.org/en), and the [`noirenberg`](https://raw.githubusercontent.com/noir-lang/noirenberg/main/npx.ts) binaries. + +::: + +We now have `noirenberg` ready. Open a new terminal and run: + +```bash +noirenberg +``` + +## Nargo + +Nargo provides the ability to initiate and execute Noir projects. Let's initialize the traditional `hello_world`: + +```sh +nargo new hello_world +``` + +Two files will be created. + +- `src/main.nr` contains a simple boilerplate circuit +- `Nargo.toml` contains environmental options, such as name, author, dependencies, and others. + +Glancing at _main.nr_ , we can see that inputs in Noir are private by default, but can be labeled public using the keyword `pub`. This means that we will _assert_ that we know a value `x` which is different from `y` without revealing `x`: + +```rust +fn main(x : Field, y : pub Field) { + assert(x != y); +} +``` + +To learn more about private and public values, check the [Data Types](../../noir/concepts/data_types/index.md) section. + +### Compiling and executing + +We can now use `nargo` to generate a _Prover.toml_ file, where our input values will be specified: + +```sh +nargo check +``` + +Let's feed some valid values into this file: + +```toml +x = "1" +y = "2" +``` + +We're now ready to compile and execute our Noir program. By default the `nargo execute` command will do both, and generate the `witness` that we need to feed to our proving backend: + +```sh +nargo execute hello-witness +``` + +You can now see the witness and the compiled circuit in the `target` folder. We're ready to prove + +## Barretenberg + +Barretenberg is a proving backend maintained by [Aztec Labs](https://www.aztec-labs.com/). + +Proving backends provide the ability to generate and verify proofs. In this example, `noirenberg` already installed `bb`, Barretenberg's CLI tool. You can read more about it in its [documentation](https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/cpp/src/barretenberg/bb/readme.md). Let's use it to prove the valid execution of your Noir program: + +```sh +bb prove -b ./target/hello_world.json -w ./target/hello-witness.gz -o ./target/proof +``` + +:::tip + +Naming can be confusing, specially as you pass them to the `bb` commands. If unsure, it won't hurt to delete the target folder and start anew to make sure you're using the most recent versions of the compiled circuit and witness. + +::: + +The proof is now generated in the `target` folder. To verify it we first need to compute the verification key from the compiled circuit, and use it to verify: + +```sh +bb write_vk -b ./target/hello_world.json -o ./target/vk +bb verify -k ./target/vk -p ./target/proof +``` + +:::info + +Notice that in order to verify a proof, the verifier knows nothing but the circuit, which is compiled and used to generate the verification key. This is obviously quite important: private inputs remain private. + +As for the public inputs, you may have noticed they haven't been specified. This behaviour varies with each particular backend, but barretenberg tipically attaches them to the proof. You can see them by parsing and splitting it. For example for if your public inputs are 32 bytes: + +```bash +head -c 32 ./target/proof | od -An -v -t x1 | tr -d $' \n' +``` + +::: + +Congratulations, you have now created and verified a proof for your very first Noir program! + +In the [next section](./getting_started/project_breakdown.md), we will go into more detail on each step performed. diff --git a/docs/docs/getting_started/_category_.json b/docs/docs/getting_started/_category_.json deleted file mode 100644 index 5d694210bbf..00000000000 --- a/docs/docs/getting_started/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "position": 0, - "collapsible": true, - "collapsed": true -} diff --git a/docs/docs/getting_started/backend/_category_.json b/docs/docs/getting_started/backend/_category_.json deleted file mode 100644 index b82e92beb0c..00000000000 --- a/docs/docs/getting_started/backend/_category_.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "position": 1, - "label": "Install Proving Backend", - "collapsible": true, - "collapsed": true -} diff --git a/docs/docs/getting_started/backend/index.md b/docs/docs/getting_started/backend/index.md deleted file mode 100644 index 7192d954877..00000000000 --- a/docs/docs/getting_started/backend/index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Proving Backend Installation -description: Proving backends offer command line tools for proving and verifying Noir programs. This page describes how to install `bb` as an example. -keywords: [ - Proving - Backend - Barretenberg - bb - bbup - Installation - Terminal - Command - CLI - Version -] -pagination_next: getting_started/hello_noir/index ---- - -Proving backends each provide their own tools for working with Noir programs, providing functionality like proof generation, proof verification, and verifier smart contract generation. - -For the latest information on tooling provided by each proving backend, installation instructions, Noir version compatibility... you may refer to the proving backends' own documentation. - -You can find the full list of proving backends compatible with Noir in [Awesome Noir](https://github.com/noir-lang/awesome-noir/?tab=readme-ov-file#proving-backends). - -## Example: Installing `bb` - -`bb` is the CLI tool provided by the [Barretenberg proving backend](https://github.com/AztecProtocol/barretenberg) developed by Aztec Labs. - -You can find the instructions for installation in [`bb`'s documentation](https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/cpp/src/barretenberg/bb/readme.md#installation). - -Once installed, we are ready to start working on [our first Noir program](../hello_noir/index.md). diff --git a/docs/docs/getting_started/hello_noir/_category_.json b/docs/docs/getting_started/hello_noir/_category_.json deleted file mode 100644 index 976a2325de0..00000000000 --- a/docs/docs/getting_started/hello_noir/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "position": 2, - "collapsible": true, - "collapsed": true -} diff --git a/docs/docs/getting_started/hello_noir/index.md b/docs/docs/getting_started/hello_noir/index.md deleted file mode 100644 index 6760e54aad1..00000000000 --- a/docs/docs/getting_started/hello_noir/index.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: Creating a Project -description: - Learn how to create and verify your first Noir program using Nargo, a programming language for - zero-knowledge proofs. -keywords: - [ - Nargo, - Noir, - zero-knowledge proofs, - programming language, - create Noir program, - verify Noir program, - step-by-step guide, - ] -sidebar_position: 1 - ---- - -Now that we have installed Nargo and a proving backend, it is time to make our first hello world program! - -### 1. Create a new project directory - -Noir code can live anywhere on your computer. Let us create a _projects_ folder in the home -directory to house our first Noir program. - -Create the directory and change directory into it by running: - -```sh -mkdir ~/projects -cd ~/projects -``` - -## Nargo - -Nargo provides the ability to initiate and execute Noir projects. Read the [Nargo installation](../installation/index.md) section to learn more about Nargo and how to install it. - -### 2. Create a new Noir project - -Now that we are in the projects directory, create a new Nargo project by running: - -```sh -nargo new hello_world -``` - -`hello_world` can be any arbitrary project name, we are simply using `hello_world` for demonstration. - -In production, it is common practice to name the project folder, `circuits`, for clarity amongst other folders in the codebase (like: `contracts`, `scripts`, and `test`). - -A `hello_world` folder would be created. Similar to Rust, the folder houses _src/main.nr_ and -_Nargo.toml_ which contain the source code and environmental options of your Noir program -respectively. - -#### Intro to Noir Syntax - -Let us take a closer look at _main.nr_. The default _main.nr_ generated should look like this: - -```rust -fn main(x : Field, y : pub Field) { - assert(x != y); -} -``` - -The first line of the program specifies the program's inputs: - -```rust -x : Field, y : pub Field -``` - -Program inputs in Noir are private by default (e.g. `x`), but can be labeled public using the -keyword `pub` (e.g. `y`). To learn more about private and public values, check the -[Data Types](../../noir/concepts/data_types/index.md) section. - -The next line of the program specifies its body: - -```rust -assert(x != y); -``` - -The Noir syntax `assert` can be interpreted as something similar to constraints in other zk-contract languages. - -For more Noir syntax, check the [Language Concepts](../../noir/concepts/comments.md) chapter. - -### 3. Build in/output files - -Change directory into _hello_world_ and build in/output files for your Noir program by running: - -```sh -cd hello_world -nargo check -``` - -A _Prover.toml_ file will be generated in your project directory, to allow specifying input values to the program. - -### 4. Execute the Noir program - -Now that the project is set up, we can execute our Noir program. - -Fill in input values for execution in the _Prover.toml_ file. For example: - -```toml -x = "1" -y = "2" -``` - -Execute your Noir program: - -```sh -nargo execute witness-name -``` - -The witness corresponding to this execution will then be written to the file `./target/witness-name.gz`. - -The command also automatically compiles your Noir program if it was not already / was edited, which you may notice the compiled artifacts being written to the file `./target/hello_world.json`. - -## Proving Backend - -Proving backends provide the ability to generate and verify proofs of executing Noir programs, following Noir's tooling that compiles and executes the programs. Read the [proving backend installation](../backend/index.md) section to learn more about proving backends and how to install them. - -Barretenberg is used as an example here to demonstrate how proving and verifying could be implemented and used. Read the [`bb` installation](../backend/index.md#example-installing-bb) section for how to install Barretenberg's CLI tool; refer to [`bb`'s documentation](https://github.com/AztecProtocol/aztec-packages/blob/master/barretenberg/cpp/src/barretenberg/bb/readme.md) for full details about the tool. - -### 5. Prove an execution of the Noir program - -Using Barretenberg as an example, prove the valid execution of your Noir program running: - -```sh -bb prove -b ./target/hello_world.json -w ./target/witness-name.gz -o ./target/proof -``` - -The proof generated will then be written to the file `./target/proof`. - -:::tip -Since the params for `nargo` and `bb` often specify multiple filenames to read from or write to, remember to check each command is referring to the desired filenames. -Or for greater certainty, delete the target folder and go through each step again (compile, witness, prove, ...) to ensure files generated in past commands are being referenced in future ones. -::: - -### 6. Verify the execution proof - -Once a proof is generated, we can verify correct execution of our Noir program by verifying the proof file. - -Using Barretenberg as an example, compute the verification key for the Noir program by running: - -```sh -bb write_vk -b ./target/hello_world.json -o ./target/vk -``` - -And verify your proof by running: - -```sh -bb verify -k ./target/vk -p ./target/proof -``` - -If successful, the verification will complete in silence; if unsuccessful, the command will trigger logging of the corresponding error. - -Congratulations, you have now created and verified a proof for your very first Noir program! - -In the [next section](./project_breakdown.md), we will go into more detail on each step performed. diff --git a/docs/docs/getting_started/installation/_category_.json b/docs/docs/getting_started/installation/_category_.json deleted file mode 100644 index 0c02fb5d4d7..00000000000 --- a/docs/docs/getting_started/installation/_category_.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "position": 0, - "label": "Install Nargo", - "collapsible": true, - "collapsed": true -} diff --git a/docs/docs/getting_started/installation/index.md b/docs/docs/getting_started/installation/index.md deleted file mode 100644 index 53ea9c7891c..00000000000 --- a/docs/docs/getting_started/installation/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Nargo Installation -description: - nargo is a command line tool for interacting with Noir programs. This page is a quick guide on how to install Nargo through the most common and easy method, noirup -keywords: [ - Nargo - Noir - Rust - Cargo - Noirup - Installation - Terminal Commands - Version Check - Nightlies - Specific Versions - Branches - Noirup Repository -] -pagination_next: getting_started/hello_noir/index ---- - -`nargo` is a tool for working with Noir programs on the CLI, providing you with the ability to start new projects, compile, execute and test Noir programs from the terminal. - -The name is inspired by Rust's package manager `cargo`; and similar to Rust's `rustup`, Noir also has an easy installation script `noirup`. - -## Installing Noirup - -Open a terminal on your machine, and write: - -```bash -curl -L https://raw.githubusercontent.com/noir-lang/noirup/main/install | bash -``` - -Close the terminal, open another one, and run - -```bash -noirup -``` - -Done. That's it. 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. - -Now we're ready to start working on [our first Noir program!](../hello_noir/index.md) diff --git a/docs/docs/getting_started/installation/other_install_methods.md b/docs/docs/getting_started/noir_installation.md similarity index 97% rename from docs/docs/getting_started/installation/other_install_methods.md rename to docs/docs/getting_started/noir_installation.md index 3634723562b..e2f4adfdbbb 100644 --- a/docs/docs/getting_started/installation/other_install_methods.md +++ b/docs/docs/getting_started/noir_installation.md @@ -1,5 +1,5 @@ --- -title: Alternative Installations +title: Standalone Noir Installation description: There are different ways to install Nargo, the one-stop shop and command-line tool for developing Noir programs. This guide explains how to specify which version to install when using noirup, and using WSL for windows. keywords: [ Installation @@ -17,7 +17,6 @@ keywords: [ sidebar_position: 1 --- -## Encouraged Installation Method: Noirup Noirup is the endorsed method for installing Nargo, streamlining the process of fetching binaries or compiling from source. It supports a range of options to cater to your specific needs, from nightly builds and specific versions to compiling from various sources. @@ -40,6 +39,7 @@ With `noirup`, you can easily switch between different Nargo versions, including ``` - **Specific Version**: Install a specific version of Nargo. + ```sh noirup --version ``` @@ -79,6 +79,7 @@ With `noirup`, you can easily switch between different Nargo versions, including ``` - **From Local Source**: Compile and install from a local directory. + ```sh noirup --path ./path/to/local/source ``` diff --git a/docs/docs/getting_started/hello_noir/project_breakdown.md b/docs/docs/getting_started/project_breakdown.md similarity index 99% rename from docs/docs/getting_started/hello_noir/project_breakdown.md rename to docs/docs/getting_started/project_breakdown.md index 96e653f6c08..772023f9c32 100644 --- a/docs/docs/getting_started/hello_noir/project_breakdown.md +++ b/docs/docs/getting_started/project_breakdown.md @@ -5,7 +5,7 @@ description: file, and how to prove and verify your program. keywords: [Nargo, Nargo project, Prover.toml, proof verification, private asset transfer] -sidebar_position: 2 +sidebar_position: 0 --- This section breaks down our hello world program from the previous section. @@ -66,7 +66,7 @@ The package section defines a number of fields including: - `entry` (optional) - a relative filepath to use as the entry point into your package (overrides the default of `src/lib.nr` or `src/main.nr`) - `backend` (optional) - `license` (optional) -- `expression_width` (optional) - Sets the default backend expression width. This field will override the default backend expression width specified by the Noir compiler (currently set to width 4). +- `expression_width` (optional) - Sets the default backend expression width. This field will override the default backend expression width specified by the Noir compiler (currently set to width 4). #### Dependencies section diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index ec3cd96efa3..88958c26b1f 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -15,7 +15,7 @@ export default { url: 'https://noir-lang.org', baseUrl: '/', onBrokenLinks: 'throw', - onBrokenMarkdownLinks: 'throw', + onBrokenMarkdownLinks: process.env.ENV === 'dev' ? 'warn' : 'throw', i18n: { defaultLocale: 'en', locales: ['en'], @@ -26,7 +26,7 @@ export default { '@docusaurus/preset-classic', { docs: { - path: 'processed-docs', + path: process.env.ENV === 'dev' ? 'docs' : 'processed-docs', sidebarPath: './sidebars.js', routeBasePath: '/', remarkPlugins: [math], @@ -48,7 +48,7 @@ export default { ], ], customFields: { - MATOMO_ENV: process.env.MATOMO_ENV, + MATOMO_ENV: process.env.ENV, }, themeConfig: { colorMode: { diff --git a/docs/package.json b/docs/package.json index 0b28a07df81..39807588eaa 100644 --- a/docs/package.json +++ b/docs/package.json @@ -4,7 +4,7 @@ "private": true, "scripts": { "preprocess": "yarn workspace @noir-lang/acvm_js build && ./scripts/codegen_nargo_reference.sh && yarn node ./scripts/preprocess/index.js", - "start": "yarn preprocess && MATOMO_ENV=dev docusaurus start", + "dev": "yarn preprocess && ENV=dev docusaurus start", "build": "yarn preprocess && docusaurus build", "clean": "rm -rf ./processed-docs ./processed-docs ./build", "version::stables": "ts-node ./scripts/setStable.ts", diff --git a/docs/sidebars.js b/docs/sidebars.js index cf7e852fed5..7c7e8bf161b 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -8,6 +8,10 @@ export default { { type: 'category', label: 'Getting Started', + link: { + type: 'doc', + id: 'getting_started', + }, items: [ { type: 'autogenerated',