From 26746c59e12a60f3869a5b885b05926c94f01215 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Pedro=20Sousa?= Date: Thu, 19 Oct 2023 18:55:42 +0100 Subject: [PATCH] feat: old docs issues (#3195) Co-authored-by: kevaundray Co-authored-by: josh crites Co-authored-by: Tom French <15848336+TomAFrench@users.noreply.github.com> Co-authored-by: Koby Hall <102518238+kobyhallx@users.noreply.github.com> Co-authored-by: Tom French Co-authored-by: github-merge-queue[bot] Co-authored-by: kek kek kek Co-authored-by: jfecher --- .github/workflows/build-docs.yml | 52 ++++- CONTRIBUTING.md | 36 +++- compiler/wasm/package.json | 1 - docs/CONTRIBUTING.md | 57 ----- docs/README.md | 8 +- docs/docs/language_concepts/01_functions.md | 39 ++++ .../modules_packages_crates/workspaces.md | 2 +- docs/docs/nargo/01_commands.md | 199 +++++++++--------- docs/docs/nargo/04_language_server.md | 18 +- .../getting_started/01_tiny_noir_app.md | 4 + docs/docs/noir_js/noir_js.md | 2 +- docs/docs/noir_js/reference/02_noirjs.md | 29 +++ 12 files changed, 271 insertions(+), 176 deletions(-) delete mode 100644 docs/CONTRIBUTING.md diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index a387f6f49f9..af3565ba61d 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -8,17 +8,57 @@ on: - opened - synchronize - labeled - push: - paths: - - 'docs/**' jobs: - - build_and_deploy: + add_label: + runs-on: ubuntu-latest + outputs: + has_label: ${{ steps.check-labels.outputs.result }} + steps: + - name: Check if label is present + id: check-labels + uses: actions/github-script@v3 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + const labels = context.payload.pull_request.labels.map(label => label.name); + if (labels.includes('documentation')) { + return true; + } + + // Fetch the list of files changed in the PR + const { data: files } = await github.pulls.listFiles({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.issue.number + }); + + // Check if any file is within the 'docs' folder + const docsChanged = files.some(file => file.filename.startsWith('docs/')); + return docsChanged; + + - name: Add label if not present + if: steps.check-labels.outputs.result == 'true' + uses: actions/github-script@v3 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + const labels = context.payload.pull_request.labels.map(label => label.name); + if (!labels.includes('documentation')) { + github.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + labels: ['documentation'] + }) + } + + deploy_docs: runs-on: ubuntu-latest permissions: pull-requests: write - if: contains(github.event.pull_request.labels.*.name, 'documentation') + needs: add_label + if: needs.add_label.outputs.has_label == 'true' steps: - name: Checkout code uses: actions/checkout@v2 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a9cddd50c55..bc2acd40829 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,11 +58,11 @@ Generally, we want to only use the three primary types defined by the specificat - `feat:` - This should be the most used type, as most work we are doing in the project are new features. Commits using this type will always show up in the Changelog. - `fix:` - When fixing a bug, we should use this type. Commits using this type will always show up in the Changelog. -- `chore:` - The least used type, these are **not** included in the Changelog unless they are breaking changes. But remain useful for an understandable commit history. +- `chore:` - The least used type, these are __not__ included in the Changelog unless they are breaking changes. But remain useful for an understandable commit history. ### Conventional Commits: Breaking Changes -Annotating **BREAKING CHANGES** is extremely important to our release process and versioning. To mark a commit as breaking, we add the `!` character after the type, but before the colon. For example: +Annotating __BREAKING CHANGES__ is extremely important to our release process and versioning. To mark a commit as breaking, we add the `!` character after the type, but before the colon. For example: ``` feat!: Rename nargo build to nargo check (#693) @@ -94,10 +94,14 @@ The easiest way to do this is to have multiple Conventional Commits while you wo ### Reviews -For any repository in the noir-lang organization, we require code review & approval by **one** Noir team member before the changes are merged, as enforced by GitHub branch protection. Non-breaking pull requests may be merged at any time. Breaking pull requests should only be merged when the team has general agreement of the changes and is preparing a breaking release. +For any repository in the noir-lang organization, we require code review & approval by __one__ Noir team member before the changes are merged, as enforced by GitHub branch protection. Non-breaking pull requests may be merged at any time. Breaking pull requests should only be merged when the team has general agreement of the changes and is preparing a breaking release. + +If your Pull Request involves changes in the docs folder, please add the `documentation` flag and request an approval by a DevRel team member[^1]. An approval from DevRel is not necessary to merge your PR. ### With Breaking Changes +Breaking changes need to be documented. Please ask for help from a DevRel[^1] team member if this is a problem for any reason. Breaking changes need a mandatory approval from DevRel. + Sometimes, we don't merge pull requests with breaking changes immediately upon approval. Since a breaking change will cause Noir to bump to the next "minor" version, we might want to land some fixes in "patch" releases before we begin working on that next breaking version. ## Merging @@ -156,6 +160,7 @@ Before merging, you should mentally review these questions: - Is continuous integration passing? - Do you have the required amount of approvals? - Does anyone else need to be pinged for thoughts? +- Does it have changes to the docs? If so, did you request an approval from a DevRel[^1] team member? - Will this cause problems for our release schedule? For example: maybe a patch release still needs to be published. - What details do we want to convey to users in the Changelog? @@ -167,11 +172,34 @@ Release Please parses Conventional Commit messages and opens (or updates) a pull When we are ready to release the version, we approve and squash the release pull request into `master`. Release Please will detect this merge and generate the appropriate tags for the release. Additional release steps may be triggered inside the GitHub Action to automate other parts of the release process. +### Documentation releases + +We aim to have every documentation version matching the versions of Noir. However, to avoid unnecessary build time and size to the existent documentation, they aren't currently released alongside the stable releases, and instead are released ad-hoc. + +Please contact any member of the DevRel[^1] team if you believe a new docs version should be cut. + +### Cutting a new version of the docs + +The Noir documentation is versioned according to the [Docusaurus documentation](https://docusaurus.io/docs/versioning). In the `versioned_docs` and `versioned_sidebar` folders you will find the docs and configs for the previous versions. If any change needs to be made to older versions, please do them in this folder. + +In the docs folder, you'll find the current, unreleased version, which we call `dev`. Any change in this folder will be reflected in the next release of the documentation. + +While the versioning is intended to be managed by the core maintainers, we feel it's important for external contributors to understand why and how is it maintained. To bump to a new version, run the following command, replacing with the intended version: + +```bash +npm run docusaurus docs:version +``` + +This should create a new version by copying the docs folder and the sidebars.js file to the relevant folders, as well as adding this version to versions.json. + +You can then open a Pull Request according to the the [PR section](#pull-requests) + ## Changelog Noir's Changelog is automatically managed by Release Please and informed by the Conventional Commits (as discussed above). Given the following commits: + - `feat(syntax): Implement String data type (#123)` - `chore(ci): Use correct rust version` - `fix(optimizer): Compile Boolean to u1` @@ -200,3 +228,5 @@ Release Please would generate add the following to the Changelog: * **optimizer:** Compile Boolean to u1 ``` + +[^1]: Currently, @critesjosh, @catmcgee and @signorecello. For Noir documentation, it is recommended to tag @signorecello diff --git a/compiler/wasm/package.json b/compiler/wasm/package.json index 2b47227c5f8..5dbc79f4c55 100644 --- a/compiler/wasm/package.json +++ b/compiler/wasm/package.json @@ -29,7 +29,6 @@ "lint": "NODE_NO_WARNINGS=1 eslint . --ext .ts --ignore-path ./.eslintignore --max-warnings 0", "build:nix": "nix build -L .#noir_wasm", "install:from:nix": "yarn clean && yarn build:nix && cp -rL ./result/noir_wasm/nodejs ./ && cp -rL ./result/noir_wasm/web ./" - }, "peerDependencies": { "@noir-lang/source-resolver": "workspace:*" diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md deleted file mode 100644 index 2b1f293fd64..00000000000 --- a/docs/CONTRIBUTING.md +++ /dev/null @@ -1,57 +0,0 @@ -# Contributing to Noir - -Thank you for your interest in contributing to Noir documentation! We value your contributions in making Noir better. - -This guide will discuss how the Noir team handles [Commits](#commits), [Pull Requests](#pull-requests), [Merging](#merging), and [Versioning](#versioning). - -__Note:__ We won't force external contributors to follow this verbatim, but following these guidelines definitely helps us in accepting your contributions. - -## Commits - -We want to keep our commits small and focused. This allows for easily reviewing individual commits and/or splitting up pull requests when they grow too big. Additionally, this allows us to merge smaller changes quicker and release more often. - -When committing, it's often useful to use the `git add -p` workflow to decide on what parts of the changeset to stage for commit. - -We don't currently enforce any commit standard, however that may change at any time. Mind that the [Noir](https://github.com/noir-lang/noir) repo does enforce the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) standard. - -## Pull Requests - -Before you create a pull request, search for any issues related to the change you are making. If none exist already, create an issue that thoroughly describes the problem that you are trying to solve. These are used to inform reviewers of the original intent and should be referenced via the pull request template. - -Pull Requests should be focused on the specific change they are working towards. If prerequisite work is required to complete the original pull request, that work should be submitted as a separate pull request. - -This strategy avoids scenarios where pull requests grow too large/out-of-scope and don't get proper reviews—we want to avoid "LGTM, I trust you" reviews. - -The easiest way to do this is to have multiple commits while you work and then you can cherry-pick the smaller changes into separate branches for pull requesting. - -### Reviews - -For any repository in the noir-lang organization, we require code review & approval by __one__ Noir team member before the changes are merged. However, while the docs repository is still getting up-to-speed with the current Noir fetures, we do allow for non-breaking pull requests to be merged at any time. Breaking pull requests should only be merged when the team has general agreement of the changes. - -The CI/CD workflow at Netlify should provide you with a preview of the website once merged. Use this preview to thoroughly test the changes before requesting reviews or merging. - -## Merging - -Once approved by the required number of team members, the pull request can be merged into the `master` branch. Sometimes, especially for external contributions, the final approver may merge the pull request instead of the submitter. - -### Merge Checklist - -Before merging, you should mentally review these questions: - -- Is continuous integration passing? -- Do you have the required amount of approvals? -- Does anyone else need to be pinged for thoughts? - -## Versioning - -The Noir documentation is versioned according to the [Docusaurus documentation](https://docusaurus.io/docs/versioning). In the `versioned_docs` and `versioned_sidebar` folders you will find the docs and configs for the previous versions. If any change needs to be made to older versions, please do it in this folder. - -In the `docs` folder, you'll find the current, unreleased version, which we call `dev`. Any change in this folder will be reflected in the next version, once the Noir team decides to release. - -We aim to have every version matching the versions of [Noir](https://github.com/noir-lang/noir). However, we would only cut a new version of the docs if there are breaking or otherwise significant changes, to avoid unecessary build time and size to the existent documentation. - -While the versioning is intended to be managed by the core maintainers, we feel it's important for external contributors to understand why and how is it maintained. To bump to a new version, run the following command, replacing with the intended version: - -`npm run docusaurus docs:version ` - -This should create a new version by copying the `docs` folder and the `sidebars.js` file to the relevant folders, as well as adding this version to `versions.json`. diff --git a/docs/README.md b/docs/README.md index 21c6b7f7ad6..92f6c5f41f7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,20 +9,20 @@ generator. Interested in contributing to the docs? -Check out the contributing guide [here](./CONTRIBUTING.md). +Check out the contributing guide [here](../CONTRIBUTING.md). ## Development ### Installation ``` -$ yarn +yarn ``` ### Local Development ``` -$ yarn start +yarn start ``` This command starts a local development server and opens up a browser window. Most changes are @@ -31,7 +31,7 @@ reflected live without having to restart the server. ### Build ``` -$ yarn build +yarn build ``` This command generates static content into the `build` directory and can be served using any static diff --git a/docs/docs/language_concepts/01_functions.md b/docs/docs/language_concepts/01_functions.md index af2c5863a2e..2168c9203b6 100644 --- a/docs/docs/language_concepts/01_functions.md +++ b/docs/docs/language_concepts/01_functions.md @@ -40,6 +40,45 @@ fn foo(x : Field, y : pub Field) -> Field { Note that a `return` keyword is unneeded in this case - the last expression in a function's body is returned. +## Main function + +If you're writing a binary, the `main` function is the starting point of your program. You can pass all types of expressions to it, as long as they have a fixed size at compile time: + +```rust +fn main(x : Field) // this is fine: passing a Field +fn main(x : [Field; 2]) // this is also fine: passing a Field with known size at compile-time +fn main(x : (Field, bool)) // 👌: passing a (Field, bool) tuple means size 2 +fn main(x : str<5>) // this is fine, as long as you pass a string of size 5 + +fn main(x : Vec) // can't compile, has variable size +fn main(x : [Field]) // can't compile, has variable size +fn main(....// i think you got it by now +``` + +Keep in mind [tests](../nargo/02_testing.md) don't differentiate between `main` and any other function. The following snippet passes tests, but won't compile or prove: + +```rust +fn main(x : [Field]) { + assert(x[0] == 1); +} + +#[test] +fn test_one() { + main([1, 2]); +} +``` + +```bash +$ nargo test +[testing] Running 1 test functions +[testing] Testing test_one... ok +[testing] All tests passed + +$ nargo check +The application panicked (crashed). +Message: Cannot have variable sized arrays as a parameter to main +``` + ## Call Expressions Calling a function in Noir is executed by using the function name and passing in the necessary diff --git a/docs/docs/modules_packages_crates/workspaces.md b/docs/docs/modules_packages_crates/workspaces.md index eaa09506698..d9ac92667c9 100644 --- a/docs/docs/modules_packages_crates/workspaces.md +++ b/docs/docs/modules_packages_crates/workspaces.md @@ -34,6 +34,6 @@ default-member = "crates/a" `default-member` indicates which package various commands process by default. -Libraries can be defined in a workspace. We just don't have a way to consume libraries from inside a workspace as external dependencies right now. +Libraries can be defined in a workspace. Inside a workspace, these are consumed as `{ path = "../to_lib" }` dependencies in Nargo.toml. Inside a workspace, these are consumed as `{ path = "../to_lib" }` dependencies in Nargo.toml. diff --git a/docs/docs/nargo/01_commands.md b/docs/docs/nargo/01_commands.md index 14c23290ce0..fbbe2b27666 100644 --- a/docs/docs/nargo/01_commands.md +++ b/docs/docs/nargo/01_commands.md @@ -20,12 +20,12 @@ keywords: ## General options -``` -Options: - --show-ssa Emit debug information for the intermediate SSA IR - --deny-warnings Quit execution when warnings are emitted - -h, --help Print help -``` +| Option | Description | +|---------------------|------------------------------------------------------| +| `--show-ssa` | Emit debug information for the intermediate SSA IR | +| `--deny-warnings` | Quit execution when warnings are emitted | +| `--silence-warnings`| Suppress warnings | +| `-h, --help` | Print help | ## `nargo help [subcommand]` @@ -33,7 +33,9 @@ Prints the list of available commands or specific information of a subcommand. _Arguments_ -- `` - The subcommand whose help message to display +| Argument | Description | +|---------------|--------------------------------------------------------| +| ``| The subcommand whose help message to display | ## `nargo backend` @@ -41,20 +43,20 @@ Installs and selects custom backends used to generate and verify proofs. ### Commands -``` - current Prints the name of the currently active backend - ls Prints the list of currently installed backends - use Select the backend to use - install Install a new backend from a URL - uninstall Uninstalls a backend - help Print this message or the help of the given subcommand(s) -``` +| Command | Description | +|------------|--------------------------------------------------| +| `current` | Prints the name of the currently active backend | +| `ls` | Prints the list of currently installed backends | +| `use` | Select the backend to use | +| `install` | Install a new backend from a URL | +| `uninstall`| Uninstalls a backend | +| `help` | Print this message or the help of the given subcommand(s) | ### Options -``` --h, --help Print help -``` +| Option | Description | +|---------------|--------------| +| `-h, --help` | Print help | ## `nargo check` @@ -63,13 +65,14 @@ values of the Noir program respectively. ### Options -``` - --package The name of the package to check - --workspace Check all packages in the workspace - --print-acir Display the ACIR for compiled circuit - --deny-warnings Treat all warnings as errors --h, --help Print help -``` +| Option | Description | +|----------------------|---------------------------------------------------| +| `--package `| The name of the package to check | +| `--workspace` | Check all packages in the workspace | +| `--print-acir` | Display the ACIR for compiled circuit | +| `--deny-warnings` | Treat all warnings as errors | +| `--silence-warnings` | Suppress warnings | +| `-h, --help` | Print help | ### `nargo codegen-verifier` @@ -77,13 +80,14 @@ Generate a Solidity verifier smart contract for the program. ### Options -``` - --package The name of the package to codegen - --workspace Codegen all packages in the workspace - --print-acir Display the ACIR for compiled circuit - --deny-warnings Treat all warnings as errors --h, --help Print help -``` +| Option | Description | +|----------------------|---------------------------------------------------| +| `--package `| The name of the package to codegen | +| `--workspace` | Codegen all packages in the workspace | +| `--print-acir` | Display the ACIR for compiled circuit | +| `--deny-warnings` | Treat all warnings as errors | +| `--silence-warnings` | Suppress warnings | +| `-h, --help` | Print help | ## `nargo compile` @@ -94,14 +98,15 @@ You can also use "build" as an alias for compile (e.g. `nargo build`). ### Options -``` - --include-keys Include Proving and Verification keys in the build artifacts - --package The name of the package to compile - --workspace Compile all packages in the workspace - --print-acir Display the ACIR for compiled circuit - --deny-warnings Treat all warnings as errors --h, --help Print help -``` +| Option | Description | +|----------------------|----------------------------------------------------| +| `--include-keys` | Include Proving and Verification keys in the build artifacts | +| `--package `| The name of the package to compile | +| `--workspace` | Compile all packages in the workspace | +| `--print-acir` | Display the ACIR for compiled circuit | +| `--deny-warnings` | Treat all warnings as errors | +| `--silence-warnings` | Suppress warnings | +| `-h, --help` | Print help | ## `nargo new ` @@ -109,19 +114,19 @@ Creates a new Noir project in a new folder. **Arguments** -``` - The path to save the new project -``` +| Argument | Description | +|-----------|------------------------------------| +| `` | The path to save the new project | ### Options -``` - --name Name of the package [default: package directory name] - --lib Use a library template - --bin Use a binary template [default] - --contract Use a contract template --h, --help Print help -``` +| Option | Description | +|-------------------|-------------------------------------------------| +| `--name ` | Name of the package [default: package directory name] | +| `--lib` | Use a library template | +| `--bin` | Use a binary template [default] | +| `--contract` | Use a contract template | +| `-h, --help` | Print help | ## `nargo init` @@ -129,13 +134,13 @@ Creates a new Noir project in the current directory. ### Options -``` - --name Name of the package [default: current directory name] - --lib Use a library template - --bin Use a binary template [default] - --contract Use a contract template --h, --help Print help -``` +| Option | Description | +|-------------------|-------------------------------------------------| +| `--name ` | Name of the package [default: current directory name] | +| `--lib` | Use a library template | +| `--bin` | Use a binary template [default] | +| `--contract` | Use a contract template | +| `-h, --help` | Print help | ## `nargo execute [WITNESS_NAME]` @@ -143,20 +148,21 @@ Runs the Noir program and prints its return value. **Arguments** -``` -[WITNESS_NAME] Write the execution witness to named file -``` +| Argument | Description | +|-----------------|------------------------------------------------| +| `[WITNESS_NAME]`| Write the execution witness to named file | ### Options -``` --p, --prover-name The name of the toml file which contains the inputs for the prover [default: Prover] - --package The name of the package to execute - --workspace Execute all packages in the workspace - --print-acir Display the ACIR for compiled circuit - --deny-warnings Treat all warnings as errors --h, --help Print help -``` +| Option | Description | +|-------------------------------|------------------------------------------------------------------| +| `-p, --prover-name ` | The name of the toml file which contains the inputs for the prover [default: Prover] | +| `--package ` | The name of the package to execute | +| `--workspace` | Execute all packages in the workspace | +| `--print-acir` | Display the ACIR for compiled circuit | +| `--deny-warnings` | Treat all warnings as errors | +| `--silence-warnings` | Suppress warnings | +| `-h, --help` | Print help | _Usage_ @@ -172,16 +178,17 @@ Creates a proof for the program. ### Options -``` --p, --prover-name The name of the toml file which contains the inputs for the prover [default: Prover] --v, --verifier-name The name of the toml file which contains the inputs for the verifier [default: Verifier] - --verify Verify proof after proving - --package The name of the package to prove - --workspace Prove all packages in the workspace - --print-acir Display the ACIR for compiled circuit - --deny-warnings Treat all warnings as errors --h, --help Print help -``` +| Option | Description | +|-------------------------------|------------------------------------------------------------------| +| `-p, --prover-name ` | The name of the toml file which contains the inputs for the prover [default: Prover] | +| `-v, --verifier-name ` | The name of the toml file which contains the inputs for the verifier [default: Verifier] | +| `--verify` | Verify proof after proving | +| `--package ` | The name of the package to prove | +| `--workspace` | Prove all packages in the workspace | +| `--print-acir` | Display the ACIR for compiled circuit | +| `--deny-warnings` | Treat all warnings as errors | +| `--silence-warnings` | Suppress warnings | +| `-h, --help` | Print help | ## `nargo verify` @@ -189,14 +196,15 @@ Given a proof and a program, verify whether the proof is valid. ### Options -``` --v, --verifier-name The name of the toml file which contains the inputs for the verifier [default: Verifier] - --package The name of the package verify - --workspace Verify all packages in the workspace - --print-acir Display the ACIR for compiled circuit - --deny-warnings Treat all warnings as errors --h, --help Print help -``` +| Option | Description | +|-------------------------------|------------------------------------------------------------------| +| `-v, --verifier-name ` | The name of the toml file which contains the inputs for the verifier [default: Verifier] | +| `--package ` | The name of the package to verify | +| `--workspace` | Verify all packages in the workspace | +| `--print-acir` | Display the ACIR for compiled circuit | +| `--deny-warnings` | Treat all warnings as errors | +| `--silence-warnings` | Suppress warnings | +| `-h, --help` | Print help | ## `nargo test [TEST_NAME]` @@ -209,15 +217,16 @@ See an example on the [testing page](./testing). ### Options -``` - --show-output Display output of `println` statements - --exact Only run tests that match exactly - --package The name of the package to test - --workspace Test all packages in the workspace - --print-acir Display the ACIR for compiled circuit - --deny-warnings Treat all warnings as errors --h, --help Print help -``` +| Option | Description | +|----------------------|---------------------------------------------------| +| `--show-output` | Display output of `println` statements | +| `--exact` | Only run tests that match exactly | +| `--package `| The name of the package to test | +| `--workspace` | Test all packages in the workspace | +| `--print-acir` | Display the ACIR for compiled circuit | +| `--deny-warnings` | Treat all warnings as errors | +| `--silence-warnings` | Suppress warnings | +| `-h, --help` | Print help | ## `nargo info` diff --git a/docs/docs/nargo/04_language_server.md b/docs/docs/nargo/04_language_server.md index 8a81d7232d8..543af9ec5ff 100644 --- a/docs/docs/nargo/04_language_server.md +++ b/docs/docs/nargo/04_language_server.md @@ -1,9 +1,7 @@ --- title: Language Server -description: - Learn about the Noir Language Server, how to install the components, and configuration that may be required. -keywords: - [Nargo, Language Server, LSP, VSCode, Visual Studio Code] +description: Learn about the Noir Language Server, how to install the components, and configuration that may be required. +keywords: [Nargo, Language Server, LSP, VSCode, Visual Studio Code] --- This section helps you install and configure the Noir Language Server. @@ -23,6 +21,10 @@ The Client component is usually an editor plugin that launches the Server. It co Currently, Noir provides a Language Client for Visual Studio Code via the [vscode-noir](https://github.com/noir-lang/vscode-noir) extension. You can install it via the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir). +> **Note:** Noir's Language Server Protocol support currently assumes users' VSCode workspace root to be the same as users' Noir project root (i.e. where Nargo.toml lies). +> +> If LSP features seem to be missing / malfunctioning, make sure you are opening your Noir project directly (instead of as a sub-folder) in your VSCode instance. + When you language server is running correctly and the VSCode plugin is installed, you should see handy codelens buttons for compilation, execution, and tests: ![Compile and Execute](./../../static/img/codelens_compile_execute.png) @@ -34,7 +36,7 @@ You should also see your tests in the `testing` panel: ### Configuration -* __Noir: Enable LSP__ - If checked, the extension will launch the Language Server via `nargo lsp` and communicate with it. -* __Noir: Nargo Flags__ - Additional flags may be specified if you require them to be added when the extension calls `nargo lsp`. -* __Noir: Nargo Path__ - An absolute path to a Nargo binary with the `lsp` command. This may be useful if Nargo is not within the `PATH` of your editor. -* __Noir > Trace: Server__ - Setting this to `"messages"` or `"verbose"` will log LSP messages between the Client and Server. Useful for debugging. +- **Noir: Enable LSP** - If checked, the extension will launch the Language Server via `nargo lsp` and communicate with it. +- **Noir: Nargo Flags** - Additional flags may be specified if you require them to be added when the extension calls `nargo lsp`. +- **Noir: Nargo Path** - An absolute path to a Nargo binary with the `lsp` command. This may be useful if Nargo is not within the `PATH` of your editor. +- **Noir > Trace: Server** - Setting this to `"messages"` or `"verbose"` will log LSP messages between the Client and Server. Useful for debugging. diff --git a/docs/docs/noir_js/getting_started/01_tiny_noir_app.md b/docs/docs/noir_js/getting_started/01_tiny_noir_app.md index 629a88fd2f1..9878554dd60 100644 --- a/docs/docs/noir_js/getting_started/01_tiny_noir_app.md +++ b/docs/docs/noir_js/getting_started/01_tiny_noir_app.md @@ -248,3 +248,7 @@ if (verification) display('logs', 'Verifying proof... ✅'); ``` By saving, your app will refresh and here's our complete Tiny Noir App! + +## Further Reading + +You can see how noirjs is used in a full stack Next.js hardhat application in the [noir-starter repo here](https://github.com/noir-lang/noir-starter/tree/main/next-hardhat). The example shows how to calculate a proof in the browser and verify it with a deployed Solidity verifier contract from noirjs. diff --git a/docs/docs/noir_js/noir_js.md b/docs/docs/noir_js/noir_js.md index a4609215f92..baaf409b522 100644 --- a/docs/docs/noir_js/noir_js.md +++ b/docs/docs/noir_js/noir_js.md @@ -17,6 +17,6 @@ Your only concern should be to write Noir. Noir.js will work out-of-the box and ## Barretenberg -Since Noir is backend agnostic, you can instantiate `noir_js` with supported backends through their own `js` interface. +Since Noir is backend agnostic, you can instantiate `noir_js` without any backend (i.e. to execute a function). But for proving, you should instantiate it with any of the supported backends through their own `js` interface. Aztec Labs maintains the `barretenberg` backend. You can use it to instantiate your `Noir` class. diff --git a/docs/docs/noir_js/reference/02_noirjs.md b/docs/docs/noir_js/reference/02_noirjs.md index 07baf1e0bbe..d9e5a0c6115 100644 --- a/docs/docs/noir_js/reference/02_noirjs.md +++ b/docs/docs/noir_js/reference/02_noirjs.md @@ -54,6 +54,35 @@ This method takes no parameters await noirInstance.init(); ``` +## `execute` + +This async method allows to execute a circuit to get its witness and return value. [`generateFinalProof`](#generatefinalproof) calls it for you, but you can call it directly (i.e. to feed directly to a backend, or to get the return value). + +### Syntax + +```js +async execute(inputs) +``` + +### Parameters + +| Parameter | Type | Description | +| --------- | ------ | ------------------------------------------------ | +| `inputs` | Object | An object containing the inputs to your circuit. | + +### Returns + +| Return value | Type | Description | +| ------------ | --------------------- | --------------------------------------------------- | +| `witness` | Promise | The witness | +| `returnValue` | Promise | The return value | + +### Usage + +```js +const { witness, returnValue } = await noir.execute(inputs) +``` + ## `generateFinalProof` This async method generates a witness and a proof given an object as input.