AztecProtocol · catmcgee · Aug 8, 2024 · Aug 7, 2024 · Aug 7, 2024 · Aug 7, 2024
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -22,6 +22,6 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-docs/reference/aztecjs
-docs/reference/smart_contract_reference/aztec-nr
+/docs/reference/developer_references/aztecjs
+/docs/reference/developer_references/smart_contract_reference/aztec-nr
 test-results
diff --git a/docs/docs/aztec.md b/docs/docs/aztec.md
@@ -1,5 +1,5 @@
 ---
-title: Programmable Privacy
+title: Building in Public
 sidebar_position: 0
 ---
 
@@ -22,7 +22,7 @@ Aztec is inspired on Ethereum. We believe in transparency for the protocol, but
 
 To allow for this, we focus on two main components:
 
-- **Noir** - We started developing Noir long before Aztec came into being. As an easy, open-source domain specific programming language for writing zero-knowledge circuits, it became the perfect language for writing [Aztec Smart Contracts](aztec/concepts/smart_contracts/index.md). Read about standalone Noir in the [Noir Lang Documentation](https://noir-lang.org).
+- **Noir** - We started developing Noir long before Aztec came into being. As an easy, open-source domain specific programming language for writing zero-knowledge circuits, it became the perfect language for writing [Aztec Smart Contracts](aztec/smart_contracts_overview.md). Read about standalone Noir in the [Noir Lang Documentation](https://noir-lang.org).
 - **Honk** - A collection of cutting-edge cryptography, from proving systems, to compilers, and other sidecars. These will support Aztec's rollup and allow for fast, private, client-side proving.
 
 ## Media

diff --git a/docs/docs/aztec/concepts/_category_.json b/docs/docs/aztec/concepts/_category_.json
@@ -0,0 +1,6 @@
+{
+    "label": "Concepts",
+    "position": 1,
+    "collapsible": true,
+    "collapsed": true
+}
diff --git a/docs/docs/aztec/concepts/accounts/authwit.md b/docs/docs/aztec/concepts/accounts/authwit.md
@@ -1,5 +1,6 @@
 ---
 title: Authentication Witness
+tags: [accounts, authwit]
 ---
 
 Authentication Witness is a scheme for authenticating actions on Aztec, so users can allow third-parties (eg protocols or other users) to execute an action on their behalf.
@@ -56,7 +57,7 @@ Adopting ERC20 for Aztec is not as simple as it might seem because of private st
 
 If you recall from the [Hybrid State model](../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 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](./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!
 ### So what can we do?
@@ -183,7 +184,7 @@ For the transfer, this could be done simply by appending a nonce to the argument
 action = H(defi, token, transfer_selector, H(alice_account, defi, 1000, nonce));
 ```
 
-Beware that the account contract will be unable to emit the nullifier since it is checked with a static call, so the calling contract must do it. This is similar to nonces in ERC20 tokens today. We provide a small library that handles this which we will see in the [developer documentation](../../../guides/smart_contracts/writing_contracts/authwit.md).
+Beware that the account contract will be unable to emit the nullifier since it is checked with a static call, so the calling contract must do it. This is similar to nonces in ERC20 tokens today. We provide a small library that handles this.
 
 ### Differences to approval
 
@@ -197,4 +198,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/smart_contracts/writing_contracts/authwit.md) to see how to implement this in your own contracts.
+Check out the [developer documentation](../../../guides/developer_guides/smart_contracts/writing_contracts/authwit.md) to see how to implement this in your own contracts.
diff --git a/docs/docs/aztec/concepts/accounts/index.md b/docs/docs/aztec/concepts/accounts/index.md
@@ -1,6 +1,6 @@
 ---
 title: Accounts
-sidebar_position: 0
+sidebar_position: 1
 tags: [accounts]
 ---
 
@@ -72,7 +72,7 @@ def entryPoint(payload):
         enqueueCall(to, data, value, gasLimit);
 ```
 
-Read more about how to write an account contract [here](../../../tutorials/contract_tutorials/write_accounts_contract.md).
+Read more about how to write an account contract [here](../../../tutorials/codealong/contract_tutorials/write_accounts_contract.md).
 
 ### Account contracts and wallets
 
@@ -135,7 +135,7 @@ These two patterns combined allow an account contract to answer whether an actio
 
 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/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`](../../../reference/developer_references/smart_contract_reference/storage/shared_state.md#sharedmutable) 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.
 

diff --git a/docs/docs/aztec/concepts/accounts/keys.md b/docs/docs/aztec/concepts/accounts/keys.md
@@ -1,16 +1,20 @@
-# Keys
+---
+title: Keys
+tags: [accounts, keys]
+---
+
 The goal of this section is to give app developer a good idea what keys there are used in the system.
-For a detailed description head over to the [protocol specification](../../../protocol-specs/addresses-and-keys/keys#cheat-sheet).
+For a detailed description head over to the [protocol specification](../../../protocol-specs/addresses-and-keys/index.md).
 
 Each account in Aztec is backed by 4 key pairs:
 
 - A **nullifier key pair** used for note nullifier computation, comprising the master nullifier secret key (`nsk_m`) and master nullifier public key (`Npk_m`).
 - A **incoming viewing key pair** used to encrypt a note for the recipient, consisting of the master incoming viewing secret key (`ivsk_m`) and master incoming viewing public key (`Ivpk_m`).
 - A **outgoing viewing key pair** used to encrypt a note for the sender, includes the master outgoing viewing secret key (`ovsk_m`) and master outgoing viewing public key (`Ovpk_m`).
-- A **tagging key pair** used to compute tags in a [tagging note discovery scheme](../../../protocol-specs/private-message-delivery/private-msg-delivery#note-tagging), comprising the master tagging secret key (`tsk_m`) and master tagging public key (`Tpk_m`).
+- A **tagging key pair** used to compute tags in a [tagging note discovery scheme](../../../protocol-specs/private-message-delivery/private-msg-delivery.md#note-tagging), comprising the master tagging secret key (`tsk_m`) and master tagging public key (`Tpk_m`).
 
 :::info
-All key pairs above are derived from a secret using a ZCash inspired scheme defined in [protocol specification](../../../protocol-specs/addresses-and-keys/keys#cheat-sheet).
+All key pairs above are derived from a secret using a ZCash inspired scheme defined in [protocol specification](../../../protocol-specs/addresses-and-keys/keys.md#cheat-sheet).
 :::
 
 :::note
@@ -40,7 +44,7 @@ Below are some ways how we could instantiate it after getting the information in
 
 #include_code instantiate-complete-address /yarn-project/circuits.js/src/structs/complete_address.test.ts rust
 
-Then to register the recipient's [complete address](#complete-address) in PXE we would call `registerRecipient` PXE endpoint using [Aztec.js](../../core_components.md#aztecjs):
+Then to register the recipient's [complete address](#complete-address) in PXE we would call `registerRecipient` PXE endpoint using Aztec.js.
 
 #include_code register-recipient /yarn-project/aztec.js/src/wallet/create_recipient.ts rust
 
@@ -116,7 +120,7 @@ This is a snippet of our Schnorr Account contract implementation, which uses Sch
 
 #include_code entrypoint /noir-projects/noir-contracts/contracts/schnorr_account_contract/src/main.nr rust
 
-Still, different accounts may use different signing schemes, may require multi-factor authentication, or _may not even use signing keys_ and instead rely on other authentication mechanisms. Read [how to write an account contract](../../../tutorials/contract_tutorials/write_accounts_contract.md) for a full example of how to manage authentication.
+Still, different accounts may use different signing schemes, may require multi-factor authentication, or _may not even use signing keys_ and instead rely on other authentication mechanisms. Read [how to write an account contract](../../../tutorials/codealong/contract_tutorials/write_accounts_contract.md) for a full example of how to manage authentication.
 
 Furthermore, and since signatures are fully abstracted, how the key is stored in the contract is abstracted as well and left to the developer of the account contract.
 In the following section we describe a few ways how an account contract could be architected to store signing keys.
@@ -133,7 +137,7 @@ Similar to using a private note, but using an immutable private note removes the
 
 #### Using shared state
 
-A compromise between the two solutions above is to use [shared state](../../../reference/smart_contract_reference/storage/shared_state.md). This 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.
+A compromise between the two solutions above is to use shared state. This 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.
 
 #### Reusing some of the in-protocol keys
 

diff --git a/docs/docs/aztec/concepts/circuits/index.md b/docs/docs/aztec/concepts/circuits/index.md
@@ -1,6 +1,7 @@
 ---
 title: Circuits
 sidebar_position: 7
+tags: [protocol, circuits]
 ---
 
 Central to Aztec's operations are 'circuits' derived both from the core protocol and the developer-written Aztec.nr contracts.
@@ -62,11 +63,11 @@ So what kinds of core protocol circuits does Aztec have?
 
 ### Kernel Circuits
 
-Read more about the Kernel circuits in the protocol specs [here](../../../protocol-specs/circuits/high-level-topology).
+Read more about the Kernel circuits in the protocol specs [here](../../../protocol-specs/circuits/high-level-topology.md).
 
 ### Rollup Circuits
 
-- [Rollup Circuits](../../../protocol-specs/rollup-circuits)
+- [Rollup Circuits](../../../protocol-specs/rollup-circuits/index.md)
 
 #### Squisher Circuits
 

diff --git a/docs/docs/aztec/concepts/circuits/kernels/private_kernel.md b/docs/docs/aztec/concepts/circuits/kernels/private_kernel.md
@@ -1,10 +1,11 @@
 ---
 title: Private Kernel Circuit
+tags: [protocol, circuits]
 ---
 
 This circuit is executed by the user, on their own device. This is to ensure private inputs to the circuit remain private!
 
-Read the latest information about the Aztec Private Kernel Circuit in the [protocol specs section](../../../../protocol-specs/circuits/private-kernel-initial).
+Read the latest information about the Aztec Private Kernel Circuit in the [protocol specs section](../../../../protocol-specs/circuits/private-kernel-tail.md).
 
 :::note
 

diff --git a/docs/docs/aztec/concepts/circuits/kernels/public_kernel.md b/docs/docs/aztec/concepts/circuits/kernels/public_kernel.md
@@ -1,7 +1,8 @@
 ---
 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/trees/index.md#public-state-tree) at any time. A Sequencer might choose to delegate proof generation to the Prover pool.
+This circuit is executed by a Sequencer, since only a Sequencer knows the current state of the [public data tree](../../storage/trees/index.md) at any time. A Sequencer might choose to delegate proof generation to the Prover pool.
 
-Read more about the public kernel circuits in the protocol specs [here](../../../../protocol-specs/circuits/private-kernel-tail).
+Read more about the public kernel circuits in the protocol specs [here](../../../../protocol-specs/circuits/public-kernel-initial.md).
diff --git a/docs/docs/aztec/concepts/circuits/rollup_circuits/index.md b/docs/docs/aztec/concepts/circuits/rollup_circuits/index.md
@@ -1,5 +1,6 @@
 ---
 title: Rollup Circuits
+tags: [protocol, circuits]
 ---
 
 The primary purpose of the Rollup Circuits is to 'squish' all of the many thousands of transactions in a rollup into a single SNARK, which can then be efficiently and verified on Ethereum.
@@ -15,4 +16,4 @@ The way we 'squish' all this data is in a 'binary tree of proofs' topology.
 
 Some of the Rollup Circuits also do some protocol checks and computations, for efficiency reasons. We might rearrange which circuit does what computation, as we discover opportunities for efficiency.
 
-Read more about the rollup circuits in the protocol spec [here](../../../../protocol-specs/rollup-circuits).
+Read more about the rollup circuits in the protocol spec [here](../../../../protocol-specs/rollup-circuits/index.md).
diff --git a/docs/docs/aztec/concepts/pxe/acir_simulator.md b/docs/docs/aztec/concepts/pxe/acir_simulator.md
@@ -14,13 +14,13 @@ It simulates three types of functions:
 
 Private functions are simulated and proved client-side, and verified client-side in the private kernel circuit.
 
-They are run with the assistance of a DB oracle that provides any private data requested by the function. You can read more about oracle functions in the smart contract section [here](../smart_contracts/oracles/index.md).
+They are run with the assistance of a DB oracle that provides any private data requested by the function. You can read more about oracle functions in the smart contract section [here](../../smart_contracts/oracles/index.md).
 
 Private functions can call other private functions and can request to call a public function. The public function execution will be performed by the sequencer asynchronously, so private functions don't have direct access to the return values of public functions.
 
 ### Public Functions
 
-Public functions are simulated and proved on the [sequencer](../nodes_clients/sequencer) side, and verified by the [public kernel circuit](../circuits/kernels/public_kernel.md).
+Public functions are simulated and proved on the [sequencer](../../network/sequencer/index.md) side, and verified by the [public kernel circuit](../../concepts/circuits/kernels/public_kernel.md).
 
 They are run with the assistance of an oracle that provides any value read from the public state tree.
 

diff --git a/docs/docs/aztec/concepts/pxe/index.md b/docs/docs/aztec/concepts/pxe/index.md
@@ -1,6 +1,7 @@
 ---
 title: Private Execution Environment (PXE)
 sidebar_position: 6
+tags: [PXE]
 ---
 
 The Private Execution Environment (or PXE, pronounced 'pixie') is a client-side library for the execution of private operations. It is a TypeScript library and can be run within Node, such as when you run the sandbox. In the future it could be run inside wallet software or a browser.
@@ -63,11 +64,11 @@ The keystore is a secure storage for private and public keys.
 
 ## Oracles
 
-Oracles are pieces of data that are injected into a smart contract function from the client side. You can read more about why and how they work in the [functions section](../smart_contracts/oracles/index.md).
+Oracles are pieces of data that are injected into a smart contract function from the client side. You can read more about why and how they work in the [smart contracts section](../../smart_contracts/oracles/index.md).
 
 ## For developers
 
 To learn how to develop on top of the PXE, refer to these guides:
 
-- [Run more than one PXE on your local machine](../../../guides/local_env/run_more_than_one_pxe_sandbox.md)
-- [Use in-built oracles including oracles for arbitrary data](guides/smart_contracts/writing_contracts/how_to_pop_capsules.md)
+- [Run more than one PXE on your local machine](../../../guides/developer_guides/local_env/run_more_than_one_pxe_sandbox.md)
+- [Use in-built oracles including oracles for arbitrary data](../../../guides/developer_guides/smart_contracts/writing_contracts/how_to_pop_capsules.md)
diff --git a/docs/docs/aztec/concepts/smart_contracts/contract_creation.md b/docs/docs/aztec/concepts/smart_contracts/contract_creation.md
diff --git a/docs/docs/aztec/concepts/state_model/index.md b/docs/docs/aztec/concepts/state_model/index.md
@@ -1,6 +1,7 @@
 ---
 title: State Model
 sidebar_position: 4
+tags: [state]
 ---
 
 Aztec has a hybrid public/private state model. Aztec contract developers can specify which data is public and which data is private, as well as the functions that can operate on that data.

diff --git a/docs/docs/aztec/concepts/state_model/public_vm.md b/docs/docs/aztec/concepts/state_model/public_vm.md
@@ -2,4 +2,4 @@
 title: Public VM
 ---
 
-Refer to the [protocol specs section](../../../protocol-specs/public-vm/intro.md) for the latest information about the Aztec Public VM.
+Refer to the [protocol specs section](../../../protocol-specs/public-vm/index.md) for the latest information about the Aztec Public VM.