feat(docs): document noir macros

docs/docs/dev_docs/contracts/context.md → docs/docs/dev_docs/contracts/context.mdx

@@ -3,6 +3,9 @@ title: Aztec.nr Context
 description: Documentation of Aztec's Private and Public execution contexts
 hide_table_of_contents: false
 ---
+
+import Image from "@theme/IdealImage";
+
 # The Function Context
 
 ## What is the context
@@ -22,31 +25,34 @@ The following section will cover both contexts.
 ## The Private Context
 
 The code snippet below shows what is contained within the private context.
-#include_code private-context /yarn-project/noir-libs/aztec-noir/src/context.nr rust
+#include_code private-context /yarn-project/aztec-nr/aztec/src/context.nr rust
 
 ### Private Context Broken Down
 #### Inputs
 The context inputs includes all of the information that is passed from the kernel circuit into the application circuit. It contains the following values.
 
-#include_code private-context-inputs /yarn-project/noir-libs/aztec-noir/src/abi.nr rust
+#include_code private-context-inputs /yarn-project/aztec-nr/aztec/src/abi.nr rust
 
 As shown in the snippet, the application context is made up of 4 main structures. The call context, the block data, the contract deployment data and the private global variables.
 
 First of all, the call context.
 
-#include_code call-context /yarn-project/noir-libs/aztec-noir/src/abi.nr rust
+#include_code call-context /yarn-project/aztec-nr/aztec/src/abi.nr rust
+
+The call context contains information about the current call being made:
+
 
-The call context contains information about the current call being made:.
 1. Msg Sender
     - The message sender is the account (Aztec Contract) that sent the message to the current context. In the first call of the kernel circuit (often the account contract call), this value will be empty. For all subsequent calls the value will be the previous call. 
 
-    ( TODO: INCLUDE A DIAGRAM HERE SHOWING HOW IT GETS UPDATED ON CONTRACT CALLS )
+> The graphic below illustrates how the message sender changes throughout the kernel circuit iterations.
+<Image img={require("/img/context/sender_context_change.png")} />
+
 2. Storage contract address
-    - This value is the address of the current context's contract address. This value will be the value of the current contract that is being executed except for when the current call is a delegate call (TODO: INCLUDE A LINK TO ITS DOCUMENTATION). In this case the value will be that of the sending contract. 
+    - This value is the address of the current context's contract address. This value will be the value of the current contract that is being executed except for when the current call is a delegate call (Warning: This is yet to be implemented). In this case the value will be that of the sending contract. 
 
-    - This value is important as it is the value that is used when siloing the storage values of a contract. ( TODO: DOES THIS NEED TO BE DIVED INTO MORE OR IS IT SOMETHING THTAT THERE IS A LINK TO).
 3. Portal Contract Address 
-    - This value stores the current contract's linked portal contract address. ( INCLUDE A LINK TO THE LITERATURE ). As a quick recap, this value is the value of the contracts related ethereum l1 contract address, and will be the recipient of any messages that are created by this contract.
+    - This value stores the current contract's linked [portal contract](./portals/main.md) address. As a quick recap, this value is the value of the contracts related ethereum l1 contract address, and will be the recipient of any messages that are created by this contract.
 4. Flags
     - Furthermore there are a series of flags that are stored within the application context:
         - is_delegate_call: Denotes whether the current call is a delegate call. If true, then the storage contract address will be the address of the sender.
@@ -56,17 +62,17 @@ The call context contains information about the current call being made:.
 ### Historic Block Data
 Another structure that is contained within the context is the Historic Block Data object. This object is a special one as it contains all of the roots of Aztec's data trees. 
 
-#include_code historic-block-data /yarn-project/noir-libs/aztec-noir/src/abi.nr rust
+#include_code historic-block-data /yarn-project/aztec-nr/aztec/src/abi.nr rust
 
 ### Contract Deployment Data
 Just like with the `is_contract_deployment` flag mentioned earlier. This data will only be set to true when the current transaction is one in which a contract is being deployed.
 
-#include_code contract-deployment-data /yarn-project/noir-libs/aztec-noir/src/abi.nr rust
+#include_code contract-deployment-data /yarn-project/aztec-nr/aztec/src/abi.nr rust
 
 ### Private Global Variables
 In the private execution context, we only have access to a subset of the total global variables, we are restricted to those which can be reliably proven by the kernel circuits.
 
-#include_code private-global-variables /yarn-project/noir-libs/aztec-noir/src/abi.nr rust
+#include_code private-global-variables /yarn-project/aztec-nr/aztec/src/abi.nr rust
 
 ### Args Hash
 To allow for flexibility in the number of arguments supported by Aztec functions, all function inputs are reduced to a singular value which can be proven from within the application. 
@@ -101,13 +107,16 @@ The public call stack contains all of the external function calls that are creat
 ### New L2 to L1 msgs
 New L2 to L1 messages contains messages that are delivered to the [l1 outbox](../../concepts/foundation/communication/cross_chain_calls.md) on the execution of each rollup.
 
