diff --git a/yellow-paper/docs-tutorial-reference/intro.md b/yellow-paper/docs-tutorial-reference/intro.md new file mode 100644 index 00000000000..8a2e69d95f9 --- /dev/null +++ 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/yellow-paper/docs/tutorial-basics/_category_.json b/yellow-paper/docs-tutorial-reference/tutorial-basics/_category_.json similarity index 100% rename from yellow-paper/docs/tutorial-basics/_category_.json rename to yellow-paper/docs-tutorial-reference/tutorial-basics/_category_.json diff --git a/yellow-paper/docs/tutorial-basics/congratulations.md b/yellow-paper/docs-tutorial-reference/tutorial-basics/congratulations.md similarity index 100% rename from yellow-paper/docs/tutorial-basics/congratulations.md rename to yellow-paper/docs-tutorial-reference/tutorial-basics/congratulations.md diff --git a/yellow-paper/docs/tutorial-basics/create-a-blog-post.md b/yellow-paper/docs-tutorial-reference/tutorial-basics/create-a-blog-post.md similarity index 100% rename from yellow-paper/docs/tutorial-basics/create-a-blog-post.md rename to yellow-paper/docs-tutorial-reference/tutorial-basics/create-a-blog-post.md diff --git a/yellow-paper/docs/tutorial-basics/create-a-document.md b/yellow-paper/docs-tutorial-reference/tutorial-basics/create-a-document.md similarity index 100% rename from yellow-paper/docs/tutorial-basics/create-a-document.md rename to yellow-paper/docs-tutorial-reference/tutorial-basics/create-a-document.md diff --git a/yellow-paper/docs/tutorial-basics/create-a-page.md b/yellow-paper/docs-tutorial-reference/tutorial-basics/create-a-page.md similarity index 100% rename from yellow-paper/docs/tutorial-basics/create-a-page.md rename to yellow-paper/docs-tutorial-reference/tutorial-basics/create-a-page.md diff --git a/yellow-paper/docs/tutorial-basics/deploy-your-site.md b/yellow-paper/docs-tutorial-reference/tutorial-basics/deploy-your-site.md similarity index 100% rename from yellow-paper/docs/tutorial-basics/deploy-your-site.md rename to yellow-paper/docs-tutorial-reference/tutorial-basics/deploy-your-site.md diff --git a/yellow-paper/docs/tutorial-basics/markdown-features.mdx b/yellow-paper/docs-tutorial-reference/tutorial-basics/markdown-features.mdx similarity index 100% rename from yellow-paper/docs/tutorial-basics/markdown-features.mdx rename to yellow-paper/docs-tutorial-reference/tutorial-basics/markdown-features.mdx diff --git a/yellow-paper/docs/tutorial-extras/_category_.json b/yellow-paper/docs-tutorial-reference/tutorial-extras/_category_.json similarity index 100% rename from yellow-paper/docs/tutorial-extras/_category_.json rename to yellow-paper/docs-tutorial-reference/tutorial-extras/_category_.json diff --git a/yellow-paper/docs/tutorial-extras/img/docsVersionDropdown.png b/yellow-paper/docs-tutorial-reference/tutorial-extras/img/docsVersionDropdown.png similarity index 100% rename from yellow-paper/docs/tutorial-extras/img/docsVersionDropdown.png rename to yellow-paper/docs-tutorial-reference/tutorial-extras/img/docsVersionDropdown.png diff --git a/yellow-paper/docs/tutorial-extras/img/localeDropdown.png b/yellow-paper/docs-tutorial-reference/tutorial-extras/img/localeDropdown.png similarity index 100% rename from yellow-paper/docs/tutorial-extras/img/localeDropdown.png rename to yellow-paper/docs-tutorial-reference/tutorial-extras/img/localeDropdown.png diff --git a/yellow-paper/docs/tutorial-extras/manage-docs-versions.md b/yellow-paper/docs-tutorial-reference/tutorial-extras/manage-docs-versions.md similarity index 100% rename from yellow-paper/docs/tutorial-extras/manage-docs-versions.md rename to yellow-paper/docs-tutorial-reference/tutorial-extras/manage-docs-versions.md diff --git a/yellow-paper/docs/tutorial-extras/translate-your-site.md b/yellow-paper/docs-tutorial-reference/tutorial-extras/translate-your-site.md similarity index 100% rename from yellow-paper/docs/tutorial-extras/translate-your-site.md rename to yellow-paper/docs-tutorial-reference/tutorial-extras/translate-your-site.md diff --git a/yellow-paper/docs/intro.md b/yellow-paper/docs/intro.md index 8a2e69d95f9..1f2e1ad5769 100644 --- 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] + + - Fields & Curves + - Hash functions + - Properties of different hash functions / pseudo-random functions + - Pedersen + - Poseidon + - Blake + - Sha256 + - Domain separation + - zk-SNARKs + + - The Data Bus + +- Addresses & Keys [Palla/Mike] + - Requirements + - Addresses + + - Keys + - Master keys + - Authorisation key abstraction + - Nullifier keys + - Incoming viewing keys + - Outgoing viewing keys + - Randomizing/tagging/ + - App-siloed keys + - Security assumptions of each key + + - Example flows, to validate (and illustrate usage of) the keys: + + - 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 [???] + + - 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 + +- Private Message Delivery [Phil] + - To constrain or not to constrain? + - Encryption & decryption [Palla/Mike] + + - 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 + + - Circuits + + - 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 \ No newline at end of file