From 751bb6a2075705931b3035117512a93769142707 Mon Sep 17 00:00:00 2001 From: PhilWindle <60546371+PhilWindle@users.noreply.github.com> Date: Mon, 4 Dec 2023 17:59:00 +0000 Subject: [PATCH] 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). --- cspell.json | 130 +++++++++--------- .../docs/decentralisation/decentralisation.md | 5 + .../docs/decentralisation/p2p-network.md | 53 +++++-- .../private-message-delivery.md | 20 +-- 4 files changed, 123 insertions(+), 85 deletions(-) diff --git a/cspell.json b/cspell.json index 3d7775f13b2..874cc050f0c 100644 --- a/cspell.json +++ b/cspell.json @@ -5,9 +5,12 @@ "acir", "acvm", "archiver", + "assignement", "asyncify", + "auditability", "authwit", "autonat", + "autorun", "awslogs", "awsvpc", "aztecprotocol", @@ -15,8 +18,10 @@ "bbfree", "bbmalloc", "benesjan", + "bleurgh", "bodyparser", "bootnode", + "bootnodes", "Brillig", "Bufferable", "bufs", @@ -27,6 +32,7 @@ "callstack", "callstacks", "camelcase", + "casemap", "cbind", "cbinds", "chainsafe", @@ -39,20 +45,32 @@ "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", @@ -60,6 +78,8 @@ "filestat", "flatmap", "foundryup", + "frontend", + "frontends", "fullpath", "fuzzer", "fuzzers", @@ -67,8 +87,11 @@ "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 index e69de29bb2d..1853cf324ac 100644 --- a/yellow-paper/docs/decentralisation/decentralisation.md +++ b/yellow-paper/docs/decentralisation/decentralisation.md @@ -0,0 +1,5 @@ +--- +sidebar_position: 1 +--- + +# Decentralisation \ No newline at end of file diff --git a/yellow-paper/docs/decentralisation/p2p-network.md b/yellow-paper/docs/decentralisation/p2p-network.md index 90d415b48ae..8ffa1179465 100644 --- 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) diff --git a/yellow-paper/docs/private-message-delivery/private-message-delivery.md b/yellow-paper/docs/private-message-delivery/private-message-delivery.md index c379a60bc30..9c905c7b7d3 100644 --- a/yellow-paper/docs/private-message-delivery/private-message-delivery.md +++ b/yellow-paper/docs/private-message-delivery/private-message-delivery.md @@ -6,13 +6,13 @@ sidebar_position: 1 ## Requirements -Maintaining the core tenet of privacy within the Aztec Network imposes a number of requirements on it. If Alice executes a function that generates state for Bob: +Maintaining the core tenet of privacy within the Aztec Network imposes a number of requirements related to the transfer of notes from one user to another. If Alice executes a function that generates a note for Bob: -1. Alice will need to encrypt that state such that Bob, and only Bob is able to decrypt it. -2. Alice will need to broadcast the encrypted state so as to make it available for Bob to retrieve. -3. Alice will need to broadcast a 'tag' alongside the encrypted state. This tag must be identifiable by Bob's chosen [note discovery protocol](./note-discovery.md) but not identifiable by any third party. +1. Alice will need to encrypt that note such that Bob, and only Bob is able to decrypt it. +2. Alice will need to broadcast the encrypted note so as to make it available for Bob to retrieve. +3. Alice will need to broadcast a 'tag' alongside the encrypted note. This tag must be identifiable by Bob's chosen [note discovery protocol](./note-discovery.md) but not identifiable by any third party. -Fulfilling these requirements will enable users to privately identify, retrieve, decrypt and consume their application state. Individual pieces of application state transmitted in this way are termed 'notes'. +Fulfilling these requirements will enable users to privately identify, retrieve, decrypt and consume their application notes. ## Constraining Message Delivery @@ -24,15 +24,19 @@ The network will constrain: Constraining [note encryption](./encryption-and-decryption.md) and tagging will be done through protocol defined functions within a user's account contract. The advantages of this approach are: -1. It enables a user to select their preferred [note discovery protocol](./note-discovery.md) and/or encryption scheme. +1. It enables a user to select their preferred [note discovery protocol](./note-discovery.md) and/or encryption scheme. 2. It ensures that notes are correctly encrypted with a user's public encryption key. -3. It ensures that notes are correctly tagged for a user's chosen [note discovery protocol](./note-discovery.md) . +3. It ensures that notes are correctly tagged for a user's chosen [note discovery protocol](./note-discovery.md). 4. It provides scope for upgrading these functions or introducing new schemes as the field progresses. 5. It protects applications from malicious account contracts providing unprovable functions. +> Note: Constraining tag generation is not solely about ensuring that the generated tag is of the correct format. It is also necessary to constrain that tags are generated in the correct sequence. A tag sequence with duplicate or missing tags makes it much more difficult for the recipient to retrieve their notes. This will likely require tags to be nullified once used. + Constraining publication to the correct data availability layer will be performed via a combination of the protocol circuits and the rollup contract on L1. ## User Handshaking -One function that is useful regardless of a user's preferred note discovery and encryption scheme is for users to be notified when they have been sent a note from another user for the first time. To facilitate this we will deploy a 'handshaking' contract that can be used to create a private note for a recipient containing the sender's information (e.g. public key). The notes generated by this contract will be easy to identify enabling users to retrieve these notes, decrypt them and use the contents in any deterministic tag generation used by their chosen note discovery protocol. Trial decryption of these notes alone should not put too high a burden on end users. +Even if Alice correctly encrypts the note she creates for Bob and generates the correct tag to go with it, how does Bob know that Alice has sent him a note? Bob's [note discovery protocol](./note-discovery.md) may require him to speculatively 'look' for notes with the tags that Alice (and his other counterparties) have generated. If Alice and Bob know each other then they can communicate out-of-protocol. But if they have no way of interacting then the network needs to provide a mechanism by which Bob can be alerted to the need to start searching for a specific sequence of tags. + +To facilitate this we will deploy a 'handshake' contract that can be used to create a private note for a recipient containing the sender's information (e.g. public key). It should only be necessary for a single handshake to take place between two users. The notes generated by this contract will be easy to identify enabling users to retrieve these notes, decrypt them and use the contents in any deterministic tag generation used by their chosen note discovery protocol.