diff --git a/circuits/cpp/src/aztec3/constants.hpp b/circuits/cpp/src/aztec3/constants.hpp index 0baa59f5d9c1..c667420e1c6a 100644 --- a/circuits/cpp/src/aztec3/constants.hpp +++ b/circuits/cpp/src/aztec3/constants.hpp @@ -39,6 +39,7 @@ constexpr size_t RETURN_VALUES_LENGTH = 4; * */ +// docs:start:constants // "PER CALL" CONSTANTS constexpr size_t MAX_NEW_COMMITMENTS_PER_CALL = 4; constexpr size_t MAX_NEW_NULLIFIERS_PER_CALL = 4; @@ -63,6 +64,7 @@ constexpr size_t MAX_OPTIONALLY_REVEALED_DATA_LENGTH_PER_TX = 4; constexpr size_t MAX_READ_REQUESTS_PER_TX = MAX_PRIVATE_CALL_STACK_LENGTH_PER_CALL * MAX_READ_REQUESTS_PER_CALL; constexpr size_t NUM_ENCRYPTED_LOGS_HASHES_PER_TX = 1; constexpr size_t NUM_UNENCRYPTED_LOGS_HASHES_PER_TX = 1; +// docs:end:constants //////////////////////////////////////////////////////////////////////////////// // ROLLUP CONTRACT CONSTANTS - constants used only in l1-contracts diff --git a/docs/docs/about_aztec/roadmap/engineering_roadmap.md b/docs/docs/about_aztec/roadmap/engineering_roadmap.md index 8afc3aa5e0b4..f5f3c8fadd17 100644 --- a/docs/docs/about_aztec/roadmap/engineering_roadmap.md +++ b/docs/docs/about_aztec/roadmap/engineering_roadmap.md @@ -1,4 +1,4 @@ -# Engineering Roadmap +# Engineering Wishlist The engineering roadmap is long. There are no timings assigned here. In a loose priority order: @@ -9,8 +9,8 @@ The engineering roadmap is long. There are no timings assigned here. In a loose - Encouraging contributions to 'good first issue' issues. - Release notes. - Versioning. -- AZIPs (improvements) -- AZRCs (standardisation efforts) +- Aztec Improvement Proposals (AZIPs) +- Aztec Requests for Comment (AZRCs) ## Benchmarking @@ -18,24 +18,9 @@ The engineering roadmap is long. There are no timings assigned here. In a loose ## Standardisation efforts -- Aztec Smart Contract coding patterns - - Private State - - When to use `Singleton` vs `Set`. - - Custom Notes & Nullifiers - - Encrypting data for someone else, via encrypted logs. - - Account contracts - - Inter-layer messaging (L1<\>L2, public<\>private) - - Function calls - - Do not return private data from an external function (unless you've thought about the consequences) - - Do not pass private data as an argument to another function (unless you've thought about the consequences) - - Any public function call is leaky. - - Unencrypted logs are leaky. - - The timing of transactions can be leaky. - - The number of new commitments / nullifiers / log fields, is leaky. - - Standardise tranches of 'sizes' of commitments/nullifiers/logs to ensure functions look the same. E.g. Tranches for 2, 4, 8, 16, 32. - - Perhaps have a version or 'mode' of the kernel circuit, which pads all arrays with random fields, up to some tranched 'size' of commitments/nullifiers/logs. -- Access Control (whitelists/blacklists) - probably needs the Slow Updates tree (or something). -- Basic example private tokens +- Recommended Aztec smart contract coding patterns +- Access Control (whitelists/blacklists) - probably needs the Slow Updates tree (or something similar). +- Basic _example_ private tokens - Including recursive calls to 'get_notes'. - Compliant private tokens - Private NFTs @@ -177,8 +162,6 @@ Some example features: ## Tooling -Work more closely with the Noir tooling team. Upskill the wider engineering team to contribute to tooling. - ## Proper Circuits ### Redesign @@ -233,11 +216,13 @@ Also, we do a lot of sha256-compressing in our kernel and rollup circuits for da - Private data must not be returned to an app, unless the user authorises it. ## Validation: preventing execution of malicious bytecode -- A node should check that some purported bytecode for a particular contract address matches the data in the contract tree. +- A node should check that the bytecode provided by an application for a given app matches the leaf in the contract tree to ensure that user doesn't execute unplanned code which might access their notes. + +## Fuzz Testing -## Fuzz Testing? +## Formal Verification -## Formal Verification? +An investigation into how formal verification techniques might improve the security of Aztec software. ## P2P network @@ -245,12 +230,12 @@ Also, we do a lot of sha256-compressing in our kernel and rollup circuits for da ## Hashes -- New Pedersen -- Poseidon +- An improved, standardised Pedersen hash in barretenberg. +- Poseidon hashing in barretenberg. ## Tree epochs -- Nullifier tree -- Maybe other trees. TBD. +- Nullifier tree epochs +- Maybe other tree epochs. ## Chaining txs - We have the ability to spend pending notes (which haven't-yet been added to the tree) _within the context of a single tx_. diff --git a/docs/docs/about_aztec/roadmap/features_initial_ldt.md b/docs/docs/about_aztec/roadmap/features_initial_ldt.md index 4191f790c018..f85c0bc28bf0 100644 --- a/docs/docs/about_aztec/roadmap/features_initial_ldt.md +++ b/docs/docs/about_aztec/roadmap/features_initial_ldt.md @@ -1,10 +1,10 @@ --- -title: Intial Sandbox Features +title: Initial Sandbox Features --- The Aztec Sandbox is intended to provide developers with a lightweight & fast node, with features similar to Ethereum's Ganache or Anvil 'local node' packages. -Devs should be able to quickly spin up local, emulated instances of an Ethereum blockchain and an Aztec encrypted rollup, and start deploying confidential contracts and submitting confidential txs. +Devs should be able to quickly spin up local, emulated instances of an Ethereum blockchain and an Aztec encrypted rollup, and start deploying private contracts and submitting private txs. Here's a summary of the features we intend to support with the first release of the Aztec Sandbox. @@ -12,22 +12,22 @@ Here's a summary of the features we intend to support with the first release of - Noir `contract` scopes. - Declare a `contract`, containing a collection of state variables and functions. -- `secret` state variables: - - `read`, `write`, and `delete` `secret` state variables within `secret` functions. -- public (non-`secret`) state variables: +- private state variables: + - `read`, `write`, and `delete` private state variables within private functions. +- public (non-private) state variables: - Manipulate 'public' state in a familiar way to Ethereum state. -- `secret` functions - - May read and modify `secret` state. +- private functions + - May read and modify private state. - public functions - May read and modify public state. - `constructor` functions, for initialising contract state. - `import` other Noir contracts, so their functions may be called. - Nested function calls, for contract composability - - `secret` functions can call `secret` functions of other contracts, and receive return values. - - `secret` functions can call public functions any contract. - - public functions can call `secret` functions of any contract. + - private functions can call private functions of other contracts, and receive return values. + - private functions can call public functions any contract. + - public functions can call private functions of any contract. - public functions can call public functions of other contracts, and receive return values. - - `secret` functions can be called recursively. + - private functions can be called recursively. - public functions can be called recursively. - Send messages from Noir contracts to Ethereum L1, for consumption by L1 smart contracts. - Useful, for example, if writing an app to withdraw funds from L2 to L1. @@ -59,7 +59,7 @@ A typescript wrapper for making RPC calls to an Aztec LDT node. A bundle of packages which emulate the actions of all eventual Aztec network participants. The goal is for developer experience to be akin to Ganache / Anvil. - Aztec RPC Client - - Simulate and/or execute `secret` functions locally. + - Simulate and/or execute private functions locally. - Aztec Public Node - Broadcasts a user's txs to the tx pool. - Simulate public functions locally. diff --git a/docs/docs/about_aztec/roadmap/full_roadmap.md b/docs/docs/about_aztec/roadmap/full_roadmap.md deleted file mode 100644 index 641cee912cab..000000000000 --- a/docs/docs/about_aztec/roadmap/full_roadmap.md +++ /dev/null @@ -1,5 +0,0 @@ -# Full Roadmap - -:::danger -Placeholder in case we want to include the org roadmap (higher level, non-engineering). -::: \ No newline at end of file diff --git a/docs/docs/about_aztec/roadmap/main.md b/docs/docs/about_aztec/roadmap/main.md index e69de29bb2d1..b54fb2572632 100644 --- a/docs/docs/about_aztec/roadmap/main.md +++ b/docs/docs/about_aztec/roadmap/main.md @@ -0,0 +1,5 @@ + \ No newline at end of file diff --git a/docs/docs/dev_docs/contracts/contract.md b/docs/docs/dev_docs/contracts/contract.md index bacc41908fe1..9e94abb09ffb 100644 --- a/docs/docs/dev_docs/contracts/contract.md +++ b/docs/docs/dev_docs/contracts/contract.md @@ -2,7 +2,7 @@ title: Contract --- -# `contract` +# Contract A contract is a collection of persistent [state variables](#state-variables), and [functions](#functions) which may modify these persistent states. Functions and states within a contract's scope are said to belong to that contract. A contract can only access and modify its own state. If a contract wishes to access or modify another contract's state, it must make a [call](#calling-functions) to an external function of that other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called. diff --git a/docs/docs/dev_docs/contracts/main.md b/docs/docs/dev_docs/contracts/main.md index fa7f9d5768d5..04238411395c 100644 --- a/docs/docs/dev_docs/contracts/main.md +++ b/docs/docs/dev_docs/contracts/main.md @@ -30,10 +30,6 @@ There are a number of tools to make writing Noir Contracts more pleasant. See [h Starter kit ::: -## Workflow - -See [here](./workflow.md) for a suggestion for how to develop your Aztec.nr contract. - ## Example Noir Contract @@ -46,6 +42,3 @@ In keeping with the origins of blockchain, here's an example of a simple private :::info Disclaimer Please note that any example contract set out herein is provided solely for informational purposes only and does not constitute any inducement to use or deploy. Any implementation of any such contract with an interface or any other infrastructure should be used in accordance with applicable laws and regulations. ::: - -## Next steps -You can read more about writing contracts [here](./syntax.md), and then move to compiling it which is detailed [here](./compiling.md). diff --git a/docs/docs/dev_docs/contracts/syntax.md b/docs/docs/dev_docs/contracts/syntax.md index 89e738fb0d90..45557873862c 100644 --- a/docs/docs/dev_docs/contracts/syntax.md +++ b/docs/docs/dev_docs/contracts/syntax.md @@ -13,10 +13,6 @@ Aztec.nr contains abstractions which remove the need to understand the low-level - secrets - Functions for communicating with Ethereum L1 -To import Aztec.nr into your Aztec contract project, simply include it as a dependency: - -:::danger TODO -https://github.com/AztecProtocol/aztec-packages/issues/1335 -::: +To import Aztec.nr into your Aztec contract project, simply include it as a dependency. #include_code importing-aztec /yarn-project/noir-contracts/src/contracts/private_token_contract/Nargo.toml toml \ No newline at end of file diff --git a/docs/docs/dev_docs/limitations/main.md b/docs/docs/dev_docs/limitations/main.md index 426a9d479db7..a8e64411d001 100644 --- a/docs/docs/dev_docs/limitations/main.md +++ b/docs/docs/dev_docs/limitations/main.md @@ -40,10 +40,6 @@ There are plans to resolve all of the below. See also the [engineering roadmap]( None of the Sandbox code is audited. It's being iterated-on every day. It will not be audited for quite some time. -#### What are the consequences? - -TODO: link to a disclaimer. - ### No Proofs! @@ -89,7 +85,6 @@ Apps won't yet be able to allow for any L2 fee logic. Once fees are introduced, ### Basic Keys and Addresses! The way in which keypairs and addresses are currently derived and implemented (inside the Sandbox) is greatly over-simplified, relative to future plans. -See [current keys] and [future keys]. They're so over-simplified that they're known to be insecure. Other features have been prioritised so-far in Sandbox development. Please refer to the [future roadmap](../../about_aztec/roadmap/engineering_roadmap.md) @@ -114,7 +109,7 @@ Please open new discussions on [discourse](http://discourse.aztec.network) or op ### It's not-yet decentralised It's an emulated blockchain entirely contained within your own laptop! It's centralised by design! -As for deploying this all to mainnet, a decentralised sequencer selection and prover selection protocols are still being discussed. There are plans for decentralised testnets in 2024. +As for deploying this all to mainnet, a decentralised sequencer selection and prover selection protocols are still [being discussed](https://discourse.aztec.network/t/request-for-proposals-decentralized-sequencer-selection/350). There are plans for decentralised testnets in 2024. ### You can't read mutable public state from a private function @@ -130,7 +125,7 @@ Reading public state from a private contract will be a common pattern. For examp A contract can't perform a delegatecall yet (if ever). Delegatecalls are quite a controversial feature of the EVM. -### No privacy-preserving queries to public nodes +### No privacy-preserving queries to nodes Ethereum has a notion of a 'full node' which keeps-up with the blockchain and stores the full chain state. Many users don't wish to run full nodes, so rely on 3rd-party 'full-node-as-a-service' infrastructure providers, who service blockchain queries from their users. @@ -176,8 +171,8 @@ There are [ongoing discussions](https://discourse.aztec.network/t/who-is-msg-sen #### What are the consequences? -When a private function makes a call to a public function, the `msg_sender` of the calling function will be given to the public world. Most critically, includes if the `msg_sender` is an account contract. -This will be patched in the near future, but unfortunately, app developers might need to 'overlook' this privacy leakage until then, with the assumption that it will be fixed. Thanks for your patience :) +When a private function makes a call to a public function, the `msg_sender` of the calling function will be given to the public world. Most critically, this includes if the `msg_sender` is an account contract. +This will be patched in the near future, but unfortunately, app developers might need to 'overlook' this privacy leakage until then, with the assumption that it will be fixed. But note, one possible 'patch' might be to set `msg_sender` to `0` for all private -> public calls. This might cause breaking changes to your public functions, if they rely on reading `msg_sender`. There are patterns to work around this, but they wouldn't be pretty, and we won't go into details until a solution is chosen. Sorry about this, and thanks for your patience whilst we work this out :) ### New Privacy Standards are required @@ -197,6 +192,10 @@ Due to the rigidity of zk-SNARK circuits, there are upper bounds on the amount o > Blockchain developers are no stranger to restrictive computational environments. Ethereum has gas limits, local variable stack limits, call stack limits, contract deployment size limits, log size limits, etc. +Here are the current constants: + +#include_code constants circuits/cpp/src/aztec3/constants.hpp cpp + #### What are the consequences? When you write an [Aztec.nr](../contracts/main.md) [function](../contracts/functions.md), there will be upper bounds on the following: diff --git a/docs/docs/dev_docs/privacy/main.md b/docs/docs/dev_docs/privacy/main.md index ccde987c48c5..38debb833e81 100644 --- a/docs/docs/dev_docs/privacy/main.md +++ b/docs/docs/dev_docs/privacy/main.md @@ -1,4 +1,4 @@ -# Preserving privacy +# Privacy Considerations Privacy is important. @@ -45,7 +45,7 @@ There are many caveats to the above. Since Aztec also enables interaction with t Any time a private function makes a call to a public function, information is leaked. Now, that might be perfectly fine in some use cases (it's up to the smart contract developer). Indeed, most interesting apps will require some public state. But let's have a look at some leaky patterns: - Calling a public function from a private function. The public function execution will be publicly visible. -- Calling a public function from a private function, without anonymising the msg_sender of that call. (Otherwise the msg_sender will be publicly visible). +- Calling a public function from a private function, without anonymising the `msg_sender` of that call. (Otherwise the `msg_sender` will be publicly visible). - Passing arguments to a public function from a private function. All of those arguments will be publicly visible. - Calling an internal public function from a private function. The fact that the call originated from a private function of that same contract will be trivially known. - Emitting unencrypted events from a private function. The unencrypted event name and arguments will be publicly visible. @@ -54,7 +54,7 @@ Any time a private function makes a call to a public function, information is le ### Crossing the public -> private boundary -If a public function sends a message to be consumed by a private function, the act of consuming that message might be leaked without following recommended patterns. See (LINK) for more details. +If a public function sends a message to be consumed by a private function, the act of consuming that message might be leaked if not following recommended patterns. See [here](../contracts/portals/inbox.md) for more details. ### Timing of transactions @@ -72,9 +72,7 @@ Tl;dr: app developers should think about the _timing_ of user transactions, and ### Function Fingerprints and Tx Fingerprints -'Fingerprint' is something of a neologism, in the context of privacy leakage. - -A 'Function Fingerprint' is any data which is exposed by a function to the outside world. A 'Tx Fingerprint' is any data which is exposed by a tx to the outside world. We're interested in minimising leakages of information from private txs. For a private function, the following information _could_ be leaked (depending on the function, of course): +A 'Function Fingerprint' is any data which is exposed by a function to the outside world. A 'Tx Fingerprint' is any data which is exposed by a tx to the outside world. We're interested in minimising leakages of information from private txs. The leakiness of a Tx Fingerprint depends on the leakiness of its consituent functions' Function Fingerprints _and_ on the appearance of the tx's Tx Fingerprint as a whole. For a private function (and by extension, for a private tx), the following information _could_ be leaked (depending on the function, of course): - All calls to public functions. - The contract address of the private function (if it calls an internal public function). @@ -85,23 +83,6 @@ A 'Function Fingerprint' is any data which is exposed by a function to the outsi - All unencrypted logs (topics and arguments). - The roots of all trees which have been read from. - The _number_ of ['side effects'](https://en.wikipedia.org/wiki/Side_effect_(computer_science)): - - \# new commitments - - \# new nullifiers - - \# bytes of encrypted logs - - \# public function calls - - \# L2->L1 messages - - \# nonzero roots** - -The leakiness of a Tx Fingerprint depends on the leakiness of its consituent functions' Function Fingerprints _and_ on the appearance of the tx's Tx Fingerprint as a whole. Txs can leak the following similar information: -- All calls to public functions. - - The contract addresses of all private function (if it calls an internal public function). - - This could be the address of the transactor themselves, if the calling contract is an account contract. - - All arguments which are passed to public functions. -- All calls to L1 functions (in the form of L2 -> L1 messages). - - The contents of L2 -> L1 messages. -- All unencrypted logs (topics and arguments). -- The roots of all trees which have been read from. -- The _number_ of ['side effects'](https://en.wikipedia.org/wiki/Side_effect_(computer_science)) in the whole tx: - \# new commitments - \# new nullifiers - \# bytes of encrypted logs @@ -110,6 +91,7 @@ The leakiness of a Tx Fingerprint depends on the leakiness of its consituent fun - \# nonzero roots[^1] + > Note: many of these were mentioned in the ["Crossing the private -> public boundary"](#crossing-the-private---public-boundary) section. > Note: the calldata submitted to L1 is [encoded](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/Decoder.sol) in such a way that all categories of data are packed together, when submitted. E.g. all commitments from all txs in a block are arranged as contiguous bytes of calldata. But that _doesn't_ mean the data from a particular tx is garbled in with all other txs' calldata: the distinct Tx Fingerprint of each tx can is publicly visible when a tx is submitted to the L2 tx pool. @@ -128,7 +110,7 @@ Ethereum has a notion of a 'full node' which keeps-up with the blockchain and st This pattern is likely to develop in Aztec as well, except there's a problem: privacy. If a privacy-seeking user makes a query to a 3rd-party 'full node', that user might leak data about who they are; about their historic network activity; or about their future intentions. One solution to this problem is "always run a full node", but pragmatically, not everyone will. To protect less-advanced users' privacy, research is underway to explore how a privacy-seeking user may request and receive data from a 3rd-party node without revealing what that data is, nor who is making the request. -App developers should be aware of this avenue for private data leakage. **Whenever an app requests information from a public node, the entity running that node is unlikely be your user!** +App developers should be aware of this avenue for private data leakage. **Whenever an app requests information from a node, the entity running that node is unlikely be your user!** #### What kind of queries can be leaky? @@ -142,9 +124,9 @@ So for maximal privacy, it's in a user's best interest to read from the very-lat Naturally, the private data tree is continuously changing as new transactions take place and their new notes are appended. Most notably, the sibling path for every leaf in the tree changes every time a new leaf is appended. -If a user runs their own public node, there's no problem: they can query the latest sibling path for their note(s) from their own machine without leaking any information to the outside world. +If a user runs their own node, there's no problem: they can query the latest sibling path for their note(s) from their own machine without leaking any information to the outside world. -But if a user is not running their own public node, they would need to query the very-latest sibling path of their note(s) from some 3rd-party public node. In order to query the sibling path of a leaf, the leaf's index needs to be provided as an argument. Revealing the leaf's index to a 3rd-party trivially reveals exactly the note(s) you're about to read. And since those notes were created in some prior transaction, the 3rd-party will be able to link you with that prior transaction. Suppose then that the 3rd-party also serviced the creator of said prior transaction: the 3rd-party will slowly be able to link more and more transactions, and gain more and more insight into a network which is meant to be private! +But if a user is not running their own node, they would need to query the very-latest sibling path of their note(s) from some 3rd-party node. In order to query the sibling path of a leaf, the leaf's index needs to be provided as an argument. Revealing the leaf's index to a 3rd-party trivially reveals exactly the note(s) you're about to read. And since those notes were created in some prior transaction, the 3rd-party will be able to link you with that prior transaction. Suppose then that the 3rd-party also serviced the creator of said prior transaction: the 3rd-party will slowly be able to link more and more transactions, and gain more and more insight into a network which is meant to be private! We're [researching](../../about_aztec/roadmap/engineering_roadmap.md) cryptographic ways to enable users to retrieve sibling paths from 3rd-parties without revealing leaf indices. @@ -152,7 +134,7 @@ We're [researching](../../about_aztec/roadmap/engineering_roadmap.md) cryptograp ##### Any query -Any query to a public node leaks information to that node. +Any query to a node leaks information to that node. We're [researching](../../about_aztec/roadmap/engineering_roadmap.md) cryptographic ways to enable users to query any data privately. diff --git a/docs/docs/misc/common/_disclaimer.mdx b/docs/docs/misc/common/_disclaimer.mdx index f854966ee17f..2bd4a3a0cfcd 100644 --- a/docs/docs/misc/common/_disclaimer.mdx +++ b/docs/docs/misc/common/_disclaimer.mdx @@ -3,6 +3,8 @@ :::caution Disclaimer We are building Aztec as transparently as we can. The documents published here are living documents. The protocol, sandbox, language, and tools are all subject to change over time. +Please see [here](../../dev_docs/limitations/main.md) for details of known Aztec protocol and Aztec Sandbox limitations. + If you would like to help us build Aztec: - Contribute code on [GitHub](https://github.com/AztecProtocol); or - Join in [forum](https://discourse.aztec.network/) discussions. diff --git a/docs/sidebars.js b/docs/sidebars.js index 6fac17da15ed..980a157f7f6b 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -322,17 +322,8 @@ const sidebars = { ], }, - { - label: "Limitations", - type: "doc", - id: "dev_docs/limitations/main", - }, - - { - label: "Privacy Considerations", - type: "doc", - id: "dev_docs/privacy/main", - }, + "dev_docs/limitations/main", + "dev_docs/privacy/main", { type: "html",