docs: initial 'protocol description' toc (#2844)

Just getting the ball rolling on "Describing the protocol". I've set out a loose toc. It's more of a guide / reminder of topics at the moment. We'll rearrange as people start writing, I'm sure. (I also kept the default 'docusaurus tutorial' around in a separate dir, because it might be a useful reference)
AztecProtocol · Oct 16, 2023 · cb18f45 · cb18f45
1 parent 2d498b3
commit cb18f45
Show file tree

Hide file tree

Showing 14 changed files with 281 additions and 43 deletions.
diff --git a/yellow-paper/docs-tutorial-reference/intro.md b/yellow-paper/docs-tutorial-reference/intro.md
@@ -0,0 +1,47 @@
+---
+sidebar_position: 1
+---
+
+# Tutorial Intro
+
+Let's discover **Docusaurus in less than 5 minutes**.
+
+## Getting Started
+
+Get started by **creating a new site**.
+
+Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
+
+### What you'll need
+
+- [Node.js](https://nodejs.org/en/download/) version 16.14 or above:
+  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
+
+## Generate a new site
+
+Generate a new Docusaurus site using the **classic template**.
+
+The classic template will automatically be added to your project after you run the command:
+
+```bash
+npm init docusaurus@latest my-website classic
+```
+
+You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
+
+The command also installs all necessary dependencies you need to run Docusaurus.
+
+## Start your site
+
+Run the development server:
+
+```bash
+cd my-website
+npm run start
+```
+
+The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
+
+The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
+
+Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
diff --git a/...aper/docs/tutorial-basics/_category_.json → ...reference/tutorial-basics/_category_.json b/...aper/docs/tutorial-basics/_category_.json → ...reference/tutorial-basics/_category_.json
diff --git a/...r/docs/tutorial-basics/congratulations.md → ...erence/tutorial-basics/congratulations.md b/...r/docs/tutorial-basics/congratulations.md → ...erence/tutorial-basics/congratulations.md
diff --git a/...ocs/tutorial-basics/create-a-blog-post.md → ...nce/tutorial-basics/create-a-blog-post.md b/...ocs/tutorial-basics/create-a-blog-post.md → ...nce/tutorial-basics/create-a-blog-post.md
diff --git a/...docs/tutorial-basics/create-a-document.md → ...ence/tutorial-basics/create-a-document.md b/...docs/tutorial-basics/create-a-document.md → ...ence/tutorial-basics/create-a-document.md
diff --git a/...per/docs/tutorial-basics/create-a-page.md → ...eference/tutorial-basics/create-a-page.md b/...per/docs/tutorial-basics/create-a-page.md → ...eference/tutorial-basics/create-a-page.md
diff --git a/.../docs/tutorial-basics/deploy-your-site.md → ...rence/tutorial-basics/deploy-your-site.md b/.../docs/tutorial-basics/deploy-your-site.md → ...rence/tutorial-basics/deploy-your-site.md
diff --git a/...ocs/tutorial-basics/markdown-features.mdx → ...nce/tutorial-basics/markdown-features.mdx b/...ocs/tutorial-basics/markdown-features.mdx → ...nce/tutorial-basics/markdown-features.mdx
diff --git a/...aper/docs/tutorial-extras/_category_.json → ...reference/tutorial-extras/_category_.json b/...aper/docs/tutorial-extras/_category_.json → ...reference/tutorial-extras/_category_.json
diff --git a/...torial-extras/img/docsVersionDropdown.png → ...torial-extras/img/docsVersionDropdown.png b/...torial-extras/img/docsVersionDropdown.png → ...torial-extras/img/docsVersionDropdown.png
diff --git a/...cs/tutorial-extras/img/localeDropdown.png → ...ce/tutorial-extras/img/localeDropdown.png b/...cs/tutorial-extras/img/localeDropdown.png → ...ce/tutorial-extras/img/localeDropdown.png
diff --git a/...s/tutorial-extras/manage-docs-versions.md → ...e/tutorial-extras/manage-docs-versions.md b/...s/tutorial-extras/manage-docs-versions.md → ...e/tutorial-extras/manage-docs-versions.md
diff --git a/...cs/tutorial-extras/translate-your-site.md → ...ce/tutorial-extras/translate-your-site.md b/...cs/tutorial-extras/translate-your-site.md → ...ce/tutorial-extras/translate-your-site.md
diff --git a/yellow-paper/docs/intro.md b/yellow-paper/docs/intro.md
@@ -2,46 +2,237 @@
 sidebar_position: 1
 ---
 
-# Tutorial Intro
-
-Let's discover **Docusaurus in less than 5 minutes**.
-
-## Getting Started
-
-Get started by **creating a new site**.
-
-Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
-
-### What you'll need
-
-- [Node.js](https://nodejs.org/en/download/) version 16.14 or above:
-  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
-
-## Generate a new site
-
-Generate a new Docusaurus site using the **classic template**.
-
-The classic template will automatically be added to your project after you run the command:
-
-```bash
-npm init docusaurus@latest my-website classic
-```
-
-You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
-
-The command also installs all necessary dependencies you need to run Docusaurus.
-
-## Start your site
-
-Run the development server:
-
-```bash
-cd my-website
-npm run start
-```
-
-The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
-
-The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
-
-Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
+# About
+
+This "yellow paper" is a first attempt to describe the Aztec protocol in its entirety.
+
+It'll be more 'beige' than a yellow paper, initially. For example, we haven't settled on exact hashes, or encryption schemes, or gas metering schedules yet, so it won't contain such exact details as the Ethereum yellow paper.
+
+## Target audience
+
+In Q4, the target audience is _ourselves_ (people at Aztec Labs). Can we explain the protocol requirements and the protocol itself _to ourselves_, without gaps?
+
+In particular, can we explain the protocol to the wider cryptography team, whose help we'll need to ensure the protocol is secure.
+
+(Naturally, if external people do stumble upon this work, they're by all means welcome to critique it and contribute!)
+
+## Editorial comments
+
+This document should be considered the foundation of the protocol. It shouldn't need to refer to the implementation details elsewhere in this monorepo. (The protocol should inform the implementation; not the other way around).
+
+The details should be sufficient for some other engineering team to implement the entire protocol (save for a few exact details, which are details (here)(LINK)).
+
+Some of the info we need to populate this document might have already been written in the top-level `docs/` dir of the monorepo. But the target audience is different. Reduce verbose prose. Remove monorepo code snippets (but note that simple pseudocode snippets to explain a protocol concept are fine). Don't describe components of the sandbox (that's an implementation detail and doesn't belong in this doc).
+
+## For each protocol feature
+
+Describe the requirements.
+Explain _why_ the requirements are requirements. Justify them.
+Recall any discarded requirements. Explain that they were considered, and explain _why_ they were discarded. (Perhaps link to discourse, if applicable).
+
+Explain _what_ the protocol is, and explain _why_ it meets each requirement.
+Provide links to discourse (if applicable), so that people can get context on protocol decisions.
+
+Flag any requirements that are not-yet being met by the protocol described within this doc.
+Discuss what we've considered (or link to a discourse discussion).
+
+
+# ToC
+
+Names of 'owners' are in brackets (they don't necessarily need to write the sections).
+
+The draft subsections are mere suggestions (and serve as a helpful reminder of topics). The actual layout can be adjusted.
+
+- Abstract [Mike]
+- High-level overview [Mike] 
+- Constants [all]
+- Cryptography [Dont do yet]
+  <!-- I wouldn't focus on this section much, in Q4 -->
+  - Fields & Curves
+  - Hash functions
+    - Properties of different hash functions / pseudo-random functions
+    - Pedersen
+    - Poseidon
+    - Blake
+    - Sha256
+    - Domain separation
+  - zk-SNARKs
+    <!-- - (Don't open this can of worms yet... this is for the crypto team to do, one day) -->
+  - The Data Bus
+    <!-- This probably should be explained now, because it'll be used a lot in the 'Protocol Statements' section, below. -->
+- Addresses & Keys [Palla/Mike]
+  - Requirements
+  - Addresses
+    <!-- 
+    - Still undecided whether this should be a hash or a public key. A public key is nice for EoAs.
+    - Embedding Bytecode
+    - Updating Bytecode
+    -->
+  - Keys
+    - Master keys
+      - Authorisation key abstraction
+      - Nullifier keys
+      - Incoming viewing keys
+      - Outgoing viewing keys
+      - Randomizing/tagging/
+    - App-siloed keys
+      - Security assumptions of each key
+        <!-- - I.e. Which software/hardware is allowed to see each secret? -->
+        - Example flows, to validate (and illustrate usage of) the keys:
+          <!-- This is a bit unconventional for a yellow paper, but I think it's important, to sanity-check the design. Not sure if it should go here, or elsewhere. There's also a later section covering the encryption/decryption algorithms, which might be a better place for this. -->
+      - BIP32
+        - Normal key derivation
+        - Hardened key derivation
+        - Deviations from BIP32
+    - Stealth keys vs Diversified keys
+    - Updating keys
+- State
+  - L2 State
+    - Trees 
+      - Private Data Tree
+      - Indexed merkle trees
+      - Nullifier tree(s)
+      - Public Data Tree
+      - Slow Updates Tree (if enshrined) [Lasse]
+      - Contract Tree (if still around)
+      - Transactions / Receipts Trees?
+      - Block hashes tree
+      - Tree Epochs
+  - L1 State [Lasse]
+- Bytecode [Alvaro]
+  - ACIR
+    - Encodings
+  - Brillig
+    - Encodings
+- Contract Creation (Deployment) [???]
+  - Computing a contract address
+  - Nullifying a contract address
+  - Broadcasting Bytecode (under various scenarios) and other contract info
+  - Committing to Brillig bytecode
+- Calls [???]
+  <!-- Still not sure about this section. The 'Protocol Statements' section might cover this. We could keep this section for 'high level' intuition, if we wanted. -->
+  - Private function call
+  - Public function call
+  - Enqueued public function call
+  - Delegatecall (if decided)
+  - Staticcall (if decided)
+  - Protocol Function Call (if decided)
+  - Inter-layer messaging
+    - L1->L2 messaging
+    - L2->L1 messaging
+    - Public->Private messaging
+- Notes & Nullifiers [Leila?]
+  - Custom Notes
+    - Encoding
+  - Custom Nullifiers
+  - Siloing
+  - Uniqueness
+- Logs [Jan?]
+  - Unencrypted
+  - Encrypted
+  - Optimisation considerations
+    <!-- Logs submitted on-chain need to be sha256-hashed/blob-committed somewhere. In which circuit should this happen? Should each circuit enable n log fields, instead of 1, and forward those log fields via the Bus? -->
+- Private Message Delivery [Phil]
+  - To constrain or not to constrain?
+  - Encryption & decryption [Palla/Mike]
+    <!-- This subsection relates _heavily_ to Keys -->
+    - Which encryption scheme(s)?
+    - Types of message
+      - Initial Handshakes
+      - Incoming messages
+      - Internal incoming messages
+      - Outgoing messages
+    - Algorithms
+      - Encryption & decryption algorithms, for each type of message (incoming/outgoing/etc).
+  - Note Discovery [Phil]
+    - Abstracting note identification to a 'tag' of bytes
+    - etc.
+- Gas & Fees [Phil]
+  - Gas Metering
+    - Categories of 'things' that contribute to compute effort
+    - Benchmarking compute effort
+    - Measuring 'gas used' at the protocol level
+  - Fees
+    - L2 fees vs L1 fees
+    - What currency is gas measured in / fee abstraction?
+    - Paying fees, and receiving rebates
+    - Paying fees privately
+    - Etc.
+- Decentralisation [Cooper]
+  - P2P network [Phil]
+    - Data that is sent between parties
+      - Users to the tx pool
+      - Sequencers to provers (and back)
+      - Sequencers to L1
+  - Sequencer selection protocol [Palla]
+  - Prover selection protocol [Cooper?]
+  - Upgrading the protocol [Cooper]
+  - Training Wheels [Lasse?]
+  - Economics [Cooper]
+- Chaining Transactions [Leila]
+- EIP-4844 [Lasse?]
+- Protocol Statements [Mike]
+  - Describe the logic of the protocol.
+  - Describe the assertions that must be in place.
+    - The constraints (assertions) of the system are spread across many circuits and L1 contracts, but they should be described as a whole, in one place. _Where_ the assertions are located (i.e. in which circuit/contract) is a matter of optimisation, which might change over time. This can then serve as a checklist, to ensure those assertions are included in at least one of the circuits/contracts.
+    -  In particular, exhaustively explain what _shouldn't_ be possible.
+  - Sub-protocols
+    <!--
+    It might help to describe certain sub-protocols, which need to be sound in their own right.
+    E.g.:
+    - Contract Deployment
+    - (Account abstraction)
+    - A private function call
+      - Nested private function calls
+    - A public function call
+      - Nested public function calls
+    - Private -> Public function calls
+    - Enqueueing many public function calls
+    - Private -> Internal Public function calls
+    - Side-effect ordering
+    - Note/Nullifier squashing optimisations
+    - Upgrading contract bytecode
+    - Upgrading keys
+    - Gas metering
+    - Fee payments
+    - Sequencer Selection
+    - Prover Selection
+    - Initiating an upgrade
+    -->
+  - Circuits
+   <!-- 
+    - For each:
+      - Explain / justify the requirements.
+      - Describe the Public Inputs ABI & the Bus ABI.
+      - Explain the statements (logic) and assertions.
+  -->
+    - High-level topology [David/Leila?]
+    - Private Circuits [David/Leila?]
+      - General features a private circuit must adhere-to.
+      - Why not a private VM?
+    - Public VM Cicuit [David] <-- big section
+    - Kernel Circuits
+      - Private [David/Leila?]
+        - Initial Private Kernel Circuit
+        - Inner Private Kernel Circuit
+        - Ordering Private Kernel Circuit
+      - Public [David/Leila?]
+        - Initial Public Kernel Circuit
+        - Inner Public Kernel Circuit
+        - (Ordering Public Kernel Circuit???)
+      - Future Kernel Optimisations
+        - Delegating chunks of compute to 'gadget' circuits
+        - A Merkle Tree of Private Kernel iterations
+    - Rollup Circuits [Lasse/Leila?]
+      - Base Rollup Circuit
+      - Merge Rollup Circuit
+      - Root Rollup Circuit
+    - Squisher Circuits [???]
+      - Honk -> UltraPlonk
+      - UltraPlonk -> Standard Plonk / Fflonk
+    - Circuits for sequencer/prover selection? [Palla]
+    - EIP-4844 circuit [???]
+    - Bytecode commitment circuit [???]
+  - Smart Contracts [Lasse]
+    - ...
+- Acknowledgements