feat(docs): Applying structure feedback + adding nodes docs (#10976)

Closes #10527
Closes #10509
Closes #10519
Closes #10516
Closes #10514
Closes #8513
Closes #10505

---------

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

docs/.gitignore

@@ -22,6 +22,6 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-/docs/reference/developer_references/aztecjs
-/docs/reference/developer_references/smart_contract_reference/aztec-nr
+/docs/developers/reference/aztecjs
+/docs/developers/reference/smart_contract_reference/aztec-nr
 test-results

docs/HOW_WE_WRITE_DOCS.md

@@ -1,12 +1,12 @@
 # How we write docs
 
-This doc covers the structure and tone of Aztec developer documentation. For the contribution guidelines, go [here](./CONTRIBUTING.md). Please keep in mind that this is constantly changing.
+This doc covers the structure and tone of Aztec developer documentation. For the contribution guidelines, go [here](./CONTRIBUTING.md). Please keep in mind that this is constantly changing. 
 
 ## Structure
 
 ### High level
 
-Aztec docs are divided into two main sections - `Learn` and `Build`.
+Aztec docs are divided into two main sections - `Learn` and `Build`. 
 
 Anyone technical can read the `Learn` section, whereas only developers who are actively building or starting to build on Aztec will read the `Build` section.
 
@@ -16,7 +16,7 @@ The `Build` section contains information that only developers need to know - thi
 
 ### Types of pages
 
-The Aztec docs roughly follow the [Diataxis](https://diataxis.fr/) framework. It is recommended to read this website before contributing to the docs.
+The Aztec docs roughly follow the [Diataxis](https://diataxis.fr/) framework. It is recommended to read this website before contributing to the docs. 
 
 Every page will fall into **one type of doc**. If your contribution covers multiple types, you will need to split it into multiple pages.
 
@@ -39,8 +39,8 @@ These are docs that developers can consult to know exact and succinct informatio
 ## Tone
 
 * Concise and informative - for example, rather than repeating information, write "to learn more, read ..."
-* Friendly and empathetic - for example, "you do not have to worry about this yet"
-* Simple and jardon-avoidant when possible
+* Friendly and empathetic - for example, "you do not have to worry about this yet" 
+* Simple and jardon-avoidant when possible 
 * Short sentences
 * Unopinionated language - we know things are exciting sometimes, but try not to tell the developer what they should be excited about
 
@@ -85,4 +85,4 @@ The Aztec docs use a sidebar - https://docusaurus.io/docs/sidebar/items
 
 ## Indexing and Search
 
-Typesense docs search - https://typesense.org/
+Algolia docs search - https://docusaurus.io/docs/search#algolia-index-configuration

docs/docs/reference/developer_references/common_errors/_category_.json → docs/docs/aztec/concepts/accounts/_category_.json

@@ -1,6 +1,6 @@
 {
-    "label": "Common Errors",
-    "position": 5,
+    "label": "Accounts",
+    "position": 2,
     "collapsible": true,
     "collapsed": true
 }

docs/docs/aztec/concepts/accounts/index.md

@@ -72,7 +72,7 @@ def entryPoint(payload):
         enqueueCall(to, data, value, gasLimit);
 ```
 
-Read more about how to write an account contract [here](../../../tutorials/codealong/contract_tutorials/write_accounts_contract.md).
+Read more about how to write an account contract [here](../../../developers/tutorials/codealong/contract_tutorials/write_accounts_contract.md).
 
 ### Account contracts and wallets
 
@@ -135,7 +135,7 @@ However, during a public function execution, it is not possible to retrieve a va
 
 These two patterns combined allow an account contract to answer whether an action `is_valid_impl` for a given user both in private and public contexts.
 
-You can read more about authorizing actions with authorization witnesses on [this page](./authwit.md).
+You can read more about authorizing actions with authorization witnesses on [this page](../advanced/authwit.md).
 
 :::info
 
@@ -147,7 +147,7 @@ Transaction simulations in the PXE are not currently simulated, this is future w
 
 Aztec requires users to define [encryption and nullifying keys](./keys.md) that are needed for receiving and spending private notes. Unlike transaction signing, encryption and nullifying is enshrined at the protocol. This means that there is a single scheme used for encryption and nullifying. These keys are derived from a master public key. This master public key, in turn, is used when deterministically deriving the account's address.
 
-A side effect of committing to a master public key as part of the address is that _this key cannot be rotated_. While an account contract implementation could include methods for rotating the signing key, this is unfortunately not possible for encryption and nullifying keys (note that rotating nullifying keys also creates other challenges such as preventing double spends). We are exploring usage of [`SharedMutable`](../../../reference/developer_references/smart_contract_reference/storage/shared_state.md#sharedmutable) to enable rotating these keys.
+A side effect of committing to a master public key as part of the address is that _this key cannot be rotated_. While an account contract implementation could include methods for rotating the signing key, this is unfortunately not possible for encryption and nullifying keys (note that rotating nullifying keys also creates other challenges such as preventing double spends). We are exploring usage of [`SharedMutable`](../../../developers/reference/smart_contract_reference/storage/shared_state.md) to enable rotating these keys.
 
 NOTE: While we entertained the idea of abstracting note encryption, where account contracts would define an `encrypt` method that would use a user-defined scheme, there are two main reasons we decided against this. First is that this entailed that, in order to receive funds, a user had to first deploy their account contract, which is a major UX issue. Second, users could define malicious `encrypt` methods that failed in certain circumstances, breaking application flows that required them to receive a private note. While this issue already exists in Ethereum when transferring ETH (see the [king of the hill](https://coinsbench.com/27-king-ethernaut-da5021cd4aa6)), its impact is made worse in Aztec since any execution failure in a private function makes the entire transaction unprovable (ie it is not possible to catch errors in calls to other private functions), and furthermore because encryption is required for any private state (not just for transferring ETH). Nevertheless, both of these problems are solvable. Initialization can be worked around by embedding a commitment to the bytecode in the address and removing the need for actually deploying contracts before interacting with them, and the king of the hill issue can be mitigated by introducing a full private VM that allows catching reverts. As such, we may be able to abstract encryption in the future as well.
 

docs/docs/aztec/concepts/accounts/keys.md

@@ -54,7 +54,7 @@ When it comes to notes encryption and decryption:
 
 ### Signing keys
 
-Thanks to the native [account abstraction](../accounts#background/index.md), authorization logic can be implemented in an alternative way that is up to the developer (e.g. using Google authorization credentials, vanilla password logic or Face ID mechanism). In these cases, signing keys may not be relevant.
+Thanks to the native [account abstraction](../accounts/index.md), authorization logic can be implemented in an alternative way that is up to the developer (e.g. using Google authorization credentials, vanilla password logic or Face ID mechanism). In these cases, signing keys may not be relevant.
 
 However if one wants to implement authorization logic containing signatures (e.g. ECDSA or Shnorr) they will need signing keys. Usually, an account contract will validate a signature of the incoming payload against a known signing public key.
 
@@ -85,7 +85,7 @@ When it comes to storing the signing key in a private note, there are several de
 
 #### Using Shared Mutable state
 
-By [Shared Mutable](../../../reference/developer_references/smart_contract_reference/storage/shared_state#sharedmutable) we mean privately readable publicly mutable state.
+By [Shared Mutable](../../../developers/reference/smart_contract_reference/storage/shared_state.md#sharedmutable) we mean privately readable publicly mutable state.
 
 To make public state accessible privately, there is a delay window in public state updates. One needs this window to be able to generate proofs client-side. This approach would not generate additional nullifiers and commitments for each transaction while allowing the user to rotate their key. However, this causes every transaction to now have a time-to-live determined by the frequency of the mutable shared state, as well as imposing restrictions on how fast keys can be rotated due to minimum delays.
 
@@ -123,7 +123,7 @@ App-siloed keys allow to minimize damage of potential key leaks as a leak of the
 
 App-siloed keys are derived from the corresponding master keys and the contract address. For example, for the app-siloed nullifier secret key: `nsk_app = hash(nsk_m, app_contract_address)`.
 
-App-siloed keys [are derived](../storage/storage_slots#implementation/index.md) in PXE every time the user interacts with the application.
+App-siloed keys [are derived](../advanced/storage/storage_slots.md#implementation) in PXE every time the user interacts with the application.
 
 App-siloed incoming viewing key also allows per-application auditability. A user may choose to disclose this key for a given application to an auditor or regulator (or for 3rd party interfaces, e.g. giving access to a block explorer to display my activity), as a means to reveal all their activity within that context, while retaining privacy across all other applications in the network.
 

docs/docs/aztec/concepts/accounts/authwit.md → docs/docs/aztec/concepts/advanced/authwit.md

@@ -1,7 +1,7 @@
 ---
 title: Authentication Witness (Authwit)
 tags: [accounts, authwit]
-importance: 1
+sidebar_position: 2
 keywords: [authwit, authentication witness, accounts]
 ---
 
@@ -42,9 +42,9 @@ All of these issues have been discussed in the community for a while, and there
 
 Adopting ERC20 for Aztec is not as simple as it might seem because of private state.
 
-If you recall from the [Hybrid State model](../storage/state_model/index.md), private state is generally only known by its owner and those they have shared it with. Because it relies on secrets, private state might be "owned" by a contract, but it needs someone with knowledge of these secrets to actually spend it. You might see where this is going.
+If you recall from the [Hybrid State model](../storage/state_model.md), private state is generally only known by its owner and those they have shared it with. Because it relies on secrets, private state might be "owned" by a contract, but it needs someone with knowledge of these secrets to actually spend it. You might see where this is going.
 
-If we were to implement the `approve` with an allowance in private, you might know the allowance, but unless you also know about the individual notes that make up the user's balances, it would be of no use to you! It is private after all. To spend the user's funds you would need to know the decryption key, see [keys for more](./keys.md).
+If we were to implement the `approve` with an allowance in private, you might know the allowance, but unless you also know about the individual notes that make up the user's balances, it would be of no use to you! It is private after all. To spend the user's funds you would need to know the decryption key, see [keys for more](../accounts/keys.md).
 
 While this might sound limiting in what we can actually do, the main use of approvals have been for simplifying contract interactions that the user is doing. In the case of private transactions, this is executed on the user device, so it is not a blocker that the user need to tell the executor a secret - the user is the executor!
 
@@ -140,4 +140,4 @@ We don't need to limit ourselves to the `transfer` function, we can use the same
 
 ### Next Steps
 
-Check out the [developer documentation](../../../guides/developer_guides/smart_contracts/writing_contracts/authwit.md) to see how to implement this in your own contracts.
+Check out the [developer documentation](../../../developers/guides/smart_contracts/writing_contracts/authwit.md) to see how to implement this in your own contracts.

docs/docs/aztec/concepts/advanced/circuits/_category_.json

@@ -0,0 +1,6 @@
+{
+    "label": "Circuits",
+    "position": 3,
+    "collapsible": true,
+    "collapsed": true
+}

docs/docs/aztec/concepts/circuits/index.md → docs/docs/aztec/concepts/advanced/circuits/index.md

@@ -1,6 +1,6 @@
 ---
 title: Circuits
-sidebar_position: 7
+sidebar_position: 2
 tags: [protocol, circuits]
 ---
 
@@ -53,7 +53,7 @@ In other words, since neither the EVM nor other rollups have rules for how to pr
 
 What kind of extra rules / checks does a rollup need, to enforce notions of private states and private functions? Stuff like:
 
-- "Perform state reads and writes using new tree structures which prevent tx linkability" (see [trees](../storage/trees/index.md)).
+- "Perform state reads and writes using new tree structures which prevent tx linkability" (see [indexed merkle tree](../storage/indexed_merkle_tree.mdx).
 - "Hide which function was just executed, by wrapping it in a zk-snark"
 - "Hide all functions which were executed as part of this tx's stack trace, by wrapping the whole tx in a zk-snark"
 

docs/docs/tutorials/examples/_category_.json → docs/docs/aztec/concepts/advanced/circuits/kernels/_category_.json

@@ -1,5 +1,5 @@
 {
-    "label": "Smart Contract Examples",
+    "label": "Kernel Circuits",
     "position": 0,
     "collapsible": true,
     "collapsed": true

docs/docs/aztec/concepts/advanced/circuits/kernels/public_kernel.md

@@ -0,0 +1,6 @@
+---
+title: Public Kernel Circuit
+tags: [protocol, circuits]
+---
+
+This circuit is executed by a Sequencer, since only a Sequencer knows the current state of the [public data tree](../../../storage/state_model.md#public-state) at any time. A Sequencer might choose to delegate proof generation to the Prover pool.

docs/docs/aztec/concepts/advanced/index.md

@@ -0,0 +1,12 @@
+---
+title: Advanced Concepts
+sidebar_position: 7
+tags: [protocol]
+---
+
+In this section, you'll learn about the more advanced concepts of the Aztec Network. It is not required to understand these in order to start building on Aztec. 
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
+

docs/docs/aztec/_category_.json → docs/docs/aztec/concepts/advanced/storage/_category_.json

@@ -1,5 +1,5 @@
 {
-    "label": "Aztec",
+    "label": "Advanced Storage Concepts",
     "position": 1,
     "collapsible": true,
     "collapsed": true

docs/docs/aztec/concepts/storage/trees/indexed_merkle_tree.mdx → docs/docs/aztec/concepts/advanced/storage/indexed_merkle_tree.mdx

@@ -1,5 +1,7 @@
 ---
-title: Indexed Merkle Tree
+title: Indexed Merkle Tree (Nullifier Tree)
+tags: [storage, concepts, advanced]
+sidebar_position: 2
 ---
 
 import Image from "@theme/IdealImage";
@@ -48,7 +50,7 @@ Data is stored at the leaf index corresponding to its value. E.g. if I have a sp
 
 ## Problems introduced by using Sparse Merkle Trees for Nullifier Trees
 
-While sparse Merkle Trees offer a simple and elegant solution, their implementation comes with some drawbacks. A sparse nullifier tree must have an index for $e \in \mathbb{F}_p$, which for the bn254 curve means that the sparse tree will need to have a depth of 254.  
+While sparse Merkle Trees offer a simple and elegant solution, their implementation comes with some drawbacks. A sparse nullifier tree must have an index for $e \in \mathbb{F}_p$, which for the bn254 curve means that the sparse tree will need to have a depth of 254.
 If you're familiar with hashing in circuits the alarm bells have probably started ringing. A tree of depth 254 means 254 hashes per membership proof.
 In routine nullifier insertions, a non membership check for a value is performed, then an insertion of said value. This amounts to two trips from leaf to root, hashing all the way up. This means that there are $254*2$ hashes per tree insertion. As the tree is sparse, insertions are random and must be performed in sequence. This means the number of hashes performed in the circuit scales linearly with the number of nullifiers being inserted. As a consequence number of constraints in a rollup circuit (where these checks are performed) will sky rocket, leading to long rollup proving times.
 

docs/docs/aztec/concepts/storage/partial_notes.md → docs/docs/aztec/concepts/advanced/storage/partial_notes.md

@@ -2,6 +2,7 @@
 title: Partial Notes
 description: Describes how partial notes are used in Aztec
 tags: [notes, storage]
+sidebar_position: 3
 ---
 
 Partial notes are a concept that allows users to commit to an encrypted value, and allows a counterparty to update that value without knowing the specific details of the encrypted value.
@@ -138,7 +139,7 @@ This is implemented by applying the `partial_note` attribute:
 
 #include_code UintNote noir-projects/aztec-nr/uint-note/src/uint_note.nr rust
 
-Those `G_x` are generators that generated [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/generators.nr). Anyone can use them for separating different fields in a "partial note".
+Those `G_x` are generators that generated [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-projects/aztec-nr/aztec/src/generators.nr). Anyone can use them for separating different fields in a "partial note".
 
 We can see the complete implementation of creating and completing partial notes in an Aztec contract in the `setup_refund` and `complete_refund` functions.