docs: limitations, privacy, roadmap

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/README.md

@@ -118,3 +118,8 @@ You can embed code snippets into a `.md`/`.mdx` file from code which lives elsew
 - You can add as a last optional parameter a comma-separated list of options to tweak the display of the code block, for example:
   - `#include_code hello path/from/repo/root/to/file.ts typescript noTitle,noLineNumbers,noSourceLink`
 - Ironically, we can't show you a rendering of these examples, because this README.md file doesn't support the `#include_code` macro!
+
+
+### Another way to include code.
+
+See [here](./src/components/GithubCode/index.js), although this approach is flakier, so the above `#include_code` macro is preferred.

docs/docs/about_aztec/roadmap/engineering_roadmap.md

@@ -0,0 +1,265 @@
+# Engineering Wishlist
+
+The engineering roadmap is long. There are no timings assigned here. In a loose priority order:
+
+## Sandbox Community Support
+
+- Triage on discord / discourse / github.
+- Iterating on the docs and code, given people's issues.
+- Encouraging contributions to 'good first issue' issues.
+- Release notes.
+- Versioning.
+- Aztec Improvement Proposals (AZIPs)
+- Aztec Requests for Comment (AZRCs)
+
+## Benchmarking
+
+- Gather metrics about everything, to guide future decisions.
+
+## Standardisation efforts
+
+- 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
+- Public tokens
+- Depositing and withdrawing tokens
+    - L1<\>L2
+    - public<\>private
+- The Aztec Connect bridging pattern
+- Using Keys (the fully-featured version of keys that we want to build)
+- Plume nullifiers
+- Negative reputation example
+- Anti-denial-of-service
+- Combining Aztec with MPC
+
+## Polishing what we have
+
+- Refactoring sprints.
+    - Reduce tech debt.
+    - More tests.
+
+## Enforcing correct ordering Public & Private State Transitions
+
+## Enforcing correct ordering of other 'side effects'
+- Log ordering
+- Enqueued public function calls
+
+## What data actually needs to be submitted on-chain?
+- For Public Functions:
+    - Just emit the initially-enqueued public function request data? (The 'inputs' of the tx);
+        - I.e. contract address, function selector, args, call_context.
+    - OR, Just emit the final state transitions? (The 'outputs' of the tx)
+        - I.e. the leaf indices and new values of the public data tree; and the new commitments/nullifiers of the private data tree; and logs; and l2->L1 messages.
+
+## Proper specs
+
+- Write detailed specs, given recent protocol changes.
+- Review the code to ensure it matches what we _think_ the protocol is.
+- Open issues to ensure the code matches the spec.
+- (Note: bringing cryptographers into the fold (to review specs) is a separate section, later in this doc).
+
+## Iterate on the Sandbox
+
+Based on community feedback, we'll need some teams to iterate on Sandbox features and fix bugs.
+
+## Iterate on the Aztec Smart Contract Library
+
+## Iterating on CI
+
+CI takes up a significant amount of time. It gets its own section here, so we remember it exists.
+
+## Sequencer & Prover Selection protocols
+
+- Decide on protocol
+- Spec
+- Build.
+
+## Upgradeability
+
+- Decide on protocol
+- Spec
+- Build.
+
+## Fees
+
+- Design the Protocol
+    - Interdependence on the Sequencer & Upgradeability protocols.
+    - Pay fees in 1 currency, or fee abstraction?
+    - Escrowing fees
+    - Rebates
+    - L1->L2 message fees.
+    - L2->L1 fees
+    - Etc.
+- Build it.
+    - Gas metering
+    - Etc.
+
+## Note Discovery
+
+- Note Discovery RFP
+- Decide on the protocol
+- Spec
+- Build it.
+
+## Privacy-preserving queries to public nodes
+
+- Explore PIR
+- Explore alternatives
+- Implement
+
+## Keys
+
+- Write up keys spec
+- Get internal comments
+- Do a RFC from the external community
+- Implement
+
+## Slow Updates tree?
+
+We _need_ a way to read mutable public data from a private function.
+
+## Contract classes and instances?
+
+- There's a suggestion to introduce contract classes.
+
+## Delegatecalls vs SetCode
+- Which? (if at all)
+
+## Remove the contracts tree? 🤯
+
+- There's a suggestion to remove the notion of a contracts tree. What do we actually need the tree for? To check that a vk hash exists for a particular contract address?
+- If the contract address contains the function tree, and it also contains data about the constructor args to that contract, then perhaps we don't need the contract tree to exist.
+- We might still need the notion of a 'deployment':
+    -  to broadcast a contract's bytecode;
+    -  to 'reserve' a contract address;
+    -  and possibly to prevent a constructor from being executed twice (although an app could do this ("constructor abstraction")).
+
+## Cryptography review checkpoint
+
+- Once we have specs (see above), we should review the rigour and secureness to our protocol.
+    - Choice of hashes
+    - Domain separation
+    - Choice of encryption scheme
+    - Keys
+    - A security review of the protocol as a whole
+
+## Testing UX team
+
+A team focussed on testing and debugging UX.
+This team should have free rein to design and add any features they see fit.
+
+Some example features:
+- Writing contract tests in Noir.
+    - Mocking oracles.
+- Taking inspiration from other testing frameworks.
+- Much more detailed logging if things go wrong.
+- Errors which only spit out opaque 254-bit hex numbers are bad.
+    - Ensure all circuits are fed the human-readable information underlying all of these hex numbers.
+    - If tree root comparisons (expected vs actual) fail, human-readable details about the leaves in trees should be provided.
+
+## Tooling
+
+## Proper Circuits
+
+### Redesign
+- The Bus
+    - The bus will have an impact on the way we design the circuit logic.
+    - We can hopefully avoid hashing in circuit 1 and unpacking that hash in circuit 2.
+    - Understand the 'bus' and how we can use it to pass variable amounts of data between recursive circuit iterations.
+    - Redesign all circuit logic to allow for the variable-sized arrays that the 'bus' enables.
+- Enable 'dynamic/variable-sized **loops**'
+    - allow each `for` loop (eg read requests, insertions, commitment squashing, call stack processing, bip32 key derivation, etc.) to vary in size, by deferring each loop to its own final circuit. This would require complex folding stuff.
+    - This would give much more flexibility over the sizes of various arrays that a circuit can output. Without it, if one array of an app circuit needs to be size 2000, but other arrays aren't used, we'd use a kernel where every array is size 2048, meaning a huge amount of unnecessary loops of computation for those empty arrays.
+- Improvements
+    - We can definitely change how call stacks are processed within a kernel, to reduce hashing.
+    - Squash pending commitments/nullifiers in every kernel iteration, to enable a deeper nested call depth.
+- Topology of a rollup
+    - Revisit the current topology:
+        - We can make the rollup trees 'wonky' (rather than balanced), meaning a sequencer doesn't need to prove a load of pointless 'padding' proofs?
+            - This would also enable new txs (entering the tx pool) to be added to a rollup block 'on-the-fly' (mid way through a rollup being proven) - but of course, the sequencer selection protocol might require an up-front commitment, so this might not be possible for that reason (sad face).
+        - We can definitely redesign the public kernel circuit to be a '2x2' topology (i.e. a tree of public kernel proofs), to get a logarithmic speed-up (parallelism). The question is, with folding schemes, do we need that optimisation?
+
+#### Refactor of packing & unpacking data in circuits
+
+We often pack data in circuit A, and then unpack it again in circuit B.
+- args_hash
+- return_values_hash
+- call stacks
+- read requests
+- etc.
+
+Also, for logs in particular, we allow arbitrary-sized logs. But this requires sha256 packing inside an app circuit (which is slow) (and sha256 unpacking in Solidity (which is relatively cheap)). Perhaps we also use the bus ideas for logs, to give _some_ variability in log length, but up to an upper bound. 
+
+Also, we do a lot of sha256-compressing in our kernel and rollup circuits for data which must be checked on-chain, but grows exponentially with every round of iteration. E.g.: new contract deployment data, new nullifiers, new commitments, public state transition data, etc. This might be unavoidable. Maybe all we can do is use polynomial commitments when the EIP-4844 work is done. But maybe we can use the bus for this stuff too.
+
+### Write proper circuits
+
+### The Public VM Circuit
+
+- Design it
+- Build it
+
+### The Brillig Bytecode Commitment Circuit
+
+- A circuit which proves the brillig bytecode being emitted matches the polynomial commitment to that bytecode.
+
+### Decide on constants!
+
+### Honk -> Ultra Squisher Circuit
+
+### Ultra -> Standard Squisher Circuit
+
+## Authentication: access to private data
+- 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 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
+
+## 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
+
+- An improved, standardised Pedersen hash in barretenberg.
+- Poseidon hashing in barretenberg.
+
+## Tree epochs
+- 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_.
+- We need the ability to spend pending notes (which haven't yet been added to the tree) across different txs, within the context of a single rollup.
+    - This happens if Alice generates two txs X & Y, where tx Y spends notes from tx X. If we want Alice to be able to generate these txs in parallel (without interacting with the network at all), we need a way for tx Y to spend notes before they've been added to the tree. The 'chaining tx' concepts from Aztec Connect can enable this.
+- This added _a lot_ of complexity to Aztec Connect. Especially around fees, iirc. Caution needed.
+
+## EIP-4844
+
+- Understand it. Spec it. Build it.
+- Includes:
+    - Smart Contract changes
+    - Circuit changes
+    - A circuit to prove equivalence vs a BLS12-381 polynomial commitment.
+
+## Make it all work in a browser
+
+## Code Freeze
+
+## Internal Audit
+
+## External Audits
+
+
+
+
+

docs/docs/about_aztec/roadmap/features_initial_ldt.md

@@ -1,37 +1,33 @@
 ---
-title: Sandbox
+title: Initial Sandbox Features
 ---
 
-:::info
-We're aiming for a minimal version of an Aztec Sandbox -- with the below features -- in Q3.
-:::
+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.
 
-The Aztec Sandbox Node 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.
@@ -63,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).
+::: -->