chore: docs restructure (#2322)

- Removed some things from the sidebar that were empty/WIP
- Filled out 'how to participate' and 'visibility' sections
- Changed around structure to make it easier to follow
- use #include_code macro to pull in code from tests for getting started
page
- closes #1905 
# Checklist:
Remove the checklist to signal you've completed it. Enable auto-merge if
the PR is ready to merge.
- [ ] If the pull request requires a cryptography review (e.g.
cryptographic algorithm implementations) I have added the 'crypto' tag.
- [ ] I have reviewed my diff in github, line by line and removed
unexpected formatting changes, testing logs, or commented-out code.
- [ ] Every change is related to the PR description.
- [ ] I have
[linked](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)
this pull request to relevant issues (if any exist).

---------

Co-authored-by: josh crites <[email protected]>
Co-authored-by: Josh Crites <[email protected]>

README.md

@@ -1,10 +1,20 @@
 # Aztec Monorepo
 
-All the packages that make up [Aztec](https://docs.aztec.network/what-is-aztec).
+All the packages that make up [Aztec](https://docs.aztec.network).
 
 - [**`circuits`**](/circuits): C++ code for circuits and cryptographic functions
 - [**`l1-contracts`**](/l1-contracts): Solidity code for the Ethereum contracts that process rollups
 - [**`yarn-project`**](/yarn-project): Typescript code for client and backend
+- [**`docs`**](/docs): Documentation source for the docs site
+
+## Popular packages
+
+- [Aztec.nr](./yarn-project/aztec-nr/): A [Noir](https://noir-lang.org) framework for smart contracts on Aztec.
+- [Aztec Sandbox](./yarn-project/aztec-sandbox/): A package for setting up a local dev net, including a local Ethereum network, deployed rollup contracts and Aztec execution environment.
+- [Aztec.js](./yarn-project/aztec.js/): A tool for interacting with the Aztec network. It communicates via the [Aztec RPC Server](./yarn-project/aztec-rpc/).
+- [Aztec Boxes](./yarn-project/boxes/): A minimal framework for building full stack applications for Aztec (using React).
+- [Example contracts](./yarn-project/noir-contracts/): Example contracts for the Aztec network, written in Noir.
+- [End to end tests](./yarn-project/end-to-end/): Integration tests writted in Typescript--a good reference for how to use the packages for specific tasks.
 
 ## Issues Board
 

docs/docs/about_aztec/how_to_contribute.md

@@ -2,19 +2,19 @@
 title: How to Participate?
 ---
 
-- Talk about how we want the Aztec network to be as decentralised as possible, hence we want to actively encourage participation.
+Decentralization is one of our core values, so we want to encourage participation as much as possible and in any way you can.
 
 ## Improve the protocol
 
-- Point to discourse forum.
+- Join us at our [Discourse forum](https://discourse.aztec.network/) or [Discord server](https://discord.gg/DgWG2DBMyB) to discuss all things related to Aztec and share your feedback
 
 ## Contribute code
 
-- Point to github
-- Point to 'good first issues'
-- Encourage people to open issues
+- Check out the monorepo on GitHub [here](https://github.com/AztecProtocol/aztec-packages)
+- We have some [good first issues](https://github.com/AztecProtocol/aztec-packages/labels/good%20first%20issue) for newcomers
+- Anyone can open an Issue, so please feel free to create one
 
 ## Grants
 
-- Discuss opportunities for grants
-
+- We often run grants programs to support awesome projects and teams, you can read some of our past grantees [here](https://aztecnetwork.notion.site/Aztec-Grants-Wave-3-RFPs-acba57016db048868e5ed07cbf549979?p=5b2bf249f8f44836a10e6210cbaf95c0&pm=s)
+- Keep checking back to see when we're opening up a new wave of grants

docs/docs/about_aztec/overview.mdx

@@ -60,8 +60,7 @@ To support Aztec's rollup, our cryptography team is building [Honk](https://gith
 
 ## Participate
 
-Keep up with the latest discussion and join the conversation in the [Aztec forum](https://discourse.aztec.network).
+Keep up with the latest discussion and join the conversation in the [Aztec forum](https://discourse.aztec.network) or [Discord server](https://discord.gg/DgWG2DBMyB).
 
-
-import Disclaimer from "../misc/common/\_disclaimer.mdx";
-<Disclaimer/>
+import Disclaimer from "../misc/common/_disclaimer.mdx";
+<Disclaimer />;

docs/docs/about_aztec/roadmap/cryptography_roadmap.md

@@ -2,7 +2,7 @@
 title: Cryptography Roadmap
 ---
 
-[Barretenberg](https://github.com/AztecProtocol/barretenberg/)
+The cryptography team is currently working on [Barretenberg here](https://github.com/AztecProtocol/aztec-packages/tree/master/barretenberg)
 
 ## R&D projects
 

docs/docs/about_aztec/roadmap/features_initial_ldt.md

@@ -2,9 +2,13 @@
 title: Initial Sandbox Features
 ---
 
+import Disclaimer from "../../misc/common/\_disclaimer.mdx";
+
+<Disclaimer/>
+
 The Aztec Sandbox is intended to provide developers with a lightweight & fast node, with features similar to Ethereum's Ganache or Anvil 'local node' packages.
 
-Devs should be able to quickly spin up local, emulated instances of an Ethereum blockchain and an Aztec encrypted rollup, and start deploying private contracts and submitting private txs.
+Developers should be able to quickly spin up local, emulated instances of an Ethereum blockchain and an Aztec encrypted rollup, and start deploying private contracts and submitting private txs.
 
 Here's a summary of the features we intend to support with the first release of the Aztec Sandbox.
 
@@ -42,7 +46,7 @@ Here's a summary of the features we intend to support with the first release of
 
 ## `aztec.js`
 
-A typescript wrapper for making RPC calls to an Aztec LDT node.
+A typescript wrapper for making RPC calls to an Aztec Sandbox node.
 
 - Similar in purpose to `web3.js`/`ethers.js`/`viem`, but for interacting with Aztec Network nodes. The RPC interface for an Aztec node is necessarily different from that of an Ethereum node, because it deals with encrypted transactions and state variables.
 - A library for public/private key management.
@@ -54,7 +58,7 @@ A typescript wrapper for making RPC calls to an Aztec LDT node.
 - Send txs to the LDT node, to be sent to the LDT network.
 - Call `unconstrained` functions of a Aztec.nr contract, to perform `pure` calculations or retrieve state.
 
-## Aztec Local Developer Testnet Node
+## Aztec Sandbox Node
 
 A bundle of packages which emulate the actions of all eventual Aztec network participants. The goal is for developer experience to be akin to Ganache / Anvil.
 
@@ -83,7 +87,3 @@ A bundle of packages which emulate the actions of all eventual Aztec network par
 ## Participate
 
 Keep up with the latest discussion and join the conversation in the [Aztec forum](https://discourse.aztec.network).
-
-
-import Disclaimer from "../../misc/common/\_disclaimer.mdx";
-<Disclaimer/>

docs/docs/about_aztec/roadmap/main.md

@@ -1,5 +1,5 @@
-<!-- # Full Roadmap
+import DocCardList from '@theme/DocCardList';
 
-:::danger
-Placeholder in case we want to include the org roadmap (higher level, non-engineering).
-::: -->
+# Roadmap
+
+<DocCardList/>

docs/docs/concepts/advanced/circuits/kernels/main.md

@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# Kernel Circuits
+
+<DocCardList />

docs/docs/concepts/advanced/data_structures/main.md

@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# Data Structures
+
+<DocCardList />

docs/docs/concepts/advanced/main.md

@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# Advanced Concepts
+
+<DocCardList />

docs/docs/concepts/foundation/main.md

@@ -0,0 +1,5 @@
+import DocCardList from '@theme/DocCardList';
+
+# Foundational Concepts
+
+<DocCardList />

docs/docs/concepts/foundation/state_model.md

@@ -6,8 +6,6 @@ import Disclaimer from '../../misc/common/\_disclaimer.mdx';
 
 <Disclaimer/>
 
-## Public State
-
 ## Private State
 
 Private state must be treated differently from public state and this must be expressed in the semantics of Aztec.nr.
@@ -29,19 +27,13 @@ This is achieved with two main features:
 1. Users sign over transactions, not over specific UTXO's
 2. Aztec.nr contracts support developer defined `unconstrained` getter functions to help dApp's make sense of UTXO's. e.g `getBalance()`. These functions can be called outside of a transaction context to read private state.
 
+## Coming soon
 
-### The lifecycle of a note
-
-#### Custom notes
-
-#### Injection of data by the kernel
-
-Nonce & contract address
-
-#### Custom nullifiers
-
-#### Emission of custom note data to L1
-
-#### Decrypting and storing encrypted note data
-
-Decryption and storing data and validating Note exists and computing nullifier
+- Public State
+- The lifecycle of a note
+- Custom notes
+- Injection of data by the kernel
+- Nonce & contract address
+- Custom nullifiers
+- Emission of custom note data to L1
+- Decrypting and storing encrypted note data

docs/docs/concepts/foundation/transactions.md

@@ -9,11 +9,3 @@ import Disclaimer from '../../misc/common/\_disclaimer.mdx';
 See [here](https://miro.com/app/board/uXjVMQbDwNk=/?share_link_id=47681418582) for a gigantic diagram (readonly) showing the flow from user to L2, to L1, back to user.
 
 > Note: the protocol and its implementation are rapidly evolving, so some info in this diagram will be out of date.
-
-## Lifecycle of a private tx
-
-- Describe, in bullet points, the lifecycle
-
-## Lifecycle of a public tx
-
-- Describe, in bullet points, the lifecycle

docs/docs/dev_docs/getting_started/cli.md → docs/docs/dev_docs/cli/cli.md

@@ -1,12 +1,12 @@
 ---
-title: Aztec CLI
+title: CLI Tutorial
 ---
 
 ## Introduction
 
 The Aztec CLI is a tool designed to enable a user to interact with the Aztec Network.
 
-This tutorial will use the Aztec Sandbox so you should first set it up by following [the Aztec Sandbox instructions](../sandbox/main.md).
+This tutorial will use the Aztec Sandbox so you should first set it up by following [the Aztec Sandbox instructions](../getting_started/quickstart.md).
 
 ## Requirements
 

docs/docs/dev_docs/cli/main.md

@@ -20,4 +20,4 @@ Once installed it is invoked via:
 
 ## Getting Started
 
-To get up and running with the Aztec CLI head over to the [getting start page](../getting_started/cli.md).
+To get up and running with the Aztec CLI head over to the [getting start page](./cli.md).

docs/docs/dev_docs/contracts/compiling.md

@@ -1,6 +1,6 @@
 # Compiling contracts
 
-Once you have written a [contract](../contracts/main.md) in Aztec.nr, you will need to compile it into an [artifact](./abi.md) in order to use it.
+Once you have written a [contract](../contracts/main.md) in Aztec.nr, you will need to compile it into an [artifact](./artifacts.md) in order to use it.
 
 In this guide we will cover how to do so, both using the CLI and programmatically.
 
@@ -28,7 +28,7 @@ Then run the `compile` command with the path to your [contract project folder](.
 aztec-cli compile ./path/to/my_aztec_contract_project
 ```
 
-This will output a JSON [artifact](./artifacts.md) for each contract in the project to a `target` folder containing their [ABI](./abi.md), which you can use for deploying or interacting with your contracts.
+This will output a JSON [artifact](./artifacts.md) for each contract in the project to a `target` folder containing their ABI, which you can use for deploying or interacting with your contracts.
 
 ### Typescript Interfaces
 
@@ -71,11 +71,11 @@ export class PrivateTokenContract extends ContractBase {
 }
 ```
 
-Read more about interacting with contracts using `aztec.js` [here](../dapps/main.md).
+Read more about interacting with contracts using `aztec.js` [here](../getting_started/sandbox.md).
 
 ### Aztec.nr interfaces
 
-An Aztec.nr contract can [call a function](./functions.md) in another contract via `context.call_private_function` or `context.call_public_function`. However, this requires manually assembling the function selector and manually serialising the arguments, which is not type-safe.
+An Aztec.nr contract can [call a function](./syntax/functions.md) in another contract via `context.call_private_function` or `context.call_public_function`. However, this requires manually assembling the function selector and manually serialising the arguments, which is not type-safe.
 
 To make this easier, the compiler can generate contract interface structs that expose a convenience method for each function listed in a given contract ABI. These structs are intended to be used from another contract project that calls into the current one. For each contract, two interface structs are generated: one to be used from private functions with a `PrivateContext`, and one to be used from open functions with a `PublicContext`.
 
@@ -98,7 +98,7 @@ impl PrivateTokenPrivateContextInterface {
   fn at(address: Field) -> Self {
       Self { address }
   }
-  
+
   fn mint(
     self, context: &mut PrivateContext, amount: Field, owner: Field
   ) -> [Field; RETURN_VALUES_LENGTH] {
@@ -109,7 +109,7 @@ impl PrivateTokenPrivateContextInterface {
     // 0x1dc9c3c0 is the function selector for `mint(field,field)`
     context.call_private_function(self.address, 0x1dc9c3c0, serialised_args)
   }
-  
+
 
   fn transfer(
     self, context: &mut PrivateContext, amount: Field, sender: Field, recipient: Field
@@ -125,7 +125,7 @@ impl PrivateTokenPrivateContextInterface {
 }
 ```
 
-Read more about how to use the Aztec.nr interfaces [here](./functions.md#contract-interface).
+Read more about how to use the Aztec.nr interfaces [here](./syntax/functions.md#contract-interface).
 
 :::info
 At the moment, the compiler generates these interfaces from already compiled ABIs, and not from source code. This means that you should not import a generated interface from within the same project as its source contract, or you risk circular references.
@@ -135,19 +135,17 @@ At the moment, the compiler generates these interfaces from already compiled ABI
 
 You can also programmatically access the compiler via the `@aztec/noir-compiler` package. To do this, install the package into your nodejs project:
 
-`
-npm install @aztec/noir-compiler
-`
+`npm install @aztec/noir-compiler`
 
 The compiler exposes the following functions:
+
 - `compileUsingNargo`: Compiles an Aztec.nr project in the target folder using the `nargo` binary available on the shell `PATH` and returns the generated ABIs.
 - `generateTypescriptContractInterface`: Generates a typescript class for the given contract ABI.
 - `generateNoirContractInterface`: Generates a Aztec.nr interface struct for the given contract ABI.
 
 ## Next steps
 
-Once you have compiled your contracts, you can use the generated artifacts via the `Contract` class in the `aztec.js` package to deploy and interact with them, or rely on the type-safe typescript classes directly. Alternatively, use the CLI [to deploy](../../dev_docs/getting_started/cli.md#deploying-a-token-contract) and [interact](../../dev_docs/getting_started/cli.md#sending-a-transaction) with them.
-
+Once you have compiled your contracts, you can use the generated artifacts via the `Contract` class in the `aztec.js` package to deploy and interact with them, or rely on the type-safe typescript classes directly. Alternatively, use the CLI [to deploy](../../dev_docs/cli/cli.md#deploying-a-token-contract) and [interact](../../dev_docs/cli/cli.md#sending-a-transaction) with them.
 
 import Disclaimer from "../../misc/common/\_disclaimer.mdx";
-<Disclaimer/>
+<Disclaimer/>

docs/docs/dev_docs/contracts/events.md

@@ -1,12 +1,17 @@
-## Events
+---
+title: Events
+---
+
 Events in Aztec work similarly to Ethereum events in the sense that they are a way for contracts to communicate with the outside world.
 They are emitted by contracts and stored inside each instance of an AztecNode.
+
 > Aztec events are currently represented as raw data and are not ABI encoded.
 > ABI encoded events are a feature that will be added in the future.
 
 Unlike on Ethereum, there are 2 types of events supported by Aztec: encrypted and unencrypted.
 
 ### Encrypted Events
+
 Encrypted events can only be emitted by private functions and are encrypted using a public key of a recipient.
 For this reason it is necessary to register a recipient in the Aztec RPC Server before encrypting the events for them.
 Recipients can be registered using the Aztec CLI or Aztec.js:
@@ -25,11 +30,21 @@ aztec-cli register-recipient --address 0x147392a39e593189902458f4303bc6e0a39128c
 <TabItem value="js" label="Aztec.js">
 
 ```ts
-const aztecAddress = AztecAddress.fromString("0x147392a39e593189902458f4303bc6e0a39128c5a1c1612f76527a162d36d529");
-const publicKey = Point.fromString("0x26e193aef4f83c70651485b5526c6d01a36d763223ab24efd1f9ff91b394ac0c20ad99d0ef669dc0dde8d5f5996c63105de8e15c2c87d8260b9e6f02f72af622");
-const partialAddress = Fr.fromString("0x200e9a6c2d2e8352012e51c6637659713d336405c29386c7c4ac56779ab54fa7");
-
-const completeAddress = CompleteAddress.create(aztecAddress, publicKey, partialKey); 
+const aztecAddress = AztecAddress.fromString(
+  "0x147392a39e593189902458f4303bc6e0a39128c5a1c1612f76527a162d36d529"
+);
+const publicKey = Point.fromString(
+  "0x26e193aef4f83c70651485b5526c6d01a36d763223ab24efd1f9ff91b394ac0c20ad99d0ef669dc0dde8d5f5996c63105de8e15c2c87d8260b9e6f02f72af622"
+);
+const partialAddress = Fr.fromString(
+  "0x200e9a6c2d2e8352012e51c6637659713d336405c29386c7c4ac56779ab54fa7"
+);
+
+const completeAddress = CompleteAddress.create(
+  aztecAddress,
+  publicKey,
+  partialKey
+);
 await aztecRpc.registerRecipient(completeAddress);
 ```
 
@@ -50,8 +65,8 @@ Then you can call the function:
 
 #include_code encrypted /yarn-project/aztec-nr/value-note/src/utils.nr rust
 
-
 ### Unencrypted Events
+
 Unencrypted events are events which can be read by anyone.
 They can be emitted by both public and private functions.
 
@@ -96,21 +111,24 @@ All event data is pushed to Ethereum as calldata by the sequencer and for this r
 > There are plans to adopt EIP-4844 blobs to reduce the cost of data submission further.
 
 ## Processing events
+
 Both the encrypted and unencrypted events are stored in AztecNode.
 Unencrypted logs can be queried by anyone as we described above in the [Unencrypted Events](#unencrypted-events) section.
 
 Encrypted logs need to first be decrypted:
 
 ### Decrypting
+
 One function of Aztec RPC Server is constantly loading encrypted logs from AztecNode and trying to decrypt them.
 When new encrypted logs are obtained, the Aztec RPC Server will try to decrypt them using the private encryption key of all the accounts registered inside Aztec RPC Server.
 If the decryption is successful, the Aztec RPC Server will store the decrypted note inside a database.
 If the decryption fails, the specific log will be discarded.
 
 For the Aztec RPC Server to successfully process the decrypted note we need to compute the note's 'note hash' and 'nullifier'.
-Aztec.nr enables smart contract developers to design custom notes, meaning developers can also customise how a note's note hash and nullifier should be computed. Because of this customisability, and because there will be a potentially-unlimited number of smart contracts deployed to Aztec, an Aztec RPR Server needs to be 'taught' how to compute the custom note hashes and nullifiers for a particular contract. Therefore, developers will need to implement a `compute_note_hash_and_nullifier` function inside their contracts.
+Aztec.nr enables smart contract developers to design custom notes, meaning developers can also customise how a note's note hash and nullifier should be computed. Because of this customisability, and because there will be a potentially-unlimited number of smart contracts deployed to Aztec, an Aztec RPC Server needs to be 'taught' how to compute the custom note hashes and nullifiers for a particular contract. Therefore, developers will need to implement a `compute_note_hash_and_nullifier` function inside their contracts.
+
 Every time a new note is successfully decrypted, the Aztec RPC Server will expect the existence of a `compute_note_hash_and_nullifier` function, which must teach it how to correctly process the new note.
 
 This is an example implementation inside the `PrivateTokenContract`:
 
-#include_code compute_note_hash_and_nullifier /yarn-project/noir-contracts/src/contracts/private_token_contract/src/main.nr rust
+#include_code compute_note_hash_and_nullifier /yarn-project/noir-contracts/src/contracts/private_token_contract/src/main.nr rust