feat: Incorporate docs feedback and add "intermediate" level intros t…

…o some pages (#2598)

Learning to build on Aztec requires learning a lot of new info. Many of
our current docs pages are walls of text the go quite deep into the
specific details of the protocol.

Create an "intermediate" level section at the top of the following docs
pages to make the information easier to parse and more digestible.

This PR also includes feedback on overall docs structure and general
editing.

Closes issue #2561 

# 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: Cat McGee <helloworld@mcgee.cat>

docs/docs/about_aztec/history/history.mdx

@@ -9,74 +9,87 @@ import Image from "@theme/IdealImage";
 <Image img={require("/img/comparison.png")} />
 
 ---
+
 ## Bitcoin
 
 The original blockchain.
 
-**Programmability**:  
-- None.  
+**Programmability**:
+
+- None.
 - Transfer bitcoin only.
 
-**Privacy**:  
+**Privacy**:
+
 - None.
 
 ---
 
 ## Ethereum
 
-**Programmability**:  
+**Programmability**:
+
 - Turing complete smart contracts.
 
-**Privacy**:  
-- Originally: None.  
-- Now: 
+**Privacy**:
+
+- Originally: None.
+- Now:
   - some specific apps on L1
   - some specific apps, deployed via L2, like zk.money and Aztec Connect.
 
 ---
 
 ## ZCash
 
-**Programmability**:  
-- None.  
+**Programmability**:
+
+- None.
 - Transfer ZCash only.
 
-**Privacy**:  
+**Privacy**:
+
 - Transfers of shielded zcash are private.
 
 ---
 
 ## zk.money
 
-**Programmability**:  
+**Programmability**:
+
 - Any custom ERC20 token (on Ethereum L1) can be deposited to L2, transferred within L2, and withdrawn from L2.
 
-**Privacy**:  
+**Privacy**:
+
 - Transfers of the ERC20 tokens within the L2 are private.
 
 ---
 
 ## Aztec Connect
 
-**Programmability**:  
-- The functionality of zk.money, plus:  
-- Tokens can be sent from the L2 shielded pool to many L1 defi contracts, and the resulting tokens can be re-shielded. This gives privacy to L1 defi users.
+**Programmability**:
+
+- The functionality of zk.money, plus:
+- Tokens can be sent from the L2 shielded pool to many L1 DeFi contracts, and the resulting tokens can be re-shielded. This gives anonymity to L1 DeFi users.
 
-**Privacy**:  
-- Transfers of the ERC20 tokens within the L2 are private.  
-- User defi interactions are private.
+**Privacy**:
+
+- Transfers of the ERC20 tokens within the L2 are private.
+- User DeFi interactions are anonymous.
 
 ---
 
 ## Aztec
 
-**Programmability**:  
+**Programmability**:
+
 - Fully programmable private smart contracts:
-  - private functions which can edit general private state
-  - cheap L2 public functions
+  - Private functions which can edit general private state
+  - Cheap L2 public functions
   - L1 (public) functions.
 
-**Privacy**:  
+**Privacy**:
+
 - Executing private functions grants:
   - Function privacy
   - Input privacy

docs/docs/about_aztec/overview.mdx

@@ -4,21 +4,21 @@ title: Overview
 
 import ReactPlayer from "react-player/youtube";
 
-The next version of our rollup, Aztec, is a privacy-preserving, programmable extension to Ethereum. It is a layer 2 zk-rollup on Ethereum that enables programable privacy via composable smart contracts.
+Aztec is an L2 that brings programmable privacy to Ethereum.
 
 ## Private Smart Contracts on Aztec
 
 A smart contract on Aztec is a collection of functions, written as ZK-SNARK circuits. These circuits can have different modes of execution:
 
-1. Secret Functions -- can read and write private state, read historic public state, consume or send messages to / from L1, and read Ethereum state. Can call other secret functions in the same contract, or other contracts. They can call public functions.
-2. Public Functions -- can read and write public state, write private state, consume or send messages to / from L1 and read Ethereum state. Can call other public functions on the same or other contracts.
-3. Portal Contracts -- these are contracts on L1 that can receive messages from L2 or allow messages to be sent to L2 from L1 contracts.
+1. Secret Functions -- can read and write private state, read historic public state, consume or send messages to / from Ethereum, and read Ethereum state. They can call other secret functions in the same contract, or other contracts, and can call public functions.
+2. Public Functions -- can read and write public state, write private state, consume or send messages to / from Ethereum and read Ethereum state. They can call other public functions on the same or other contracts.
+3. Portal Contracts -- these are contracts on Ethereum that can receive messages from Aztec or send messages to Aztec from Ethereum contracts.
 
 Using these different modes of execution, developers can build applications with user privacy, data privacy and code privacy.
 
 User privacy -- transactions may not reveal information about the sender or the recipient.
 
-Data privacy -- transactions may not reveal information about the payload of the transaction, e.g the asset or value being transacted.
+Data privacy -- transactions may not reveal information about the payload of the transaction, e.g., the asset or value being transacted.
 
 Code privacy -- transactions may not reveal the program logic.
 
@@ -50,7 +50,7 @@ Contributors to Aztec uphold many of the values of the Ethereum community -- bui
 
 ## Noir
 
-Noir is a domain specific programming language for writing zero knowledge circuits. On Aztec a smart contract is a collection of circuits that developers write using Noir.
+Noir is a domain specific programming language for writing zero-knowledge circuits. On Aztec a smart contract is a collection of circuits that developers write using Noir.
 
 You can find more information and resources for learning about Noir smart contracts on [this page](../dev_docs/contracts/main.md).
 

docs/docs/about_aztec/roadmap/cryptography_roadmap.md

@@ -2,26 +2,23 @@
 title: Cryptography Roadmap
 ---
 
-The cryptography team is currently working on [Barretenberg here](https://github.com/AztecProtocol/aztec-packages/tree/master/barretenberg)
+The cryptography team is currently working on [Barretenberg here.](https://github.com/AztecProtocol/aztec-packages/tree/master/barretenberg)
 
 ## R&D projects
 
-- Publish the Honk paper, describing practical considerations for constructing our cutting-edge proving system Honk along with formal proofs of its security properties.
+Publish the Honk paper, describing practical considerations for constructing our cutting-edge proving system Honk along with formal proofs of its security properties.
 
 ## Honk
 
-- Honk is a sumcheck-based zk-SNARK protocol with blazing-fast zk proof construction. We need Honk to allow users to prove correct execution of complicated, multi-step computations using recursion in a resource constraint environment like a cell phone. This is necessary for our mission, because we need to make sure our users' sensitive information never leaves their devices!
-- List of Honk projects
-  - Completed: basic Honk prover and verifier with respectable construction and verification speeds, but no optimization.
-  - Upcoming:
-    - Bringing "Ultra" functionality to Honk: lookup tables, efficient range constraints, RAM, ROM, and more will result in orders-of-magnitude improvements to Honk's prover times.
-    - Recursion using cycles of curves will allow for efficient recursive verification of Honk proofs. Using this technique will lower the barrier to entry of our rollup providers, resulting in a more robust set of providers and greater security for the Aztec network.
+Honk is a sumcheck-based zk-SNARK protocol with blazing-fast zk proof construction. We need Honk to allow users to prove correct execution of complicated, multi-step computations using recursion in a resource constraint environment like a cell phone. This is necessary for our mission, because we need to make sure our users' sensitive information never leaves their devices!
 
-## Goblin projects
+List of Honk projects:
 
-- Goblin is a deferred verification framework thats allow for an order-of-magnitude increase in the complexity of computations that Aztec users can execute with full privacy. This corresponds to a 10x increase in the expressivity of Noir programs that can be run in practice without melting anybody's favorite phone or laptop.
+- Completed: basic Honk prover and verifier with respectable construction and verification speeds, but no optimization.
+- Upcoming:
+  - Bringing "Ultra" functionality to Honk: lookup tables, efficient range constraints, RAM, ROM, and more will result in orders-of-magnitude improvements to Honk's prover times.
+  - Recursion using cycles of curves will allow for efficient recursive verification of Honk proofs. Using this technique will lower the barrier to entry of our rollup providers, resulting in a more robust set of providers and greater security for the Aztec network.
 
-Read more here. https://hackmd.io/@aztec-network/B19AA8812
+## Goblin projects
 
-- List of Goblin projects
-  - Aside from some prototype code by Zac, we have not begun working on this yet.
+Goblin is a deferred verification framework thats allow for an order-of-magnitude increase in the complexity of computations that Aztec users can execute with full privacy. This corresponds to a 10x increase in the expressivity of Noir programs that can be run in practice without melting anybody's favorite phone or laptop. Read more [here](https://hackmd.io/@aztec-network/B19AA8812).

docs/docs/about_aztec/roadmap/features_initial_ldt.md

@@ -1,87 +1,16 @@
 ---
-title: Initial Sandbox Features
+title: 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.
+The Aztec Sandbox is intended to provide developers with a lightweight and fast local node.
 
 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.
-
-## Aztec.nr Contracts
-
-See the source on Github [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/aztec-nr).
-
-- Noir `contract` scopes.
-  - Declare a `contract`, containing a collection of state variables and functions.
-- private state variables:
-  - `read`, `write`, and `delete` private state variables within private functions.
-- public (non-private) state variables:
-  - Manipulate 'public' state in a familiar way to Ethereum state.
-- private functions
-  - May read and modify private state.
-- public functions
-  - May read and modify public state.
-- `constructor` functions, for initialising contract state.
-- `import` other Aztec.nr contracts, so their functions may be called.
-- Nested function calls, for contract composability
-  - private functions can call private functions of other contracts, and receive return values.
-  - private functions can call public functions any contract.
-  - public functions can call private functions of any contract.
-  - public functions can call public functions of other contracts, and receive return values.
-  - private functions can be called recursively.
-  - public functions can be called recursively.
-- Send messages from Aztec.nr contracts to Ethereum L1, for consumption by L1 smart contracts.
-  - Useful, for example, if writing an app to withdraw funds from L2 to L1.
-- Consume messages which have been sent by:
-  - L1 functions.
-    - Useful, for example, if writing an app to deposit funds from L1 to L2.
-  - public L2 functions.
-- Emit `event` data from a Aztec.nr Contract.
-  - Allows applications to subscribe to events which have been emitted by a Aztec.nr contract's functions, for example.
-- Write `unconstrained` functions.
-  - These allow developers to write `pure` and `view` functions, which can perform calculations and retrieve state. E.g. for fetching contract-specific information, which may then be consumed by a dapp, without having to generate a zero-knowledge proof or interact with the 'network'.
-
-## `aztec.js`
-
-A typescript wrapper for making RPC calls to an Aztec Sandbox node. See the source on Github [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/aztec.js).
-
-- 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.
-- Construct `Contract` instances from a Aztec.nr contract's JSON artifact.
-- Deploy new contracts to the Aztec Sandbox.
-- Construct tx requests, passing arguments to a function of a contract.
-- Sign tx requests.
-- Send txs to the Sandbox node, for simulating.
-- Send txs to the Sandbox node, to be sent to the Sandbox network.
-- Call `unconstrained` functions of a Aztec.nr contract, to perform `pure` calculations or retrieve state.
-
-## 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.
+The sandbox allows developers to:
 
-- PXE client
-  - Simulate and/or execute private functions locally.
-- Aztec Public Node
-  - Broadcasts a user's txs to the tx pool.
-  - Simulate public functions locally.
-- Tx Pool
-  - An in-memory emulation of a tx pool. By default, a user's txs will be rolled-up into an L2 block immediately.
-- Sequencer Node
-  - Reads the tx pool and bundles pending txs into a rollup block immediately.
-  - Orders txs.
-  - Executes public functions.
-  - Passes messages between L1 and L2.
-- L1 Rollup smart contract
-  - Verifies the rollup's snark.
-  - Reconciles calldata with snark public inputs.
-  - Updates the rollup's state hash.
-- L1 data archiver
-  - Gobbles up and stores all calldata, events, and state changes from L1
-- World state DB
-  - Reconstructs the Aztec Network's various trees.
-  - Allows tree state to be queried.
+- Write and deploy Aztec contracts
+- Leverage private and public state variables in contracts
+- Write private and public functions in contracts
+- Call private and public functions on other Aztec contracts (contract composability)
+- Send messages between Aztec and Ethereum contracts
+- Interact with the Aztec network using a familiar Typescript SDK ([aztec.js](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/aztec.js))

docs/docs/about_aztec/roadmap/main.md

@@ -1,5 +1,14 @@
+---
+title: Roadmap
+---
+
 import DocCardList from '@theme/DocCardList';
+import Image from '@theme/IdealImage';
+
+The next major milestone on the journey to mainnet is launching our testnet.
+
+<Image img={require('/img/road_to_testnet.png')} />
 
-# Roadmap
+## Read more
 
 <DocCardList/>

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

@@ -21,5 +21,5 @@ This circuit is executed by the user, on their own device. This is to ensure pri
 - Verifies a previous 'Private Kernel Proof', recursively, when verifying transactions which are composed of many private function calls.
 - Optionally can [deploy](../../contract_creation) a new private contract.
 
-> Note: **This is the only core protocol circuit which actually needs to be "zk" (zero knowledge)!!!** That's because this is the only core protocol circuit which handles private data, and hence the only circuit for which proofs must not leak any information about witnesses! (The private data being handled includes: details of the Aztec.nr Contract function which has been executed; the address of the user who executed the function; the intelligible inputs and outputs of that function).
-> This is a really interesting point. Most so-called "zk-Rollups" do not make use of this "zero knowledge" property. Their snarks are "snarks"; with no need for zero-knowledge, because they don't seek privacy; they only seek the 'succinct' computation-compression properties of snarks. Aztec's "zk-Rollup" actually makes use of "zero knowledge" snarks. That's why we sometimes call it a "zk-zk-Rollup", or "_actual_ zk-Rollup".
+> Note: **This is the only core protocol circuit which actually needs to be "zk" (zero-knowledge)!!!** That's because this is the only core protocol circuit which handles private data, and hence the only circuit for which proofs must not leak any information about witnesses! (The private data being handled includes: details of the Aztec.nr Contract function which has been executed; the address of the user who executed the function; the intelligible inputs and outputs of that function).
+> This is a really interesting point. Most so-called "zk-Rollups" do not make use of this "zero-knowledge" property. Their snarks are "snarks"; with no need for zero-knowledge, because they don't seek privacy; they only seek the 'succinct' computation-compression properties of snarks. Aztec's "zk-Rollup" actually makes use of "zero-knowledge" snarks. That's why we sometimes call it a "zk-zk-Rollup", or "_actual_ zk-Rollup".

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

@@ -2,6 +2,12 @@
 title: Circuits
 ---
 
+Central to Aztec's operations are 'circuits' derived both from the core protocol and the developer-written Aztec.nr contracts.
+
+The core circuits enhance privacy by adding additional security checks and preserving transaction details - a characteristic Ethereum lacks.
+
+On this page, you’ll learn a bit more about these circuits and their integral role in promoting secure and efficient transactions within Aztec's privacy-centric framework.
+
 ## Motivation
 
 In Aztec, circuits come from two sources:

docs/docs/concepts/advanced/data_structures/indexed_merkle_tree.md

@@ -3,17 +3,24 @@ title: Indexed Merkle Tree
 ---
 
 import Image from "@theme/IdealImage";
-import Disclaimer from "../../../misc/common/\_disclaimer.mdx";
 
-<Disclaimer />
+## Overview
 
-## Indexed Merkle Trees
+This article will introduce the concept of an indexed merkle tree, and how it can be used to improve the performance of nullifier trees in circuits.
 
-This article will introduce the concept of an indexed merkle tree, and how it can be used to improve the performance of nullifier trees in circuits. The content was also covered in a presentation for the [Privacy + Scaling Explorations team at the Ethereum Foundation](https://pse.dev/).
+This page will answer:
+
+- Why we need nullifier trees at all
+- How indexed merkle trees work
+- How they can be used for membership exclusion proofs
+- How they can leverage batch insertions
+- Tradoffs of using indexed merkle trees
+
+The content was also covered in a presentation for the [Privacy + Scaling Explorations team at the Ethereum Foundation](https://pse.dev/).
 
 <iframe width="100%" height="720" src="https://www.youtube-nocookie.com/embed/x_0ZhUKtWSs?si=TmguEhgz4Gu07Dac" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
 
-#### Primer on Nullifier Trees
+## Primer on Nullifier Trees
 
 Currently the only feasible way to get privacy in public blockchains is via a UTXO model. In this model, state is stored in encrypted UTXO's in merkle trees. However, to maintain privacy, state can not be updated. The very act of performing an update leaks information. In order to simulate "updating" the state, we "destroy" old UTXO's and create new ones for each state update. Resulting in a merkle tree that is append-only.