Private function example

Author: jzaki

.gitignore

@@ -0,0 +1 @@
+target

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "noir.nargoPath": "~/.nargo/bin/nargo"
+}

README.md

@@ -1,2 +1,10 @@
 # aztec-examples
-A place for example Aztec projects
+
+A place for example Aztec contracts to learn in a hands-on way.
+
+## Documentation
+
+See raw markdown [here](./docs/index.md), or serve locally.
+
+- [Install mkdocs](https://www.mkdocs.org/getting-started/#installation)
+- Serve locally: `mkdocs serve-docs`

docs/docs/hello.md

@@ -0,0 +1 @@
+../../hello/hello.md

docs/docs/index.md

@@ -0,0 +1,19 @@
+# Contents
+
+## Using examples
+
+To see all commands from within an example directory use: `make help`
+
+On linux, if you do not have `make`, you will need the package `build-essential`.
+
+Note: Examples assume you have aztec tools installed: `bash -i <(curl -s https://install.aztec.network)`
+
+Some commands require having a local network running (without its PXE): `NO_PXE=true aztec start --sandbox`
+The Private eXecution Environment (PXE) within the `aztec-wallet` will be used.
+
+
+## Contributions
+
+Example in this repo are heavily curated to showcase and explain atomic functionality of Aztec, as well as slightly larger examples for broader concepts.
+
+Developers: Pull requests contining examples with code AND documentation that fit the brief will be considered.

docs/mkdocs.yml

@@ -0,0 +1,5 @@
+site_name: My Docs
+nav:
+  - Home: index.md
+  - Hello: hello.md
+theme: readthedocs

hello/Makefile

@@ -0,0 +1,25 @@
+.PHONY: all build gate-flamegraph clean
+
+# Default target
+all: build
+
+# Build the project
+build:
+	aztec-nargo compile
+
+# Generate gate flamegraph of a private function
+gate-flamegraph:
+	@echo "Building gates flamegraph of $(filter-out $@,$(MAKECMDGOALS)) ..."
+	SERVE=1 aztec flamegraph target/hello-Hello.json $(filter-out $@,$(MAKECMDGOALS))
+
+# Clean build artifacts
+clean:
+	rm -rf target/
+
+# Help command
+help:
+	@echo "Available commands:"
+	@echo "  make build  - Compile the project"
+	@echo "  make clean  - Remove build artifacts"
+	@echo "  make gate-flamegraph <function_name> - Generate gate flamegraph for the given private function"
+	@echo "  make help   - Show this help message" 

hello/Nargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "hello"
+type = "contract"
+authors = [""]
+
+[dependencies]
+aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "v0.87.8", directory = "noir-projects/aztec-nr/aztec" }

hello/hello.md

