diff --git a/docs/docs/dev_docs/contracts/aztec_types.md b/docs/docs/dev_docs/contracts/aztec_types.md index ca73d7ab5b26..53561364f191 100644 --- a/docs/docs/dev_docs/contracts/aztec_types.md +++ b/docs/docs/dev_docs/contracts/aztec_types.md @@ -3,13 +3,15 @@ title: Aztec.nr Types description: Documentation of Aztec's Types --- -With Aztec.nr we are include a series of types that are useful for writing Aztec contracts. While almost anything is modelled just as plain Fields underneath it can be quite useful for developers to have a series of types when writing that apply different types of constrains on top to make the code more readable and easier to follow. +With Aztec.nr we include a series of useful types. While most types are Fields underneath it can be useful for developers to have custom types that: +1. Apply different types of constrains +2. Make the code easier to follow -## `AztecAddress` +A Field wrapper that alters the name. Making it explicit that the value is an address, and not something else. A wrapper around a Field that mainly just alters the name to make it more clear that the value is an address and not a number of a hash or something else. -## `EthereumAddress` +A wrapper around a Field that performs a range check to ensure that the value is 20 bytes. A wrapper around a Field that perform a range check to ensure that the number of bytes used don't exceed 20. diff --git a/docs/docs/dev_docs/contracts/layout.md b/docs/docs/dev_docs/contracts/layout.md index 2e6420cf75d0..50832159f1aa 100644 --- a/docs/docs/dev_docs/contracts/layout.md +++ b/docs/docs/dev_docs/contracts/layout.md @@ -2,7 +2,7 @@ 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 that other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called. +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 @@ -20,7 +20,7 @@ contract MyContract { } ``` :::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. This is because more than one function of a contract may be called and proven as external (as opposed to inlined by the compiler). +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 diff --git a/docs/docs/dev_docs/contracts/syntax/events.md b/docs/docs/dev_docs/contracts/syntax/events.md index 2c47231e139c..f09a4aa66d47 100644 --- a/docs/docs/dev_docs/contracts/syntax/events.md +++ b/docs/docs/dev_docs/contracts/syntax/events.md @@ -61,7 +61,7 @@ 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 which wraps an oracle: +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 @@ -71,7 +71,7 @@ Then you can call the function: ### Processing Encrypted Events -One function of Aztec RPC Server is constantly loading encrypted logs from AztecNode and trying to decrypt them. +One function of Aztec RPC Server is constantly loading encrypted logs from an 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. @@ -127,7 +127,7 @@ 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. :::info -the cost of submitting calldata to Ethereum is currently 4 gas per byte. Currently, 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. +The cost of submitting calldata to Ethereum is currently 4 gas per byte. 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. A `ValueNote`, for example, currently uses 3 fields elements (plus the fixed overhead of 4). That's roughly `7 * 32 = 224` bytes of information. diff --git a/docs/docs/dev_docs/contracts/syntax/functions.md b/docs/docs/dev_docs/contracts/syntax/functions.md index 5ebfb7e268d7..656d1367eec8 100644 --- a/docs/docs/dev_docs/contracts/syntax/functions.md +++ b/docs/docs/dev_docs/contracts/syntax/functions.md @@ -1,6 +1,6 @@ --- title: Functions -description: This page will go over functions, how private and public functions differ and how then can be used together. +description: This page covers functions, private and public functions composability, as well as their differences. --- diff --git a/docs/docs/dev_docs/contracts/syntax/storage.md b/docs/docs/dev_docs/contracts/syntax/storage.md index 3d5c06c91695..9b04e3efecca 100644 --- a/docs/docs/dev_docs/contracts/syntax/storage.md +++ b/docs/docs/dev_docs/contracts/syntax/storage.md @@ -3,35 +3,35 @@ 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). 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 follow: +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 include 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. +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 here, we are setting up a mix of public and private state variables. The public state variables can be read by anyone, and functions manipulating them are executed by the sequence, we will see more to this in [functions](./functions.md#public-functions) in a few moments. The private state variables are only readable by their owner, or people whom the owner have shared the data with. +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 are following a UTXO model where only the people knowing the pre-images of the commitments in the state will be able to use that knowledge. +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. The length will depend on the type of the state variable you are using with the length being the number of Field elements used to represent it. +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 on top of 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. +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 require that you specify how this storage struct is going to be initialized. Initialized here being how the state variables should be "setup" such that they can be read properly by the contract. This is done by specifying an `init` function that is run in functions that rely on reading or altering the state variables. +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 :::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 bug that will be fixed in the future. +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. ::: 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 the 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. +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 diff --git a/docs/docs/dev_docs/limitations/main.md b/docs/docs/dev_docs/limitations/main.md index 4b54fd87ea93..4a5200c2de14 100644 --- a/docs/docs/dev_docs/limitations/main.md +++ b/docs/docs/dev_docs/limitations/main.md @@ -26,14 +26,14 @@ Help shape and define: - Educational content; - Core protocol improvements; -## Limitations that devs need to know about -- It is a testing environment, it is insecure, unaudited and don't generate any proofs, its only for testing purposes; -- Constructor can't call or alter public state - - the constructor is completely executed in private domain, WITHOUT the ability to call public functions or alter public state. This means that to set initial storage values, you need to follow a pattern similar to proxies in Eth, where you `initialize` the contract with values after it have been deployed, see [constructor](../contracts/syntax/functions.md#constructor). -- No static or delegate calls (see [mutability](../contracts/syntax/functions.md#mutability)). - - there are values in the call-context, but they are not used. Beware that what you think of as a `view` could alter state ATM! Notable the account could alter state or re-enter whenever the account `is_valid` is called. +## 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)). + - There are unused values 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 leaked when doing private -> public calls - - the `msg_sender` will always be set, so 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 `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.