chore(docs): cut new docs version for tag v1.0.0-beta.19

Author: noirwhal

docs/versioned_docs/version-v1.0.0-beta.19/explainers/explainer-oracle.md

@@ -0,0 +1,69 @@
+---
+title: Oracles
+description: This guide provides an in-depth understanding of how Oracles work in Noir programming. Learn how to use outside calculations in your programs, constrain oracles, and understand their uses and limitations.
+keywords:
+  - Noir Programming
+  - Oracles
+  - JSON-RPC
+  - Foreign Call Handlers
+  - Constrained Functions
+  - Blockchain Programming
+sidebar_position: 1
+---
+
+If you've seen "The Matrix" you may recall "The Oracle" as Gloria Foster smoking cigarettes and baking cookies. While she appears to "know things", she is actually providing a calculation of a pre-determined future. Noir Oracles are similar, in a way. They don't calculate the future (yet), but they allow you to use outside calculations in your programs.
+
+![matrix oracle prediction](@site/static/img/memes/matrix_oracle.jpeg)
+
+A Noir program is usually self-contained. You can pass certain inputs to it, and it will generate a deterministic output for those inputs. But what if you wanted to defer some calculation to an outside process or source?
+
+Oracles are functions that provide this feature.
+
+## Use cases
+
+An example usage for Oracles is proving something on-chain. For example, proving that the ETH-USDC quote was below a certain target at a certain block time. Or even making more complex proofs like proving the ownership of an NFT as an anonymous login method.
+
+Another interesting use case is to defer expensive calculations to be made outside of the Noir program, and then constraining the result; similar to the use of [unconstrained functions](../noir/concepts//unconstrained.md).
+
+In short, anything that can be constrained in a Noir program but needs to be fetched from an external source is a great candidate to be used in oracles.
+
+## Constraining oracles
+
+Just like in The Matrix, Oracles are powerful. But with great power, comes great responsibility. Just because you're using them in a Noir program doesn't mean they're true. Noir has no superpowers. If you want to prove that Portugal won the Euro Cup 2016, you're still relying on potentially untrusted information.
+
+To give a concrete example, Alice wants to login to the [NounsDAO](https://nouns.wtf/) forum with her username "noir_nouner" by proving she owns a noun without revealing her ethereum address. Her Noir program could have an oracle call like this:
+
+```rust
+#[oracle(getNoun)]
+unconstrained fn get_noun(address: Field) -> Field
+```
+
+This oracle could naively resolve with the number of Nouns she possesses. However, it is useless as a trusted source, as the oracle could resolve to anything Alice wants. In order to make this oracle call actually useful, Alice would need to constrain the response from the oracle, by proving her address and the noun count belongs to the state tree of the contract.
+
+In short, **Oracles don't prove anything. Your Noir program does.**
+
+:::danger
+
+If you don't constrain the return of your oracle, you could be clearly opening an attack vector on your Noir program. Make double-triple sure that the return of an oracle call is constrained!
+
+:::
+
+## Return Type
+
+Oracles cannot return references (e.g., `&Field`, `&mut T`) because oracle functions represent external computations that execute outside the Noir program's memory space. Since oracles bridge between the Noir runtime and external environments, any values they return must be copied into the caller's context rather than referenced. Attempting to return a reference from an oracle would be meaningless, as there is no shared memory space between the oracle's execution environment and the Noir program.
+
+This restriction applies to any type containing references, including:
+- Direct references: `&Field`, `&mut u32`
+- Tuples with references: `(Field, &u32)`
+- Structs with reference fields
+- Enums with reference variants
+
+The compiler will produce an error if an oracle function's return type contains any references.
+
+## How to use Oracles
+
+On CLI, Nargo resolves oracles by making JSON RPC calls, which means it would require an RPC node to be running.
+
+In JavaScript, NoirJS accepts and resolves arbitrary call handlers (that is, not limited to JSON) as long as they match the expected types the developer defines.
+
+If you want to build using oracles, follow through to the [oracle guide](../how_to/how-to-oracles.md) for a simple example on how to do that.

docs/versioned_docs/version-v1.0.0-beta.19/explainers/explainer-writing-noir.md

@@ -0,0 +1,207 @@
+---
+title: Thinking in Circuits
+description: Considerations when writing Noir programs
+keywords: [Noir, programming, rust]
+tags: [Optimization]
+sidebar_position: 0
+---
+
+
+This article intends to set you up with key concepts essential for writing more viable applications that use zero knowledge proofs, namely around efficient circuits.
+
+## Context - 'Efficient' is subjective
+
+When writing a web application for a performant computer with high-speed internet connection, writing efficient code sometimes is seen as an afterthought only if needed. Large multiplications running at the innermost of nested loops may not even be on a dev's radar.
+When writing firmware for a battery-powered microcontroller, you think of cpu cycles as rations to keep within a product's power budget.
+
+> Code is written to create applications that perform specific tasks within specific constraints
+
+And these constraints differ depending on where the compiled code is execute.
+
+### The Ethereum Virtual Machine (EVM)
+
+In scenarios where extremely low gas costs are required for an Ethereum application to be viable/competitive, Ethereum smart contract developers get into what is colloquially known as: "*gas golfing*". Finding the lowest execution cost of their compiled code (EVM bytecode) to achieve a specific task.
+
+The equivalent optimization task when writing zk circuits is affectionately referred to as "*gate golfing*", finding the lowest gate representation of the compiled Noir code.
+
+### Coding for circuits - a paradigm shift
+
+In zero knowledge cryptography, code is compiled to "circuits" consisting of arithmetic gates, and gate count is the significant cost. Depending on the proving system this is linearly proportionate to proof size and proving time, so from a product point of view this should be kept as low as possible.
+
+Whilst writing efficient code for web apps and Solidity have some differences, writing efficient circuits have a different set of considerations. It is a bit of a paradigm shift, like writing code for GPUs for the first time...
+
+For example, drawing a circle at (0, 0) of radius `r`:
+- For a single CPU thread,
+```
+for theta in 0..2*pi {
+  let x = r * cos(theta);
+  let y = r * sin(theta);
+  draw(x, y);
+} // note: would do 0 - pi/2 and draw +ve/-ve x and y.
+```
+
+- For GPUs (simultaneous parallel calls with x, y across image),
+```
+if (x^2 + y^2 = r^2) {
+  draw(x, y);
+}
+```
+
+([Related](https://www.youtube.com/watch?v=-P28LKWTzrI))
+
+Whilst this CPU -> GPU does not translate to circuits exactly, it is intended to exemplify the difference in intuition when coding for different machine capabilities/constraints.
+
+### Context Takeaway
+
+For those coming from a primarily web app background, this article will explain what you need to consider when writing circuits. Furthermore, for those experienced writing efficient machine code, prepare to shift what you think is efficient 😬
+
+## Translating from Rust
+
+Programs written in anything from pseudo code to C, can be translated into Noir. A Rust program written for execution can be readily ported to Noir thanks to the similarities in syntax.
+
+:::note
+Many valuable functions and algorithms have been written in more established languages (C/C++), and converted to modern ones (like Rust).
+:::
+
+Fortunately for Noir developers, when needing a particular function a Rust implementation can be readily compiled into Noir with some key changes. While the compiler does a decent amount of optimizations, it won't be able to change code that has been optimized for clock-cycles into code optimized for arithmetic gates.
+
+A few things to do when converting Rust code to Noir:
+- `println!` is not a macro, use `println` function (same for `assert_eq`)
+- No early `return` in function. Use constrain via assertion instead
+- No passing by reference. Remove `&` operator to pass by value (copy)
+- No boolean operators (`&&`, `||`). Use bitwise operators (`&`, `|`) with boolean values
+- No type `usize`. Use types `u8`, `u32`, `u64`, ...
+- `main` return must be public, `pub`
+- No `const`, use `global`
+- Noir's LSP is your friend, so error message should be informative enough to resolve syntax issues.
+
+## Writing efficient Noir for performant products
+
+The following points help refine our understanding over time.
+
+:::note
+A Noir program makes a statement that can be verified.
+:::
+
+It compiles to a structure that represents the calculation, and can assert results within the calculation at any stage (via the `constrain` keyword).
+
+A Noir program compiles to an Abstract Circuit Intermediate Representation which is:
+ - Conceptually a tree structure
+ - Leaves (inputs) are the `Field` type
+ - Nodes contain arithmetic operations to combine them (gates)
+ - The root is the final result (return value)
+
+:::tip
+The command `nargo info` shows the programs circuit size, and is useful to compare the value of changes made.
+You can dig deeper and use the `--print-acir` param to take a closer look at individual ACIR opcodes, and the proving backend to see its gate count (eg for barretenberg, the `bb` binary has a `gates` option).
+:::
+
+### Numerical types
+
+As mentioned earlier Noir has many familiar integer types (eg `i8`, `u64`). Ideally after bringing a program into Noir, proving/verifying of its execution just works where needed: client/server side, on an evm, or on the Aztec network.
+
+A program optimized for execution may leverage the binary representations of integers, reducing the number of clock cycles, and thus time of execution.
+The cryptography in a proving backend makes use of a `Field` type, and leveraging this lower level type correctly can reduce gate count, and thus proof size and proving time.
+
+In some instances simply replacing the integer type with a `Field` could save on some range checks (and hence gates).
+Note: when casting a `Field` to an integer type, the value is converted based on the integer binary representation. Eg a Field variable with a value of 260 `as u8` becomes 4
+
+### `Field`s for efficiency
+
+`Field` types have their own underlying representation that is efficient for cryptography, which is different to binary representations efficient for CPUs. So, mathematically speaking, things like bitwise operations do not directly translate to fields. That said, the same outcome can be achieved if wanting to use the Field type as a number with lower overhead.
+
+For instance shift (`<<`) and or (`|`) work seamlessly with integer types (bit-packing `u8`'s into a `u16`):
+```
+  high as u16 << 8 | low as u16
+```
+
+More efficiently with `Field` types, the equivalent is:
+```
+  low.assert_max_bit_size::<8>(); // ensure Field values could be represented as 8 bit numbers
+  high.assert_max_bit_size::<8>();
+  (high * 2.pow_32(8) + low)
+```
+(Note, the power of two can instead be a constant (256) or global evaluated at compile time)
+
+The first snippet is good for compatibility when using existing code, converting to the latter can help optimize frequently used functions.
+
+:::tip
+Where possible, use the `Field` type for values. Writing code with smaller value types and bit-packing strategies will result in MORE gates
+:::
+
+### Use Arithmetic over non-arithmetic operations
+
+Since circuits are made of arithmetic gates, the cost of arithmetic operations tends to be one gate. Whereas for procedural code, they represent several clock cycles.
+
+Inversely, non-arithmetic operators are achieved with multiple gates, vs 1 clock cycle for procedural code.
+
+| (cost\op)  | arithmetic<br>(`*`, `+`) | bit-wise ops<br>(eg `<`, `\|`, `>>`) |
+| - | - | - |
+| **cycles** | 10+ | 1 |
+| **gates**  | 1 | 10+ |
+
+Bit-wise operations (e.g. bit shifts `<<` and `>>`), albeit commonly used in general programming and especially for clock cycle optimizations, are on the contrary expensive in gates when performed within circuits.
+
+Translate away from bit shifts when writing constrained functions for the best performance.
+
+On the flip side, feel free to use bit shifts in unconstrained functions and tests if necessary, as they are executed outside of circuits and does not induce performance hits.
+
+### Use static over dynamic values
+
+Another general theme that manifests in different ways is that static reads are represented with less gates than dynamic ones.
+
+Reading from read-only memory (ROM) adds less gates than random-access memory (RAM), 2 vs ~3.25 due to the additional bounds checks. Arrays of fixed length (albeit used at a lower capacity), will generate less gates than dynamic storage.
+
+Related to this, if an index used to access an array is not known at compile time (ie unknown until run time), then ROM will be converted to RAM, expanding the gate count.
+
+:::tip
+Use arrays and indices that are known at compile time where possible.
+Using `assert_constant(i);` before an index, `i`, is used in an array will give a compile error if `i` is NOT known at compile time.
+:::
+
+### Reduce what is inside loops and conditional logic
+
+Putting less logic  inside an `if` (`else`, etc) paths, or inside a loop, translates to less gates required to represent the program. The compiler should mostly take care of this.
+
+A loop duplicates the gates for each iteration of the loop, or put another way, "unrolls" the loop. Any calculations/calls that are unchanged in the loop should be calculated once before, and the result used in the loop.
+
+An `if` statement is "flattened" and gates created for each path even if execution uses only one path. Furthermore, there are additional operations required for each path. Sometimes this can have a multiplying effect on the operations in the `if` and `else` etc.
+
+:::tip
+Only have essential computation inside conditional logic and loops, and calculate anything else once (before, or after, depending).
+:::
+
+### Leverage unconstrained execution
+
+Constrained verification can leverage unconstrained execution, this is especially useful for operations that are represented by many gates.
+Use an [unconstrained function](../noir/concepts/unconstrained.md) to perform gate-heavy calculations, then verify and constrain the result.
+
+Eg division generates more gates than multiplication, so calculating the quotient in an unconstrained function then constraining the product for the quotient and divisor (+ any remainder) equals the dividend will be more efficient.
+
+Use `  if is_unconstrained() { /`, to conditionally execute code if being called in an unconstrained vs constrained way.
+
+## Advanced
+
+Unless you're well into the depth of gate optimization, this advanced section can be ignored.
+
+### Combine arithmetic operations
+
+A Noir program can be honed further by combining arithmetic operators in a way that makes the most of each constraint of the backend proving system. This is in scenarios where the backend might not be doing this perfectly.
+
+Eg Barretenberg backend (current default for Noir) is a width-4 PLONKish constraint system
+$ w_1*w_2*q_m + w_1*q_1 + w_2*q_2 + w_3*q_3 + w_4*q_4 + q_c = 0 $
+
+Here we see there is one occurrence of witness 1 and 2 ($w_1$, $w_2$) being multiplied together, with addition to witnesses 1-4 ($w_1$ .. $w_4$) multiplied by 4 corresponding circuit constants ($q_1$ .. $q_4$) (plus a final circuit constant, $q_c$).
+
+Use `nargo info --print-acir`, to inspect the ACIR opcodes (and the proving system for gates), and it may present opportunities to amend the order of operations and reduce the number of constraints.
+
+#### Variable as witness vs expression
+
+If you've come this far and really know what you're doing at the equation level, a temporary lever (that will become unnecessary/useless over time) is: `std::as_witness`. This informs the compiler to save a variable as a witness not an expression.
+
+The compiler will mostly be correct and optimal, but this may help some near term edge cases that are yet to optimize.
+Note: When used incorrectly it will create **less** efficient circuits (higher gate count).
+
+## References
+- Guillaume's ["`Crypdoku`" talk](https://www.youtube.com/watch?v=MrQyzuogxgg) (Jun'23)
+- [Idiomatic Noir](https://www.vlayer.xyz/blog/idiomatic-noir-part-1-collections) blog post

docs/versioned_docs/version-v1.0.0-beta.19/getting_started/noir_installation.md

@@ -0,0 +1,106 @@
+---
+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
+    Nargo
+    Noirup
+    Binaries
+    Compiling from Source
+    WSL for Windows
+    macOS
+    Linux
+    Nix
+    Direnv
+    Uninstalling Nargo
+  ]
+sidebar_position: 2
+---
+
+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.
+
+### Installing Noirup
+
+First, ensure you have `noirup` installed:
+
+```sh
+curl -L https://raw.githubusercontent.com/noir-lang/noirup/main/install | bash
+```
+
+### Fetching Binaries
+
+With `noirup`, you can easily switch between different Nargo versions, including nightly builds:
+
+- **Nightly Version**: Install the latest nightly build.
+
+  ```sh
+  noirup --version nightly
+  ```
+
+- **Specific Version**: Install a specific version of Nargo.
+
+  ```sh
+  noirup --version <version>
+  ```
+
+### Compiling from Source
+
+`noirup` also enables compiling Nargo from various sources:
+
+- **From a Specific Branch**: Install from the latest commit on a branch.
+
+  ```sh
+  noirup --branch <branch-name>
+  ```
+
+- **From a Fork**: Install from the main branch of a fork.
+
+  ```sh
+  noirup --repo <username/repo>
+  ```
+
+- **From a Specific Branch in a Fork**: Install from a specific branch in a fork.
+
+  ```sh
+  noirup --repo <username/repo> --branch <branch-name>
+  ```
+
+- **From a Specific Pull Request**: Install from a specific PR.
+
+  ```sh
+  noirup --pr <pr-number>
+  ```
+
+- **From a Specific Commit**: Install from a specific commit.
+
+  ```sh
+  noirup -C <commit-hash>
+  ```
+
+- **From Local Source**: Compile and install from a local directory.
+
+  ```sh
+  noirup --path ./path/to/local/source
+  ```
+
+## Installation on Windows
+
+The default backend for Noir (Barretenberg) doesn't provide Windows binaries at this time. For that reason, Noir cannot be installed natively. 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](#installing-noirup).
+
+## Setting up shell completions
+
+Once `nargo` is installed, you can [set up shell completions for it](../tooling/shell_completions.md).
+
+## Uninstalling Nargo
+
+If you installed Nargo with `noirup`, you can uninstall Nargo by removing the files in `~/.nargo`, `~/nargo`, and `~/noir_cache`. This ensures that all installed binaries, configurations, and cache related to Nargo are fully removed from your system.
+
+```bash
+rm -r ~/.nargo
+rm -r ~/nargo
+rm -r ~/noir_cache
+```