-## Public Context Inputs
+## Public Context
+The Public Context includes all of the information passed from the `Public VM` into the execution environment. It is very similar to the [Private Context](#the-private-context), however it has some minor differences (detailed below).
+
+### Public Context Inputs
 In the current version of the system, the public context is almost a clone of the private execution context. It contains the same call context data, access to the same historic tree roots, however it does NOT have access to contract deployment data, this is due to traditional contract deployments only currently being possible from private transactions.
 
-#include_code public-context-inputs /yarn-project/noir-libs/aztec-noir/src/abi.nr rust
+#include_code public-context-inputs /yarn-project/aztec-nr/aztec/src/abi.nr rust
 
 
 ### Public Global Variables
 The public global variables are provided by the rollup sequencer and consequently contain some more values than the private global variables.
 
-#include_code public-global-variables /yarn-project/noir-libs/aztec-noir/src/abi.nr rust
+#include_code public-global-variables /yarn-project/aztec-nr/aztec/src/abi.nr rust

docs/docs/dev_docs/contracts/functions.md

@@ -8,9 +8,9 @@
 - A constructor behaves almost identically to any other function. It's just important for Aztec to be able to identify this function as special: it may only be called once, and will not be deployed as part of the contract.
 
 An example of a constructor is as follows:
-#include_code constructor /yarn-project/noir-contracts/src/contracts/private_token_contract/src/main.nr rust
+#include_code constructor /yarn-project/noir-contracts/src/contracts/escrow_contract/src/main.nr rust
 
-In this example (taken from a token contract), the constructor mints `initial_supply` tokens to the passed in `owner`. 
+In this example (taken from an escrow contract), the constructor sets the deployer as an `owner`.
 
 Although constructors are always needed, they are not required to do anything. A empty constructor can be created as follows:
 
@@ -25,8 +25,7 @@ To create a private function you can annotate it with the `#[aztec(private)]` at
 
 ## `Public` Functions
 
-<!-- TODO: UPDATE LINK TO PUBLIC CONTEXT NOT THE INPTUS -->
-To create a public function you can annotate it with the `#[aztec(public)]` attribute. This will make the [public context](./context.md#public-context-inputs) available within your current function's execution scope.
+To create a public function you can annotate it with the `#[aztec(public)]` attribute. This will make the [public context](./context.md#public-context) available within your current function's execution scope.
 
 #include_code functions-OpenFunction /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr rust
 
@@ -67,8 +66,10 @@ The context available within functions includes the ability to send messages to
 
 ### What happens behind the scenes?
 When a user sends a message from a [portal contract](../../concepts/foundation/communication/cross_chain_calls.md#portal) to the rollup's inbox it gets processed and added to the `l1 to l2 messages tree`.
+
  <-- TODO(Maddiaa): INCLUDE LINK TO WHERE the messages tree is discussed elsewhere in the docs. -->
-The l1 to l2 messages tree contains all messages that have been sent from l1 to the l2. The good thing about this tree is that it does not reveal when it's messages have been spent, as consuming a message from the l1 to l2 messages tree is done by nullifing a message, rather than marking it as consumed.
+
+The l1 to l2 messages tree contains all messages that have been sent from l1 to the l2. The good thing about this tree is that it does not reveal when it's messages have been spent, as consuming a message from the l1 to l2 messages tree is done by nullifing a message.
 
 When calling the `consume_l1_to_l2_message` function on a contract; a number of actions are performed by `Aztec.nr`.
 
@@ -77,10 +78,10 @@ When calling the `consume_l1_to_l2_message` function on a contract; a number of
 3. Check that the message content matches the content reproduced earlier on. 
 4. Validate that caller know's the preimage to the message's `secretHash`. See more information [here](../../concepts/foundation/communication/cross_chain_calls.md#messages).
 5. We compute the nullifier for the message.
-#include_code l1_to_l2_message_compute_nullifier  /yarn-project/noir-libs/aztec-noir/src/messaging/l1_to_l2_message.nr rust
+#include_code l1_to_l2_message_compute_nullifier  /yarn-project/aztec-nr/aztec/src/messaging/l1_to_l2_message.nr rust
 6. Finally we push the nullifier to the context. Allowing it to be checked for validity by the kernel and rollup circuits. 
 
-#include_code consume_l1_to_l2_message  /yarn-project/noir-libs/aztec-noir/src/context.nr rust
+#include_code consume_l1_to_l2_message  /yarn-project/aztec-nr/aztec/src/context.nr rust
 
 As the same nullifier cannot be created twice. We cannot consume the message again.
 
@@ -97,7 +98,7 @@ Aztec.nr uses an attribute system to annotate a function's type. Annotating a fu
 
 However; `#aztec(private)` is just syntactic sugar. At compile time, the framework inserts code that allows the function to interact with the [kernel](../../concepts/advanced/circuits/kernels/private_kernel.md).
 
-To help illustrate how this interacts with the internals of Aztec and its kernel circuits, we can take an example private function, and explore what it looks like after Aztec.nr's macro expansion.
+To help illustrate how this interacts with the internals of #public-contextAztec and its kernel circuits, we can take an example private function, and explore what it looks like after Aztec.nr's macro expansion.
 
 #### Before expansion
 #include_code simple_macro_example /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr rust
@@ -109,7 +110,6 @@ To help illustrate how this interacts with the internals of Aztec and its kernel
 #### The expansion broken down?
 Viewing the expanded noir contract uncovers a lot about how noir contracts interact with the [kernel](../../concepts/advanced/circuits/kernels/private_kernel.md). To aid with developing intuition, we will break down each inserted line.
 
-<!-- Comment on what each of the lines do -> make a nice way to the processor to copy sub snippets / ignore sub snippets -->
 **Receiving context from the kernel.**
 #include_code context-example-inputs /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr rust
 
@@ -132,7 +132,7 @@ This structure contains a host of information about the executed program. It wil
 **Hashing the function inputs.**
 #include_code context-example-hasher /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr rust
 
-What is the hasher and why is it needed? 
+*What is the hasher and why is it needed?*
 
 Inside the kernel circuits, the inputs to functions are reduced to a single value; the inputs hash. This prevents the need for multiple different kernel circuits; each supporting differing numbers of inputs. The hasher abstraction that allows us to create an array of all of the inputs that can be reduced to a single value. 
 

docs/docs/dev_docs/contracts/syntax.md

@@ -24,7 +24,9 @@ compiler_version = "0.10.0"
 type = "contract"
 
 [dependencies]
-aztec = { git="https://github.com/AztecProtocol/aztec-packages", tag="master", directory="yarn-project/noir-libs/aztec-noir" }
+aztec = { git="https://github.com/AztecProtocol/aztec-packages", tag="master", directory="yarn-project/aztec-nr/aztec" }
 ```
 
-Note: currently the dependency name ***MUST*** be `aztec`. The framework expects this namespace to be available when compiling into contracts. This limitation may be removed in the future.
+:::info 
+Note: currently the dependency name ***MUST*** be `aztec`. The framework expects this namespace to be available when compiling into contracts. This limitation may be removed in the future.
+:::

docs/docs/dev_docs/dapps/tutorials/contract_deployment.md

@@ -19,8 +19,8 @@ Then, open the `contracts/private_token/Nargo.toml` configuration file, and add
 
 ```toml
 [dependencies]
-aztec = { git="https://github.com/AztecProtocol/aztec-packages", tag="master", directory="yarn-project/noir-libs/aztec-noir" }
-value_note = { git="https://github.com/AztecProtocol/aztec-packages", tag="master", directory="yarn-project/noir-libs/value-note" }
+aztec = { git="https://github.com/AztecProtocol/aztec-nr", tag="master", directory="aztec" }
+value_note = { git="https://github.com/AztecProtocol/aztec-nr", tag="master", directory="value-note" }
 ```
 
 Last, copy-paste the code from the `PrivateToken` contract into `contracts/private_token/main.nr`:

docs/package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
-    "start:dev": "concurrently \"yarn preprocess:dev\" \"docusaurus start --host 0.0.0.0\"",
+    "start:dev": "concurrently \"yarn preprocess:dev\" \"docusaurus start --host 0.0.0.0 --port 3001\"",
     "start:dev:local": "concurrently \"yarn preprocess:dev\" \"docusaurus start\"",
     "build": "yarn preprocess && docusaurus build",
     "swizzle": "docusaurus swizzle",

yarn-project/noir-contracts/src/contracts/escrow_contract/src/main.nr

@@ -36,14 +36,19 @@ contract Escrow {
     }
 
     // Creates a new instance
+    // docs:start:constructor
     #[aztec(private)]
     fn constructor(
         owner: pub Field
     ) {
-        let this = context.this_address();
-
         let storage = Storage::init(Context::private(&mut context));
+
+        let this = context.this_address();
+
+        // Create a new note and add it to the owners set.
         let mut note = AddressNote::new(owner, this);
+
+        // Insert the owner into storage
         storage.owners.insert(&mut note);
         emit_encrypted_log(
             &mut context,
@@ -53,6 +58,7 @@ contract Escrow {
             note.serialise(),
         );
     }
+    // docs:end:constructor
 
     // Withdraws balance. Requires that msg.sender is registered as an owner.
     #[aztec(private)]

yarn-project/noir-contracts/src/contracts/private_token_contract/src/main.nr

@@ -34,7 +34,6 @@ contract PrivateToken {
         }
     }
 
-    // docs:start:constructor
     // Constructs the contract and sets `initial_supply` which is fully owned by `owner`.
     #[aztec(private)]
     fn constructor(
@@ -48,7 +47,6 @@ contract PrivateToken {
             increment(owner_balance, initial_supply, owner);
         }
     }
-    // docs:end:constructor
 
     // docs:start:mint
     // Mints `amount` of tokens to `owner`.