pr review changes

circuits/cpp/src/aztec3/constants.hpp

@@ -39,6 +39,7 @@ constexpr size_t RETURN_VALUES_LENGTH = 4;
  *
  */
 
+// docs:start:constants
 // "PER CALL" CONSTANTS
 constexpr size_t MAX_NEW_COMMITMENTS_PER_CALL = 4;
 constexpr size_t MAX_NEW_NULLIFIERS_PER_CALL = 4;
@@ -63,6 +64,7 @@ constexpr size_t MAX_OPTIONALLY_REVEALED_DATA_LENGTH_PER_TX = 4;
 constexpr size_t MAX_READ_REQUESTS_PER_TX = MAX_PRIVATE_CALL_STACK_LENGTH_PER_CALL * MAX_READ_REQUESTS_PER_CALL;
 constexpr size_t NUM_ENCRYPTED_LOGS_HASHES_PER_TX = 1;
 constexpr size_t NUM_UNENCRYPTED_LOGS_HASHES_PER_TX = 1;
+// docs:end:constants
 
 ////////////////////////////////////////////////////////////////////////////////
 // ROLLUP CONTRACT CONSTANTS - constants used only in l1-contracts

docs/docs/about_aztec/roadmap/engineering_roadmap.md

@@ -1,4 +1,4 @@
-# Engineering Roadmap
+# Engineering Wishlist
 
 The engineering roadmap is long. There are no timings assigned here. In a loose priority order:
 
@@ -9,33 +9,18 @@ The engineering roadmap is long. There are no timings assigned here. In a loose
 - Encouraging contributions to 'good first issue' issues.
 - Release notes.
 - Versioning.
-- AZIPs (improvements)
-- AZRCs (standardisation efforts)
+- Aztec Improvement Proposals (AZIPs)
+- Aztec Requests for Comment (AZRCs)
 
 ## Benchmarking
 
 - Gather metrics about everything, to guide future decisions.
 
 ## Standardisation efforts
 
