cherry-pick: 49e2563 fix(docs): update CLI commands, ABI fields, and tutorial fixes (with conflicts)

Author: critesjosh

docs/developer_versioned_docs/version-v4.2.0-aztecnr-rc.2/docs/tutorials/contract_tutorials/counter_contract.md

@@ -0,0 +1,200 @@
+---
+title: Counter Contract
+description: Code-along tutorial for creating a simple counter contract on Aztec.
+sidebar_position: 0
+references: ["docs/examples/contracts/counter_contract/src/main.nr"]
+---
+
+import Image from "@theme/IdealImage";
+
+In this guide, we will create our first Aztec.nr smart contract. We will build a simple private counter, where you can keep your own private counter - so no one knows what ID you are at or when you increment! This contract will get you started with the basic setup and syntax of Aztec.nr, but doesn't showcase all of the awesome stuff Aztec is capable of.
+
+This tutorial is compatible with the Aztec version `4.2.0-aztecnr-rc.2`. Install the correct version with `VERSION=4.2.0-aztecnr-rc.2 bash -i <(curl -sL https://install.aztec.network/4.2.0-aztecnr-rc.2)`. Or if you'd like to use a different version, you can find the relevant tutorial by clicking the version dropdown at the top of the page.
+
+## Prerequisites
+
+- You have followed the [quickstart](../../../getting_started_on_local_network.md)
+- Running Aztec local network
+- Installed [Noir LSP](../../aztec-nr/installation.md) (optional)
+
+## Set up a project
+
+Run this to create a new contract project:
+
+```bash
+aztec new counter
+```
+
+Your structure should look like this:
+
+```tree
+.
+|-counter
+| |-src
+| | |-main.nr
+| |-Nargo.toml
+```
+
+The file `main.nr` will soon turn into our smart contract!
+
+Add the following dependencies to `Nargo.toml` under the autogenerated content:
+
+```toml
+[dependencies]
+aztec = { git="https://github.com/AztecProtocol/aztec-nr/", tag="v4.2.0-aztecnr-rc.2", directory="aztec" }
+balance_set = { git="https://github.com/AztecProtocol/aztec-nr/", tag="v4.2.0-aztecnr-rc.2", directory="balance-set" }
+```
+
+## Define the functions
+
+Go to `main.nr`, and replace the boilerplate code with this contract initialization:
+
+```rust
+use aztec::macros::aztec;
+
+#[aztec]
+pub contract Counter {
+}
+```
+
+This defines a contract called `Counter`.
+
+## Imports
+
+We need to define some imports.
+
+Write this inside your contract, ie inside these brackets:
+
+```rust
+pub contract Counter {
+    // imports go here!
+}
+```
+
+```rust title="imports" showLineNumbers 
+use aztec::{
+    macros::{functions::{external, initializer}, storage::storage},
+    messages::message_delivery::MessageDelivery,
+    oracle::logging::debug_log_format,
+    protocol::{address::AztecAddress, traits::ToField},
+    state_vars::Owned,
+};
+use balance_set::BalanceSet;
+```
+> <sup><sub><a href="https://github.com/AztecProtocol/aztec-packages/blob/v4.2.0-aztecnr-rc.2/docs/examples/contracts/counter_contract/src/main.nr#L7-L16" target="_blank" rel="noopener noreferrer">Source code: docs/examples/contracts/counter_contract/src/main.nr#L7-L16</a></sub></sup>
+
+
+- `macros::{functions::{external, initializer}, storage::storage}`
+  Imports the macros needed to define function types (`external`, `initializer`) and the `storage` macro for declaring contract storage structures.
+
+- `messages::message_delivery::MessageDelivery`
+  Imports `MessageDelivery` for specifying how note delivery should be handled (e.g., constrained onchain delivery).
+
+- `oracle::debug_log::debug_log_format`
+  Imports a debug logging utility for printing formatted messages during contract execution.
+
+- `protocol::{address::AztecAddress, traits::ToField}`
+  Brings in `AztecAddress` (used to identify accounts/contracts) and traits for converting values to field elements, necessary for serialization and formatting inside Aztec.
+
+- `state_vars::Owned`
+  Brings in `Owned`, a wrapper for state variables that have a single owner.
+
+- `use balance_set::BalanceSet`
+  Imports `BalanceSet` from the `balance_set` dependency, which provides functionality for managing private balances (used for our counter).
+
+## Declare storage
+
+Add this below the imports. It declares the storage variables for our contract. We use an `Owned` state variable wrapping a `BalanceSet` to manage private balances for each owner.
+
+```rust title="storage_struct" showLineNumbers 
+#[storage]
+struct Storage<Context> {
+    counters: Owned<BalanceSet<Context>, Context>,
+}
+```
+> <sup><sub><a href="https://github.com/AztecProtocol/aztec-packages/blob/v4.2.0-aztecnr-rc.2/docs/examples/contracts/counter_contract/src/main.nr#L18-L23" target="_blank" rel="noopener noreferrer">Source code: docs/examples/contracts/counter_contract/src/main.nr#L18-L23</a></sub></sup>
+
+
+## Keep the counter private
+
+Now we’ve got a mechanism for storing our private state, we can start using it to ensure the privacy of balances.
+
+Let’s create a constructor method to run on deployment that assigns an initial count to a specified owner. This function is called `initialize`, but behaves like a constructor. It is the `#[initializer]` decorator that specifies that this function behaves like a constructor. Write this:
+
+```rust title="constructor" showLineNumbers 
+#[initializer]
+#[external("private")]
+// We can name our initializer anything we want as long as it's marked as aztec(initializer)
+fn initialize(headstart: u64, owner: AztecAddress) {
+    self.storage.counters.at(owner).add(headstart as u128).deliver(
+        MessageDelivery.ONCHAIN_CONSTRAINED,
+    );
+}
+```
+> <sup><sub><a href="https://github.com/AztecProtocol/aztec-packages/blob/v4.2.0-aztecnr-rc.2/docs/examples/contracts/counter_contract/src/main.nr#L25-L34" target="_blank" rel="noopener noreferrer">Source code: docs/examples/contracts/counter_contract/src/main.nr#L25-L34</a></sub></sup>
+
+
+This function accesses the counters from storage. It adds the `headstart` value to the `owner`'s counter using `at().add()`, then calls `.deliver(MessageDelivery.ONCHAIN_CONSTRAINED)` to ensure the note is delivered onchain.
+
+We have annotated this and other functions with `#[external("private")]` which are ABI macros so the compiler understands it will handle private inputs.
+
+## Incrementing our counter
+
+Now let's implement an `increment` function to increase the counter.
+
+```rust title="increment" showLineNumbers 
+#[external("private")]
+fn increment(owner: AztecAddress) {
+    debug_log_format("Incrementing counter for owner {0}", [owner.to_field()]);
+    self.storage.counters.at(owner).add(1).deliver(MessageDelivery.ONCHAIN_CONSTRAINED);
+}
+```
+> <sup><sub><a href="https://github.com/AztecProtocol/aztec-packages/blob/v4.2.0-aztecnr-rc.2/docs/examples/contracts/counter_contract/src/main.nr#L36-L42" target="_blank" rel="noopener noreferrer">Source code: docs/examples/contracts/counter_contract/src/main.nr#L36-L42</a></sub></sup>
+
+
+The `increment` function works similarly to the `initialize` function. It logs a debug message, then adds 1 to the owner's counter and delivers the note onchain.
+
+## Getting a counter
+
+The last thing we need to implement is a function to retrieve a counter value.
+
+```rust title="get_counter" showLineNumbers 
+#[external("utility")]
+unconstrained fn get_counter(owner: AztecAddress) -> pub u128 {
+    self.storage.counters.at(owner).balance_of()
+}
+```
+> <sup><sub><a href="https://github.com/AztecProtocol/aztec-packages/blob/v4.2.0-aztecnr-rc.2/docs/examples/contracts/counter_contract/src/main.nr#L44-L49" target="_blank" rel="noopener noreferrer">Source code: docs/examples/contracts/counter_contract/src/main.nr#L44-L49</a></sub></sup>
+
+
+This is a `utility` function used to obtain the counter value outside of a transaction. We access the `owner`'s balance from the `counters` storage variable using `at(owner)`, then call `balance_of()` to retrieve the current count. This yields a private counter that only the owner can decrypt.
+
+## Compile
+
+Now we've written a simple Aztec.nr smart contract, we can compile it.
+
+### Compile the smart contract
+
+In the `./counter/` directory, run:
+
+```bash
+aztec compile
+```
+
+This command compiles your Noir contract and creates a `target` folder with a `.json` artifact inside.
+
+After compiling, you can generate a TypeScript class using the `aztec codegen` command.
+
+In the same directory, run this:
+
+```bash
+aztec codegen -o src/artifacts target
+```
+
+You can now use the artifact and/or the TS class in your Aztec.js!
+
+## Next Steps
+
+### Optional: Learn more about concepts mentioned here
+
+- [Functions and annotations like `#[external("private")]`](../../aztec-nr/framework-description/functions/function_transforms.md#private-functions)