Restructure sidebar

docs/pages/aztec-nr/advanced-features/custom-notes.md

@@ -4,8 +4,8 @@ This guide shows you how to create custom note types for storing specialized pri
 
 ## Prerequisites
 
-- Basic understanding of [Aztec private state](../../concepts/storage/state_model.md)
-- Familiarity with [notes and UTXOs](../../concepts/storage/index.md)
+- Basic understanding of Aztec private state
+- Familiarity with notes and UTXOs
 - Aztec development environment set up
 
 ## Why create custom notes?
@@ -329,11 +329,10 @@ fn get_order(owner: AztecAddress, target_id: Field) -> OrderNote {
 
 ## Further reading
 
-- [What the `#[note]` macro does](../../concepts/smart_contracts/functions/attributes.md#implementing-notes)
-- [Note lifecycle and nullifiers](../../concepts/advanced/storage/indexed_merkle_tree.mdx)
-- [Advanced note patterns](./advanced/how_to_retrieve_filter_notes.md)
-- [Note portals for L1 communication](./how_to_communicate_cross_chain.md)
-- [Macros reference](../../reference/smart_contract_reference/macros.md)
-- [Keys, including npk_m_hash](../../concepts/accounts/keys.md)
+- What the `#[note]` macro does - See concepts section
+- Note lifecycle and nullifiers - See concepts section
+- Advanced note patterns - See advanced features
+- Note portals for L1 communication - See cross-chain interactions
+- Macros reference - See reference section
+- Keys, including npk_m_hash - See concepts section
 
-<!-- docs:end:how_to_implement_custom_notes -->

docs/pages/aztec-nr/compile.md

@@ -87,4 +87,3 @@ After compilation, use the generated artifacts to:
 - Interact with deployed contracts using type-safe interfaces
 - Import contracts in other Aztec.nr projects
 
-<!-- docs:end:compile_contracts -->

docs/pages/aztec-nr/debugging.md

@@ -185,6 +185,6 @@ Check hex errors against [Errors.sol](https://github.com/AztecProtocol/aztec-pac
 
 ## Related Resources
 
-- [Circuit Architecture](../../concepts/advanced/circuits/index.md)
-- [Private-Public Execution](../../concepts/smart_contracts/functions/public_private_calls.md)
-- [Aztec.nr Dependencies](../../reference/smart_contract_reference/dependencies.md)
+- Circuit Architecture - See concepts section
+- Private-Public Execution - See concepts section
+- Aztec.nr Dependencies - See reference section

docs/pages/aztec-nr/getting-started.md

@@ -2,7 +2,6 @@
 
 ## Noir VSCode Extension
 
-<!-- docs:start:installing_noir_lsp -->
 
 Install the [Noir Language Support extension](https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir) to get syntax highlighting, syntax error detection and go-to definitions for your Aztec contracts. 
 
@@ -16,7 +15,6 @@ which aztec-nargo
 
 To specify a custom nargo executable, go to the VSCode settings and search for "noir", or click extension settings on the `noir-lang` LSP plugin. Update the `Noir: Nargo Path` field to point to your desired `aztec-nargo` executable.
 
-<!-- docs:end:installing_noir_lsp -->
 
 ## Creating an Aztec.nr Project
 

docs/pages/aztec-nr/installation.md

@@ -15,7 +15,7 @@ Before learning how to create Aztec smart contracts, we must first install some
 
 - [Docker](https://docs.docker.com/get-docker/)
 
-## Install Aztec Tools
+## Install Aztec Tools
 
 1. Docker needs to be running in order to install the sandbox.
 
@@ -33,7 +33,6 @@ aztec --version
 
 ## Noir VSCode Extension
 
-<!-- docs:start:installing_noir_lsp -->
 
 Install the [Noir Language Support extension](https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir) to get syntax highlighting, syntax error detection and go-to definitions for your Aztec contracts. 
 
@@ -47,7 +46,6 @@ which aztec-nargo
 
 To specify a custom nargo executable, go to the VSCode settings and search for "noir", or click extension settings on the `noir-lang` LSP plugin. Update the `Noir: Nargo Path` field to point to your desired `aztec-nargo` executable.
 
-<!-- docs:end:installing_noir_lsp -->
 
 ## Creating an Aztec.nr Project
 

docs/pages/aztec-nr/introduction-to-private-smart-contracts/index.md

@@ -8,8 +8,8 @@ Private smart contracts on Aztec allow you to build applications where transacti
 
 ## Getting Started
 
-- [A Simple Aztec Smart Contract](./simple-contract) - Start with a basic example
-- [Example Aztec Smart Contracts](./examples) - Explore more complex patterns
+- A Simple Aztec Smart Contract - Start with a basic example
+- Example Aztec Smart Contracts - Explore more complex patterns
 
 ## Key Concepts
 

docs/pages/aztec-nr/language-description/authentication-witness.md

@@ -1,6 +1,5 @@
 # Authentication Witness
 
-<!-- docs:start:use_authwit -->
 
 Authentication witnesses (authwit) allow other contracts to execute actions on behalf of your account. This guide shows you how to implement and use authwits in your Aztec smart contracts.
 
@@ -10,7 +9,7 @@ Authentication witnesses (authwit) allow other contracts to execute actions on b
 - Understanding of private and public functions in Aztec
 - Access to the `authwit` library in your contract
 
-For conceptual background, see [Authentication Witnesses](../../concepts/advanced/authwit.md).
+For conceptual background, see Authentication Witnesses in the concepts section.
 
 ## Set up the authwit library
 
@@ -91,4 +90,3 @@ fn _approve_and_execute_action(
 }
 ```
 
-<!-- docs:end:use_authwit -->

docs/pages/aztec-nr/language-description/calling-other-contracts.md

@@ -20,7 +20,6 @@
             - Stealthifying Addresses
                 - Custom Stealth Addresses
 
-<!-- docs:start:call_contracts -->
 
 This guide shows you how to call functions in other contracts from your Aztec smart contracts, enabling contract composability and interaction.
 
@@ -83,11 +82,10 @@ OtherContract::at(contract_address)
 ```
 
 :::info
-Public functions always execute after private execution completes. Learn more in the [concepts overview](../../concepts/index.md).
+Public functions always execute after private execution completes. Learn more in the concepts overview.
 :::
 
 ### Use other call types
 
-Explore additional call types for specialized use cases in the [call types reference](../../concepts/call_types.md).
+Explore additional call types for specialized use cases in the call types reference.
 
-<!-- docs:end:call_contracts -->

docs/pages/aztec-nr/language-description/contract-structure.md

@@ -8,7 +8,7 @@
     - Events
         - See the dedicated section below
 
-A contract is a collection of persistent state variables and [functions](./functions/index.md) which may manipulate these variables. Functions and state variables within a contract's scope are said to belong to that contract. A contract can only access and modify its own state. If a contract wishes to access or modify another contract's state, it must make a call to an external function of the other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called.
+A contract is a collection of persistent state variables and functions which may manipulate these variables. Functions and state variables within a contract's scope are said to belong to that contract. A contract can only access and modify its own state. If a contract wishes to access or modify another contract's state, it must make a call to an external function of the other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called.
 
 ## Contract
 

docs/pages/aztec-nr/language-description/cross-chain-interactions.md

@@ -13,7 +13,7 @@
 - An Aztec contract project set up with `aztec-nr` dependency
 - Understanding of Aztec L1/L2 architecture
 - Access to Ethereum development environment for L1 contracts
-- Deployed portal contract on L1 (see [token bridge tutorial](../../tutorials/js_tutorials/token_bridge.md))
+- Deployed portal contract on L1 (see token bridge tutorial)
 
 ## Send messages from L1 to L2
 
@@ -195,6 +195,5 @@ bytes memory message = abi.encodeWithSignature(
 
 ## Next steps
 
-Follow the [cross-chain messaging tutorial](../../tutorials/js_tutorials/token_bridge.md) for a complete implementation example.
+Follow the cross-chain messaging tutorial for a complete implementation example.
 
-<!-- docs:end:communicate_cross_chain -->

docs/pages/aztec-nr/language-description/events-and-logs.md

@@ -104,4 +104,3 @@ Event data is published to Ethereum as blobs, which incurs costs. Consider:
 - Future alternatives for data availability may become available
 - Balance event utility with cost implications
 
-<!-- docs:end:emit_events -->

docs/pages/aztec-nr/language-description/index.md

@@ -27,7 +27,7 @@ This section covers all aspects of the Aztec.nr language:
 
 ### Communication
 - **Private Messaging** - Encrypted messaging between accounts
-- **L1<>L2 Messaging** - Cross-layer communication
+- **L1↔L2 Messaging** - Cross-layer communication
 - **Cross-chain Interactions** - Interacting with other chains
 
 ### Advanced Topics

docs/pages/aztec-nr/language-description/macros.md

@@ -25,4 +25,4 @@ It is also worth mentioning Noir's `unconstrained` function type [here (Noir doc
 - `#[storage]` - Defines contract storage
 
 ## Further reading
-[How do Aztec macros work?](../../concepts/smart_contracts/functions/function_transforms.md)
+How do Aztec macros work? - See concepts section

docs/pages/aztec-nr/testing.md

@@ -5,7 +5,6 @@
 2. Testing end-to-end apps.
     - See Aztec.js?
 
-<!-- docs:start:test_contracts -->
 
 This guide shows you how to test your Aztec smart contracts using Noir's `TestEnvironment` for fast, lightweight testing.
 
@@ -16,7 +15,7 @@ This guide shows you how to test your Aztec smart contracts using Noir's `TestEn
 - Basic understanding of Noir syntax
 
 :::tip
-For complex cross-chain or integration testing, see the [TypeScript testing guide](../aztec-js/how_to_test.md).
+For complex cross-chain or integration testing, see the TypeScript testing guide in the Aztec.js section.
 :::
 
 ## Write Aztec contract tests
@@ -27,7 +26,7 @@ Use `TestEnvironment` from `aztec-nr` for contract unit testing:
 - **Convenient**: Similar to Foundry for simple contract tests
 - **Limited**: No rollup circuits or cross-chain messaging
 
-For complex end-to-end tests, use [TypeScript testing](../aztec-js/how_to_test.md) with `aztec.js`.
+For complex end-to-end tests, use TypeScript testing with `aztec.js`.
 
 ## Run your tests
 
@@ -334,4 +333,3 @@ unconstrained fn test_missing_authwit() {
 
 ```
 
-<!-- docs:end:test_contracts -->

docs/pages/protocol-architecture/addresses-and-keys.md → docs/pages/foundational-topics/addresses-and-keys.md

@@ -122,13 +122,13 @@ Account contracts are also expected, though not required by the protocol, to imp
 
 When executing a private function, this authorization is checked by requesting an authentication witness from the execution oracle, which is usually a signed message. Authentication Witness is a scheme for authenticating actions on Aztec, so users can allow third-parties (e.g. contracts) to execute an action on their behalf.
 
-The user's [Private eXecution Environment (PXE)](../pxe/index.md) is responsible for storing these auth witnesses and returning them to the requesting account contract. Auth witnesses can belong to the current user executing the local transaction, or to another user who shared it offchain.
+The user's Private eXecution Environment (PXE) is responsible for storing these auth witnesses and returning them to the requesting account contract. Auth witnesses can belong to the current user executing the local transaction, or to another user who shared it offchain.
 
-However, during a public function execution, it is not possible to retrieve a value from the local [oracle](../smart_contracts/oracles/index.md). To support authorizations in public functions, account contracts should save in a public authwit registry what actions have been pre-authorized by their owner.
+However, during a public function execution, it is not possible to retrieve a value from the local oracle. To support authorizations in public functions, account contracts should save in a public authwit registry what actions have been pre-authorized by their owner.
 
 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](../advanced/authwit.md).
+You can read more about authorizing actions with authorization witnesses in the concepts section.
 
 :::info
 
@@ -152,7 +152,7 @@ Nonce abstraction is mostly relevant to those building wallets. For example, a d
 
 ### Fee abstraction
 
-It doesn't have to be the transaction sender who pays the transaction fees. Wallets or dapp developers can choose any payment logic they want using a paymaster. To learn more about fees on Aztec – check [this page](../fees.md).
+It doesn't have to be the transaction sender who pays the transaction fees. Wallets or dapp developers can choose any payment logic they want using a paymaster. To learn more about fees on Aztec – check the fees section.
 
 Paymaster is a contract that can pay for transactions on behalf of users. It is invoked during the private execution stage and set as the fee payer.
 
@@ -184,9 +184,9 @@ To spend a note, the user computes a nullifier corresponding to this note. A nul
 
 ### Address keys
 
-Address keys are used for account [address derivation](../accounts/index.md).
+Address keys are used for account address derivation.
 
-<Image img={require("@site/static/img/address_derivation.png")} />
+![address-derivation](/address_derivation.png)
 
 Address keys are a pair of keys `AddressPublicKey` and `address_sk` where `address_sk` is a scalar defined as `address_sk = pre_address + ivsk` and `AddressPublicKey` is an elliptic curve point defined as `AddressPublicKey = address_sk * G`. This is useful for encrypting notes for the recipient with only their address.
 
@@ -232,7 +232,7 @@ When it comes to notes encryption and decryption:
 
 ### Signing keys
 
-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.
+Thanks to the native account abstraction, 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.
 
@@ -263,7 +263,7 @@ When it comes to storing the signing key in a private note, there are several de
 
 #### Using Delayed Public Mutable state
 
-By [Delayed Public Mutable](../../guides/smart_contracts/how_to_define_storage.md#delayed-public-mutable) we mean privately readable publicly mutable state.
+By Delayed Public Mutable 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 delayed mutable state, as well as imposing restrictions on how fast keys can be rotated due to minimum delays.
 
@@ -277,7 +277,7 @@ Since there are no restrictions on the actions that an account contract may exec
 
 ### Keys generation
 
-All key pairs (except for the signing keys) are generated in the [Private Execution Environment](../pxe/index.md) (PXE) when a user creates an account. PXE is also responsible for the further key management (oracle access to keys, app siloed keys derivation, etc.)
+All key pairs (except for the signing keys) are generated in the Private Execution Environment (PXE) when a user creates an account. PXE is also responsible for the further key management (oracle access to keys, app siloed keys derivation, etc.)
 
 ### Keys derivation
 
@@ -301,7 +301,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](../advanced/storage/storage_slots.md#implementation) in PXE every time the user interacts with the application.
+App-siloed keys are derived 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/pages/protocol-architecture/call-types.md → docs/pages/foundational-topics/call-types.md

@@ -144,7 +144,7 @@ aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "#incl
 
 Even with the router contract achieving good privacy is hard.
 For example, if the value being checked against is unique and stored in the contract's public storage, it's then simple to find private transactions that are using that value in the enqueued public reads, and therefore link them to this contract.
-For this reason it is encouraged to try to avoid public function calls and instead privately read [Shared State](../guides/smart_contracts/how_to_define_storage.md#delayed-public-mutable) when possible.
+For this reason it is encouraged to try to avoid public function calls and instead privately read Shared State when possible.
 
 ### Public Execution
 

docs/pages/protocol-architecture/circuits.md → docs/pages/foundational-topics/circuits.md

@@ -49,7 +49,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 [indexed merkle tree](../storage/indexed_merkle_tree.mdx).
+- "Perform state reads and writes using new tree structures which prevent tx linkability" (see indexed merkle tree section).
 - "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"
 
@@ -77,7 +77,7 @@ Most so-called "zk-Rollups" do not make use of this "zero-knowledge" property. T
 
 ### Public Kernel Circuit
 
-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.
+This circuit is executed by a Sequencer, since only a Sequencer knows the current state of the public data tree at any time. A Sequencer might choose to delegate proof generation to the Prover pool.
 
 ## Rollup Circuits