chore(docs): Edit Aztec.nr Guide section (#10866)

Updates the Aztec.nr guide section.
- adds a landing page for the section
- updates the page ordering to be more intuitive to how the development
flow goes in practice
- adds a landing page for the "writing contracts" section

closes: #10523

docs/docs/guides/developer_guides/smart_contracts/how_to_compile_contract.md

@@ -448,7 +448,7 @@ Read more about interacting with contracts using `aztec.js` [by following this t
 
 ### Aztec.nr interfaces
 
-An Aztec.nr contract can [call a function](./writing_contracts/call_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 serializing the arguments, which is not type-safe.
+An Aztec.nr contract can [call a function](./writing_contracts/call_contracts.md) in another contract via `context.call_private_function` or `context.call_public_function`. However, this requires manually assembling the function selector and manually serializing the arguments, which is not type-safe.
 
 To make this easier, the compiler automatically generates interface structs that expose a convenience method for each function listed in a given contract artifact. These structs are intended to be used from another contract project that calls into the current one.
 

docs/docs/guides/developer_guides/smart_contracts/how_to_deploy_contract.md

@@ -4,10 +4,10 @@ sidebar_position: 4
 tags: [contracts, sandbox]
 ---
 
-# Deploying contracts
-
 Once you have [compiled](./how_to_compile_contract.md) your contracts you can proceed to deploying them using aztec.js which is a Typescript client to interact with the sandbox.
 
+You can use this method to deploy your contracts to the sandbox or to a remote network.
+
 ## Prerequisites
 
 - `aztec-nargo` installed (go to [Sandbox section](../../../reference/developer_references/sandbox_reference/sandbox-reference.md) for installation instructions)

docs/docs/guides/developer_guides/smart_contracts/index.mdx

@@ -0,0 +1,39 @@
+---
+title: Aztec.nr
+tags: [aztec.nr]
+---
+
+import DocCardList from "@theme/DocCardList";
+
+Aztec.nr is the smart contract development framework for Aztec. It is a set of utilities that
+help you write Noir programs to deploy on the Aztec network.
+
+## Contract Development
+
+### Prerequisites
+
+- Install [Aztec Sandbox and tooling](../../getting_started.md)
+- Install the [Noir LSP](../local_env/installing_noir_lsp.md) for your editor.
+
+### Flow
+
+1. Write your contract and specify your contract dependencies. Every contract written for Aztec will have
+   aztec-nr as a dependency. Add it to your `Nargo.toml` with
+
+```toml
+# Nargo.toml
+[dependencies]
+aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/aztec-nr/aztec" }
+```
+
+2.  [Write your contracts](./writing_contracts/index.mdx).
+3.  [Profile](./profiling_transactions.md) the private functions in your contract to get
+    a sense of how long generating client side proofs will take
+4.  Write unit tests [using the TXE](testing.md) and end-to-end
+    tests [with typescript](../js_apps/test.md)
+5.  [Compile](how_to_compile_contract.md) your contract
+6.  [Deploy](how_to_deploy_contract.md) your contract
+
+## Section Contents
+
+<DocCardList />

docs/docs/guides/developer_guides/smart_contracts/profiling_transactions.md

@@ -1,11 +1,9 @@
 ---
 title: Profiling Transactions
-sidebar_position: 5
+sidebar_position: 1
 tags: [contracts, profiling]
 ---
 
-# Profiling Transactions
-
 An Aztec transaction typically consists of a private and a public part. The private part is where the user executes contract logic within the PXE and generates a proof of execution, which is then sent to the sequencer.
 
 Since proof generation is an expensive operation that needs to be done on the client side, it is important to optimize the private contract logic. It is desirable to keep the gate count of circuits representing the private contract logic as low as possible.

docs/docs/guides/developer_guides/smart_contracts/testing_contracts/testing.md → docs/docs/guides/developer_guides/smart_contracts/testing.md

@@ -1,13 +1,14 @@
 ---
-title: Testing Contracts in the TXE
+title: Testing Contracts
 tags: [contracts, tests, testing, txe]
 keywords: [tests, testing, txe]
+sidebar_position: 2
 importance: 1
 ---
 
 Aztec contracts can be tested in a variety of ways depending on the needs of a particular application and the complexity of the interactions they must support.
 
-To test individual contract functions, you can use the Testing eXecution Environment (TXE) described below. For more complex interactions that require checking that the protocol rules are enforced, you should [write end-to-end tests using TypeScript](../../js_apps/test.md).
+To test individual contract functions, you can use the Testing eXecution Environment (TXE) described below. For more complex interactions that require checking that the protocol rules are enforced, you should [write end-to-end tests using TypeScript](../js_apps/test.md).
 
 ## Pure Noir tests
 
@@ -27,7 +28,7 @@ TXE is a JSON RPC server much like PXE, but provides an extra set of oracle func
 
 ## TXE vs End-to-end tests
 
-End-to-end tests are written in typescripts and use compiled Aztec contracts and generated Typescript interfaces, a private execution environment (PXE) and a simulated execution environment to process transactions, create blocks and apply state updates. This allows for advanced checks on state updates like generation the of logs, cross-chain messages and checking transaction status and also enforce the rules of the protocol (e.g. checks in our rollup circuits). If you need the rules of the protocol to be enforced or require complex interactions (such as with L1 contracts), please refer to [Testing Aztec.nr contracts with Typescript](../../js_apps/test.md).
+End-to-end tests are written in typescripts and use compiled Aztec contracts and generated Typescript interfaces, a private execution environment (PXE) and a simulated execution environment to process transactions, create blocks and apply state updates. This allows for advanced checks on state updates like generation the of logs, cross-chain messages and checking transaction status and also enforce the rules of the protocol (e.g. checks in our rollup circuits). If you need the rules of the protocol to be enforced or require complex interactions (such as with L1 contracts), please refer to [Testing Aztec.nr contracts with Typescript](../js_apps/test.md).
 
 The TXE is a super fast framework in Noir to quickly test your smart contract code.
 
@@ -38,7 +39,7 @@ So to summarize:
 
 ### Running TXE
 
-If you have [the sandbox](../../../getting_started.md) installed, you can run TXE tests using:
+If you have [the sandbox](../../getting_started.md) installed, you can run TXE tests using:
 
 `aztec test`
 
@@ -176,7 +177,7 @@ Reading notes:
 
 #### Private
 
-You can add [authwits](../writing_contracts/authwit.md) to the TXE. Here is an example of testing a private token transfer using authwits:
+You can add [authwits](writing_contracts/authwit.md) to the TXE. Here is an example of testing a private token transfer using authwits:
 
 #include_code private_authwit /noir-projects/noir-contracts/contracts/token_contract/src/test/transfer_in_private.nr rust
 
@@ -214,7 +215,7 @@ You can also use the `assert_public_call_fails` or `assert_private_call_fails` m
 
 ### Logging
 
-You can use `aztec.nr`'s oracles as usual for debug logging, as explained [here](../../../../reference/developer_references/debugging.md)
+You can use `aztec.nr`'s oracles as usual for debug logging, as explained [here](../../../reference/developer_references/debugging.md)
 
 :::warning
 Remember to set the following environment variables to activate debug logging:

docs/docs/guides/developer_guides/smart_contracts/writing_contracts/call_functions.md → docs/docs/guides/developer_guides/smart_contracts/writing_contracts/call_contracts.md

@@ -1,48 +1,28 @@
 ---
-title: Calling Other Functions
-sidebar_position: 2
+title: Calling Other Contracts
+sidebar_position: 4
 tags: [functions, contracts]
 ---
 
-
-A contract is a collection of persistent state variables and functions which may manipulate these variables. 
+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.
 
-### Defining a contract
-
-A contract may be declared and given a name using the `contract` keyword (see snippet below). By convention, contracts are named in `PascalCase`.
-
-```rust title="contract keyword"
-// highlight-next-line
-contract MyContract {
-
-    // Imports 
-
-    // Storage 
-
-    // Functions
-}
-```
-:::info A note for vanilla Noir devs
-There is no [`main()` (GitHub link)](https://noir-lang.org/docs/getting_started/project_breakdown/#mainnr) function within a Noir `contract` scope. More than one function can be an entrypoint.
-:::
-
-### Add as a dependency in Nargo.toml
+### Add Contract as a Dependency
 
 Import the contract that you want to call into your `Nargo.toml` under `dependencies` like this:
 
-```
+```toml
 token = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/noir-contracts/contracts/token_contract" }
 ```
 
 ### Import into your contract
 
 At the top of your contract, import the contract you want to call like this:
 
-```
+```rust
 use token::Token;
 ```
 
@@ -53,7 +33,7 @@ To call the function, you need to
 - Specify the address of the contract with `Contract::at(contract_address)`
 - Call the function name with `.function_name()`
 - Pass the parameters into the function call, like `.function_name(param1,param2)`
-- Specify the type of call you want to make and pass a mut reference to the context, like `.call(&mut context)` 
+- Specify the type of call you want to make and pass a mut reference to the context, like `.call(&mut context)`
 
 #### Private calls
 
@@ -77,6 +57,4 @@ Public functions are always executed after private execution. To learn why, read
 
 #### Other call types
 
-There are other call types, for example to ensure no state changes are made. You can learn more about them in the [call types glossary](../../../../aztec/glossary/call_types.md). 
-
-
+There are other call types, for example to ensure no state changes are made. You can learn more about them in the [call types glossary](../../../../aztec/glossary/call_types.md).

docs/docs/guides/developer_guides/smart_contracts/writing_contracts/how_to_emit_event.md

@@ -1,6 +1,6 @@
 ---
 title: Emitting Events
-sidebar_position: 3
+sidebar_position: 4
 tags: [contracts]
 ---
 

docs/docs/guides/developer_guides/smart_contracts/writing_contracts/index.mdx

@@ -0,0 +1,47 @@
+---
+title: Writing Contracts
+tags: [aztec.nr]
+---
+
+import DocCardList from "@theme/DocCardList";
+
+## Overview
+
+To write a contract:
+
+1. Import aztec.nr and declare your contract
+
+```rust
+#include_code declaration /noir-projects/noir-contracts/contracts/easy_private_voting_contract/src/main.nr raw
+
+    // Imports
+
+    // Storage
+
+    // Functions
+}
+```
+
+2. Define imports in your contract block
+
+#include_code imports /noir-projects/noir-contracts/contracts/easy_private_voting_contract/src/main.nr rust
+
+3. Declare your contract storage below your imports
+
+#include_code storage_struct /noir-projects/noir-contracts/contracts/easy_private_voting_contract/src/main.nr rust
+
+4. Declare a constructor with `#[initializer]`. Constructors can be private or public functions.
+
+#include_code constructor /noir-projects/noir-contracts/contracts/easy_private_voting_contract/src/main.nr rust
+
+5. Declare your contract functions
+
+#include_code cast_vote /noir-projects/noir-contracts/contracts/easy_private_voting_contract/src/main.nr rust
+
+There is a lot more detail and nuance to writing contracts, but this should give you a good starting point.
+Read contents of this section for more details about authorizing contract to act on your behalf (authenticaion witnesses),
+emitting events, calling functions on other contracts and other common patterns.
+
+## Section Contents
+
+<DocCardList />

docs/docs/guides/developer_guides/smart_contracts/writing_contracts/initializers.md

@@ -37,7 +37,7 @@ Initializers are commonly used to set an admin, such as this example:
 
 #include_code constructor /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust
 
-Here, the initializer is writing to storage. It can also call another function. Learn more about calling functions from functions [here](./call_functions.md).
+Here, the initializer is writing to storage. It can also call another function. Learn more about calling functions from functions [here](./call_contracts.md).
 
 ## Multiple initializers
 

docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/index.md

@@ -1,7 +1,7 @@
 ---
 title: Notes
-sidebar_position: 6
+sidebar_position: 3
 tags: [contracts, notes]
 ---
 
-Notes are the fundamental data structure in Aztec when working with private state. In this section there are guides about how to work with `AddressNote`, `ValueNote`, and custom notes in Aztec.nr. You can learn more about notes in the [concepts section](../../../../../aztec/concepts/storage/state_model/index.md#private-state).
+Notes are the fundamental data structure in Aztec when working with private state. In this section there are guides about how to work with `AddressNote`, `ValueNote`, and custom notes in Aztec.nr. You can learn more about notes in the [concepts section](../../../../../aztec/concepts/storage/state_model/index.md#private-state).

docs/docs/guides/developer_guides/smart_contracts/writing_contracts/storage/index.md

@@ -1,5 +1,6 @@
 ---
 title: Declaring Storage
+sidebar_position: 2
 tags: [contracts, storage]
 ---