Prv fn example update+doc

Author: jzaki

.vscode/settings.json

@@ -14,6 +14,6 @@ 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.
+Examples 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.
+Developers: Pull requests containing examples with code AND documentation that fit the brief will be considered.

docs/docs/index.md

@@ -4,4 +4,4 @@ type = "contract"
 authors = [""]
 
 [dependencies]
-aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "v0.87.8", directory = "noir-projects/aztec-nr/aztec" }
+aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "v0.87.9", directory = "noir-projects/aztec-nr/aztec" }

hello/Nargo.toml

@@ -24,7 +24,7 @@ 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
+echo 'aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "v0.87.9", directory = "noir-projects/aztec-nr/aztec" }' >> Nargo.toml
 ```
 
 ```bash
@@ -37,26 +37,49 @@ pub contract Hello {
 }' > src/main.nr
 ```
 
-### Add a private function
+### Division example
 
-Inside the empty contract, add the following functions and their requisite macro imports:
+For demonstration purposes we'll show an implementation of division that is efficient for proving in private, but has an extra cost in public.
+
+Inside the empty contract, we'll add the same function as public and private; outside will have the helper function.
 
 ```rust
-    // ...
+#[aztec]
+pub contract Hello {
+    use crate::divide; // Noir helper function outside of contract
+
     // 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
+    fn div_prv(dividend: u32, divisor: u32) -> u32 {
+        //Safety: constrain after
+        let (quotient, remainder) = unsafe { divide(dividend, divisor) };
+        assert(quotient * divisor + remainder == dividend);
+        quotient
     }
 
     #[public] // use macro to wrap for public execution
-    fn mul_8_exe(num: u32) -> u32 {
-        num << 3 // more efficient for execution
+    fn div_exe(dividend: u32, divisor: u32) -> u32 {
+        let (quotient, remainder) = divide(dividend, divisor);
+        quotient
     }
-
-// ...
+} // contract Hello
+
+// iterative divide function
+pub unconstrained fn divide(dividend: u32, divisor: u32) -> (u32, u32) {
+    let mut quotient: u32 = 0;
+    let mut remainder: u32 = dividend;
+    if divisor == 0 {
+        (0, 0)
+    } else {
+        while remainder >= divisor {
+            remainder = remainder - divisor;
+            quotient = quotient + 1;
+        }
+        (quotient, remainder)
+    }
+}
 ```
 
 ## Understanding performance
@@ -65,7 +88,7 @@ Since private functions are executed client side and the proof of execution is u
 
 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.
+We can compile and then calculate the gates required for the private function, `div_prv`. To see gas for the public function, we will deploy the contract and call `div_exe`.
 
 ## Building the project
 ### Compile the contract
@@ -82,12 +105,36 @@ make
 The gate flamegraph of a specific function can be calculate and presented by passing the function name to:
 
 ```bash
-make gate-flamegraph <function-name>
+make gate-flamegraph div_prv
 ```
 
-eg: `make gate-flamegraph mul_8_prv`
+In the terminal you'll see: `Opcode count: 775, Total gates by opcodes: 5197, Circuit size: 5962`
+
+Also 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.
+
+### Unconstrained cost in private
 
-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.
+To assess the cost of the unconstrained function in private, lets replace its call with a result directly, eg `(2, 2)`
+
+```rust
+    #[private] // use macro to wrap for private execution
+    fn div_prv(dividend: u32, divisor: u32) -> u32 {
+        //Safety: constrain after
+        let (quotient, remainder) = (2, 2); //unsafe { divide(dividend, divisor) };
+        assert(quotient * divisor + remainder == dividend);
+        quotient
+    }
+
+```
+
+Now calculating the gates flamegraph again:
+```bash
+make gate-flamegraph div_prv
+```
+
+In the terminal you'll see the same counts: `Opcode count: 775, Total gates by opcodes: 5197, Circuit size: 5962`
+
+That is, the unconstrained function does NOT contribute to gate count in the private function. So the result from this unconstrained function must then be verified in the calling constrained function (via `assert`).
 
 ## Using the project
 ### Deploy contract to Aztec dev node
@@ -115,7 +162,7 @@ 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
+- `no-init` is specified because we do not have or need a constructor/`initializer` for this example
 - The last param requests the deployed contract address be aliased to `hello`
 
 ### Command summary script
@@ -125,24 +172,75 @@ For convenience/reference, these commands are consolidated in a script. To see t
 ./run.sh --help
 ```
 
-### Profile gate count
+### Showing gas cost for a transaction
 
-To see a breakdown of proving times and gate counts per inner-circuit:
+With the sandbox running and contract deployed (see earlier section), we can now interact with the public function:
 
 ```bash
-./run.sh gate-profile mul_8_prv 8
+./run.sh hello-fn div_exe 8 3
 ```
 
-This command expects the contract in `hello.nr` to be deployed, and the contract address aliased to `hello`.
+```bash
+Transaction has been mined
+ Tx fee: 39680550
+ ...
+```
 
-This uses the deployed contract to provide a breakdown of time and gates for each inner function. This will become useful when comparing 
+Lets assess the cost of the unconstrained function in public by replacing the call with a result:
 
-## Compare implementations
+```rust
+    let (quotient, remainder) = (2, 2); // divide(dividend, divisor);
+```
 
+Compiling, deploying, then calling:
 
+```bash
+make
+./run.sh hello-deploy
+./run.sh hello-fn div_exe 8 3
+```
+
+The result will show a lower gas cost:
+```bash
+Transaction has been mined
+ Tx fee: 33770160
+```
+
+That is, the unconstrained function call from public contributes to the cost.
+
+### Comparison
+
+The above example highlights that coding things well in private may have unexpected costs if used in public.
+
+Another example of this is in the use of memory. This is cheaper in private circuits (witness values) and expensive in public (operations to read across different memory locations).
+
+## Further use
+
+### Testing output
 
-## Calling private functions
+For a quick sneak peak into testing, see the functions after the Noir divide function: `setup()` and `test_funcs()`. Notice the more explicity way of calling a function from a private or public context.
+
+Tests are simply run with the command: `aztec test`
+
+Under the hood this does two things:
+- Starts a Testing eXecution Environment - `aztec start --txe --port=8081`
+- Runs nargo tests pointing to the txe as an oracle - `nargo test --silence-warnings --pedantic-solving --oracle-resolver http://127.0.0.1:8081`
+
+We'll modify the second command to show the `println` output:
+- Start TXE - `aztec start --txe --port=8081` (in a separate terminal)
+- Test - `nargo test --oracle-resolver http://127.0.0.1:8081 --show-output`
+
+### Profile gate count
+
+To see a breakdown of proving times and gate counts per inner-circuit:
+
+```bash
+./run.sh gate-profile div_prv 8 3
+```
+
+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 calls into contexts.
 
 
 ## Further reading

hello/hello.md

@@ -11,6 +11,8 @@ Commands:
     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
+  hello-sim-fn <function_name> [args...]   Simulate a function call on deployed hello contract
+  hello-fn <function_name> [args...]       Call a function on deployed hello contract
   -h, --help                               Show this help message
 
 Examples:
@@ -19,6 +21,8 @@ Examples:
   $0 deploy-hello
   $0 gate-flamegraph myFunction
   $0 gate-profile myFunction 1 2 3
+  $0 hello-sim-fn myFunction 1 2 3
+  $0 hello-fn myFunction 1 2 3
 EOF
 }
 
