feat(docs): Merge yellow paper into docs protocol specs section (#5668)

This PR removes the yellow-paper directory and adds the contents to the
docs, under the protocol-specs section.

Adds a new item called "Protocol Specs" with its own sidebar to the top
Navigation bar.


![image](https://github.com/AztecProtocol/aztec-packages/assets/18372439/39b1b962-9567-4425-a932-7bd32d109307)

.circleci/config.yml

@@ -807,18 +807,6 @@ jobs:
             echo "Deploying docs"
             docs/deploy_netlify.sh $BRANCH $PULL_REQUEST
 
-  yellow-paper:
-    machine:
-      image: default
-    resource_class: large
-    steps:
-      - *checkout
-      - *setup_env
-      - run:
-          name: "Build yellow paper"
-          command: build yellow-paper
-          aztec_manifest_key: yellow-paper
-
   e2e-join:
     docker:
       - image: cimg/base:2023.09
@@ -1073,8 +1061,6 @@ workflows:
 
       - mainnet-fork: *defaults
 
-      - yellow-paper: *defaults
-
       - noir-projects:
           requires:
             - avm-transpiler
@@ -1178,7 +1164,6 @@ workflows:
             - guides-up-quick-start
             - boxes-vanilla
             - boxes-react
-            - yellow-paper
             - noir-packages-tests
             - yarn-project-test
             - prover-client-test

.vscode/settings.json

@@ -125,10 +125,6 @@
   "[javascript]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },
-  // Now when a new file is pasted in /yellow-paper/docs/readme.md, the image file is created at /yellow-paper/docs/images/readme/image.png.
-  "markdown.copyFiles.destination": {
-    "/yellow-paper/**/*": "images/${documentBaseName}/"
-  },
   ///////////////////////////////////////
   // C++/Circuits settings
   ///////////////////////////////////////

CONTRIBUTING.md

@@ -25,9 +25,10 @@ When opening the pull request you will be presented with a template and a series
 If you're looking for a good place to start, look for issues labeled ["good first issue"](https://github.com/AztecProtocol/aztec-packages/labels/good%20first%20issue)!
 
 ## Pull request checklist:
+
 - I've provided a paragraph or two giving a summary of the change in the description, including relevant motivation and context.
 - I've enabled auto-merge if the PR is ready to merge.
-- I have updated the yellow paper when making changes to associated functionality (e.g. outward-facing spec changes).
+- I have updated the protocol specs in the docs (aka the yellow paper) when making changes to associated functionality (e.g. outward-facing spec changes).
 - I have reviewed my diff in github, line by line and removed unexpected formatting changes, testing logs, or commented-out code.
 - Every change is related to the PR description.
 - I have [linked](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) this pull request to relevant issues (if any exist).

avm-transpiler/src/opcodes.rs

@@ -1,5 +1,5 @@
 /// All AVM opcodes
-/// Keep updated with TS and yellow paper!
+/// Keep updated with TS and docs protocol specs!
 #[derive(PartialEq, Copy, Clone, Debug)]
 pub enum AvmOpcode {
     // Compute

build_manifest.yml

@@ -263,8 +263,3 @@ docs:
     - noir-packages
     - l1-contracts
     - noir-projects
-
-yellow-paper:
-  buildDir: yellow-paper
-  rebuildPatterns:
-    - ^yellow-paper/

yellow-paper/docs/addresses-and-keys/address.md → docs/docs/protocol-specs/addresses-and-keys/address.md

@@ -73,7 +73,7 @@ address_crh(
 }
 ```
 
-The `public_keys` array can vary depending on the format of keys used by the address, but it is suggested it includes the master keys defined in the [keys section](./keys.mdx). For example:
+The `public_keys` array can vary depending on the format of keys used by the address, but it is suggested it includes the master keys defined in the [keys section](./keys.md). For example:
 
 ```rust
 let public_keys_hash: Field = poseidon2(

yellow-paper/docs/addresses-and-keys/diversified-and-stealth.md → docs/docs/protocol-specs/addresses-and-keys/diversified-and-stealth.md

@@ -2,7 +2,7 @@
 title: Diversified and Stealth Accounts
 ---
 
-The [keys specification](./keys.mdx) describes derivation mechanisms for diversified and stealth public keys. However, the protocol requires users to interact with addresses.
+The [keys specification](./keys.md) describes derivation mechanisms for diversified and stealth public keys. However, the protocol requires users to interact with addresses.
 
 ## Computing Addresses
 

yellow-paper/docs/addresses-and-keys/example-usage/diversified-and-stealth-keys.mdx → docs/docs/protocol-specs/addresses-and-keys/example-usage/diversified-and-stealth-keys.md

@@ -1,8 +1,3 @@
-<!-- @dev: if you want to import the preamble, remember to make the importing file a `.mdx` file. -->
-
-import LatexPreamble from "../0-keys-latex-preamble.md";
-<LatexPreamble />;
-
 ## Deriving diversified public keys
 
 A diversified public key can be derived from Alice's keys, to enhance Alice's transaction privacy. If Alice's counterparties' databases are compromised, it enables Alice to retain privacy from such leakages. Diversified public keys are used for generating diversified addresses.

yellow-paper/docs/addresses-and-keys/example-usage/encrypt-and-tag.mdx → docs/docs/protocol-specs/addresses-and-keys/example-usage/encrypt-and-tag.md

@@ -1,8 +1,3 @@
-<!-- @dev: if you want to import the preamble, remember to make the importing file a `.mdx` file. -->
-
-import LatexPreamble from "../0-keys-latex-preamble.md";
-<LatexPreamble />;
-
 ## Encrypt and tag an incoming message
 
 Bob wants to send Alice a private message, e.g. the contents of a note, which we'll refer to as the $\plaintext$. Bob and Alice are using a "tag hopping" scheme to help with note discovery. Let's assume they've already handshaked to establish a shared secret $\sharedsecret_{m,tagging}^{Bob \rightarrow Alice}$, from which a sequence of tags $\tagg_{m,i}^{Bob \rightarrow Alice}$ can be derived.

yellow-paper/docs/addresses-and-keys/example-usage/nullifier.mdx → docs/docs/protocol-specs/addresses-and-keys/example-usage/nullifier.md

@@ -1,8 +1,3 @@
-<!-- @dev: if you want to import the preamble, remember to make the importing file a `.mdx` file. -->
-
-import LatexPreamble from "../0-keys-latex-preamble.md";
-<LatexPreamble />;
-
 ## Deriving a nullifier within an app contract
 
 Let's assume a developer wants a nullifier of a note to be derived as:
@@ -17,14 +12,14 @@ Here's example for how an app circuit _could_ constrain the nullifier key to be
 
 It's easiest to take a look at this first:
 
-![Alt text](../images/addresses-and-keys/image.png)
+![Alt text](/img/protocol-specs/addresses-and-keys/image.png)
 
 ### Within the app circuit
 
 Within the app, we can prove links between:
 
-- the user's [$\nskapp$](../keys.mdx#app-siloed-nullifier-secret-key) and their [$\Nkapp$](../keys.mdx#app-siloed-nullifier-key); and between
-- the user's [$\Npkm$](../keys.mdx#master-nullifier-public-key) and their [$\address$](../address.md).
+- the user's [$\nskapp$](../keys.md#app-siloed-nullifier-secret-key) and their [$\Nkapp$](../keys.md#app-siloed-nullifier-key); and between
+- the user's [$\Npkm$](../keys.md#master-nullifier-public-key) and their [$\address$](../address.md).
 
 The link that's missing is to prove that $\Npkm$ relates to $\nskapp$. To compute this missing link requires the $\nskm$, which MUST NOT be passed into an app circuit, and may only be passed into a kernel circuit. See the next ['Within the kernel circuit'](#within-the-kernel-circuit) section for details of this logic.
 

yellow-paper/docs/addresses-and-keys/example-usage/tag-sequence-derivation.mdx → docs/docs/protocol-specs/addresses-and-keys/example-usage/tag-sequence-derivation.md

@@ -1,8 +1,3 @@
-<!-- @dev: if you want to import the preamble, remember to make this importing file a `.mdx` file. -->
-
-import LatexPreamble from "../0-keys-latex-preamble.md";
-<LatexPreamble />;
-
 # Handshaking for tag-hopping
 
 Deriving a sequence of tags for tag-hopping.

yellow-paper/docs/addresses-and-keys/index.md → docs/docs/protocol-specs/addresses-and-keys/index.md

@@ -14,7 +14,7 @@ Keys in Aztec are used both for authorization and privacy. Authorization keys ar
 
 Privacy keys are used for note encryption, tagging, and nullifying. These are also not enforced by the protocol. However, for facilitating composability, the protocol enshrines a set of enshrined encryption and tagging mechanisms, that can be leveraged by applications as they interact with accounts.
 
-The [requirements](./keys-requirements.md) section outlines the features that were sought when designing Aztec's addresses and keys. We then specify how [addresses](./address.md) are derived, as well as the default way in which [keys](./keys.mdx) will be derived. The [precompiles](./precompiles.md) section describes enshrined contract addresses, with implementations defined by the protocol, used for note encryption and tagging.
+The [requirements](./keys-requirements.md) section outlines the features that were sought when designing Aztec's addresses and keys. We then specify how [addresses](./address.md) are derived, as well as the default way in which [keys](./keys.md) will be derived. The [precompiles](./precompiles.md) section describes enshrined contract addresses, with implementations defined by the protocol, used for note encryption and tagging.
 
 Last, the [diversified and stealth accounts](./diversified-and-stealth.md) sections describe application-level recommendations for diversified and stealth accounts.
 

yellow-paper/docs/addresses-and-keys/keys.mdx → docs/docs/protocol-specs/addresses-and-keys/keys.md

@@ -7,9 +7,6 @@ description: Specification for default privacy keys format and derivation, and n
 
 <!-- @dev: if you want to import the preamble, remember to make the importing file a `.mdx` file. -->
 
-import LatexPreamble from "./0-keys-latex-preamble.md";
-<LatexPreamble />;
-
 ## Cheat Sheet
 
 The protocol does not enforce the usage of any of the following keys, and does not enforce the keys to conform to a particular length or algorithm. Users are expected to pick a set of keys valid for the encryption and tagging precompile they choose for their account.
@@ -51,7 +48,7 @@ The protocol does not enforce the usage of any of the following keys, and does n
 Diagram is out of date vs the content on this page
 :::
 
-![Alt text](images/addresses-and-keys/image-5.png)
+<Image img={require("/img/protocol-specs/addresses-and-keys/image-5.png")} />
 
 The red boxes are uncertainties, which are explained later in this doc.
 

yellow-paper/docs/bytecode/index.md → docs/docs/protocol-specs/bytecode/index.md

@@ -42,7 +42,7 @@ There are three different (but related) bytecode standards that are used in Azte
 
 # AVM Bytecode
 
-The AVM bytecode is the compilation target of the public functions of a contract. It's specified in the [AVM section](../public-vm/instruction-set). It allows control flow and uses a flat memory model which tracks bit sizes of values stored in memory via tagging of memory indexes. Sequencers run the AVM bytecode of the public functions of a contract using the AVM and prove the correct execution of it.
+The AVM bytecode is the compilation target of the public functions of a contract. It's specified in the [AVM section](../public-vm/instruction-set.mdx). It allows control flow and uses a flat memory model which tracks bit sizes of values stored in memory via tagging of memory indexes. Sequencers run the AVM bytecode of the public functions of a contract using the AVM and prove the correct execution of it.
 
 # Brillig Bytecode
 
@@ -52,7 +52,7 @@ Brillig bytecode will be very similar to AVM bytecode. While AVM bytecode is spe
 
 Oracles allow nondeterminism during the execution of a given function, allowing the simulator entity to choose the value that an oracle will return during the simulation process. Oracles are heavily used by aztec.nr to fetch data during simulation of private and unconstrained functions, such as fetching notes. They are also used to notify the simulator about events arising during execution, such as a nullified note so that it's not offered again during the simulation.
 
-However, AVM bytecode doesn't allow arbitrary oracles, any nondeterminism introduced is done in a way that the protocol can ensure that the simulator entity (the sequencer) cannot manipulate the result of an oracle. As such, when transforming brillig bytecode to AVM bytecode, all the oracles are replaced by the specific opcodes that the AVM supports for nondeterminism, like [TIMESTAMP](../public-vm/instruction-set#isa-section-timestamp), [ADDRESS](../public-vm/instruction-set#isa-section-address), etc. Any opcode that requires the simulator entity to provide data external to the AVM memory is non-deterministic.
+However, AVM bytecode doesn't allow arbitrary oracles, any nondeterminism introduced is done in a way that the protocol can ensure that the simulator entity (the sequencer) cannot manipulate the result of an oracle. As such, when transforming brillig bytecode to AVM bytecode, all the oracles are replaced by the specific opcodes that the AVM supports for nondeterminism, like [TIMESTAMP](../public-vm/instruction-set.mdx#isa-section-timestamp), [ADDRESS](../public-vm/instruction-set.mdx#isa-section-address), etc. Any opcode that requires the simulator entity to provide data external to the AVM memory is non-deterministic.
 
 The current implementation of Brillig can be found [in the noir repository](https://github.com/noir-lang/noir/blob/master/acvm-repo/brillig/src/opcodes.rs#L60). It's actively being changed to become "AVM bytecode without arbitrary oracles" and right now the differences are handled by a transpiler.
 
@@ -73,7 +73,7 @@ This implies that a block of ACIR bytecode can represent more than one program,
 
 ## Compiling a contract
 
-When a contract is compiled, an artifact will be generated. This artifact needs to be hashed in a specific manner [detailed in the deployment section](../contract-deployment/classes#artifact-hash) for publishing.
+When a contract is compiled, an artifact will be generated. This artifact needs to be hashed in a specific manner [detailed in the deployment section](../contract-deployment/classes.md#artifact-hash) for publishing.
 
 The exact form of the artifact is not specified by the protocol, but it needs at least the following information:
 
@@ -148,19 +148,19 @@ If the function is public, the entry will be its ABI. If the function is private
 
 ### Bytecode in the artifact
 
-The protocol mandates that public bytecode needs to be published to a data availability solution, since the sequencers need to have the data available to run the public functions. Also, it needs to use an encoding that is friendly to the public VM, such as the one specified in the [AVM section](../public-vm/bytecode-validation-circuit).
+The protocol mandates that public bytecode needs to be published to a data availability solution, since the sequencers need to have the data available to run the public functions. Also, it needs to use an encoding that is friendly to the public VM, such as the one specified in the [AVM section](../public-vm/bytecode-validation-circuit.md).
 
-The bytecode of private and unconstrained functions doesn't need to be published, instead, users that desire to use a given contract can add the artifact to their PXE before interacting with it. Publishing it is [supported but not required](../contract-deployment/classes/#broadcast) by the protocol. However, the verification key of a private function is hashed into the function's leaf of the contract's function tree, so the user can prove to the protocol that he executed the function correctly. Also, contract classes contain an [artifact hash](../contract-deployment/classes#artifact-hash) so the PXE can verify that the artifact corresponds with the contract class.
+The bytecode of private and unconstrained functions doesn't need to be published, instead, users that desire to use a given contract can add the artifact to their PXE before interacting with it. Publishing it is [supported but not required](../contract-deployment/classes.md#broadcast) by the protocol. However, the verification key of a private function is hashed into the function's leaf of the contract's function tree, so the user can prove to the protocol that he executed the function correctly. Also, contract classes contain an [artifact hash](../contract-deployment/classes.md#artifact-hash) so the PXE can verify that the artifact corresponds with the contract class.
 
 The encoding of private and unconstrained functions is not specified by the protocol, but it's recommended to follow [the encoding](https://github.com/noir-lang/noir/blob/master/acvm-repo/acir/src/circuit/mod.rs#L157) that Barretenberg and the ACVM share that is serialization using bincode and gzip for compression.
 
-This implies that the encoding of private and unconstrained functions does not need to be friendly to circuits, since when publishing it the protocol only sees a [generic array of field elements](../contract-deployment/classes#broadcast).
+This implies that the encoding of private and unconstrained functions does not need to be friendly to circuits, since when publishing it the protocol only sees a [generic array of field elements](../contract-deployment/classes.md#broadcast).
 
 ## Executing a private function
 
 When executing a private function, its ACIR bytecode will be executed by the PXE using the ACVM. The ACVM will generate the witness of the execution. The proving system can be used to generate a proof of the correctness of the witness.
 
-The fact that the correct function was executed is checked by the protocol by verifying that the [contract class ID](../contract-deployment/classes#class-identifier) contains one leaf in the function tree with this selector and the verification key of the function.
+The fact that the correct function was executed is checked by the protocol by verifying that the [contract class ID](../contract-deployment/classes.md#class-identifier) contains one leaf in the function tree with this selector and the verification key of the function.
 
 ## Executing an unconstrained function
 
@@ -170,4 +170,4 @@ When executing an unconstrained function, its Brillig bytecode will be executed
 
 When executing a public function, its AVM bytecode will be executed by the sequencer with the specified selector and arguments. The sequencer will generate a public VM proof of the correct execution of the AVM bytecode.
 
-The fact that the correct bytecode was executed is checked by the protocol by verifying that the [contract class ID](../contract-deployment/classes#class-identifier) contains the [commitment](../public-vm/bytecode-validation-circuit#committed-representation) to the bytecode used.
+The fact that the correct bytecode was executed is checked by the protocol by verifying that the [contract class ID](../contract-deployment/classes.md#class-identifier) contains the [commitment](../public-vm/bytecode-validation-circuit.md#committed-representation) to the bytecode used.

yellow-paper/docs/calls/public-private-messaging.md → docs/docs/protocol-specs/calls/public-private-messaging.md

@@ -81,4 +81,4 @@ To elaborate, a public function may not have read access to encrypted private st
 
 In the picture below, it is worth noting that all data reads performed by private functions are historical in nature, and that private functions are not capable of modifying public storage. Conversely, public functions have the capacity to manipulate private storage (e.g., inserting new note hashes, potentially as part of transferring funds from the public domain to the private domain).
 
-![Public - Private Messaging](./images/calls/pub_pvt_messaging.png)
+![Public - Private Messaging](/img/protocol-specs/calls/pub_pvt_messaging.png)

yellow-paper/docs/circuits/high-level-topology.md → docs/docs/protocol-specs/circuits/high-level-topology.md

@@ -9,7 +9,7 @@ Once all functions in a transaction are executed, the accumulated data is output
 To illustrate, consider a transaction involving the following functions, where circles depict private functions, and squares denote public functions:
 
 :::info
-A note for Aztec protocol developers: In this yellow paper, the order in which the kernel circuit processes calls is different from previous literature, and is different from the current implementation (as at January 2024).
+A note for Aztec protocol developers: In this protocol spec, the order in which the kernel circuit processes calls is different from previous literature, and is different from the current implementation (as at January 2024).
 :::
 
 <!-- Mike review: perhaps a more comprehensive example would be if f2 makes the calls to f4 and f5, to cover a case which isn't covered in the current example: If f2 calls f4 & f5, then which is processed by the kernel first out of f3, f4, or f5?

yellow-paper/docs/circuits/private-kernel-initial.mdx → docs/docs/protocol-specs/circuits/private-kernel-initial.mdx

@@ -775,7 +775,7 @@ Would it be accurate to describe this as `AccumulatedTransientSideEffects`, perh
 
 ### `ContractClass`
 
-<!-- TODO: ensure this aligns with the Contract Class section of this yellow paper -->
+<!-- TODO: ensure this aligns with the Contract Class section of this protocol specs -->
 <!-- TODO:
 Public functions and unconstrained functions won't be stored in a function tree; only private functions will be. Please liaise with Palla and David to align on how contract data will be deployed, and how AVM bytecode will be consumed.
 -->

yellow-paper/docs/circuits/private-kernel-inner.mdx → docs/docs/protocol-specs/circuits/private-kernel-inner.mdx

@@ -1,6 +1,6 @@
 # Private Kernel Circuit - Inner
 
-<!-- Please align use of `backticks` instead of _italics_ for all definitions, for consistency across the yellow paper -->
+<!-- Please align use of `backticks` instead of _italics_ for all definitions, for consistency across the protocol specs -->
 
 ## Requirements