-- Aztec Smart Contract coding patterns
-    - Private State
-    - When to use `Singleton` vs `Set`.
-    - Custom Notes & Nullifiers
-    - Encrypting data for someone else, via encrypted logs.
-    - Account contracts
-    - Inter-layer messaging (L1<\>L2, public<\>private)
-    - Function calls
-    - Do not return private data from an external function (unless you've thought about the consequences)
-    - Do not pass private data as an argument to another function (unless you've thought about the consequences)
-    - Any public function call is leaky.
-    - Unencrypted logs are leaky.
-    - The timing of transactions can be leaky.
-    - The number of new commitments / nullifiers / log fields, is leaky. 
-        - Standardise tranches of 'sizes' of commitments/nullifiers/logs to ensure functions look the same. E.g. Tranches for 2, 4, 8, 16, 32.
-        - Perhaps have a version or 'mode' of the kernel circuit, which pads all arrays with random fields, up to some tranched 'size' of commitments/nullifiers/logs.
-- Access Control (whitelists/blacklists) - probably needs the Slow Updates tree (or something).
-- Basic example private tokens
+- Recommended Aztec smart contract coding patterns
+- Access Control (whitelists/blacklists) - probably needs the Slow Updates tree (or something similar).
+- Basic _example_ private tokens
     - Including recursive calls to 'get_notes'.
 - Compliant private tokens
 - Private NFTs
@@ -177,8 +162,6 @@ Some example features:
 
 ## Tooling
 
-Work more closely with the Noir tooling team. Upskill the wider engineering team to contribute to tooling.
-
 ## Proper Circuits
 
 ### Redesign
@@ -233,24 +216,26 @@ Also, we do a lot of sha256-compressing in our kernel and rollup circuits for da
 - Private data must not be returned to an app, unless the user authorises it.
 
 ## Validation: preventing execution of malicious bytecode
-- A node should check that some purported bytecode for a particular contract address matches the data in the contract tree.
+- A node should check that the bytecode provided by an application for a given app matches the leaf in the contract tree to ensure that user doesn't execute unplanned code which might access their notes.
+
+## Fuzz Testing
 
-## Fuzz Testing?
+## Formal Verification
 
-## Formal Verification?
+An investigation into how formal verification techniques might improve the security of Aztec software.
 
 ## P2P network
 
 - A robust p2p network for the tx pool and the proof pool.
 
 ## Hashes
 
-- New Pedersen
-- Poseidon
+- An improved, standardised Pedersen hash in barretenberg.
+- Poseidon hashing in barretenberg.
 
 ## Tree epochs
-- Nullifier tree
-- Maybe other trees. TBD.
+- Nullifier tree epochs
+- Maybe other tree epochs.
 
 ## Chaining txs
 - We have the ability to spend pending notes (which haven't-yet been added to the tree) _within the context of a single tx_.

docs/docs/about_aztec/roadmap/features_initial_ldt.md

@@ -1,33 +1,33 @@
 ---
-title: Intial Sandbox Features
+title: Initial Sandbox Features
 ---
 
 The Aztec Sandbox is intended to provide developers with a lightweight & fast node, with features similar to Ethereum's Ganache or Anvil 'local node' packages.
 
-Devs should be able to quickly spin up local, emulated instances of an Ethereum blockchain and an Aztec encrypted rollup, and start deploying confidential contracts and submitting confidential txs.
+Devs should be able to quickly spin up local, emulated instances of an Ethereum blockchain and an Aztec encrypted rollup, and start deploying private contracts and submitting private txs.
 
 Here's a summary of the features we intend to support with the first release of the Aztec Sandbox.
 
 ## Noir Contracts
 
 - Noir `contract` scopes.
   - Declare a `contract`, containing a collection of state variables and functions.
-- `secret` state variables:
-  - `read`, `write`, and `delete` `secret` state variables within `secret` functions.
-- public (non-`secret`) state variables:
+- private state variables:
+  - `read`, `write`, and `delete` private state variables within private functions.
+- public (non-private) state variables:
   - Manipulate 'public' state in a familiar way to Ethereum state.
-- `secret` functions
-  - May read and modify `secret` state.
+- private functions
+  - May read and modify private state.
 - public functions
   - May read and modify public state.
 - `constructor` functions, for initialising contract state.
 - `import` other Noir contracts, so their functions may be called.
 - Nested function calls, for contract composability
-  - `secret` functions can call `secret` functions of other contracts, and receive return values.
-  - `secret` functions can call public functions any contract.
-  - public functions can call `secret` functions of any contract.
+  - private functions can call private functions of other contracts, and receive return values.
+  - private functions can call public functions any contract.
+  - public functions can call private functions of any contract.
   - public functions can call public functions of other contracts, and receive return values.
-  - `secret` functions can be called recursively.
+  - private functions can be called recursively.
   - public functions can be called recursively.
 - Send messages from Noir contracts to Ethereum L1, for consumption by L1 smart contracts.
   - Useful, for example, if writing an app to withdraw funds from L2 to L1.
@@ -59,7 +59,7 @@ A typescript wrapper for making RPC calls to an Aztec LDT node.
 A bundle of packages which emulate the actions of all eventual Aztec network participants. The goal is for developer experience to be akin to Ganache / Anvil.
 
 - Aztec RPC Client
-  - Simulate and/or execute `secret` functions locally.
+  - Simulate and/or execute private functions locally.
 - Aztec Public Node
   - Broadcasts a user's txs to the tx pool.
   - Simulate public functions locally.

docs/docs/about_aztec/roadmap/main.md

@@ -0,0 +1,5 @@
+<!-- # Full Roadmap
+
+:::danger
+Placeholder in case we want to include the org roadmap (higher level, non-engineering).
+::: -->

docs/docs/dev_docs/contracts/contract.md

@@ -2,7 +2,7 @@
 title: Contract
 ---
 
-# `contract`
+# Contract
 
 A contract is a collection of persistent [state variables](#state-variables), and [functions](#functions) which may modify these persistent states. Functions and states 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](#calling-functions) to an external function of that other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called.
 

docs/docs/dev_docs/contracts/main.md

@@ -30,10 +30,6 @@ There are a number of tools to make writing Noir Contracts more pleasant. See [h
 Starter kit
 :::
 
-## Workflow
-
-See [here](./workflow.md) for a suggestion for how to develop your Aztec.nr contract.
-
 
 ## Example Noir Contract
 
@@ -46,6 +42,3 @@ In keeping with the origins of blockchain, here's an example of a simple private
 :::info Disclaimer
 Please note that any example contract set out herein is provided solely for informational purposes only and does not constitute any inducement to use or deploy. Any implementation of any such contract with an interface or any other infrastructure should be used in accordance with applicable laws and regulations.
 :::
-
-## Next steps
-You can read more about writing contracts [here](./syntax.md), and then move to compiling it which is detailed [here](./compiling.md).

docs/docs/dev_docs/contracts/syntax.md

@@ -13,10 +13,6 @@ Aztec.nr contains abstractions which remove the need to understand the low-level
   - secrets
 - Functions for communicating with Ethereum L1
 
-To import Aztec.nr into your Aztec contract project, simply include it as a dependency:
-
-:::danger TODO
-https://github.com/AztecProtocol/aztec-packages/issues/1335
-:::
+To import Aztec.nr into your Aztec contract project, simply include it as a dependency.
 
 #include_code importing-aztec /yarn-project/noir-contracts/src/contracts/private_token_contract/Nargo.toml toml

docs/docs/dev_docs/limitations/main.md

@@ -40,10 +40,6 @@ There are plans to resolve all of the below. See also the [engineering roadmap](
 
 None of the Sandbox code is audited. It's being iterated-on every day. It will not be audited for quite some time.
 
-#### What are the consequences?
-
-TODO: link to a disclaimer.
-
 
 ### No Proofs!
 
@@ -89,7 +85,6 @@ Apps won't yet be able to allow for any L2 fee logic. Once fees are introduced,
 ### Basic Keys and Addresses!
 
 The way in which keypairs and addresses are currently derived and implemented (inside the Sandbox) is greatly over-simplified, relative to future plans.
-See [current keys] and [future keys].
 
 They're so over-simplified that they're known to be insecure. Other features have been prioritised so-far in Sandbox development. Please refer to the [future roadmap](../../about_aztec/roadmap/engineering_roadmap.md)
 
@@ -114,7 +109,7 @@ Please open new discussions on [discourse](http://discourse.aztec.network) or op
 ### It's not-yet decentralised
 
 It's an emulated blockchain entirely contained within your own laptop! It's centralised by design!
-As for deploying this all to mainnet, a decentralised sequencer selection and prover selection protocols are still being discussed. There are plans for decentralised testnets in 2024.
+As for deploying this all to mainnet, a decentralised sequencer selection and prover selection protocols are still [being discussed](https://discourse.aztec.network/t/request-for-proposals-decentralized-sequencer-selection/350). There are plans for decentralised testnets in 2024.
 
 
 ### You can't read mutable public state from a private function
@@ -130,7 +125,7 @@ Reading public state from a private contract will be a common pattern. For examp
 
 A contract can't perform a delegatecall yet (if ever). Delegatecalls are quite a controversial feature of the EVM.
 
-### No privacy-preserving queries to public nodes
+### No privacy-preserving queries to nodes
 
 Ethereum has a notion of a 'full node' which keeps-up with the blockchain and stores the full chain state. Many users don't wish to run full nodes, so rely on 3rd-party 'full-node-as-a-service' infrastructure providers, who service blockchain queries from their users.
 
@@ -176,8 +171,8 @@ There are [ongoing discussions](https://discourse.aztec.network/t/who-is-msg-sen
 
 #### What are the consequences?
 
-When a private function makes a call to a public function, the `msg_sender` of the calling function will be given to the public world. Most critically, includes if the `msg_sender` is an account contract.
-This will be patched in the near future, but unfortunately, app developers might need to 'overlook' this privacy leakage until then, with the assumption that it will be fixed. Thanks for your patience :)
+When a private function makes a call to a public function, the `msg_sender` of the calling function will be given to the public world. Most critically, this includes if the `msg_sender` is an account contract.
+This will be patched in the near future, but unfortunately, app developers might need to 'overlook' this privacy leakage until then, with the assumption that it will be fixed. But note, one possible 'patch' might be to set `msg_sender` to `0` for all private -> public calls. This might cause breaking changes to your public functions, if they rely on reading `msg_sender`. There are patterns to work around this, but they wouldn't be pretty, and we won't go into details until a solution is chosen. Sorry about this, and thanks for your patience whilst we work this out :)
 
 
 ### New Privacy Standards are required
@@ -197,6 +192,10 @@ Due to the rigidity of zk-SNARK circuits, there are upper bounds on the amount o
 
 > Blockchain developers are no stranger to restrictive computational environments. Ethereum has gas limits, local variable stack limits, call stack limits, contract deployment size limits, log size limits, etc.
 
+Here are the current constants:
+
+#include_code constants circuits/cpp/src/aztec3/constants.hpp cpp
+
 #### What are the consequences?
 
 When you write an [Aztec.nr](../contracts/main.md) [function](../contracts/functions.md), there will be upper bounds on the following: