docs: Further update to the yellow paper (#3542)

This PR contains further updates to the yellow paper. # Checklist: Remove the checklist to signal you've completed it. Enable auto-merge if the PR is ready to merge. - [ ] If the pull request requires a cryptography review (e.g. cryptographic algorithm implementations) I have added the 'crypto' tag. - [ ] 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).
AztecProtocol · Dec 4, 2023 · 751bb6a · 751bb6a
1 parent a8b2608
commit 751bb6a
Show file tree

Hide file tree

Showing 4 changed files with 123 additions and 85 deletions.
diff --git a/cspell.json b/cspell.json
@@ -5,18 +5,23 @@
     "acir",
     "acvm",
     "archiver",
+    "assignement",
     "asyncify",
+    "auditability",
     "authwit",
     "autonat",
+    "autorun",
     "awslogs",
     "awsvpc",
     "aztecprotocol",
     "barretenberg",
     "bbfree",
     "bbmalloc",
     "benesjan",
+    "bleurgh",
     "bodyparser",
     "bootnode",
+    "bootnodes",
     "Brillig",
     "Bufferable",
     "bufs",
@@ -27,6 +32,7 @@
     "callstack",
     "callstacks",
     "camelcase",
+    "casemap",
     "cbind",
     "cbinds",
     "chainsafe",
@@ -39,36 +45,53 @@
     "codegen",
     "comlink",
     "composability",
+    "composablity",
     "concat",
     "cond",
+    "counterparty",
     "cpus",
     "customizability",
     "danlee",
     "Daos",
+    "Datas",
     "dbanks",
     "decrementation",
+    "defi",
     "delegatecall",
+    "delegatecalls",
+    "deregistration",
+    "devex",
+    "devnet",
     "devs",
     "diffie",
     "direnv",
     "dockerfiles",
     "dockerhub",
+    "dockerized",
+    "doesnt",
+    "dont",
+    "elif",
     "entrypoints",
     "erc",
     "falsey",
     "fargate",
     "filestat",
     "flatmap",
     "foundryup",
+    "frontend",
+    "frontends",
     "fullpath",
     "fuzzer",
     "fuzzers",
     "gitmodules",
     "gitrepo",
     "grumpkin",
     "gtest",
+    "hardfork",
     "hardlinks",
+    "hashable",
     "hasher",
+    "headstart",
     "herskind",
     "ierc",
     "indexeddb",
@@ -79,32 +102,45 @@
     "keccak",
     "keypairs",
     "keyscan",
+    "kothari",
+    "Lasse",
     "leveldb",
     "leveldown",
     "leveljs",
     "libp",
     "linkability",
+    "lmdb",
+    "maddiaa",
     "memdown",
+    "memfs",
     "Merkle",
     "messagebox",
     "mimc",
     "mktemp",
     "mload",
     "mockify",
+    "monomorphization",
+    "monomorphize",
     "mplex",
     "msgpack",
     "muldiv",
     "multiarch",
     "multivalue",
     "muxers",
+    "nada",
+    "namespacing",
     "Nargo",
     "nixpkgs",
+    "nodebuffer",
+    "noirc",
     "noirup",
     "nullifer",
+    "offchain",
     "otterscan",
     "outdir",
     "overlayfs",
     "pako",
+    "Palla",
     "parallelizable",
     "Pedersen",
     "permissionless",
@@ -118,16 +154,24 @@
     "preimage",
     "preimages",
     "prestat",
+    "println",
     "productionify",
     "protobuf",
     "proxied",
     "proxified",
     "proxify",
+    "pseudocode",
     "pubkey",
     "pxes",
     "quickstart",
+    "Quickstarts",
     "rahul",
+    "REALDIR",
+    "realpath",
+    "rebundle",
     "repr",
+    "Reserialize",
+    "retag",
     "rethrown",
     "rollup",
     "rollups",
@@ -140,25 +184,43 @@
     "sload",
     "snakecase",
     "solhint",
+    "SSTORE",
+    "staticcall",
     "stdlib",
     "struct",
     "structs",
+    "subarrays",
+    "subdir",
+    "sublabel",
+    "sublabels",
+    "subpackage",
+    "subpackages",
     "subrepo",
+    "subroot",
     "suyash",
+    "templating",
+    "tldr",
     "toplevel",
     "tparam",
     "transferables",
     "trivago",
     "tsbuildinfo",
     "tsdoc",
+    "typechain",
     "typecheck",
+    "typegen",
     "typeparam",
     "unexclude",
     "unexcluded",
+    "unprefixed",
     "unshield",
     "unshielding",
+    "unzipit",
     "upperfirst",
+    "usecase",
+    "usecases",
     "utxo",
+    "UTXOS",
     "vals",
     "viem",
     "wasms",
@@ -167,69 +229,7 @@
     "yamux",
     "yarnrc",
     "zerocash",
-    "zexe",
-    "Lasse",
-    "Palla",
-    "pseudocode",
-    "staticcall",
-    "subdir",
-    "noirc",
-    "devex",
-    "monomorphize",
-    "hashable",
-    "typechain",
-    "subroot",
-    "dont",
-    "monomorphization",
-    "println",
-    "usecase",
-    "doesnt",
-    "Quickstarts",
-    "headstart",
-    "kothari",
-    "autorun",
-    "realpath",
-    "namespacing",
-    "memfs",
-    "unzipit",
-    "Datas",
-    "nada",
-    "maddiaa",
-    "subpackage",
-    "subpackages",
-    "nodebuffer",
-    "devnet",
-    "Reserialize",
-    "tldr",
-    "subarrays",
-    "dockerized",
-    "elif",
-    "assignement",
-    "REALDIR",
-    "unprefixed",
-    "casemap",
-    "rebundle",
-    "sublabel",
-    "sublabels",
-    "retag",
-    "frontend",
-    "frontends",
-    "typegen",
-    "deregistration",
-    "SSTORE",
-    "UTXOS",
-    "defi",
-    "usecases",
-    "usecase",
-    "templating",
-    "bleurgh",
-    "offchain",
-    "delegatecalls",
-    "auditability",
-    "hardfork",
-    "composablity",
-    "counterparty",
-    "lmdb"
+    "zexe"
   ],
   "ignorePaths": [
     "node_modules/",
@@ -256,5 +256,7 @@
     "lib",
     "*.cmake"
   ],
-  "flagWords": ["anonymous"]
+  "flagWords": [
+    "anonymous"
+  ]
 }
diff --git a/yellow-paper/docs/decentralisation/decentralisation.md b/yellow-paper/docs/decentralisation/decentralisation.md
@@ -0,0 +1,5 @@
+---
+sidebar_position: 1
+---
+
+# Decentralisation
diff --git a/yellow-paper/docs/decentralisation/p2p-network.md b/yellow-paper/docs/decentralisation/p2p-network.md
@@ -1,41 +1,68 @@
+---
+sidebar_position: 1
+---
+
+# P2P Network
+
 ## Requirements for a P2P Network
 
 :::info Disclaimer
 This is a draft. These requirements need to be considered by the wider team, and might change significantly before a mainnet release.
 :::
 
-When rollups are successfully published, the state transitions are published along with it and are publically retrievable. This category of state does not depend on the Aztec network for its persistence or distribution. Transient data such as pending user transactions for inclusion in future rollups however does rely on the network for these functions. Network participants will consist of:
+When a rollup is successfully published, the state transitions it produces are published along with it, making them publicly available. This broadcasted state does not depend on the Aztec network for its persistence or distribution. Transient data however, such as pending user transactions for inclusion in future rollups, does rely on the network for this. It is important that the network provides a performant, permissionless and censorship resistant mechanism for the effective propagation of these transactions to all network participants. Without this, transactions may be disadvantaged and the throughput of the network will deteriorate.
+
+Other data that may be transmitted over the network are the final rollup proofs to be submitted to the rollup contract, however the size and rate of these payloads should not make any meaningful impact on the bandwidth requirements.
+
+### Network Participants
+
+For the purpose of this discussion, we define the 'Aztec Network' as the set of components required to ensure the continual distribution of user transactions and production of rollups. The participants in such a network are:
 
 * Sequencers - responsible for selecting transactions from the global pool and including them in rollups
 * Provers - responsible for generating zk-proofs for the transaction and rollup circuits
+* Transaction Pool Nodes - responsible for maintaining a local representation of the pending transaction pool
+* Bootnodes - responsible for providing an entrypoint into the network for new participants
+
+Sequencers and Provers will likely run their own transaction pools but it is important that the ability to do so is not limited to these participants. Anyone can operate a transaction pool, providing increased privacy and censorship resistance. 
+
+Client PXEs will not interact directly with the network but instead via instances of the Aztec Node and it's JSON RPC interface. The Aztec Node in turn will publish user transactions to the network.
+
+### Network Topology and Transaction Submission
+
+The network will likely be based on the LibP2P specification.
+
+#### Discovery
 
-Pending transactions will be the primary category of data being transmitted through the network. It is important that the network provides a performant, permissionless and censorship resistant mechanism for the effective propagation of these transactions to all sequencers. Without this, transactions may be disadvantaged and the throughput of the network will deteriorate.
+When a node such as a sequencer joins the network for the first time it will need to contact a bootnode. This will be one of a hardcoded set of nodes whose sole purpose is to provide an initial set of peers to connect with. Once a node has made contact with and stored address data for a number of peers it should no longer need to contact the bootnodes, provided it's peers remain available.
 
-Other data that may be transmitted over the network are the final rollup proofs to be submitted to the rollup contract, the size and rate of these payloads should not make any meaningful impact on the bandwidth requirements.
+#### Gossip
 
-### Network Capacity
+Transactions will need to be propagated throughout the network, to every participant. Due to the size of the transaction payloads it will be necessary to ensure that transaction propagation is performed as efficiently as possible taking steps to reduce the amount of redundant data transfer.
 
-Transactions are composed of a number of data elements and can vary in size predominantly based on their deployment of any public bytecode and the private kernel proof. A typical transaction that emits a private note and an unencrypted log, makes a public call and contains a valid proof would consume approximately 40Kb of data. A transaction that additionally deploys a contract would need to transmit the public bytecode on top of this.
+#### Client Interactions
+
+Aztec Node instances will offer a JSON RPC interface for consumption by a user's PXE. Part of this API will facilitate transaction submission directly to the node which will then forward it to the network via the transaction pool.
+
+![P2P Network](../decentralisation/images/network.png)
+
+### Network Bandwidth
+
+Transactions are composed of several data elements and can vary in size. The transaction size is determined largely by the private kernel proof and whether the transaction deloys any public bytecode. A typical transaction that emits a private note and an unencrypted log, makes a public call and contains a valid proof would consume approximately 40Kb of data. A transaction that additionally deploys a contract would need to transmit the public bytecode on top of this.
 
 | Element | Size |
 | ------- | ---------------- |
 | Public Inputs, Public Calls and Emitted Logs | ~8Kb |
 | Private Kernel Proof | ~32Kb |
 
-At throughputs of 10 and 100 transactions per second, we can arrive at average network bandwidth requirements of 400Kb and 4000Kb per second respectively.
+If we take 2 values of transaction throughput of 10 and 100 transactions per second, we can arrive at average network bandwidth requirements of 400Kb and 4000Kb per second respectively.
 
 ### Sequencer to Prover Communication
 
-There shouldn't be any requirement for the network to handle communication from sequencers to provers for the purpose of generating proofs. Proving is an out-of-protocol activity so it is likely that provers will obtain their input data in one of 2 ways.
-
-* Via a direct interface to a prover marketplace over a protocol such as http
-* The provers will independently know the sequence of transactions from the commitment phase of the sequencer selection protocol. They can then use the transaction pool to maintain their own state for proof generation
+Proving is an out-of-protocol activity. The nature of the communication between sequencers and provers will depend entirely on the prover/s selected by the sequencer. Provers may choose to run their own Transaction Pool Node infrastructure so that they are prepared for generating proofs and don't need to receive this data out-of-band.
 
-### Network Topology and Submitting Transactions
+Although proving is an out-of-protocol activity, it may be necessary for the final rollup proof to be gossiped over the P2P network such that anyone can submit it to the rollup contract.
 
-Aztec Node instances will offer a JSON RPC interface for consumption by a user's PXE. Part of this API will facilitate transaction submission directly to the node which will then forward it to the network via the transaction pool.
 
-![P2P Network](../decentralisation/images/network.png)