From 0e789c7c31a6272ec5b063f4583fb2d59e6ba73f Mon Sep 17 00:00:00 2001 From: Lasse Herskind <16536249+LHerskind@users.noreply.github.com> Date: Wed, 20 Sep 2023 13:33:34 +0100 Subject: [PATCH] docs: misc docs changes (#2416) Addresses miscellaneous issues in the documentation. Building on top of #2408. --- docs/docs/dev_docs/contracts/layout.md | 28 +- .../dev_docs/contracts/syntax/context.mdx | 2 +- .../dev_docs/contracts/syntax/contract.md | 31 --- .../dev_docs/contracts/{ => syntax}/events.md | 76 +++--- .../dev_docs/contracts/syntax/functions.md | 11 + .../docs/dev_docs/contracts/syntax/globals.md | 4 +- docs/docs/dev_docs/contracts/syntax/main.md | 6 +- .../contracts/syntax/state_variables.md | 2 +- .../docs/dev_docs/contracts/syntax/storage.md | 35 ++- .../dapps/tutorials/contract_interaction.md | 2 +- docs/docs/dev_docs/limitations/main.md | 17 +- docs/docs/dev_docs/testing/testing.md | 2 +- docs/sidebars.js | 255 +++++++++--------- .../docs_example_contract/src/main.nr | 4 +- .../src/contracts/token_contract/src/main.nr | 2 + 15 files changed, 263 insertions(+), 214 deletions(-) delete mode 100644 docs/docs/dev_docs/contracts/syntax/contract.md rename docs/docs/dev_docs/contracts/{ => syntax}/events.md (64%) diff --git a/docs/docs/dev_docs/contracts/layout.md b/docs/docs/dev_docs/contracts/layout.md index a6db7b63a6d..50832159f1a 100644 --- a/docs/docs/dev_docs/contracts/layout.md +++ b/docs/docs/dev_docs/contracts/layout.md @@ -1,4 +1,27 @@ -# Layout +--- +title: Structure +--- + +A contract is a collection of persistent [state variables](./syntax/state_variables.md), and [functions](./syntax/functions) which may manipulate these variables. Functions and state variables 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 to an external function of the other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called. + +# Contract + +A contract may be declared and given a name using the `contract` keyword (see snippet below). By convention, contracts are named in `PascalCase`. + +```rust title="contract keyword" +// highlight-next-line +contract MyContract { + + // Imports + + // Storage + + // Functions +} +``` +:::info A note for vanilla Noir devs +There is no [`main()`](https://noir-lang.org/getting_started/breakdown/#mainnr) function within a Noir `contract` scope. More than one function can be an entrypoint. +::: ## Directory structure @@ -11,4 +34,5 @@ Here's a common layout for a basic Aztec.nr Contract project: └── Nargo.toml <-- package and dependency management ``` -> See the vanilla Noir docs for [more info on packages](https://noir-lang.org/modules_packages_crates/crates_and_packages). +- See the vanilla Noir docs for [more info on packages](https://noir-lang.org/modules_packages_crates/crates_and_packages). +- You can review the structure of a complete contract in the token contract tutorial [here](../getting_started/token_contract_tutorial.md). diff --git a/docs/docs/dev_docs/contracts/syntax/context.mdx b/docs/docs/dev_docs/contracts/syntax/context.mdx index 3ea5a60ab16..3b8afffd983 100644 --- a/docs/docs/dev_docs/contracts/syntax/context.mdx +++ b/docs/docs/dev_docs/contracts/syntax/context.mdx @@ -1,5 +1,5 @@ --- -title: Aztec.nr Context +title: Function Context description: Documentation of Aztec's Private and Public execution contexts hide_table_of_contents: false --- diff --git a/docs/docs/dev_docs/contracts/syntax/contract.md b/docs/docs/dev_docs/contracts/syntax/contract.md deleted file mode 100644 index 5e125b8a797..00000000000 --- a/docs/docs/dev_docs/contracts/syntax/contract.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Contract ---- - -# Contract - -A contract is a collection of persistent [state variables](./state_variables.md), 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 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. - -A contract may be declared and given a name using the `contract` keyword (see snippet below). By convention, contracts are named in `PascalCase`. - -```rust title="contract keyword" -// highlight-next-line -contract MyContract { - - // Functions and state variables belonging to this contract are not shown here. - -} -``` - -> A note for vanilla Noir devs: There is no [`main()`](https://noir-lang.org/getting_started/breakdown/#mainnr) function within a Noir `contract` scope. This is because more than one function of a contract may be called and proven as external (as opposed to inlined by the compiler). - -## Structure of a contract - -- Private state variables -- Public state variables -- Private functions -- Public functions -- Encrypted events -- Unencrypted events - -You can review the structure of a complete contract in the token contract tutorial [here](../../getting_started/token_contract_tutorial.md). diff --git a/docs/docs/dev_docs/contracts/events.md b/docs/docs/dev_docs/contracts/syntax/events.md similarity index 64% rename from docs/docs/dev_docs/contracts/events.md rename to docs/docs/dev_docs/contracts/syntax/events.md index 36a809fde36..c50526530f0 100644 --- a/docs/docs/dev_docs/contracts/events.md +++ b/docs/docs/dev_docs/contracts/syntax/events.md @@ -5,12 +5,14 @@ title: Events Events in Aztec work similarly to Ethereum events in the sense that they are a way for contracts to communicate with the outside world. They are emitted by contracts and stored inside each instance of an AztecNode. -> Aztec events are currently represented as raw data and are not ABI encoded. -> ABI encoded events are a feature that will be added in the future. +:::info +Aztec events are currently represented as raw data and are not ABI encoded. +ABI encoded events are a feature that will be added in the future. +::: Unlike on Ethereum, there are 2 types of events supported by Aztec: encrypted and unencrypted. -### Encrypted Events +## Encrypted Events Encrypted events can only be emitted by private functions and are encrypted using a public key of a recipient. For this reason it is necessary to register a recipient in the Aztec RPC Server before encrypting the events for them. @@ -51,13 +53,15 @@ await aztecRpc.registerRecipient(completeAddress); -> **NOTE**: If a note recipient is one of the accounts inside the Aztec RPC Server, we don't need to register it as a recipient because we already have the public key available. +:::info +If a note recipient is one of the accounts inside the Aztec RPC Server, we don't need to register it as a recipient because we already have the public key available. You can register a recipient as shown [here](../deploying#deploying-private-token-contract) -> At this point the Sandbox only enables the emitting of encrypted note preimages through encrypted events. -> In the future we will allow emitting arbitrary information. -> (If you currently emit arbitrary information, Aztec RPC Server will fail to decrypt, process and store this data, so it will not be queryable). +At this point the Sandbox only enables the emitting of encrypted note preimages through encrypted events. +In the future we will allow emitting arbitrary information. +(If you currently emit arbitrary information, Aztec RPC Server will fail to decrypt, process and store this data, so it will not be queryable). +::: -To emit encrypted logs first import the `emit_encrypted_log` utility function inside your contract: +To emit encrypted logs first import the `emit_encrypted_log` utility function which wraps an [oracle](./functions.md#oracle-functions): #include_code encrypted_import /yarn-project/aztec-nr/value-note/src/utils.nr rust @@ -65,15 +69,33 @@ Then you can call the function: #include_code encrypted /yarn-project/aztec-nr/value-note/src/utils.nr rust -### Unencrypted Events +### Processing Encrypted Events -Unencrypted events are events which can be read by anyone. -They can be emitted by both public and private functions. +One of the functions of the Aztec RPC Server is constantly loading encrypted logs from the `AztecNode` and decrypting them. +When new encrypted logs are obtained, the Aztec RPC Server will try to decrypt them using the private encryption key of all the accounts registered inside Aztec RPC Server. +If the decryption is successful, the Aztec RPC Server will store the decrypted note inside a database. +If the decryption fails, the specific log will be discarded. + +For the Aztec RPC Server to successfully process the decrypted note we need to compute the note's 'note hash' and 'nullifier'. +Aztec.nr enables smart contract developers to design custom notes, meaning developers can also customize how a note's note hash and nullifier should be computed. Because of this customizability, and because there will be a potentially-unlimited number of smart contracts deployed to Aztec, an Aztec RPC Server needs to be 'taught' how to compute the custom note hashes and nullifiers for a particular contract. Therefore, developers will need to implement a `compute_note_hash_and_nullifier` function inside their contracts. :::danger +If your function has private state variables, you **MUST** include a `compute_note_hash_and_nullifier` function to allow the RPC to process encrypted events. +::: + +Every time a new note is successfully decrypted, the Aztec RPC Server will expect the existence of a `compute_note_hash_and_nullifier` function, which must teach it how to correctly process the new note. + +#include_code compute_note_hash_and_nullifier /yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr rust + + +## Unencrypted Events -Emitting unencrypted events from private function is a significant privacy leak and it should be considered by the developer whether it is acceptable. +Unencrypted events are events which can be read by anyone. +They can be emitted by both public and private functions. +:::danger +- Emitting unencrypted events from private function is a significant privacy leak and it should be considered by the developer whether it is acceptable. +- Unencrypted events are currently **NOT** linked to the contract emitting them, so it is practically a [`debug_log`](./functions.md#a-few-useful-inbuilt-oracles). ::: To emit unencrypted logs first import the `emit_unencrypted_log` utility function inside your contract: @@ -104,31 +126,11 @@ aztec-cli get-logs --from 5 --limit 1 All event data is pushed to Ethereum as calldata by the sequencer and for this reason the cost of emitting an event is non-trivial. -> Note: the cost of submitting calldata to Ethereum is currently 4 gas per byte. Currently, in the Sandbox, an encypted note has a fixed overhead of 4 field elements (to broadcast an ephemeral public key, a contract address, and a storage slot); plus a variable number of field elements depending on the type of note being emitted. -> A `ValueNote`, for example, currently uses 3 fields elements (plus the fixed overhead of 4). That's roughly `7 * 32 = 224` bytes of information, costing roughly 896 gas. - -> There are plans to compress encrypted note data further. -> There are plans to adopt EIP-4844 blobs to reduce the cost of data submission further. - -## Processing events - -Both the encrypted and unencrypted events are stored in AztecNode. -Unencrypted logs can be queried by anyone as we described above in the [Unencrypted Events](#unencrypted-events) section. - -Encrypted logs need to first be decrypted: - -### Decrypting +In the Sandbox, an encrypted note has a fixed overhead of 4 field elements (to broadcast an ephemeral public key, a contract address, and a storage slot); plus a variable number of field elements depending on the type of note being emitted. -One function of Aztec RPC Server is constantly loading encrypted logs from AztecNode and trying to decrypt them. -When new encrypted logs are obtained, the Aztec RPC Server will try to decrypt them using the private encryption key of all the accounts registered inside Aztec RPC Server. -If the decryption is successful, the Aztec RPC Server will store the decrypted note inside a database. -If the decryption fails, the specific log will be discarded. - -For the Aztec RPC Server to successfully process the decrypted note we need to compute the note's 'note hash' and 'nullifier'. -Aztec.nr enables smart contract developers to design custom notes, meaning developers can also customise how a note's note hash and nullifier should be computed. Because of this customisability, and because there will be a potentially-unlimited number of smart contracts deployed to Aztec, an Aztec RPC Server needs to be 'taught' how to compute the custom note hashes and nullifiers for a particular contract. Therefore, developers will need to implement a `compute_note_hash_and_nullifier` function inside their contracts. - -Every time a new note is successfully decrypted, the Aztec RPC Server will expect the existence of a `compute_note_hash_and_nullifier` function, which must teach it how to correctly process the new note. +A `ValueNote`, for example, currently uses 3 fields elements (plus the fixed overhead of 4). That's roughly `7 * 32 = 224` bytes of information. -This is an example implementation inside the `PrivateTokenContract`: +#include_code value-note-def /yarn-project/aztec-nr/value-note/src/value_note.nr -#include_code compute_note_hash_and_nullifier /yarn-project/noir-contracts/src/contracts/private_token_contract/src/main.nr rust +- There are plans to compress encrypted note data further. +- There are plans to adopt EIP-4844 blobs to reduce the cost of data submission further. \ No newline at end of file diff --git a/docs/docs/dev_docs/contracts/syntax/functions.md b/docs/docs/dev_docs/contracts/syntax/functions.md index b68c18e515f..e1a01f03dd0 100644 --- a/docs/docs/dev_docs/contracts/syntax/functions.md +++ b/docs/docs/dev_docs/contracts/syntax/functions.md @@ -1,5 +1,6 @@ --- title: Functions +description: This page covers functions, private and public functions composability, as well as their differences. --- @@ -23,6 +24,15 @@ A good place to use `internal` is when you want a private function to be able to Note that non-internal functions could be used directly as an entry-point, which currently means that the `msg_sender` would be `0`, so for now, using address `0` as a burn address is not recommended. ::: +## Mutability +Currently, any function is "mutable" in the sense that it might alter state. In the future, we will support static calls, similarly to EVM. A static call is essentially a call that does not alter state (it keeps state static). This is useful for when you want to call a function in a separate contract, but ensure that it cannot alter state, or call other functions that might alter state (such as re-entering). + +Similarly, a special case of a mutating call is the `delegatecall` where the function executed might not be in the same contract as the state being altered. It is at this moment, not certain if `delegatecall`s should become a fully fledged feature. + +:::danger No `staticcall` or `delegatecall` support +While `staticcall` and `delegatecall` both have flags in the call context, they are currently not supported and will not behave as one would expect if usage is attempted. +::: + ## `constructor` - A special `constructor` function MUST be declared within a contract's scope. @@ -92,6 +102,7 @@ Oracles introduce **non-determinism** into a circuit, and thus are `unconstraine - [`auth_witness`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec-nr/aztec/src/oracle/auth_witness.nr) - Provides a way to fetch the authentication witness for a given address. This is useful when building account contracts to support approve-like functionality. - [`get_l1_to_l2_message`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec-nr/aztec/src/oracle/get_l1_to_l2_message.nr) - Useful for application that receive messages from L1 to be consumed on L2, such as token bridges or other cross-chain applications. - [`notes`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec-nr/aztec/src/oracle/notes.nr) - Provides a lot of functions related to notes, such as fetches notes from storage etc, used behind the scenes for value notes and other pre-build note implementations. +- [`logs`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec-nr/aztec/src/oracle/logs.nr) - Provides the to log encrypted and unencrypted data. --- diff --git a/docs/docs/dev_docs/contracts/syntax/globals.md b/docs/docs/dev_docs/contracts/syntax/globals.md index 39dc32abdff..1a50ac54066 100644 --- a/docs/docs/dev_docs/contracts/syntax/globals.md +++ b/docs/docs/dev_docs/contracts/syntax/globals.md @@ -47,6 +47,6 @@ context.block_number(); ``` :::info *Why do the available global variables differ per execution environment?* -> The global variables are constrained by the proving environment. In the case of public functions, they are executed on a sequencer that will know the timestamp and number of the next block ( as they are the block producer ). -> In the case of private functions, we cannot be sure which block our transaction will be included in, hence we can not guarantee values for the timestamp or block number. +The global variables are constrained by the proving environment. In the case of public functions, they are executed on a sequencer that will know the timestamp and number of the next block ( as they are the block producer ). +In the case of private functions, we cannot be sure which block our transaction will be included in, hence we can not guarantee values for the timestamp or block number. ::: \ No newline at end of file diff --git a/docs/docs/dev_docs/contracts/syntax/main.md b/docs/docs/dev_docs/contracts/syntax/main.md index 870466e98de..7dfa37376c7 100644 --- a/docs/docs/dev_docs/contracts/syntax/main.md +++ b/docs/docs/dev_docs/contracts/syntax/main.md @@ -10,11 +10,11 @@ Aztec.nr contains abstractions which remove the need to understand the low-level - Public and private [state variable types](./state_variables.md) - Some pre-designed notes -- Functions for [emitting](../events.md) encrypted and unencrypted logs -- [Oracle functions](./functions.md#oracle-calls) for accessing: +- Functions for [emitting](./events.md) encrypted and unencrypted logs +- [Oracle functions](./functions.md#oracle-functions) for accessing: - private state - secrets -- Functions for communicating with Ethereum L1 +- Functions for communicating with [Ethereum L1](./messaging.md) To import Aztec.nr into your Aztec contract project, simply include it as a dependency. For example: diff --git a/docs/docs/dev_docs/contracts/syntax/state_variables.md b/docs/docs/dev_docs/contracts/syntax/state_variables.md index 517671de8a5..c9868cc47bf 100644 --- a/docs/docs/dev_docs/contracts/syntax/state_variables.md +++ b/docs/docs/dev_docs/contracts/syntax/state_variables.md @@ -92,7 +92,7 @@ For example, the following function calls the account contract before it updates In contrast to public state, private state is persistent state that is _not_ visible to the whole world. Depending on the logic of the smart contract, a _private_ state variable's current value will only be known to one entity, or a closed group of entities. -The value of a private state variable can either be shared via [events](../events), or offchain via web2, or completely offline: it's up to the app developer. +The value of a private state variable can either be shared via [events](./events.md), or offchain via web2, or completely offline: it's up to the app developer. Aztec private state follows a utxo-based model. That is, a private state's current value is represented as one or many [notes](#notes). Each note is stored as an individual leaf in a utxo-based merkle tree: the [private state tree](/concepts/advanced/data_structures/trees#private-state-tree). diff --git a/docs/docs/dev_docs/contracts/syntax/storage.md b/docs/docs/dev_docs/contracts/syntax/storage.md index 2ef2b361037..9b04e3efecc 100644 --- a/docs/docs/dev_docs/contracts/syntax/storage.md +++ b/docs/docs/dev_docs/contracts/syntax/storage.md @@ -1,13 +1,40 @@ # Storage -State variables must be declared inside a struct. (This enables us to declare types composed of nested generics in Noir). +In an Aztec.nr contract, storage is to be defined as a single struct. (This enables us to declare types composed of nested generics in Noir). -We could define any kinds of state variables in the Storage struct: +The struct **must** be called `Storage` for the Aztec.nr library to properly handle it (will be fixed in the future to support more flexibility). +An example of such a struct could be as follows: + +#include_code storage-struct-declaration /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr rust + +:::info +If your storage includes private state variables it must include a `compute_note_hash_and_nullifier` function to allow the RPC to process encrypted events, see [encrypted events](./events.md#processing-encrypted-events) for more. +::: + +In the storage stuct, we set up a mixture of public and private state variables. The public state variables can be read by anyone, and functions manipulating them are executed by the sequencer, (see [functions](./functions.md#public-functions)). Private state variables are only readable by their owner, or people whom the owner has shared the data with. + +As mentioned earlier in the foundational concepts ([state model](./../../../concepts/foundation/state_model.md) and [private/public execution](./../../../concepts/foundation/communication/public_private_calls.md)) private state follows a UTXO model. Where note pre-images are only known to those able to decrypt them. + +It is currently required to specify the length of the types when declaring the storage struct. If your type is a struct, this will be the number of values in your struct ( with arrays flattened ). + +Since Aztec.nr is a library written in Noir, we can use the types defined in Noir, so it can be useful to consult the [Noir documentation](https://noir-lang.org/language_concepts/data_types) for information on types. + +Currently, the sandbox also requires that you specify how this storage struct is "initialized". This is done by specifying an `init` function that is run in functions that rely on reading or altering the state variables. + +An example of such a function for the above storage struct would be: #include_code storage-declaration /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr rust -See [State Variables](./state_variables.md) for how to initialise them. +:::warning Using slot `0` is not supported! +No storage values should be initialized at slot `0`. If you are using slot `0` for storage, you will not get an error when compiling, but the contract will not be updating the storage! This is a known issue that will be fixed in the future. +::: -Using Storage in a contract is like using any other struct in Noir. For each function that needs access to the storage, initialise the storage inside the function, and then access its state variable members: +In [State Variables](./state_variables.md) we will see in more detail what each of these types are, how they work and how to initialize them. + +To use storage in functions, e.g., functions where you would read or write storage, you need to initialize the struct first, and then you can read and write afterwards. #include_code storage-init /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr rust + +:::info +https://github.com/AztecProtocol/aztec-packages/pull/2406 is removing the need to explicitly initialize the storage in each function before reading or writing. This will be updated in the docs once the PR is merged. +::: \ No newline at end of file diff --git a/docs/docs/dev_docs/dapps/tutorials/contract_interaction.md b/docs/docs/dev_docs/dapps/tutorials/contract_interaction.md index bf029bdea39..545cc827100 100644 --- a/docs/docs/dev_docs/dapps/tutorials/contract_interaction.md +++ b/docs/docs/dev_docs/dapps/tutorials/contract_interaction.md @@ -121,7 +121,7 @@ Balance of 0x226f8087792beff8d5009eb94e65d2a4a505b70baf4a9f28d33c8d620b0ba972: 0 Balance of 0x0e1f60e8566e2c6d32378bdcadb7c63696e853281be798c107266b8c3a88ea9b: 0 ``` -Public functions can emit [unencrypted public logs](../../contracts/events.md#unencrypted-events), which we can query via the RPC Server interface. For example, here we have a `mint` method that emits a generic `Coins minted` whenever it is called: +Public functions can emit [unencrypted public logs](../../contracts/syntax/events.md#unencrypted-events), which we can query via the RPC Server interface. In particular, the public token contract emits a generic `Coins minted` whenever the `mint` method is called: #include_code unencrypted_log yarn-project/noir-contracts/src/contracts/public_token_contract/src/main.nr rust diff --git a/docs/docs/dev_docs/limitations/main.md b/docs/docs/dev_docs/limitations/main.md index 7790b895cff..d55bb375404 100644 --- a/docs/docs/dev_docs/limitations/main.md +++ b/docs/docs/dev_docs/limitations/main.md @@ -12,9 +12,6 @@ The Aztec Sandbox and the Aztec Smart Contract Library are **prototypes**, and s - An 'unpolished' UX; - Missing information. -## Why isn't it working perfectly yet? - -These things take time :) ## Why participate? @@ -29,6 +26,20 @@ Help shape and define: - Educational content; - Core protocol improvements; +## Limitations developers need to know about +- It is a testing environment, it is insecure, unaudited and does not generate any proofs, its only for testing purposes; +- Constructors can not call nor alter public state + - The constructor is executed exclusively in private domain, WITHOUT the ability to call public functions or alter public state. This means to set initial storage values, you need to follow a pattern similar to [proxies in Ethereum](https://blog.openzeppelin.com/proxy-patterns), where you `initialize` the contract with values after it have been deployed, see [constructor](../contracts/syntax/functions.md#constructor). +- No static nor delegate calls (see [mutability](../contracts/syntax/functions.md#mutability)). + - These values are unused in the call-context. + - Beware that what you think of as a `view` could alter state ATM! Notably the account could alter state or re-enter whenever the account contract's `is_valid` function is called. +- `msg_sender` is currently leaking when doing private -> public calls + - The `msg_sender` will always be set, if you call a public function from the private world, the `msg_sender` will be set to the private caller's address. See [function context](../contracts/syntax/context.mdx). +- The initial `msg_sender` is 0, which can be problematic for some contracts, see [function visibility](../contracts/syntax/functions.md#function-visibility). +- Unencrypted logs don't link to the contract that emitted it, so essentially just a `debug_log`` that you can match values against. +- A note that is created and nullified in the same transaction will still emit an encrypted log. +- A limited amount of new commitments, nullifiers and calls that are supported by a transaction, see [circuit limitations](#circuit-limitations). + ## Limitations There are plans to resolve all of the below. See also the [engineering roadmap](../../about_aztec/roadmap/engineering_roadmap.md). diff --git a/docs/docs/dev_docs/testing/testing.md b/docs/docs/dev_docs/testing/testing.md index ef2ce16123a..d8bdf31adbe 100644 --- a/docs/docs/dev_docs/testing/testing.md +++ b/docs/docs/dev_docs/testing/testing.md @@ -149,7 +149,7 @@ We can query the RPC server for all notes encrypted for a given user in a contra ### Logs -Last but not least, we can check the logs of [events](../contracts/events.md) emitted by our contracts. Contracts in Aztec can emit both [encrypted](../contracts/events.md#encrypted-events) and [unencrypted](../contracts/events.md#unencrypted-events) events. +Last but not least, we can check the logs of [events](../contracts/syntax/events.md) emitted by our contracts. Contracts in Aztec can emit both [encrypted](../contracts/syntax/events.md#encrypted-events) and [unencrypted](../contracts/syntax/events.md#unencrypted-events) events. :::info At the time of this writing, only unencrypted events can be queried directly. Encrypted events are always assumed to be encrypted notes. diff --git a/docs/sidebars.js b/docs/sidebars.js index b5424636ddf..099c6b0a230 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -58,6 +58,125 @@ const sidebars = { value: '', }, + // SPECIFICATION + + { + type: "html", + className: "sidebar-title", + value: "Specification", + defaultStyle: true, + }, + + { + label: "Foundational Concepts", + type: "category", + link: { + type: "doc", + id: "concepts/foundation/main", + }, + items: [ + "concepts/foundation/state_model", + { + label: "Accounts", + type: "category", + link: { type: "doc", id: "concepts/foundation/accounts/main" }, + items: ["concepts/foundation/accounts/keys"], + }, + "concepts/foundation/contracts", + "concepts/foundation/transactions", + // "concepts/foundation/blocks", + // "concepts/foundation/globals", + { + label: "Communication", + type: "category", + link: { + type: "doc", + id: "concepts/foundation/communication/main", + }, + items: [ + "concepts/foundation/communication/public_private_calls", + "concepts/foundation/communication/cross_chain_calls", + ], + }, + // { + // label: "Nodes and Clients", + // type: "category", + // link: { + // type: "doc", + // id: "concepts/foundation/nodes_clients/main", + // }, + // items: [ + // "concepts/foundation/nodes_clients/execution_client", + // "concepts/foundation/nodes_clients/prover_client", + // "concepts/foundation/nodes_clients/sequencer_client", + // ], + // }, + // "concepts/foundation/block_production", + // "concepts/foundation/upgrade_mechanism", + ], + }, + + { + label: "Advanced Concepts", + type: "category", + link: { + type: "doc", + id: "concepts/advanced/main", + }, + items: [ + { + label: "Data Structures", + type: "category", + link: { + type: "doc", + id: "concepts/advanced/data_structures/main", + }, + items: [ + "concepts/advanced/data_structures/trees", + "concepts/advanced/data_structures/indexed_merkle_tree", + ], + }, + { + label: "Circuits", + type: "category", + link: { + type: "doc", + id: "concepts/advanced/circuits/main", + }, + items: [ + { + label: "Kernels", + type: "category", + link: { + type: "doc", + id: "concepts/advanced/circuits/kernels/main", + }, + items: [ + "concepts/advanced/circuits/kernels/private_kernel", + "concepts/advanced/circuits/kernels/public_kernel", + ], + }, + { + label: "Rollup Circuits", + type: "category", + link: { + type: "doc", + id: "concepts/advanced/circuits/rollup_circuits/main", + }, + items: [], + }, + ], + }, + "concepts/advanced/public_vm", + "concepts/advanced/contract_creation", + ], + }, + + { + type: "html", + value: '', + }, + // DEVELOPER DOCUMENTATION { @@ -92,10 +211,6 @@ const sidebars = { items: [ "dev_docs/contracts/workflow", "dev_docs/contracts/layout", - "dev_docs/contracts/events", - "dev_docs/contracts/compiling", - "dev_docs/contracts/deploying", - "dev_docs/contracts/artifacts", { label: "Syntax", type: "category", @@ -104,9 +219,9 @@ const sidebars = { id: "dev_docs/contracts/syntax/main", }, items: [ - "dev_docs/contracts/syntax/contract", "dev_docs/contracts/syntax/storage", "dev_docs/contracts/syntax/state_variables", + "dev_docs/contracts/syntax/events", "dev_docs/contracts/syntax/functions", "dev_docs/contracts/syntax/context", "dev_docs/contracts/syntax/globals", @@ -127,6 +242,9 @@ const sidebars = { "dev_docs/contracts/portals/outbox", ], }, + "dev_docs/contracts/compiling", + "dev_docs/contracts/deploying", + "dev_docs/contracts/artifacts", // { // label: "Resources", // type: "category", @@ -242,130 +360,13 @@ const sidebars = { ], }, - { + /* { label: "Security Considerations", type: "category", - items: ["dev_docs/limitations/main", "dev_docs/privacy/main"], - }, - - { - type: "html", - value: '', - }, - - // SPECIFICATION - - { - type: "html", - className: "sidebar-title", - value: "Specification", - defaultStyle: true, - }, - - { - label: "Foundational Concepts", - type: "category", - link: { - type: "doc", - id: "concepts/foundation/main", - }, - items: [ - "concepts/foundation/state_model", - { - label: "Accounts", - type: "category", - link: { type: "doc", id: "concepts/foundation/accounts/main" }, - items: ["concepts/foundation/accounts/keys"], - }, - "concepts/foundation/contracts", - "concepts/foundation/transactions", - // "concepts/foundation/blocks", - // "concepts/foundation/globals", - { - label: "Communication", - type: "category", - link: { - type: "doc", - id: "concepts/foundation/communication/main", - }, - items: [ - "concepts/foundation/communication/public_private_calls", - "concepts/foundation/communication/cross_chain_calls", - ], - }, - // { - // label: "Nodes and Clients", - // type: "category", - // link: { - // type: "doc", - // id: "concepts/foundation/nodes_clients/main", - // }, - // items: [ - // "concepts/foundation/nodes_clients/execution_client", - // "concepts/foundation/nodes_clients/prover_client", - // "concepts/foundation/nodes_clients/sequencer_client", - // ], - // }, - // "concepts/foundation/block_production", - // "concepts/foundation/upgrade_mechanism", - ], - }, - - { - label: "Advanced Concepts", - type: "category", - link: { - type: "doc", - id: "concepts/advanced/main", - }, - items: [ - { - label: "Data Structures", - type: "category", - link: { - type: "doc", - id: "concepts/advanced/data_structures/main", - }, - items: [ - "concepts/advanced/data_structures/trees", - "concepts/advanced/data_structures/indexed_merkle_tree", - ], - }, - { - label: "Circuits", - type: "category", - link: { - type: "doc", - id: "concepts/advanced/circuits/main", - }, - items: [ - { - label: "Kernels", - type: "category", - link: { - type: "doc", - id: "concepts/advanced/circuits/kernels/main", - }, - items: [ - "concepts/advanced/circuits/kernels/private_kernel", - "concepts/advanced/circuits/kernels/public_kernel", - ], - }, - { - label: "Rollup Circuits", - type: "category", - link: { - type: "doc", - id: "concepts/advanced/circuits/rollup_circuits/main", - }, - items: [], - }, - ], - }, - "concepts/advanced/public_vm", - "concepts/advanced/contract_creation", - ], - }, + items: [], + },*/ + "dev_docs/privacy/main", + "dev_docs/limitations/main", { type: "html", diff --git a/yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr b/yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr index 14af9b686e6..961de5cc9ae 100644 --- a/yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr +++ b/yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr @@ -27,7 +27,7 @@ contract DocsExample { rules_note::{RulesNote, RulesNoteMethods, RULES_NOTE_LEN}, }; - // docs:start:storage-declaration + // docs:start:storage-struct-declaration struct Storage { locked: PublicState, queen: PublicState, @@ -36,7 +36,9 @@ contract DocsExample { cards: Set, profiles: Map>, } + // docs:end:storage-struct-declaration + // docs:start:storage-declaration // docs:start:state_vars-PublicState // docs:start:state_vars-PublicStateCustomStruct // docs:start:state_vars-Singleton diff --git a/yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr b/yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr index 6105bb8f675..9fc38917054 100644 --- a/yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr +++ b/yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr @@ -419,6 +419,7 @@ contract Token { // Below this point is the stuff of nightmares. // This should ideally not be required. What do we do if vastly different types of preimages? + // docs:start:compute_note_hash_and_nullifier // Computes note hash and nullifier. // Note 1: Needs to be defined by every contract producing logs. // Note 2: Having it in all the contracts gives us the ability to compute the note hash and nullifier differently for different kind of notes. @@ -430,6 +431,7 @@ contract Token { note_utils::compute_note_hash_and_nullifier(ValueNoteMethods, note_header, preimage) } } + // docs:end:compute_note_hash_and_nullifier } // docs:end:token_all