@@ -57,6 +61,24 @@ case "$COMMAND" in
     fn="$1"; shift
     aztec-wallet profile "$fn" --args "$@" --contract-address hello -f test0
     ;;
+  hello-sim-fn)
+    if [[ $# -lt 1 ]]; then
+      echo "Error: function_name required for call"
+      usage
+      exit 1
+    fi
+    fn="$1"; shift
+    aztec-wallet simulate "$fn" --args "$@" --contract-address hello -f test0
+    ;;
+  hello-fn)
+    if [[ $# -lt 1 ]]; then
+      echo "Error: function_name required for call"
+      usage
+      exit 1
+    fi
+    fn="$1"; shift
+    aztec-wallet send "$fn" --args "$@" --contract-address hello -f test0
+    ;;
   *)
     echo "Unknown command: $COMMAND"
     usage

hello/run.sh

@@ -2,45 +2,71 @@ use dep::aztec::macros::aztec;
 
 #[aztec]
 pub contract Hello {
+    use crate::divide;
 
-    use dep::aztec::macros::functions::{private, public, utility};
-    use dep::aztec::prelude::{AztecAddress, FunctionSelector};
+    // import function types
+    use dep::aztec::macros::functions::{private, public};
 
-    #[private]
-    pub fn mul_8_exe(num: u32) -> u32 {
-        num << 3
-    }
+    #[private] // use macro to wrap for private execution
+    fn div_prv(dividend: u32, divisor: u32) -> u32 {
+        //Safety: constrain after
+        let (quotient, remainder) = unsafe { divide(dividend, divisor) };
+        assert(quotient * divisor + remainder == dividend);
+        quotient
+    } // tx fee: 567952000 (with unconstrained divide)
 
-    #[private]
-    pub fn mul_8_prv(num: u32) -> u32 {
-        num * 8
-    }
+    #[public] // use macro to wrap for public execution
+    fn div_exe(dividend: u32, divisor: u32) -> u32 {
+        let (quotient, remainder) = divide(dividend, divisor);
+        quotient
+    } // tx fee: 1945438440 (with unconstrained divide)
+
+}
 
-    #[private]
-    fn math_ops_3_prv(num: u32) -> u32 {
-        let mut result = num;
-        result = context
-            .call_private_function(
-                context.this_address(),
-                FunctionSelector::from_signature("mul_8_prv"),
-                [result as Field],
-            )
-            .get_preimage();
-        result = context
-            .call_private_function(
-                context.this_address(),
-                FunctionSelector::from_signature("mul_8_prv"),
-                [result as Field],
-            )
-            .get_preimage();
-        result = context
-            .call_private_function(
-                context.this_address(),
-                FunctionSelector::from_signature("mul_8_prv"),
-                [result as Field],
-            )
-            .get_preimage();
-        result
+pub unconstrained fn divide(dividend: u32, divisor: u32) -> (u32, u32) {
+    let mut quotient: u32 = 0;
+    let mut remainder: u32 = dividend;
+    if divisor == 0 {
+        (0, 0)
+    } else {
+        while remainder >= divisor {
+            remainder = remainder - divisor;
+            quotient = quotient + 1;
+        }
+        (quotient, remainder)
     }
+}
+
+//////TESTING//////
+use dep::aztec::prelude::AztecAddress;
+use dep::aztec::test::helpers::test_environment::TestEnvironment;
+
+#[test]
+unconstrained fn test_funcs() {
+    let (env, hello_contract_address, user) = setup();
+    env.advance_block_by(1);
+
+    // let result = env.call_private(contract_address, Hello::interface().math_ops_3_prv(8));
+    let result = Hello::at(hello_contract_address).div_prv(8, 3).call(&mut env.private());
+    println(result); // can use println in txe tests, but not aztec functions called by tests. debug_log doesn't work.
+    assert(result == 2, "Expected 2 but got {result}");
+
+    let result = Hello::at(hello_contract_address).div_exe(8, 3).call(&mut env.public());
+    println(result); // can use println in txe tests, but not aztec functions called by tests. debug_log doesn't work.
+    assert(result == 2, "Expected 2 but got {result}");
+}
+
+pub unconstrained fn setup() -> (&mut TestEnvironment, AztecAddress, AztecAddress) {
+    // Setup env, generate keys
+    let mut env = TestEnvironment::new();
+    let user = env.create_account_contract(1);
+
+    // Start the test in the account contract address
+    env.impersonate(user);
+
+    // Deploy token contract
+    let hello_contract = env.deploy_self("Hello").without_initializer();
+    let hello_contract_address = hello_contract.to_address();
 
+    (&mut env, hello_contract_address, user)
 }