@@ -0,0 +1,151 @@
+# Coding for Execution vs Proving
+
+In this intro example you will:
+
+- Create an Aztec contract from scratch
+- Add Aztec dependencies and macros
+- Appreciate different function types/considerations
+- Measure proving cost
+- Run a local node, deploy/interact with contract
+
+## Self Setup
+
+The steps in this section explain how to recreate a project like this from scratch.
+
+### Create project files and first contract
+
+The flow with Noir is much like that of Rust.
+
+```bash
+# Create project dir and boilerplate files
+aztec-nargo new --contract hello
+```
+
+```bash
+# Add Aztec dependency to `hello/Nargo.toml`
+cd hello
+echo 'aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "v0.87.8", directory = "noir-projects/aztec-nr/aztec" }' >> Nargo.toml
+```
+
+```bash
+# Replace src/main.nr with empty Aztec contract
+echo 'use dep::aztec::macros::aztec; // import aztec macro for use
+
+#[aztec] // use macro for contract
+pub contract Hello {
+  // imports, storage struct, and functions go here
+}' > src/main.nr
+```
+
+### Add a private function
+
+Inside the empty contract, add the following functions and their requisite macro imports:
+
+```rust
+    // ...
+    // import function types
+    use dep::aztec::macros::functions::{private, public};
+
+    #[private] // use macro to wrap for private execution
+    fn mul_8_prv(num: u32) -> u32 {
+        num * 8 // more efficient for proving
+    }
+
+    #[public] // use macro to wrap for public execution
+    fn mul_8_exe(num: u32) -> u32 {
+        num << 3 // more efficient for execution
+    }
+
+// ...
+```
+
+## Understanding performance
+
+Since private functions are executed client side and the proof of execution is used to advance private state, the size of the circuit is important. The size of a circuit is measured in gates.
+
+Public functions are executed as part of the protocol, so the total cost of operations is important, which is measured in gas.
+
+We can compile and then calculate the gates required for this private function.
+
+## Building the project
+### Compile the contract
+
+For simplicity this project uses make, where `make build` calls `aztec-nargo compile`. Build is the default make target so for convenience simply compile the contract with:
+
+```bash
+# From directory with Markefile & Nargo.toml
+make
+```
+
+### Showing gate counts in a flamegraph
+
+The gate flamegraph of a specific function can be calculate and presented by passing the function name to:
+
+```bash
+make gate-flamegraph <function-name>
+```
+
+eg: `make gate-flamegraph mul_8_prv`
+
+Go to the URL in the command output to see the gate count total, and of each sub-section. The exported .svg file is in the `target` directory.
+
+## Using the project
+### Deploy contract to Aztec dev node
+
+First we'll run a local dev environment, aka "sandbox", which includes:
+
+- an Aztec dev node
+- a Private eXecution Environment (PXE)
+
+Both can be started together in a terminal with: `aztec start --sandbox`
+
+We will now use the `aztec-wallet` to interact with them.
+
+```bash
+# Register test account contract addresses from sandbox, into the pxe
+aztec-wallet import-test-accounts
+aztec-wallet get-alias accounts # show account contract aliases -> addresses
+```
+
+Use the test account aliased to, `test0`, to deploy the compiled contract:
+
+```bash
+aztec-wallet deploy --no-init target/hello-Hello.json --from test0 --alias hello
+```
+
+Note:
+
+- `no-init` is specified because we do not have or need a constractor/`initializer` for this example
+- The last param requests the deployed contract address be aliased to `hello`
+
+### Command summary script
+
+For convenience/reference, these commands are consolidated in a script. To see them:
+```bash
+./run.sh --help
+```
+
+### Profile gate count
+
+To see a breakdown of proving times and gate counts per inner-circuit:
+
+```bash
+./run.sh gate-profile mul_8_prv 8
+```
+
+This command expects the contract in `hello.nr` to be deployed, and the contract address aliased to `hello`.
+
+This uses the deployed contract to provide a breakdown of time and gates for each inner function. This will become useful when comparing 
+
+## Compare implementations
+
+
+
+## Calling private functions
+
+
+
+## Further reading
+
+- For more about optimisation, see [Thinking in Circuits](https://noir-lang.org/docs/explainers/explainer-writing-noir), and [aztec-examples]().
+- To see a side-by-side comparison with Rust, see [noir_by_example](https://github.com/noir-lang/noir-examples/tree/master/noir_by_example#readme).

hello/run.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+
+usage() {
+  cat <<EOF
+Usage: $0 <command> [options]
+
+Commands:
+  Setup:
+    sandbox                                Run Aztec node + pxe locally
+    import-test-accounts                   Import test accounts into aztec-wallet
+    deploy-hello                           Deploy the hello contract without initialization
+  gate-flamegraph <function_name>          Generate gate flamegraph for the specified private function
+  gate-profile <function_name> [args...]   Show total gates for the specified private function with optional arguments
+  -h, --help                               Show this help message
+
+Examples:
+  $0 sandbox
+  $0 import-test-accounts
+  $0 deploy-hello
+  $0 gate-flamegraph myFunction
+  $0 gate-profile myFunction 1 2 3
+EOF
+}
+
+if [[ $# -lt 1 ]] || [[ "$1" == "-h" ]] || [[ "$1" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+COMMAND="$1"
+shift
+
+case "$COMMAND" in
+  sandbox)
+    aztec start --sandbox
+    ;;
+  import-test-accounts)
+    aztec-wallet import-test-accounts
+    ;;
+  deploy-hello)
+    aztec-wallet deploy --no-init target/hello-Hello.json --from test0 --alias hello
+    ;;
+  gate-flamegraph)
+    if [[ $# -lt 1 ]]; then
+      echo "Error: function_name required for flamegraph"
+      usage
+      exit 1
+    fi
+    SERVE=1 aztec flamegraph target/hello-Hello.json "$1"
+    ;;
+  gate-profile)
+    if [[ $# -lt 1 ]]; then
+      echo "Error: function_name required for profile"
+      usage
+      exit 1
+    fi
+    fn="$1"; shift
+    aztec-wallet profile "$fn" --args "$@" --contract-address hello -f test0
+    ;;
+  *)
+    echo "Unknown command: $COMMAND"
+    usage
+    exit 1
+    ;;
+esac