diff --git a/docs/.gitignore b/docs/.gitignore index bfd44418b7d..2b2fad56010 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -22,6 +22,6 @@ npm-debug.log* yarn-debug.log* yarn-error.log* -docs/reference/aztecjs -docs/reference/smart_contract_reference/aztec-nr +/docs/reference/developer_references/aztecjs +/docs/reference/developer_references/smart_contract_reference/aztec-nr test-results diff --git a/docs/.yarn/install-state.gz b/docs/.yarn/install-state.gz new file mode 100644 index 00000000000..c89d944a5b6 Binary files /dev/null and b/docs/.yarn/install-state.gz differ diff --git a/docs/docs/aztec.md b/docs/docs/aztec.md index 16b1ab227e2..d3abe381171 100644 --- a/docs/docs/aztec.md +++ b/docs/docs/aztec.md @@ -1,5 +1,5 @@ --- -title: Programmable Privacy +title: Building in Public sidebar_position: 0 --- @@ -22,7 +22,7 @@ Aztec is inspired on Ethereum. We believe in transparency for the protocol, but To allow for this, we focus on two main components: -- **Noir** - We started developing Noir long before Aztec came into being. As an easy, open-source domain specific programming language for writing zero-knowledge circuits, it became the perfect language for writing [Aztec Smart Contracts](aztec/concepts/smart_contracts/index.md). Read about standalone Noir in the [Noir Lang Documentation](https://noir-lang.org). +- **Noir** - We started developing Noir long before Aztec came into being. As an easy, open-source domain specific programming language for writing zero-knowledge circuits, it became the perfect language for writing [Aztec Smart Contracts](aztec/smart_contracts_overview.md). Read about standalone Noir in the [Noir Lang Documentation](https://noir-lang.org). - **Honk** - A collection of cutting-edge cryptography, from proving systems, to compilers, and other sidecars. These will support Aztec's rollup and allow for fast, private, client-side proving. ## Media diff --git a/docs/docs/aztec/concepts/_category_.json b/docs/docs/aztec/concepts/_category_.json new file mode 100644 index 00000000000..88de50877b4 --- /dev/null +++ b/docs/docs/aztec/concepts/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Concepts", + "position": 1, + "collapsible": true, + "collapsed": true +} diff --git a/docs/docs/aztec/concepts/accounts/authwit.md b/docs/docs/aztec/concepts/accounts/authwit.md index d416abfd4ed..182f0ee4bc2 100644 --- a/docs/docs/aztec/concepts/accounts/authwit.md +++ b/docs/docs/aztec/concepts/accounts/authwit.md @@ -1,5 +1,6 @@ --- title: Authentication Witness +tags: [accounts, authwit] --- Authentication Witness is a scheme for authenticating actions on Aztec, so users can allow third-parties (eg protocols or other users) to execute an action on their behalf. @@ -56,7 +57,7 @@ Adopting ERC20 for Aztec is not as simple as it might seem because of private st If you recall from the [Hybrid State model](../state_model/index.md), private state is generally only known by its owner and those they have shared it with. Because it relies on secrets, private state might be "owned" by a contract, but it needs someone with knowledge of these secrets to actually spend it. You might see where this is going. -If we were to implement the `approve` with an allowance in private, you might know the allowance, but unless you also know about the individual notes that make up the user's balances, it would be of no use to you! It is private after all. To spend the user's funds you would need to know the decryption key, see [keys for more](keys.md). +If we were to implement the `approve` with an allowance in private, you might know the allowance, but unless you also know about the individual notes that make up the user's balances, it would be of no use to you! It is private after all. To spend the user's funds you would need to know the decryption key, see [keys for more](./keys.md). While this might sound limiting in what we can actually do, the main use of approvals have been for simplifying contract interactions that the user is doing. In the case of private transactions, this is executed on the user device, so it is not a blocker that the user need to tell the executor a secret - the user is the executor! ### So what can we do? @@ -183,7 +184,7 @@ For the transfer, this could be done simply by appending a nonce to the argument action = H(defi, token, transfer_selector, H(alice_account, defi, 1000, nonce)); ``` -Beware that the account contract will be unable to emit the nullifier since it is checked with a static call, so the calling contract must do it. This is similar to nonces in ERC20 tokens today. We provide a small library that handles this which we will see in the [developer documentation](../../../guides/smart_contracts/writing_contracts/authwit.md). +Beware that the account contract will be unable to emit the nullifier since it is checked with a static call, so the calling contract must do it. This is similar to nonces in ERC20 tokens today. We provide a small library that handles this. ### Differences to approval @@ -197,4 +198,4 @@ We don't need to limit ourselves to the `transfer` function, we can use the same ### Next Steps -Check out the [developer documentation](../../../guides/smart_contracts/writing_contracts/authwit.md) to see how to implement this in your own contracts. +Check out the [developer documentation](../../../guides/developer_guides/smart_contracts/writing_contracts/authwit.md) to see how to implement this in your own contracts. diff --git a/docs/docs/aztec/concepts/accounts/index.md b/docs/docs/aztec/concepts/accounts/index.md index 05c405ed950..07bb6295451 100644 --- a/docs/docs/aztec/concepts/accounts/index.md +++ b/docs/docs/aztec/concepts/accounts/index.md @@ -1,6 +1,6 @@ --- title: Accounts -sidebar_position: 0 +sidebar_position: 1 tags: [accounts] --- @@ -72,7 +72,7 @@ def entryPoint(payload): enqueueCall(to, data, value, gasLimit); ``` -Read more about how to write an account contract [here](../../../tutorials/contract_tutorials/write_accounts_contract.md). +Read more about how to write an account contract [here](../../../tutorials/codealong/contract_tutorials/write_accounts_contract.md). ### Account contracts and wallets @@ -135,7 +135,7 @@ These two patterns combined allow an account contract to answer whether an actio Aztec requires users to define [encryption and nullifying keys](./keys.md) that are needed for receiving and spending private notes. Unlike transaction signing, encryption and nullifying is enshrined at the protocol. This means that there is a single scheme used for encryption and nullifying. These keys are derived from a master public key. This master public key, in turn, is used when deterministically deriving the account's address. -A side effect of committing to a master public key as part of the address is that _this key cannot be rotated_. While an account contract implementation could include methods for rotating the signing key, this is unfortunately not possible for encryption and nullifying keys (note that rotating nullifying keys also creates other challenges such as preventing double spends). We are exploring usage of [`SharedMutable`](../../../reference/smart_contract_reference/storage/shared_state.md#sharedmutable) to enable rotating these keys. +A side effect of committing to a master public key as part of the address is that _this key cannot be rotated_. While an account contract implementation could include methods for rotating the signing key, this is unfortunately not possible for encryption and nullifying keys (note that rotating nullifying keys also creates other challenges such as preventing double spends). We are exploring usage of [`SharedMutable`](../../../reference/developer_references/smart_contract_reference/storage/shared_state.md#sharedmutable) to enable rotating these keys. NOTE: While we entertained the idea of abstracting note encryption, where account contracts would define an `encrypt` method that would use a user-defined scheme, there are two main reasons we decided against this. First is that this entailed that, in order to receive funds, a user had to first deploy their account contract, which is a major UX issue. Second, users could define malicious `encrypt` methods that failed in certain circumstances, breaking application flows that required them to receive a private note. While this issue already exists in Ethereum when transferring ETH (see the [king of the hill](https://coinsbench.com/27-king-ethernaut-da5021cd4aa6)), its impact is made worse in Aztec since any execution failure in a private function makes the entire transaction unprovable (ie it is not possible to catch errors in calls to other private functions), and furthermore because encryption is required for any private state (not just for transferring ETH). Nevertheless, both of these problems are solvable. Initialization can be worked around by embedding a commitment to the bytecode in the address and removing the need for actually deploying contracts before interacting with them, and the king of the hill issue can be mitigated by introducing a full private VM that allows catching reverts. As such, we may be able to abstract encryption in the future as well. diff --git a/docs/docs/aztec/concepts/accounts/keys.md b/docs/docs/aztec/concepts/accounts/keys.md index 5d6a6135267..bb2c7340225 100644 --- a/docs/docs/aztec/concepts/accounts/keys.md +++ b/docs/docs/aztec/concepts/accounts/keys.md @@ -1,16 +1,20 @@ -# Keys +--- +title: Keys +tags: [accounts, keys] +--- + The goal of this section is to give app developer a good idea what keys there are used in the system. -For a detailed description head over to the [protocol specification](../../../protocol-specs/addresses-and-keys/keys#cheat-sheet). +For a detailed description head over to the [protocol specification](../../../protocol-specs/addresses-and-keys/index.md). Each account in Aztec is backed by 4 key pairs: - A **nullifier key pair** used for note nullifier computation, comprising the master nullifier secret key (`nsk_m`) and master nullifier public key (`Npk_m`). - A **incoming viewing key pair** used to encrypt a note for the recipient, consisting of the master incoming viewing secret key (`ivsk_m`) and master incoming viewing public key (`Ivpk_m`). - A **outgoing viewing key pair** used to encrypt a note for the sender, includes the master outgoing viewing secret key (`ovsk_m`) and master outgoing viewing public key (`Ovpk_m`). -- A **tagging key pair** used to compute tags in a [tagging note discovery scheme](../../../protocol-specs/private-message-delivery/private-msg-delivery#note-tagging), comprising the master tagging secret key (`tsk_m`) and master tagging public key (`Tpk_m`). +- A **tagging key pair** used to compute tags in a [tagging note discovery scheme](../../../protocol-specs/private-message-delivery/private-msg-delivery.md#note-tagging), comprising the master tagging secret key (`tsk_m`) and master tagging public key (`Tpk_m`). :::info -All key pairs above are derived from a secret using a ZCash inspired scheme defined in [protocol specification](../../../protocol-specs/addresses-and-keys/keys#cheat-sheet). +All key pairs above are derived from a secret using a ZCash inspired scheme defined in [protocol specification](../../../protocol-specs/addresses-and-keys/keys.md#cheat-sheet). ::: :::note @@ -40,7 +44,7 @@ Below are some ways how we could instantiate it after getting the information in #include_code instantiate-complete-address /yarn-project/circuits.js/src/structs/complete_address.test.ts rust -Then to register the recipient's [complete address](#complete-address) in PXE we would call `registerRecipient` PXE endpoint using [Aztec.js](../../core_components.md#aztecjs): +Then to register the recipient's [complete address](#complete-address) in PXE we would call `registerRecipient` PXE endpoint using Aztec.js. #include_code register-recipient /yarn-project/aztec.js/src/wallet/create_recipient.ts rust @@ -116,7 +120,7 @@ This is a snippet of our Schnorr Account contract implementation, which uses Sch #include_code entrypoint /noir-projects/noir-contracts/contracts/schnorr_account_contract/src/main.nr rust -Still, different accounts may use different signing schemes, may require multi-factor authentication, or _may not even use signing keys_ and instead rely on other authentication mechanisms. Read [how to write an account contract](../../../tutorials/contract_tutorials/write_accounts_contract.md) for a full example of how to manage authentication. +Still, different accounts may use different signing schemes, may require multi-factor authentication, or _may not even use signing keys_ and instead rely on other authentication mechanisms. Read [how to write an account contract](../../../tutorials/codealong/contract_tutorials/write_accounts_contract.md) for a full example of how to manage authentication. Furthermore, and since signatures are fully abstracted, how the key is stored in the contract is abstracted as well and left to the developer of the account contract. In the following section we describe a few ways how an account contract could be architected to store signing keys. @@ -133,7 +137,7 @@ Similar to using a private note, but using an immutable private note removes the #### Using shared state -A compromise between the two solutions above is to use [shared state](../../../reference/smart_contract_reference/storage/shared_state.md). This would not generate additional nullifiers and commitments for each transaction while allowing the user to rotate their key. However, this causes every transaction to now have a time-to-live determined by the frequency of the mutable shared state, as well as imposing restrictions on how fast keys can be rotated due to minimum delays. +A compromise between the two solutions above is to use shared state. This would not generate additional nullifiers and commitments for each transaction while allowing the user to rotate their key. However, this causes every transaction to now have a time-to-live determined by the frequency of the mutable shared state, as well as imposing restrictions on how fast keys can be rotated due to minimum delays. #### Reusing some of the in-protocol keys diff --git a/docs/docs/aztec/concepts/circuits/index.md b/docs/docs/aztec/concepts/circuits/index.md index 34bd5d74f2b..aad4f994459 100644 --- a/docs/docs/aztec/concepts/circuits/index.md +++ b/docs/docs/aztec/concepts/circuits/index.md @@ -1,6 +1,7 @@ --- title: Circuits sidebar_position: 7 +tags: [protocol, circuits] --- Central to Aztec's operations are 'circuits' derived both from the core protocol and the developer-written Aztec.nr contracts. @@ -62,11 +63,11 @@ So what kinds of core protocol circuits does Aztec have? ### Kernel Circuits -Read more about the Kernel circuits in the protocol specs [here](../../../protocol-specs/circuits/high-level-topology). +Read more about the Kernel circuits in the protocol specs [here](../../../protocol-specs/circuits/high-level-topology.md). ### Rollup Circuits -- [Rollup Circuits](../../../protocol-specs/rollup-circuits) +- [Rollup Circuits](../../../protocol-specs/rollup-circuits/index.md) #### Squisher Circuits diff --git a/docs/docs/aztec/concepts/circuits/kernels/private_kernel.md b/docs/docs/aztec/concepts/circuits/kernels/private_kernel.md index 177c18c3351..9bdba98cb8a 100644 --- a/docs/docs/aztec/concepts/circuits/kernels/private_kernel.md +++ b/docs/docs/aztec/concepts/circuits/kernels/private_kernel.md @@ -1,10 +1,11 @@ --- title: Private Kernel Circuit +tags: [protocol, circuits] --- This circuit is executed by the user, on their own device. This is to ensure private inputs to the circuit remain private! -Read the latest information about the Aztec Private Kernel Circuit in the [protocol specs section](../../../../protocol-specs/circuits/private-kernel-initial). +Read the latest information about the Aztec Private Kernel Circuit in the [protocol specs section](../../../../protocol-specs/circuits/private-kernel-tail.md). :::note diff --git a/docs/docs/aztec/concepts/circuits/kernels/public_kernel.md b/docs/docs/aztec/concepts/circuits/kernels/public_kernel.md index 2cac4594568..e7f139f8662 100644 --- a/docs/docs/aztec/concepts/circuits/kernels/public_kernel.md +++ b/docs/docs/aztec/concepts/circuits/kernels/public_kernel.md @@ -1,7 +1,8 @@ --- title: Public Kernel Circuit +tags: [protocol, circuits] --- -This circuit is executed by a Sequencer, since only a Sequencer knows the current state of the [public data tree](../../storage/trees/index.md#public-state-tree) at any time. A Sequencer might choose to delegate proof generation to the Prover pool. +This circuit is executed by a Sequencer, since only a Sequencer knows the current state of the [public data tree](../../storage/trees/index.md) at any time. A Sequencer might choose to delegate proof generation to the Prover pool. -Read more about the public kernel circuits in the protocol specs [here](../../../../protocol-specs/circuits/private-kernel-tail). +Read more about the public kernel circuits in the protocol specs [here](../../../../protocol-specs/circuits/public-kernel-initial.md). diff --git a/docs/docs/aztec/concepts/circuits/rollup_circuits/index.md b/docs/docs/aztec/concepts/circuits/rollup_circuits/index.md index a0d3a606782..72f08e093d3 100644 --- a/docs/docs/aztec/concepts/circuits/rollup_circuits/index.md +++ b/docs/docs/aztec/concepts/circuits/rollup_circuits/index.md @@ -1,5 +1,6 @@ --- title: Rollup Circuits +tags: [protocol, circuits] --- The primary purpose of the Rollup Circuits is to 'squish' all of the many thousands of transactions in a rollup into a single SNARK, which can then be efficiently and verified on Ethereum. @@ -15,4 +16,4 @@ The way we 'squish' all this data is in a 'binary tree of proofs' topology. Some of the Rollup Circuits also do some protocol checks and computations, for efficiency reasons. We might rearrange which circuit does what computation, as we discover opportunities for efficiency. -Read more about the rollup circuits in the protocol spec [here](../../../../protocol-specs/rollup-circuits). +Read more about the rollup circuits in the protocol spec [here](../../../../protocol-specs/rollup-circuits/index.md). diff --git a/docs/docs/aztec/concepts/index.md b/docs/docs/aztec/concepts/index.md deleted file mode 100644 index f1920549acb..00000000000 --- a/docs/docs/aztec/concepts/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Concepts -sidebar_position: 2 ---- - -import Image from "@theme/IdealImage"; -import DocCardList from "@theme/DocCardList"; - -This page outlines Aztec's fundamental technical concepts. - -## Aztec Overview - - - -1. A user interacts with Aztec through Aztec.js (like web3js or ethersjs) -2. Private functions are executed in the PXE, which is client-side -3. They are rolled up and sent to the Public VM (running on an Aztec node) -4. Public functions are executed in the Public VM -5. The Public VM rolls up the private & public transaction rollups -6. These rollups are submitted to Ethereum - -The PXE is unaware of the Public VM. And the Public VM is unaware of the PXE. They are completely separate execution environments. This means: - -- The PXE and the Public VM cannot directly communicate with each other -- Private transactions in the PXE are executed first, followed by public transactions - -### Private and public state - -Private state works with UTXOs, or what we call notes. To keep things private, everything is stored in an [append-only UTXO tree](storage/trees/index.md#note-hash-tree), and a nullifier is created when notes are invalidated. Nullifiers are then stored in their own [nullifier tree](storage/trees/indexed_merkle_tree.mdx#primer-on-nullifier-trees). - -Public state works similarly to other chains like Ethereum, behaving like a public ledger. Public data is stored in a [public data tree](storage/trees/index.md#public-state-tree). - -Aztec [smart contract](smart_contracts/index.md) developers should keep in mind that different types are used when manipulating private or public state. Working with private state is creating commitments and nullifiers to state, whereas working with public state is directly updating state. - -## Accounts - -Every account in Aztec is a smart contract (account abstraction). This allows implementing different schemes for transaction signing, nonce management, and fee payments. - -Developers can write their own account contract to define the rules by which user transactions are authorized and paid for, as well as how user keys are managed. - -Learn more about account contracts [here](index.md). - -## Smart contracts - -Developers can write [smart contracts](smart_contracts/index.md) that manipulate both public and private state. They are written in a framework on top of Noir, the zero-knowledge domain-specific language developed specifically for Aztec. Outside of Aztec, Noir is used for writing circuits that can be verified on EVM chains. - -Noir has its own doc site that you can find [here](https://noir-lang.org). - -## Communication with Ethereum - -Aztec allows private communications with Ethereum - ie no-one knows where the transaction is coming from, just that it is coming from somewhere on Aztec. - -This is achieved through portals - these are smart contracts deployed on an EVM that are related to the Ethereum smart contract you want to interact with. - -Learn more about portals [here](../../protocol-specs/l1-smart-contracts/index.md). - -## Circuits - -Aztec operates on three types of circuits: - -- [Private kernel circuits](circuits/kernels/private_kernel.md), which are executed by the user on their own device and prove correct execution of a function -- [Public kernel circuits](./circuits/kernels/public_kernel.md), which are executed by the [sequencer](nodes_clients/sequencer/index.md) and ensure the stack trace of transactions adheres to function execution rules -- [Rollup circuits](circuits/index.md), which bundle all of the Aztec transactions into a proof that can be efficiently verified on Ethereum - -## What's next? - -### Dive deeper into how Aztec works - -Explore the Concepts for a deeper understanding into the components that make up Aztec: - - - -### Start coding - -Follow the [developer getting started guide](../../getting_started.md). diff --git a/docs/docs/aztec/concepts/pxe/acir_simulator.md b/docs/docs/aztec/concepts/pxe/acir_simulator.md index 5413fba5d81..020dbdb812a 100644 --- a/docs/docs/aztec/concepts/pxe/acir_simulator.md +++ b/docs/docs/aztec/concepts/pxe/acir_simulator.md @@ -14,13 +14,13 @@ It simulates three types of functions: Private functions are simulated and proved client-side, and verified client-side in the private kernel circuit. -They are run with the assistance of a DB oracle that provides any private data requested by the function. You can read more about oracle functions in the smart contract section [here](../smart_contracts/oracles/index.md). +They are run with the assistance of a DB oracle that provides any private data requested by the function. You can read more about oracle functions in the smart contract section [here](../../smart_contracts/oracles/index.md). Private functions can call other private functions and can request to call a public function. The public function execution will be performed by the sequencer asynchronously, so private functions don't have direct access to the return values of public functions. ### Public Functions -Public functions are simulated and proved on the [sequencer](../nodes_clients/sequencer) side, and verified by the [public kernel circuit](../circuits/kernels/public_kernel.md). +Public functions are simulated and proved on the [sequencer](../../network/sequencer/index.md) side, and verified by the [public kernel circuit](../../concepts/circuits/kernels/public_kernel.md). They are run with the assistance of an oracle that provides any value read from the public state tree. diff --git a/docs/docs/aztec/concepts/pxe/index.md b/docs/docs/aztec/concepts/pxe/index.md index 151ceb89787..0018caecd50 100644 --- a/docs/docs/aztec/concepts/pxe/index.md +++ b/docs/docs/aztec/concepts/pxe/index.md @@ -1,6 +1,7 @@ --- title: Private Execution Environment (PXE) sidebar_position: 6 +tags: [PXE] --- The Private Execution Environment (or PXE, pronounced 'pixie') is a client-side library for the execution of private operations. It is a TypeScript library and can be run within Node, such as when you run the sandbox. In the future it could be run inside wallet software or a browser. @@ -63,11 +64,11 @@ The keystore is a secure storage for private and public keys. ## Oracles -Oracles are pieces of data that are injected into a smart contract function from the client side. You can read more about why and how they work in the [functions section](../smart_contracts/oracles/index.md). +Oracles are pieces of data that are injected into a smart contract function from the client side. You can read more about why and how they work in the [smart contracts section](../../smart_contracts/oracles/index.md). ## For developers To learn how to develop on top of the PXE, refer to these guides: -- [Run more than one PXE on your local machine](../../../guides/local_env/run_more_than_one_pxe_sandbox.md) -- [Use in-built oracles including oracles for arbitrary data](guides/smart_contracts/writing_contracts/how_to_pop_capsules.md) +- [Run more than one PXE on your local machine](../../../guides/developer_guides/local_env/run_more_than_one_pxe_sandbox.md) +- [Use in-built oracles including oracles for arbitrary data](../../../guides/developer_guides/smart_contracts/writing_contracts/how_to_pop_capsules.md) diff --git a/docs/docs/aztec/concepts/smart_contracts/contract_creation.md b/docs/docs/aztec/concepts/smart_contracts/contract_creation.md deleted file mode 100644 index f77aa94d58d..00000000000 --- a/docs/docs/aztec/concepts/smart_contracts/contract_creation.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Contract Deployment ---- - -The latest information about contract deployment has moved to the protocol specification. You can find it [here](../../../protocol-specs/contract-deployment/index.md). - -## Further reading - -To see how to deploy a contract in practice, check out the [dapp development tutorial](../../../tutorials/simple_dapp). diff --git a/docs/docs/aztec/concepts/state_model/index.md b/docs/docs/aztec/concepts/state_model/index.md index 406d1adf41f..914ccf51ae5 100644 --- a/docs/docs/aztec/concepts/state_model/index.md +++ b/docs/docs/aztec/concepts/state_model/index.md @@ -1,6 +1,7 @@ --- title: State Model sidebar_position: 4 +tags: [state] --- Aztec has a hybrid public/private state model. Aztec contract developers can specify which data is public and which data is private, as well as the functions that can operate on that data. diff --git a/docs/docs/aztec/concepts/state_model/public_vm.md b/docs/docs/aztec/concepts/state_model/public_vm.md index dc02f375932..d5c26f1d33d 100644 --- a/docs/docs/aztec/concepts/state_model/public_vm.md +++ b/docs/docs/aztec/concepts/state_model/public_vm.md @@ -2,4 +2,4 @@ title: Public VM --- -Refer to the [protocol specs section](../../../protocol-specs/public-vm/intro.md) for the latest information about the Aztec Public VM. +Refer to the [protocol specs section](../../../protocol-specs/public-vm/index.md) for the latest information about the Aztec Public VM. diff --git a/docs/docs/aztec/concepts/storage/index.md b/docs/docs/aztec/concepts/storage/index.md index de69d7fdf3e..9b3987f901f 100644 --- a/docs/docs/aztec/concepts/storage/index.md +++ b/docs/docs/aztec/concepts/storage/index.md @@ -2,6 +2,7 @@ title: Storage description: How are storage slots derived for public and private state sidebar_position: 2 +tags: [protocol, storage] --- In Aztec, private data and public data are stored in two trees; a public data tree and a note hashes tree. @@ -61,4 +62,4 @@ By doing this address-siloing at the kernel circuit we _force_ the inserted comm To ensure that nullifiers don't collide across contracts we also force this contract siloing at the kernel level. ::: -For an example of this see [developer documentation storage slots](../../../guides/smart_contracts/writing_contracts/storage/storage_slots). +For an example of this see [developer documentation on storage](../../../reference/developer_references/smart_contract_reference/storage/index.md). diff --git a/docs/docs/aztec/concepts/transactions.md b/docs/docs/aztec/concepts/transactions.md index dc7980c9c4e..fee7a8a0cd5 100644 --- a/docs/docs/aztec/concepts/transactions.md +++ b/docs/docs/aztec/concepts/transactions.md @@ -1,6 +1,7 @@ --- title: Transactions sidebar_position: 3 +tags: [protocol] --- import Image from '@theme/IdealImage'; @@ -48,7 +49,7 @@ Transactions on Aztec start with a call from Aztec.js, which creates a request c See [this diagram](https://raw.githubusercontent.com/AztecProtocol/aztec-packages/2fa143e4d88b3089ebbe2a9e53645edf66157dc8/docs/static/img/sandbox_sending_a_tx.svg) for a more detailed overview of the transaction execution process. It highlights 3 different types of transaction execution: contract deployments, private transactions and public transactions. -See the page on [contract communication](smart_contracts/communication/index.md) for more context on transaction execution. +See the page on [contract communication](../smart_contracts/communication/index.md) for more context on transaction execution. ### Enabling Transaction Semantics: The Aztec Kernel diff --git a/docs/docs/aztec/concepts/wallets/architecture.md b/docs/docs/aztec/concepts/wallets/architecture.md index 4d0c60229cf..fcab210d5ab 100644 --- a/docs/docs/aztec/concepts/wallets/architecture.md +++ b/docs/docs/aztec/concepts/wallets/architecture.md @@ -1,5 +1,6 @@ --- title: Wallet Architecture +tags: [protocol, accounts] --- This page talks about the architecture of a wallet in Aztec. Wallets expose to dapps an interface that allows them to act on behalf of the user, such as querying private state or sending transactions. Bear mind that, as in Ethereum, wallets should require user confirmation whenever carrying out a potentially sensitive action requested by a dapp. @@ -10,7 +11,7 @@ Architecture-wise, a wallet is an instance of an **Private Execution Environment The PXE also communicates with an **Aztec Node** for retrieving public information or broadcasting transactions. Note that the PXE requires a local database for keeping private state, and is also expected to be continuously syncing new blocks for trial-decryption of user notes. -Additionally, a wallet must be able to handle one or more [account contract implementations](../accounts/index.md#account-contracts-and-wallets). When a user creates a new account, the account is represented on-chain by an account contract. The wallet is responsible for deploying and interacting with this contract. A wallet may support multiple flavours of accounts, such as an account that uses ECDSA signatures, or one that relies on WebAuthn, or one that requires multi-factor authentication. For a user, the choice of what account implementation to use is then determined by the wallet they interact with. +Additionally, a wallet must be able to handle one or more account contract implementation. When a user creates a new account, the account is represented on-chain by an account contract. The wallet is responsible for deploying and interacting with this contract. A wallet may support multiple flavours of accounts, such as an account that uses ECDSA signatures, or one that relies on WebAuthn, or one that requires multi-factor authentication. For a user, the choice of what account implementation to use is then determined by the wallet they interact with. In code, this translates to a wallet implementing an **AccountInterface** interface that defines [how to create an _execution request_ out of an array of _function calls_](./index.md#transaction-lifecycle) for the specific implementation of an account contract and [how to generate an _auth witness_](./index.md#authorizing-actions) for authorizing actions on behalf of the user. Think of this interface as the Javascript counterpart of an account contract, or the piece of code that knows how to format a transaction and authenticate an action based on the rules defined by the user's account contract implementation. diff --git a/docs/docs/aztec/concepts/wallets/index.md b/docs/docs/aztec/concepts/wallets/index.md index 7c47de34b7e..c8550e418c0 100644 --- a/docs/docs/aztec/concepts/wallets/index.md +++ b/docs/docs/aztec/concepts/wallets/index.md @@ -6,7 +6,7 @@ tags: [accounts] In this page we will cover the main responsibilities of a wallet in the Aztec network. -Refer to [writing an account contract](../../../tutorials/contract_tutorials/write_accounts_contract.md) for a tutorial on how to write a contract to back a user's account. +Refer to [writing an account contract](../../../tutorials/codealong/contract_tutorials/write_accounts_contract.md) for a tutorial on how to write a contract to back a user's account. Go to [wallet architecture](./architecture.md) for an overview of its architecture and a reference on the interface a wallet must implement. @@ -20,7 +20,7 @@ In addition to these usual responsibilities, wallets in Aztec also need to track The first step for any wallet is to let the user set up their [accounts](../accounts/index.md). An account in Aztec is represented on-chain by its corresponding account contract that the user must deploy to begin interacting with the network. This account contract dictates how transactions are authenticated and executed. -A wallet must support at least one specific [account contract implementation](../../../tutorials/contract_tutorials/write_accounts_contract.md), which means being able to deploy such a contract, as well as interacting with it when sending transactions. Code-wise, this requires [implementing the `AccountContract` interface](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec.js/src/account_contract/index.ts). +A wallet must support at least one specific account contract implementation, which means being able to deploy such a contract, as well as interacting with it when sending transactions. Code-wise, this requires [implementing the `AccountContract` interface](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec.js/src/account_contract/index.ts). Note that users must be able to receive funds in Aztec before deploying their account. A wallet should let a user generate a [deterministic complete address](../accounts/keys.md#complete-address) without having to interact with the network, so they can share it with others to receive funds. This requires that the wallet pins a specific contract implementation, its initialization arguments, a deployment salt, and a privacy key. These values yield a deterministic address, so when the account contract is actually deployed, it is available at the precalculated address. Once the account contract is deployed, the user can start sending transactions using it as the transaction origin. @@ -28,7 +28,7 @@ Note that users must be able to receive funds in Aztec before deploying their ac Every transaction in Aztec is broadcast to the network as a zero-knowledge proof of correct execution, in order to preserve privacy. This means that transaction proofs are generated on the wallet and not on a remote node. This is one of the biggest differences with regard to EVM chain wallets. -A wallet is responsible for **creating** an _execution request_ out of one or more _function calls_ requested by a dapp. For example, a dapp may request a wallet to "invoke the `transfer` function on the contract at `0x1234` with the following arguments", in response to a user action. The wallet [turns that into an execution request](../../../protocol-specs/transactions/local-execution#execution-request) with the signed instructions to execute that function call from the user's account contract. In an [ECDSA-based account](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/ecdsa_account_contract/src/main.nr), for instance, this is an execution request that encodes the function call in the _entrypoint payload_, and includes its ECDSA signature with the account's signing private key. +A wallet is responsible for **creating** an _execution request_ out of one or more _function calls_ requested by a dapp. For example, a dapp may request a wallet to "invoke the `transfer` function on the contract at `0x1234` with the following arguments", in response to a user action. The wallet [turns that into an execution request](../../../protocol-specs/transactions/local-execution.md#execution-request) with the signed instructions to execute that function call from the user's account contract. In an [ECDSA-based account](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/ecdsa_account_contract/src/main.nr), for instance, this is an execution request that encodes the function call in the _entrypoint payload_, and includes its ECDSA signature with the account's signing private key. Once the _execution request_ is created, the wallet is responsible for **simulating** and **proving** the execution of its private functions. The simulation yields an execution trace, which can be used to provide the user with a list of side effects of the private execution of the transaction. During this simulation, the wallet is responsible of providing data to the virtual machine, such as private notes, encryption keys, or nullifier secrets. This execution trace is fed into the prover, which returns a zero-knowledge proof that guarantees correct execution and hides all private information. The output of this process is a [_transaction object_](../../../protocol-specs/transactions/tx-object.md). diff --git a/docs/docs/aztec/core_components.md b/docs/docs/aztec/core_components.md deleted file mode 100644 index 91c0da1f686..00000000000 --- a/docs/docs/aztec/core_components.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Core Components -sidebar_position: 1 ---- - -## Private Smart Contracts - -A smart contract on Aztec is a collection of functions, written as ZK-SNARK circuits. These circuits can have different modes of execution: - -1. Private Functions -- can read and write private state, read historical public state, consume or send messages to / from Ethereum, and read Ethereum state. They can call other private functions in the same contract, or other contracts, and can call public functions. -2. Public Functions -- can read and write public state, write private state, consume or send messages to / from Ethereum and read Ethereum state. They can call other public functions on the same or other contracts. -3. Portal Contracts -- these are contracts on Ethereum that can receive messages from Aztec or send messages to Aztec from Ethereum contracts. - -Using these different modes of execution, developers can build applications with user privacy, data privacy and code privacy. - -- User privacy - transactions may not reveal information about the sender or the recipient. -- Data privacy - transactions may not reveal information about the payload of the transaction, e.g., the asset or value being transacted. -- Code privacy - transactions may not reveal the program logic. - -## High level network architecture - -An overview of the Aztec network architecture will help contextualize the concepts introduced in this section. - -network architecture - -### Aztec.js - -A user of the Aztec network will interact with the network through Aztec.js. Aztec.js is a library that provides APIs for managing accounts and interacting with smart contracts (including account contracts) on the Aztec network. It communicates with the [Private eXecution Environment (PXE)](concepts/pxe/index.md) through a `PXE` implementation, allowing developers to easily register new accounts, deploy contracts, view functions, and send transactions. - -### Private Execution Environment - -The PXE provides a secure environment for the execution of sensitive operations, ensuring private information and decrypted data are not accessible to unauthorized applications. It hides the details of the [state model](concepts/state_model/index.md) from end users, but the state model is important for Aztec developers to understand as it has implications for [private/public execution](concepts/smart_contracts/communication/public_private_calls.md) and [L1/L2 communication](../protocol-specs/l1-smart-contracts/index.md). The PXE also includes the [ACIR Simulator](concepts/pxe/acir_simulator.md) for private executions and the KeyStore for secure key management. - -Procedurally, the PXE sends results of private function execution and requests for public function executions to the [sequencer](concepts/nodes_clients/sequencer/index.md), which will update the state of the rollup. - -### Sequencer - -The sequencer aggregates transactions into a block, generates proofs of the state updates (or delegates proof generate to the prover network) and posts it to the rollup contract on Ethereum, along with any required public data for data availability. - -## Further Reading - -- [The state model](concepts/state_model/index.md) -- [Accounts](concepts/accounts/index.md) -- [Aztec Smart Contracts](concepts/smart_contracts/index.md) -- [Transactions](concepts/transactions.md) -- [Communication between network components](concepts/smart_contracts/communication/index.md) diff --git a/docs/docs/aztec/glossary/call_types.md b/docs/docs/aztec/glossary/call_types.md index d121c607f12..1f1b3cd8008 100644 --- a/docs/docs/aztec/glossary/call_types.md +++ b/docs/docs/aztec/glossary/call_types.md @@ -121,7 +121,7 @@ A common pattern is to enqueue public calls to check some validity condition on #include_code deadline /noir-projects/noir-contracts/contracts/crowdfunding_contract/src/main.nr rust :::warning -Calling public functions privately leaks some privacy! The caller of the function and all arguments will be revelead, so exercise care when mixing the private and public domains. To learn about alternative ways to access public state privately, look into [Shared State](../../reference/smart_contract_reference/storage/shared_state.md). +Calling public functions privately leaks some privacy! The caller of the function and all arguments will be revelead, so exercise care when mixing the private and public domains. To learn about alternative ways to access public state privately, look into [Shared State](../../reference/developer_references/smart_contract_reference/storage/shared_state.md). ::: ### Public Execution diff --git a/docs/docs/aztec/glossary/index.md b/docs/docs/aztec/glossary/index.md index 8a4d155744a..efe652c62af 100644 --- a/docs/docs/aztec/glossary/index.md +++ b/docs/docs/aztec/glossary/index.md @@ -64,7 +64,7 @@ Previously in [Aztec Connect](https://medium.com/aztec-protocol/sunsetting-aztec Programs that run on the Aztec network are called smart contracts, similar to [programs](https://ethereum.org/en/developers/docs/smart-contracts/) that run on Ethereum. -However, these will be written in the [Noir](https://noir-lang.org/index.html) programming language, and may optionally include [private state and private functions](../../aztec/core_components.md). +However, these will be written in the [Noir](https://noir-lang.org/index.html) programming language, and may optionally include private state and private functions. ### Proving Key diff --git a/docs/docs/aztec/concepts/nodes_clients/_category_.json b/docs/docs/aztec/network/_category_.json similarity index 100% rename from docs/docs/aztec/concepts/nodes_clients/_category_.json rename to docs/docs/aztec/network/_category_.json diff --git a/docs/docs/aztec/concepts/nodes_clients/sequencer/index.md b/docs/docs/aztec/network/sequencer/index.md similarity index 99% rename from docs/docs/aztec/concepts/nodes_clients/sequencer/index.md rename to docs/docs/aztec/network/sequencer/index.md index 36f49a24a95..614f405daad 100644 --- a/docs/docs/aztec/concepts/nodes_clients/sequencer/index.md +++ b/docs/docs/aztec/network/sequencer/index.md @@ -1,5 +1,6 @@ --- title: Sequencer +tags: [protocol] --- The sequencer is a module responsible for creating and publishing new rollup blocks. This involves fetching txs from the P2P pool, ordering them, executing any public functions, running them through the rollup circuits, assembling the L2 block, and posting it to the L1 rollup contract along with any contract deployment public data. diff --git a/docs/docs/aztec/concepts/nodes_clients/sequencer/sequencer_selection.md b/docs/docs/aztec/network/sequencer/sequencer_selection.md similarity index 99% rename from docs/docs/aztec/concepts/nodes_clients/sequencer/sequencer_selection.md rename to docs/docs/aztec/network/sequencer/sequencer_selection.md index 72937391468..9feb7710294 100644 --- a/docs/docs/aztec/concepts/nodes_clients/sequencer/sequencer_selection.md +++ b/docs/docs/aztec/network/sequencer/sequencer_selection.md @@ -1,5 +1,6 @@ --- title: Sequencer Selection +tags: [protocol] --- ## Fernet diff --git a/docs/docs/aztec/network_overview.md b/docs/docs/aztec/network_overview.md new file mode 100644 index 00000000000..787a59d2a96 --- /dev/null +++ b/docs/docs/aztec/network_overview.md @@ -0,0 +1,12 @@ +--- +title: Overview +sidebar_position: 0 +tags: [protocol] +draft: true +--- + +# Aztec Network Infrastructure + +Explore this section to learn about [sequencers](../aztec/network/sequencer/index.md) and the [sequencer selection process](../aztec/network/sequencer/sequencer_selection.md). + +More information will be added here as we develop the protocol. \ No newline at end of file diff --git a/docs/docs/aztec/overview.md b/docs/docs/aztec/overview.md new file mode 100644 index 00000000000..06150ec4ded --- /dev/null +++ b/docs/docs/aztec/overview.md @@ -0,0 +1,141 @@ +--- +title: What is Aztec? +sidebar_position: 0 +id: overview +tags: [protocol] +--- + +import Image from "@theme/IdealImage"; + +This page outlines Aztec's fundamental technical concepts. + +## Aztec Overview + + + +1. A user interacts with Aztec through Aztec.js (like web3js or ethersjs) +2. Private functions are executed in the PXE, which is client-side +3. They are rolled up and sent to the Public VM (running on an Aztec node) +4. Public functions are executed in the Public VM +5. The Public VM rolls up the private & public transaction rollups +6. These rollups are submitted to Ethereum + +The PXE is unaware of the Public VM. And the Public VM is unaware of the PXE. They are completely separate execution environments. This means: + +- The PXE and the Public VM cannot directly communicate with each other +- Private transactions in the PXE are executed first, followed by public transactions + +### Private and public state + +Private state works with UTXOs, or what we call notes. To keep things private, everything is stored in an [append-only UTXO tree](./concepts/storage/trees/index.md), and a nullifier is created when notes are invalidated. Nullifiers are then stored in their own [nullifier tree](./concepts/storage/trees/index.md). + +Public state works similarly to other chains like Ethereum, behaving like a public ledger. Public data is stored in a [public data tree](./concepts/storage/trees/index.md#public-state-tree). + +Aztec [smart contract](./smart_contracts_overview.md) developers should keep in mind that different types are used when manipulating private or public state. Working with private state is creating commitments and nullifiers to state, whereas working with public state is directly updating state. + +## Accounts + +Every account in Aztec is a smart contract (account abstraction). This allows implementing different schemes for transaction signing, nonce management, and fee payments. + +Developers can write their own account contract to define the rules by which user transactions are authorized and paid for, as well as how user keys are managed. + +Learn more about account contracts [here](./concepts/accounts/index.md). + +## Smart contracts + +Developers can write [smart contracts](./smart_contracts_overview.md) that manipulate both public and private state. They are written in a framework on top of Noir, the zero-knowledge domain-specific language developed specifically for Aztec. Outside of Aztec, Noir is used for writing circuits that can be verified on EVM chains. + +Noir has its own doc site that you can find [here](https://noir-lang.org). + +## Communication with Ethereum + +Aztec allows private communications with Ethereum - ie no-one knows where the transaction is coming from, just that it is coming from somewhere on Aztec. + +This is achieved through portals - these are smart contracts deployed on an EVM that are related to the Ethereum smart contract you want to interact with. + +Learn more about portals [here](../protocol-specs/l1-smart-contracts/index.md). + +## Circuits + +Aztec operates on three types of circuits: + +- [Private kernel circuits](../aztec/concepts/circuits/kernels/private_kernel.md), which are executed by the user on their own device and prove correct execution of a function +- [Public kernel circuits](../aztec/concepts/circuits/kernels/public_kernel.md), which are executed by the [sequencer](./network/sequencer/index.md) and ensure the stack trace of transactions adheres to function execution rules +- [Rollup circuits](../aztec/concepts/circuits/index.md), which bundle all of the Aztec transactions into a proof that can be efficiently verified on Ethereum + +## What's next? + +### Dive deeper into how Aztec works + +Explore the Concepts for a deeper understanding into the components that make up Aztec: + +
+ + + +

Accounts

+ + + Learn about Aztec's native account abstraction - every account in Aztec is a smart contract which defines the rules for whether a transaction is or is not valid + + + + + +

Circuits

+ + + Central to Aztec's operations are circuits in the core protocol and the developer-written Aztec.nr contracts + + + + + +

PXE (pronounced 'pixie')

+ + + The Private Execution Environment (or PXE) is a client-side library for the execution of private operations + + + + + +

State model

+ + + Aztec has a hybrid public/private state model + + + + + +

Storage

+ + + In Aztec, private data and public data are stored in two trees: a public data tree and a note hashes tree + + + + + +

Wallets

+ + + Wallets expose to dapps an interface that allows them to act on behalf of the user, such as querying private state or sending transactions + + + +
+ +### Start coding + +
+ + +

Developer quickstart

+ + + Follow the getting started guide to start developing with the Aztec Sandbox + + +
\ No newline at end of file diff --git a/docs/docs/aztec/roadmap/_category_.json b/docs/docs/aztec/roadmap/_category_.json new file mode 100644 index 00000000000..231aa372f13 --- /dev/null +++ b/docs/docs/aztec/roadmap/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Roadmap", + "collapsible": true, + "collapsed": true, + "link": { "type": "doc", "id": "roadmap/index" } + +} diff --git a/docs/docs/aztec/roadmap/cryptography_roadmap.md b/docs/docs/aztec/roadmap/cryptography_roadmap.md index 9b455aa4bb1..4b732f0aa9a 100644 --- a/docs/docs/aztec/roadmap/cryptography_roadmap.md +++ b/docs/docs/aztec/roadmap/cryptography_roadmap.md @@ -2,7 +2,7 @@ title: Cryptography Roadmap sidebar_position: 2 --- ---- + The cryptography team is currently working on [Barretenberg here.](https://github.com/AztecProtocol/aztec-packages/tree/master/barretenberg) diff --git a/docs/docs/aztec/roadmap/engineering_roadmap.md b/docs/docs/aztec/roadmap/engineering_roadmap.md index 7f62da58857..14b1431f6b1 100644 --- a/docs/docs/aztec/roadmap/engineering_roadmap.md +++ b/docs/docs/aztec/roadmap/engineering_roadmap.md @@ -124,7 +124,7 @@ CI takes up a significant amount of time. It gets its own section here, so we re ## Shared Mutable State -We _need_ a way to read mutable public data from a private function. We are moving away from the old Slow Updates Tree in favor of [Shared Mutable](../../reference/smart_contract_reference/storage/shared_state.md). +We _need_ a way to read mutable public data from a private function. We are moving away from the old Slow Updates Tree in favor of [Shared Mutable](../../reference/developer_references/smart_contract_reference/storage/shared_state.md#sharedmutable). ## Contract classes and instances? diff --git a/docs/docs/aztec/roadmap/features_initial_ldt.md b/docs/docs/aztec/roadmap/features_initial_ldt.md index 3dcacfb76f8..9a43cb3dbd1 100644 --- a/docs/docs/aztec/roadmap/features_initial_ldt.md +++ b/docs/docs/aztec/roadmap/features_initial_ldt.md @@ -1,11 +1,12 @@ --- -title: Sandbox +title: Sandbox Features Roadmap sidebar_position: 0 +tags: [sandbox] --- The Aztec Sandbox is intended to provide developers with a lightweight and fast local node, running alongside a PXE. -You can learn more about running the Sandbox [here](../../reference/sandbox_reference/sandbox-reference.md). +You can learn more about running the Sandbox [here](../../reference/developer_references/sandbox_reference/index.md). Developers 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. diff --git a/docs/docs/aztec/roadmap/index.md b/docs/docs/aztec/roadmap/index.md deleted file mode 100644 index 1bc67b5ad4b..00000000000 --- a/docs/docs/aztec/roadmap/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Roadmap -sidebar_position: 3 ---- - -import DocCardList from '@theme/DocCardList'; -import Image from '@theme/IdealImage'; - -The next major milestone on the journey to mainnet is launching our testnet. - - - -## Read more - - diff --git a/docs/docs/aztec/concepts/smart_contracts/communication/index.md b/docs/docs/aztec/smart_contracts/communication/index.md similarity index 79% rename from docs/docs/aztec/concepts/smart_contracts/communication/index.md rename to docs/docs/aztec/smart_contracts/communication/index.md index d2815095610..1b1aa003d7f 100644 --- a/docs/docs/aztec/concepts/smart_contracts/communication/index.md +++ b/docs/docs/aztec/smart_contracts/communication/index.md @@ -9,4 +9,4 @@ See [Private \<--\> Public execution](./public_private_calls.md) for information ## Cross-chain communication -Read the protocol specification about Cross-chain communication between Aztec and Ethereum [here](../../../../protocol-specs/l1-smart-contracts/index.md). +Read the protocol specification about Cross-chain communication between Aztec and Ethereum [here](../communication/index.md). diff --git a/docs/docs/aztec/concepts/smart_contracts/communication/public_private_calls.md b/docs/docs/aztec/smart_contracts/communication/public_private_calls.md similarity index 94% rename from docs/docs/aztec/concepts/smart_contracts/communication/public_private_calls.md rename to docs/docs/aztec/smart_contracts/communication/public_private_calls.md index 6841f7ec071..027c5d17b01 100644 --- a/docs/docs/aztec/concepts/smart_contracts/communication/public_private_calls.md +++ b/docs/docs/aztec/smart_contracts/communication/public_private_calls.md @@ -84,6 +84,6 @@ Many applications rely on some form of access control to function well. USDC hav Access control like this cannot easily be enforced in the private domain, as reading is also nullifying (to ensure data is up to date). However, as it is possible to read historical public state, one can combine private and public functions to get the desired effect. -This concept is known as [shared state](../../../../reference/smart_contract_reference/storage/shared_state.md), and relies on using delays when changing public data so that it can also be read in private with currentness guarantees. Since values cannot be immediately modified but instead require delays to elapse, it is possible to privately prove that an application is using the current value _as long as the transaction gets included before some time in the future_, which would be the earliest the value could possibly change. +This concept is known as shared state, and relies on using delays when changing public data so that it can also be read in private with currentness guarantees. Since values cannot be immediately modified but instead require delays to elapse, it is possible to privately prove that an application is using the current value _as long as the transaction gets included before some time in the future_, which would be the earliest the value could possibly change. If the public state is only changed infrequently, and it is acceptable to have delays when doing so, then shared state is a good solution to this problem. diff --git a/docs/docs/aztec/smart_contracts/contract_creation.md b/docs/docs/aztec/smart_contracts/contract_creation.md new file mode 100644 index 00000000000..b648178e14e --- /dev/null +++ b/docs/docs/aztec/smart_contracts/contract_creation.md @@ -0,0 +1,10 @@ +--- +title: Contract Deployment +tags: [contracts, protocol] +--- + +The latest information about contract deployment has moved to the protocol specification. You can find it [here](../../protocol-specs/contract-deployment/index.md). + +## Further reading + +To see how to deploy a contract in practice, check out the [dapp development tutorial](../../tutorials/codealong/simple_dapp/index.md). diff --git a/docs/docs/aztec/concepts/smart_contracts/contract_structure.md b/docs/docs/aztec/smart_contracts/contract_structure.md similarity index 63% rename from docs/docs/aztec/concepts/smart_contracts/contract_structure.md rename to docs/docs/aztec/smart_contracts/contract_structure.md index d62ca2acfeb..b625256ee56 100644 --- a/docs/docs/aztec/concepts/smart_contracts/contract_structure.md +++ b/docs/docs/aztec/smart_contracts/contract_structure.md @@ -1,8 +1,9 @@ --- title: Contract Structure +tags: [contracts] --- -A contract is a collection of persistent [state variables](../storage/index.md), and [functions](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. +A contract is a collection of persistent state varibles and [functions](./functions/index.md) 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 @@ -36,4 +37,4 @@ Here's a common layout for a basic Aztec.nr Contract project: ``` - See the vanilla Noir docs for [more info on packages](https://noir-lang.org/docs/noir/modules_packages_crates/crates_and_packages). -- You can review the structure of a complete contract in the token contract tutorial [here](../../../tutorials/contract_tutorials/token_contract.md). +- You can review the structure of a complete contract in the token contract tutorial [here](../../tutorials/codealong/contract_tutorials/token_contract.md). diff --git a/docs/docs/aztec/concepts/smart_contracts/functions/context.md b/docs/docs/aztec/smart_contracts/functions/context.md similarity index 91% rename from docs/docs/aztec/concepts/smart_contracts/functions/context.md rename to docs/docs/aztec/smart_contracts/functions/context.md index a105d246acc..d7383a7924e 100644 --- a/docs/docs/aztec/concepts/smart_contracts/functions/context.md +++ b/docs/docs/aztec/smart_contracts/functions/context.md @@ -6,7 +6,7 @@ tags: [functions, context] ## What is the context -The context is an object that is made available within every function in `Aztec.nr`. As mentioned in the [kernel circuit documentation](../../circuits/kernels/private_kernel.md). At the beginning of a function's execution, the context contains all of the kernel information that application needs to execute. During the lifecycle of a transaction, the function will update the context with each of it's side effects (created notes, nullifiers etc.). At the end of a function's execution the mutated context is returned to the kernel to be checked for validity. +The context is an object that is made available within every function in `Aztec.nr`. As mentioned in the [kernel circuit documentation](../../concepts/circuits/kernels/private_kernel.md). At the beginning of a function's execution, the context contains all of the kernel information that application needs to execute. During the lifecycle of a transaction, the function will update the context with each of it's side effects (created notes, nullifiers etc.). At the end of a function's execution the mutated context is returned to the kernel to be checked for validity. Behind the scenes, Aztec.nr will pass data the kernel needs to and from a circuit, this is abstracted away from the developer. In an developer's eyes; the context is a useful structure that allows access and mutate the state of the `Aztec` blockchain. @@ -20,7 +20,7 @@ On this page, you'll learn ## Two contexts, one API -The `Aztec` blockchain contains two environments [public and private](../../state_model/index.md). +The `Aztec` blockchain contains two environments - public and private. - Private, for private transactions taking place on user's devices. - Public, for public transactions taking place on the network's sequencers. @@ -88,7 +88,7 @@ The `args_hash` is the result of pedersen hashing all of a function's inputs. ### Return Values -The return values are a set of values that are returned from an applications execution to be passed to other functions through the kernel. Developers do not need to worry about passing their function return values to the `context` directly as `Aztec.nr` takes care of it for you. See the documentation surrounding `Aztec.nr` [macro expansion](./inner_workings.md#after-expansion) for more details. +The return values are a set of values that are returned from an applications execution to be passed to other functions through the kernel. Developers do not need to worry about passing their function return values to the `context` directly as `Aztec.nr` takes care of it for you. See the documentation surrounding `Aztec.nr` [macro expansion](./inner_workings.md) for more details. return_values : BoundedVec\, @@ -128,7 +128,7 @@ The public call stack contains all of the external function calls that are creat ### New L2 to L1 msgs -New L2 to L1 messages contains messages that are delivered to the [l1 outbox](../../../../protocol-specs/l1-smart-contracts/index.md) on the execution of each rollup. +New L2 to L1 messages contains messages that are delivered to the [l1 outbox](../../../protocol-specs/l1-smart-contracts/index.md) on the execution of each rollup. ## Public Context diff --git a/docs/docs/aztec/concepts/smart_contracts/functions/index.md b/docs/docs/aztec/smart_contracts/functions/index.md similarity index 69% rename from docs/docs/aztec/concepts/smart_contracts/functions/index.md rename to docs/docs/aztec/smart_contracts/functions/index.md index edc475c13d0..e991e14ad5e 100644 --- a/docs/docs/aztec/concepts/smart_contracts/functions/index.md +++ b/docs/docs/aztec/smart_contracts/functions/index.md @@ -1,10 +1,11 @@ --- title: Defining Functions +tags: [functions] --- -Functions serve as the building blocks of smart contracts. Functions can be either **public**, ie they are publicly available for anyone to see and can directly interact with public state, or **private**, meaning they are executed completely client-side in the [PXE](../../pxe/index.md). Read more about how private functions work [here](./inner_workings.md#private-functions). +Functions serve as the building blocks of smart contracts. Functions can be either **public**, ie they are publicly available for anyone to see and can directly interact with public state, or **private**, meaning they are executed completely client-side in the [PXE](../../concepts/pxe/index.md). Read more about how private functions work [here](./inner_workings.md#private-functions). -For a more practical guide of using multiple types of functions, follow the [token tutorial](../../../../tutorials/contract_tutorials/token_contract.md). +For a more practical guide of using multiple types of functions, follow the [token tutorial](../../../tutorials/codealong/contract_tutorials/token_contract.md). Currently, any function is "mutable" in the sense that it might alter state. However, we also support support static calls, similarly to EVM. A static call is essentially a call that does not alter state (it keeps state static). @@ -21,9 +22,8 @@ There are also special oracle functions, which can get data from outside of the ## Learn more about functions - [How function visibility works in Aztec](./visibility.md) -- How to write an [initializer function](../../../../guides/smart_contracts/writing_contracts/initializers.md) -- [Calling functions from within the same smart contract and from different contracts](../../../../guides/smart_contracts/writing_contracts/call_functions.md), including calling private functions from private functions, public from public, and even private from public +- How to write an [initializer function](../../../guides/developer_guides/smart_contracts/writing_contracts/initializers.md) - [Oracles](../oracles/index.md) and how Aztec smart contracts might use them - [How functions work under the hood](./inner_workings.md) -Find a function macros reference [here](../../../../reference/smart_contract_reference/macros.md). \ No newline at end of file +Find a function macros reference [here](../../../reference/developer_references/smart_contract_reference/macros.md) diff --git a/docs/docs/aztec/concepts/smart_contracts/functions/inner_workings.md b/docs/docs/aztec/smart_contracts/functions/inner_workings.md similarity index 91% rename from docs/docs/aztec/concepts/smart_contracts/functions/inner_workings.md rename to docs/docs/aztec/smart_contracts/functions/inner_workings.md index 02e5b0a5984..d4e476085f2 100644 --- a/docs/docs/aztec/concepts/smart_contracts/functions/inner_workings.md +++ b/docs/docs/aztec/smart_contracts/functions/inner_workings.md @@ -6,13 +6,13 @@ tags: [functions] Below, we go more into depth of what is happening under the hood when you create a function in an Aztec contract and what the attributes are really doing. -If you are looking for a reference of function macros, go [here](../../../../reference/smart_contract_reference/macros.md). +If you are looking for a reference of function macros, go [here](../../../reference/developer_references/smart_contract_reference/macros.md). ## Private functions #[aztec(private)] A private function operates on private information, and is executed by the user on their device. Annotate the function with the `#[aztec(private)]` attribute to tell the compiler it's a private function. This will make the [private context](./context.md#the-private-context) available within the function's execution scope. The compiler will create a circuit to define this function. -`#aztec(private)` is just syntactic sugar. At compile time, the Aztec.nr framework inserts code that allows the function to interact with the [kernel](../../circuits/kernels/private_kernel.md). +`#aztec(private)` is just syntactic sugar. At compile time, the Aztec.nr framework inserts code that allows the function to interact with the [kernel](../../../aztec/concepts/circuits/kernels/private_kernel.md). To help illustrate how this interacts with the internals of Aztec and its kernel circuits, we can take an example private function, and explore what it looks like after Aztec.nr's macro expansion. @@ -26,12 +26,12 @@ To help illustrate how this interacts with the internals of Aztec and its kernel #### The expansion broken down -Viewing the expanded Aztec contract uncovers a lot about how Aztec contracts interact with the [kernel](../../circuits/kernels/private_kernel.md). To aid with developing intuition, we will break down each inserted line. +Viewing the expanded Aztec contract uncovers a lot about how Aztec contracts interact with the kernel. To aid with developing intuition, we will break down each inserted line. **Receiving context from the kernel.** #include_code context-example-inputs /noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr rust -Private function calls are able to interact with each other through orchestration from within the [kernel circuit](../../circuits/kernels/private_kernel.md). The kernel circuit forwards information to each contract function (recall each contract function is a circuit). This information then becomes part of the private context. +Private function calls are able to interact with each other through orchestration from within the kernel circuits. The kernel circuit forwards information to each contract function (recall each contract function is a circuit). This information then becomes part of the private context. For example, within each private function we can access some global variables. To access them we can call on the `context`, e.g. `context.chain_id()`. The value of the chain ID comes from the values passed into the circuit from the kernel. The kernel checks that all of the values passed to each circuit in a function call are the same. @@ -66,7 +66,7 @@ We achieve this by pushing return values to the execution context, which we then **Making the contract's storage available** #include_code storage-example-context /noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr rust -When a [`Storage` struct](../../../../guides/smart_contracts/writing_contracts/storage) is declared within a contract, the `storage` keyword is made available. As shown in the macro expansion above, this calls the init function on the storage struct with the current function's context. +When a `Storage` struct is declared within a contract, the `storage` keyword is made available. As shown in the macro expansion above, this calls the init function on the storage struct with the current function's context. Any state variables declared in the `Storage` struct can now be accessed as normal struct members. @@ -79,14 +79,14 @@ This function takes the application context, and converts it into the `PrivateCi Unconstrained functions are an underlying part of Noir. In short, they are functions which are not directly constrained and therefore should be seen as un-trusted. That they are un-trusted means that the developer must make sure to constrain their return values when used. Note: Calling an unconstrained function from a private function means that you are injecting unconstrained values. -Defining a function as `unconstrained` tells Aztec to simulate it completely client-side in the [ACIR simulator](../../pxe/acir_simulator.md) without generating proofs. They are useful for extracting information from a user through an [oracle](../oracles). +Defining a function as `unconstrained` tells Aztec to simulate it completely client-side in the [ACIR simulator](../../../aztec/concepts/pxe/index.md) without generating proofs. They are useful for extracting information from a user through an [oracle](../oracles/index.md). When an unconstrained function is called, it prompts the ACIR simulator to 1. generate the execution environment 2. execute the function within this environment -To generate the environment, the simulator gets the blockheader from the [PXE database](../../pxe/index.md#database) and passes it along with the contract address to `ViewDataOracle`. This creates a context that simulates the state of the blockchain at a specific block, allowing the unconstrained function to access and interact with blockchain data as it would appear in that block, but without affecting the actual blockchain state. +To generate the environment, the simulator gets the blockheader from the [PXE database](../../../aztec/concepts/pxe/index.md#database) and passes it along with the contract address to `ViewDataOracle`. This creates a context that simulates the state of the blockchain at a specific block, allowing the unconstrained function to access and interact with blockchain data as it would appear in that block, but without affecting the actual blockchain state. Once the execution environment is created, `execute_unconstrained_function` is invoked: @@ -97,7 +97,7 @@ This: 1. Prepares the ACIR for execution 2. Converts `args` into a format suitable for the ACVM (Abstract Circuit Virtual Machine), creating an initial witness (witness = set of inputs required to compute the function). `args` might be an oracle to request a user's balance 3. Executes the function in the ACVM, which involves running the ACIR with the initial witness and the context. If requesting a user's balance, this would query the balance from the PXE database -4. Extracts the return values from the `partialWitness` and decodes them based on the artifact to get the final function output. The [artifact](../../../../reference/smart_contract_reference/contract_artifact.md) is the compiled output of the contract, and has information like the function signature, parameter types, and return types +4. Extracts the return values from the `partialWitness` and decodes them based on the artifact to get the final function output. The artifact is the compiled output of the contract, and has information like the function signature, parameter types, and return types Beyond using them inside your other functions, they are convenient for providing an interface that reads storage, applies logic and returns values to a UI or test. Below is a snippet from exposing the `balance_of_private` function from a token implementation, which allows a user to easily read their balance, similar to the `balanceOf` function in the ERC20 standard. @@ -115,7 +115,7 @@ A public function is executed by the sequencer and has access to a state model t All data inserted into private storage from a public function will be publicly viewable (not private). ::: -To create a public function you can annotate it with the `#[aztec(public)]` attribute. This will make the [public context](./context.md) available within the function's execution scope. +To create a public function you can annotate it with the `#[aztec(public)]` attribute. This will make the public context available within the function's execution scope. #include_code set_minter /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust @@ -183,7 +183,7 @@ assert(context.msg_sender() == context.this_address(), "Function can only be cal ## Custom notes #[aztec(note)] -The `#[aztec(note)]` attribute is used to define custom note types in Aztec contracts. Learn more about notes [here](../../../concepts/storage/index.md). +The `#[aztec(note)]` attribute is used to define custom note types in Aztec contracts. Learn more about notes [here](../../concepts/storage/index.md). When a struct is annotated with `#[aztec(note)]`, the Aztec macro applies a series of transformations and generates implementations to turn it into a note that can be used in contracts to store private data. @@ -361,6 +361,6 @@ Key things to keep in mind: ## Further reading - [How do macros work](./inner_workings.md) -- [Macros reference](../../../../reference/smart_contract_reference/macros.md) +- [Macros reference](../../../reference/developer_references/smart_contract_reference/macros.md) diff --git a/docs/docs/aztec/concepts/smart_contracts/functions/visibility.md b/docs/docs/aztec/smart_contracts/functions/visibility.md similarity index 92% rename from docs/docs/aztec/concepts/smart_contracts/functions/visibility.md rename to docs/docs/aztec/smart_contracts/functions/visibility.md index d534953aa65..84bdcb04f52 100644 --- a/docs/docs/aztec/concepts/smart_contracts/functions/visibility.md +++ b/docs/docs/aztec/smart_contracts/functions/visibility.md @@ -6,7 +6,7 @@ tags: [functions] In Aztec there are multiple different types of visibility that can be applied to functions. Namely we have `data visibility` and `function visibility`. This page explains these types of visibility. -For a practical guide of using multiple types of data and function visibility,follow the [token tutorial](../../../../tutorials/contract_tutorials/token_contract.md). +For a practical guide of using multiple types of data and function visibility,follow the [token tutorial](../../../tutorials/codealong/contract_tutorials/token_contract.md). ### Data Visibility @@ -21,7 +21,7 @@ By default, all functions are callable from other contracts, similarly to the So A good place to use `internal` is when you want a private function to be able to alter public state. As mentioned above, private functions cannot do this directly. They are able to call public functions and by making these internal we can ensure that this state manipulating function is only callable from our private function. :::danger -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. You can learn more about this in the [Accounts concept page](../../index.md#entrypoint-restrictions). +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. You can learn more about this in the [Accounts concept page](../../concepts/accounts/keys.md). ::: To understand how visibility works under the hood, check out the [Inner Workings page](./inner_workings.md). diff --git a/docs/docs/aztec/concepts/smart_contracts/oracles/index.md b/docs/docs/aztec/smart_contracts/oracles/index.md similarity index 91% rename from docs/docs/aztec/concepts/smart_contracts/oracles/index.md rename to docs/docs/aztec/smart_contracts/oracles/index.md index fd36f37b706..bd2f2ddc0a5 100644 --- a/docs/docs/aztec/concepts/smart_contracts/oracles/index.md +++ b/docs/docs/aztec/smart_contracts/oracles/index.md @@ -1,10 +1,11 @@ --- title: Oracle Functions +tags: [functions, oracles] --- This page goes over what oracles are in Aztec and how they work. -Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](../../../../guides/smart_contracts/writing_contracts/how_to_pop_capsules.md). +Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](../../../guides/developer_guides/smart_contracts/writing_contracts/how_to_pop_capsules.md). An oracle is something that allows us to get data from the outside world into our contracts. The most widely-known types of oracles in blockchain systems are probably Chainlink price feeds, which allow us to get the price of an asset in USD taking non-blockchain data into account. @@ -13,7 +14,7 @@ While this is one type of oracle, the more general oracle, allows us to get any **Why is this useful? Why don't just pass them as input parameters?** In the world of EVM, you would just read the values directly from storage and call it a day. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you actually allowed to modify them. -If we fetch the notes using an oracle call, we can keep the function signature independent of the underlying data and make it easier to use. A similar idea, applied to the authentication mechanism is used for the Authentication Witnesses that allow us to have a single function signature for any wallet implementation, see [AuthWit](../../wallets/index.md#authorizing-actions) for more information on this. +If we fetch the notes using an oracle call, we can keep the function signature independent of the underlying data and make it easier to use. A similar idea, applied to the authentication mechanism is used for the Authentication Witnesses that allow us to have a single function signature for any wallet implementation, see [AuthWit](../../concepts/accounts/authwit.md) for more information on this. Oracles introduce **non-determinism** into a circuit, and thus are `unconstrained`. It is important that any information that is injected into a circuit through an oracle is later constrained for correctness. Otherwise, the circuit will be **under-constrained** and potentially insecure! @@ -22,7 +23,7 @@ Oracles introduce **non-determinism** into a circuit, and thus are `unconstraine ## Inbuilt oracles -- [`debug_log`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/debug_log.nr) - Provides a couple of debug functions that can be used to log information to the console. Read more about debugging [here](../../../../reference/debugging.md#logging-in-aztecnr). +- [`debug_log`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/debug_log.nr) - Provides a couple of debug functions that can be used to log information to the console. Read more about debugging [here](../../../reference/developer_references/debugging.md). - [`auth_witness`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/authwit/src/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/noir-projects/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/noir-projects/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. @@ -30,4 +31,4 @@ Oracles introduce **non-determinism** into a circuit, and thus are `unconstraine Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr/aztec/src/oracle). -Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [popCapsule](../../../../guides/smart_contracts/writing_contracts/how_to_pop_capsules.md). +Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [popCapsule](../../../guides/developer_guides/smart_contracts/writing_contracts/how_to_pop_capsules.md). diff --git a/docs/docs/aztec/concepts/smart_contracts/index.md b/docs/docs/aztec/smart_contracts_overview.md similarity index 92% rename from docs/docs/aztec/concepts/smart_contracts/index.md rename to docs/docs/aztec/smart_contracts_overview.md index 04f1c6ea5d0..2ccb8b76692 100644 --- a/docs/docs/aztec/concepts/smart_contracts/index.md +++ b/docs/docs/aztec/smart_contracts_overview.md @@ -1,6 +1,7 @@ --- title: Smart Contracts sidebar_position: 3 +tags: [contracts] --- Smart contracts in Aztec are privacy-first, and can include both public and private elements. They are written in Noir framework called Aztec.nr, and allow high-level programs to be converted into ZK circuits. @@ -24,4 +25,4 @@ There are no plans for EVM compatibility or to support Solidity in Aztec. The pr ## Further reading -Read more about writing Aztec contracts [here](../../../guides/smart_contracts/writing_contracts/initializers). +Jump in and write your first smart contract [here](../tutorials/codealong/contract_tutorials/counter_contract.md) diff --git a/docs/docs/guides/_category_.json b/docs/docs/guides/_category_.json new file mode 100644 index 00000000000..3d8f3e3bf4c --- /dev/null +++ b/docs/docs/guides/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Guides", + "link": { "type": "doc", "id": "guides/index" } +} diff --git a/docs/docs/guides/developer_guides/getting_started/_category_.json b/docs/docs/guides/developer_guides/getting_started/_category_.json new file mode 100644 index 00000000000..4b7c1cbad3b --- /dev/null +++ b/docs/docs/guides/developer_guides/getting_started/_category_.json @@ -0,0 +1,6 @@ +{ + "position": 1, + "collapsible": true, + "collapsed": false, + "label": "Getting Started" +} diff --git a/docs/docs/getting_started/codespaces.md b/docs/docs/guides/developer_guides/getting_started/codespaces.md similarity index 98% rename from docs/docs/getting_started/codespaces.md rename to docs/docs/guides/developer_guides/getting_started/codespaces.md index bc6d494e7e9..10658c856c2 100644 --- a/docs/docs/getting_started/codespaces.md +++ b/docs/docs/guides/developer_guides/getting_started/codespaces.md @@ -1,6 +1,6 @@ --- title: Codespaces -sidebar_position: 0 +sidebar_position: 1 draft: true --- diff --git a/docs/docs/getting_started.md b/docs/docs/guides/developer_guides/getting_started/quickstart.md similarity index 84% rename from docs/docs/getting_started.md rename to docs/docs/guides/developer_guides/getting_started/quickstart.md index 923d5e303a8..edf15edd5ea 100644 --- a/docs/docs/getting_started.md +++ b/docs/docs/guides/developer_guides/getting_started/quickstart.md @@ -1,5 +1,7 @@ --- title: Quickstart +sidebar_position: 0 +tags: [sandbox] --- You can get started with an Aztec development environment (A.K.A. Sandbox) in less than 5 minutes. @@ -61,7 +63,7 @@ If you wish to run components of the Aztec network stack separately, you can use aztec start --node [nodeOptions] --pxe [pxeOptions] --archiver [archiverOptions] --sequencer [sequencerOptions] --prover [proverOptions] ----p2p-bootstrap [p2pOptions] ``` -Starting the aztec node alongside a PXE, sequencer or archiver, will attach the components to the node. Eg if you want to run a PXE separately to a node, you can [read this guide](./aztec/concepts/pxe/index.md). +Starting the aztec node alongside a PXE, sequencer or archiver, will attach the components to the node. Eg if you want to run a PXE separately to a node, you can [read this guide](../local_env/run_more_than_one_pxe_sandbox.md). ## Update the sandbox @@ -91,7 +93,15 @@ Update the `Noir: Nargo Path` field to point to your desired `aztec-nargo` execu Now you have a development network running, so you're ready to start coding your first app with Aztec.nr and Aztec.js! -To follow the series of tutorials, start with the private voting contract [here](./tutorials/contract_tutorials/private_voting_contract.md). - -If you want to just keep learning, you can read about the high level architecture on the [Core Components page](./aztec/concepts/state_model/index.md) and [the lifecycle of a transaction](./aztec/concepts/transactions.md). - +If you want to start coding, it is recommended to go through the tutorials in order. Click on the link below to dive in! + +
+ + +

Write your first contract

+ + + Write and deploy a simple private counter smart contract on your local sandbox + + +
diff --git a/docs/docs/guides/js_apps/_category_.json b/docs/docs/guides/developer_guides/js_apps/_category_.json similarity index 80% rename from docs/docs/guides/js_apps/_category_.json rename to docs/docs/guides/developer_guides/js_apps/_category_.json index f5afa68de01..5e0931f01e5 100644 --- a/docs/docs/guides/js_apps/_category_.json +++ b/docs/docs/guides/developer_guides/js_apps/_category_.json @@ -1,5 +1,5 @@ { - "position": 2, + "position": 3, "collapsible": true, "collapsed": true, "label": "Aztec.js" diff --git a/docs/docs/guides/js_apps/authwit.md b/docs/docs/guides/developer_guides/js_apps/authwit.md similarity index 96% rename from docs/docs/guides/js_apps/authwit.md rename to docs/docs/guides/developer_guides/js_apps/authwit.md index 702a8a29bb4..9dc7dcae0d8 100644 --- a/docs/docs/guides/js_apps/authwit.md +++ b/docs/docs/guides/developer_guides/js_apps/authwit.md @@ -1,11 +1,11 @@ --- title: How to use authentication witnesses (authwit) -tags: [accounts] +tags: [accounts, authwit] --- This page assumes you have authwit set up correctly in your contract. To learn how to do that, [go here](../smart_contracts/writing_contracts/authwit.md). -For an introduction to authentication witnesses on Aztec, [read this explainer](../../aztec/concepts/accounts/authwit.md). +For an introduction to authentication witnesses on Aztec, [read this explainer](../../../aztec/concepts/accounts/authwit.md). ## Import libraries @@ -117,5 +117,5 @@ If you created an arbitrary message, you would replace the first param struct wi ## Further reading -- [An explainer of authentication witnesses](../../aztec/concepts/accounts/authwit.md) +- [An explainer of authentication witnesses](../../../aztec/concepts/accounts/authwit.md) - [Authwits in Aztec.nr](../smart_contracts/writing_contracts/authwit.md) diff --git a/docs/docs/guides/js_apps/call_view_function.md b/docs/docs/guides/developer_guides/js_apps/call_view_function.md similarity index 98% rename from docs/docs/guides/js_apps/call_view_function.md rename to docs/docs/guides/developer_guides/js_apps/call_view_function.md index 0c1232722b7..952464a2327 100644 --- a/docs/docs/guides/js_apps/call_view_function.md +++ b/docs/docs/guides/developer_guides/js_apps/call_view_function.md @@ -1,5 +1,6 @@ --- title: How to Simulate a Function Call +tags: [functions] --- This guide explains how to `simulate` a function call using Aztec.js. diff --git a/docs/docs/guides/js_apps/create_account.md b/docs/docs/guides/developer_guides/js_apps/create_account.md similarity index 100% rename from docs/docs/guides/js_apps/create_account.md rename to docs/docs/guides/developer_guides/js_apps/create_account.md diff --git a/docs/docs/guides/js_apps/deploy_contract.md b/docs/docs/guides/developer_guides/js_apps/deploy_contract.md similarity index 78% rename from docs/docs/guides/js_apps/deploy_contract.md rename to docs/docs/guides/developer_guides/js_apps/deploy_contract.md index 51ddd83c74e..2b59f7588e8 100644 --- a/docs/docs/guides/js_apps/deploy_contract.md +++ b/docs/docs/guides/developer_guides/js_apps/deploy_contract.md @@ -1,5 +1,6 @@ --- title: How to Deploy a Contract +tags: [contracts] --- This guide explains how to deploy a smart contract using Aztec.js. @@ -10,11 +11,11 @@ You should have a wallet to act as the deployer, and a contract artifact ready t You can learn how to create wallets from [this guide](./create_account.md). -You can read about contract artifacts [here](../../aztec/concepts/smart_contracts/contract_structure.md). +You can read about contract artifacts [here](../../../aztec/smart_contracts/contract_structure.md). ## Import the contract artifact -In this guide we are using a Token contract artifact. This comes from the [token contract tutorial](../../tutorials/contract_tutorials/token_contract.md). +In this guide we are using a Token contract artifact. This comes from the [token contract tutorial](../../../tutorials/codealong/contract_tutorials/token_contract.md). #include_code import_token_contract yarn-project/end-to-end/src/composed/docs_examples.test.ts typescript diff --git a/docs/docs/guides/js_apps/rotate_keys.md b/docs/docs/guides/developer_guides/js_apps/rotate_keys.md similarity index 91% rename from docs/docs/guides/js_apps/rotate_keys.md rename to docs/docs/guides/developer_guides/js_apps/rotate_keys.md index 01d240b8dd0..55eba15e4ef 100644 --- a/docs/docs/guides/js_apps/rotate_keys.md +++ b/docs/docs/guides/developer_guides/js_apps/rotate_keys.md @@ -1,8 +1,9 @@ --- title: How to Rotate Nullifier Keys +tags: [accounts, keys] --- -This guide explains how to rotate nullifer secret and public keys using Aztec.js. To learn more about key rotation, read the [concepts section](../../aztec/concepts/accounts/keys.md#key-rotation). +This guide explains how to rotate nullifer secret and public keys using Aztec.js. To learn more about key rotation, read the [concepts section](../../../aztec/concepts/accounts/keys.md#key-rotation) ## Prerequisites diff --git a/docs/docs/guides/js_apps/send_transaction.md b/docs/docs/guides/developer_guides/js_apps/send_transaction.md similarity index 100% rename from docs/docs/guides/js_apps/send_transaction.md rename to docs/docs/guides/developer_guides/js_apps/send_transaction.md diff --git a/docs/docs/guides/js_apps/test.md b/docs/docs/guides/developer_guides/js_apps/test.md similarity index 74% rename from docs/docs/guides/js_apps/test.md rename to docs/docs/guides/developer_guides/js_apps/test.md index 546ce64a8b6..59c8dd4b869 100644 --- a/docs/docs/guides/js_apps/test.md +++ b/docs/docs/guides/developer_guides/js_apps/test.md @@ -1,5 +1,6 @@ --- title: Testing Aztec.nr contracts with TypeScript +tags: [contracts, tests] --- In this guide we will cover how to interact with your Aztec.nr smart contracts in a testing environment to write automated tests for your apps. @@ -7,7 +8,7 @@ In this guide we will cover how to interact with your Aztec.nr smart contracts i ## Prerequisites - A compiled contract with TS interface (read [how to compile](../smart_contracts/how_to_compile_contract.md)) -- Your sandbox running (read [getting started](../../getting_started.md)) +- Your sandbox running (read [getting started](../getting_started/quickstart.md)) ## Create TS file and install libraries @@ -60,7 +61,7 @@ This debug information will be populated in the transaction receipt. You can log #include_code debug /yarn-project/end-to-end/src/e2e_token_contract/minting.test.ts typescript -You can also log directly from Aztec contracts. Read [this guide](/reference/debugging.md##logging-in-aztecnr) for some more information. +You can also log directly from Aztec contracts. Read [this guide](../../../reference/developer_references/debugging.md#logging-in-aztecnr) for some more information. ### Examples @@ -82,7 +83,7 @@ We can have private transactions that work fine locally, but are dropped by the #### A public call fails locally -Public function calls can be caught failing locally similar to how we catch private function calls. For this example, we use a [`TokenContract`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/token_contract/src/main.nr) instead of a private one. +Public function calls can be caught failing locally similar to how we catch private function calls. For this example, we use a [`TokenContract` (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/token_contract/src/main.nr) instead of a private one. #include_code local-pub-fails /yarn-project/end-to-end/src/guides/dapp_testing.test.ts typescript @@ -100,25 +101,25 @@ WARN Error processing tx 06dc87c4d64462916ea58426ffcfaf20017880b353c9ec3e0f0ee5f We can check private or public state directly rather than going through view-only methods, as we did in the initial example by calling `token.methods.balance().simulate()`. -To query storage directly, you'll need to know the slot you want to access. This can be checked in the [contract's `Storage` definition](../../reference/smart_contract_reference/storage/index.md) directly for most data types. However, when it comes to mapping types, as in most EVM languages, we'll need to calculate the slot for a given key. To do this, we'll use the [`CheatCodes`](../../reference/sandbox_reference/cheat_codes.md) utility class: +To query storage directly, you'll need to know the slot you want to access. This can be checked in the [contract's `Storage` definition](../../../reference/developer_references/smart_contract_reference/storage/index.md) directly for most data types. However, when it comes to mapping types, as in most EVM languages, we'll need to calculate the slot for a given key. To do this, we'll use the [`CheatCodes`](../../../reference/developer_references/sandbox_reference/cheat_codes.md) utility class: #include_code calc-slot /yarn-project/end-to-end/src/guides/dapp_testing.test.ts typescript #### Querying private state -Private state in the Aztec is represented via sets of [private notes](../../aztec/concepts/state_model/index.md#private-state). We can query the Private Execution Environment (PXE) for all notes encrypted for a given user in a contract slot. For example, this gets all notes encrypted for the `owner` user that are stored on the token contract address and on the slot that was calculated earlier. To calculate the actual balance, it extracts the `value` of each note, which is the first element, and sums them up. +Private state in the Aztec is represented via sets of [private notes](../../../aztec/concepts/state_model/index.md#private-state). We can query the Private Execution Environment (PXE) for all notes encrypted for a given user in a contract slot. For example, this gets all notes encrypted for the `owner` user that are stored on the token contract address and on the slot that was calculated earlier. To calculate the actual balance, it extracts the `value` of each note, which is the first element, and sums them up. #include_code private-storage /yarn-project/end-to-end/src/guides/dapp_testing.test.ts typescript #### Querying public state -[Public state](../../aztec/concepts/state_model/index.md#public-state) behaves as a key-value store, much like in the EVM. We can directly query the target slot and get the result back as a buffer. Note that we use the [`TokenContract`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/token_contract/src/main.nr) in this example, which defines a mapping of public balances on slot 6. +Public state behaves as a key-value store, much like in the EVM. We can directly query the target slot and get the result back as a buffer. Note that we use the [`TokenContract` (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/token_contract/src/main.nr) in this example, which defines a mapping of public balances on slot 6. #include_code public-storage /yarn-project/end-to-end/src/guides/dapp_testing.test.ts typescript ### Logs -You can check the logs of [events](../smart_contracts/writing_contracts/how_to_emit_event.md) emitted by contracts. Contracts in Aztec can emit both [encrypted](../smart_contracts/writing_contracts/how_to_emit_event.md#Encrypted-Events) and [unencrypted](../smart_contracts/writing_contracts/how_to_emit_event.md#Unencrypted-Events) events. +You can check the logs of events emitted by contracts. Contracts in Aztec can emit both encrypted and unencrypted events. #### Querying unencrypted logs @@ -128,7 +129,7 @@ We can query the PXE for the unencrypted logs emitted in the block where our tra ## Cheats -The [`CheatCodes`](../../reference/sandbox_reference/cheat_codes.md) class, which we used for [calculating the storage slot above](#querying-state), also includes a set of cheat methods for modifying the chain state that can be handy for testing. +The [`CheatCodes`](../../../reference/developer_references/sandbox_reference/cheat_codes.md) class, which we used for [calculating the storage slot above](#querying-state), also includes a set of cheat methods for modifying the chain state that can be handy for testing. ### Set next block timestamp @@ -146,5 +147,5 @@ We can then call `warp` and rely on the `isTimeEqual` function to check that the - [How to send a transactions in Aztec.js](./send_transaction.md) - [How to deploy a contract in Aztec.js](./deploy_contract.md) - [How to create an account in Aztec.js](./create_account.md) -- [Cheat codes](../../reference/sandbox_reference/cheat_codes.md) +- [Cheat codes](../../../reference/developer_references/sandbox_reference/cheat_codes.md) - [How to compile a contract](../smart_contracts/how_to_compile_contract.md). diff --git a/docs/docs/guides/local_env/_category_.json b/docs/docs/guides/developer_guides/local_env/_category_.json similarity index 82% rename from docs/docs/guides/local_env/_category_.json rename to docs/docs/guides/developer_guides/local_env/_category_.json index 808175f5ff1..5c8df7e68a1 100644 --- a/docs/docs/guides/local_env/_category_.json +++ b/docs/docs/guides/developer_guides/local_env/_category_.json @@ -1,5 +1,5 @@ { - "position": 0, + "position": 2, "collapsible": true, "collapsed": true, "label": "Development Environment" diff --git a/docs/docs/guides/local_env/creating_schnorr_accounts.md b/docs/docs/guides/developer_guides/local_env/creating_schnorr_accounts.md similarity index 89% rename from docs/docs/guides/local_env/creating_schnorr_accounts.md rename to docs/docs/guides/developer_guides/local_env/creating_schnorr_accounts.md index 92c145af408..d9b3837f274 100644 --- a/docs/docs/guides/local_env/creating_schnorr_accounts.md +++ b/docs/docs/guides/developer_guides/local_env/creating_schnorr_accounts.md @@ -2,6 +2,7 @@ title: Creating Schnorr Accounts sidebar_position: 1 draft: true +tags: [accounts] --- @@ -10,14 +11,14 @@ draft: true This section shows how to create schnorr account wallets on the Aztec Sandbox. -An in-depth explaining about accounts on aztec can be found [here](../../aztec/concepts/accounts/index.md). But creating an account on the Sandbox does 2 things: +An in-depth explainer about accounts on aztec can be found [here](../../../aztec/concepts/accounts/index.md). But creating an account on the Sandbox does 2 things: 1. Deploys an account contract -- representing you -- allowing you to perform actions on the network (deploy contracts, call functions etc). 2. Adds your encryption keys to the Private eXecution Environment (PXE) allowing it to decrypt and manage your private state. ## Pre-requisites -Have a running Sandbox and a repository that interacts with it as explained [here](../../getting_started.md). +Have a running Sandbox and a repository that interacts with it as explained [in the quickstart](../getting_started/quickstart.md). Let's assume you have a file `src/index.ts` from the example used in the Sandbox page. @@ -64,4 +65,4 @@ Once this has completed, the L2 block is retrieved and pulled down to the PXE so ## Next Steps -Check out our section on [Writing your own Account Contract](../../tutorials/write_accounts_contract.md) leveraging our account abstraction +Check out our section on [Writing your own Account Contract](../../../tutorials/codealong/contract_tutorials/write_accounts_contract.md) leveraging our account abstraction. diff --git a/docs/docs/guides/local_env/run_more_than_one_pxe_sandbox.md b/docs/docs/guides/developer_guides/local_env/run_more_than_one_pxe_sandbox.md similarity index 95% rename from docs/docs/guides/local_env/run_more_than_one_pxe_sandbox.md rename to docs/docs/guides/developer_guides/local_env/run_more_than_one_pxe_sandbox.md index 53c4b3cb8be..d8530befc98 100644 --- a/docs/docs/guides/local_env/run_more_than_one_pxe_sandbox.md +++ b/docs/docs/guides/developer_guides/local_env/run_more_than_one_pxe_sandbox.md @@ -1,6 +1,7 @@ --- title: Running Multiple PXEs in the Sandbox sidebar_position: 2 +tags: [PXE] --- :::warning @@ -49,4 +50,4 @@ You should see something like this: Aztec Server listening on port 8080 ``` -You can learn more about custom commands in the [sandbox reference](../../reference/sandbox_reference/sandbox-reference.md). +You can learn more about custom commands in the [sandbox reference](../../../reference/developer_references/sandbox_reference/sandbox-reference.md). diff --git a/docs/docs/guides/local_env/versions-updating.md b/docs/docs/guides/developer_guides/local_env/versions-updating.md similarity index 88% rename from docs/docs/guides/local_env/versions-updating.md rename to docs/docs/guides/developer_guides/local_env/versions-updating.md index b310225bc25..263a00ec5aa 100644 --- a/docs/docs/guides/local_env/versions-updating.md +++ b/docs/docs/guides/developer_guides/local_env/versions-updating.md @@ -1,6 +1,7 @@ --- title: Updating the Sandbox sidebar_position: 0 +tags: [sandbox] --- - Current version: `#include_aztec_version` @@ -55,7 +56,7 @@ diff ~/nargo/github.com/AztecProtocol/aztec-packages-v0.23.0/yarn-project/noir-c ### Language server version (aztec-nargo) -The [Noir LSP](../../getting_started.md#install-noir-lsp-recommended) uses your local version of `aztec-nargo`, and thus also `aztec-nargo compile`. +The [Noir LSP](../getting_started/quickstart.md#install-noir-lsp-recommended) uses your local version of `aztec-nargo`, and thus also `aztec-nargo compile`. The path of the former (once installed) can be seen by hovering over "Nargo" in the bottom status bar of VS Code, and the latter via the `which aztec-nargo` command. :::caution @@ -93,11 +94,11 @@ cd your/aztec/project aztec update . --contract src/contract1 --contract src/contract2 ``` -The sandbox must be running for the update command to work. Make sure it is [installed and running](../../reference/sandbox_reference/sandbox-reference.md). +The sandbox must be running for the update command to work. Make sure it is [installed and running](../../../reference/developer_references/sandbox_reference/sandbox-reference.md). Follow [updating Aztec.nr packages](#updating-aztecnr-packages) and [updating JavaScript packages](#updating-aztecjs-packages) guides. -3. Refer to [Migration Notes](../../migration_notes.md) on any breaking changes that might affect your dapp +3. Refer to [Migration Notes](../../../migration_notes.md) on any breaking changes that might affect your dapp --- @@ -139,7 +140,7 @@ cd /your/contract/directory aztec-nargo compile ``` -If the dependencies fail to resolve ensure that the tag matches a tag in the [aztec-packages repository](https://github.com/AztecProtocol/aztec-packages/tags). +If the dependencies fail to resolve ensure that the tag matches a tag in the [aztec-packages repository (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tags). ## Updating Aztec.js packages @@ -161,9 +162,9 @@ As mentioned in the tl;dr, `aztec-nargo` is updated as part of updating the whol aztec-up ``` -The version of aztec-nargo that comes with a particular version of the Aztec sandbox can be seen in the monorepo. Eg tag: aztec-packages-v0.35.0 contains aztec-nargo [v0.27.0](https://github.com/AztecProtocol/aztec-packages/blob/aztec-packages-v0.35.0/noir/noir-repo/Cargo.toml#L44). +The version of aztec-nargo that comes with a particular version of the Aztec sandbox can be seen in the monorepo. Eg tag: aztec-packages-v0.35.0 contains aztec-nargo [v0.27.0 (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/aztec-packages-v0.35.0/noir/noir-repo/Cargo.toml#L44). -Set VERSION to specify the desired Aztec sandbox version, eg monorepo tag suffix [0.35.0](https://github.com/AztecProtocol/aztec-packages/tree/aztec-packages-v0.35.0) (to have `aztec-nargo` v0.27.0). +Set VERSION to specify the desired Aztec sandbox version, eg monorepo tag suffix [0.35.0 (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/aztec-packages-v0.35.0) (to have `aztec-nargo` v0.27.0). ```bash VERSION= aztec-up diff --git a/docs/docs/guides/smart_contracts/_category_.json b/docs/docs/guides/developer_guides/smart_contracts/_category_.json similarity index 80% rename from docs/docs/guides/smart_contracts/_category_.json rename to docs/docs/guides/developer_guides/smart_contracts/_category_.json index e323c74a391..d0bf2983301 100644 --- a/docs/docs/guides/smart_contracts/_category_.json +++ b/docs/docs/guides/developer_guides/smart_contracts/_category_.json @@ -1,5 +1,5 @@ { - "position": 1, + "position": 4, "collapsible": true, "collapsed": true, "label": "Aztec.nr" diff --git a/docs/docs/guides/smart_contracts/how_to_compile_contract.md b/docs/docs/guides/developer_guides/smart_contracts/how_to_compile_contract.md similarity index 88% rename from docs/docs/guides/smart_contracts/how_to_compile_contract.md rename to docs/docs/guides/developer_guides/smart_contracts/how_to_compile_contract.md index c63d7e28876..1bea4c72e2d 100644 --- a/docs/docs/guides/smart_contracts/how_to_compile_contract.md +++ b/docs/docs/guides/developer_guides/smart_contracts/how_to_compile_contract.md @@ -1,9 +1,10 @@ --- title: How to Compile a Contract sidebar_position: 3 +tags: [contracts] --- -Once you have written a contract in Aztec.nr, you will need to compile it into an [artifact](../../aztec/concepts/smart_contracts/contract_structure.md) in order to use it. +Once you have written a contract in Aztec.nr, you will need to compile it into an artifact in order to use it. In this guide we will cover how to do so, both using the `aztec-nargo` command and programmatically. @@ -19,7 +20,7 @@ Run the `aztec-nargo compile` command within your contract project folder (the o aztec-nargo compile ``` -This will output a JSON [artifact](../../aztec/concepts/smart_contracts/contract_structure.md) for each contract in the project to a `target` folder containing the Noir ABI artifacts. +This will output a JSON artifact for each contract in the project to a `target` folder containing the Noir ABI artifacts. :::note This command looks for `Nargo.toml` files by ascending up the parent directories, and will compile the top-most Nargo.toml file it finds. @@ -42,7 +43,7 @@ You can use the code generator to autogenerate type-safe typescript classes for aztec codegen ./aztec-nargo/output/target/path -o src/artifacts ``` -Below is typescript code generated from the [Token](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/token_contract/src/main.nr) contract: +Below is typescript code generated from the [Token (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/token_contract/src/main.nr) contract: ```ts showLineNumbers export class TokenContract extends ContractBase { @@ -222,15 +223,15 @@ export class TokenContract extends ContractBase { } ``` -Read more about interacting with contracts using `aztec.js` [here](../../tutorials/aztecjs-getting-started.md). +Read more about interacting with contracts using `aztec.js` [by following this tutorial](../../../tutorials/codealong/aztecjs-getting-started.md). ### Aztec.nr interfaces -An Aztec.nr contract can [call a function](writing_contracts/call_functions.md) in another contract via `context.call_private_function` or `context.call_public_function`. However, this requires manually assembling the function selector and manually serializing the arguments, which is not type-safe. +An Aztec.nr contract can [call a function](./writing_contracts/call_functions.md) in another contract via `context.call_private_function` or `context.call_public_function`. However, this requires manually assembling the function selector and manually serializing the arguments, which is not type-safe. To make this easier, the compiler automatically generates interface structs that expose a convenience method for each function listed in a given contract artifact. These structs are intended to be used from another contract project that calls into the current one. -Below is an example of interface usage generated from the [Token](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/token_contract/src/main.nr) contract, used from the [FPC](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/fpc_contract/src/main.nr): +Below is an example of interface usage generated from the [Token (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/token_contract/src/main.nr) contract, used from the [FPC (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/fpc_contract/src/main.nr): ```rust contract FPC { @@ -260,7 +261,7 @@ contract FPC { } ``` -Read more about how to use the Aztec.nr interfaces [here](../../aztec/concepts/smart_contracts/functions/index.md). +Read more about how to use the Aztec.nr interfaces [here](../../../aztec/smart_contracts/functions/index.md). :::info At the moment, the compiler generates these interfaces from already compiled ABIs, and not from source code. This means that you should not import a generated interface from within the same project as its source contract, or you risk circular references. diff --git a/docs/docs/guides/smart_contracts/how_to_deploy_contract.md b/docs/docs/guides/developer_guides/smart_contracts/how_to_deploy_contract.md similarity index 71% rename from docs/docs/guides/smart_contracts/how_to_deploy_contract.md rename to docs/docs/guides/developer_guides/smart_contracts/how_to_deploy_contract.md index eb07475b884..90584a31e08 100644 --- a/docs/docs/guides/smart_contracts/how_to_deploy_contract.md +++ b/docs/docs/guides/developer_guides/smart_contracts/how_to_deploy_contract.md @@ -1,17 +1,18 @@ --- title: How to Deploy a Contract sidebar_position: 4 +tags: [contracts, sandbox] --- # Deploying contracts -Once you have [compiled](how_to_compile_contract.md) your contracts you can proceed to deploying them using aztec.js which is a Typescript client to interact with the sandbox. +Once you have [compiled](./how_to_compile_contract.md) your contracts you can proceed to deploying them using aztec.js which is a Typescript client to interact with the sandbox. ## Prerequisites -- `aztec-nargo` installed (go to [Sandbox section](../../reference/sandbox_reference/index.md) for installation instructions) -- contract artifacts ready (go to [How to Compile Contract](how_to_compile_contract.md) for instructions on how to compile contracts) -- Aztec Sandbox running (go to [Sandbox section](../../getting_started.md) for instructions on how to install and run the sandbox) +- `aztec-nargo` installed (go to [Sandbox section](../../../reference/developer_references/sandbox_reference/sandbox-reference.md) for installation instructions) +- contract artifacts ready (go to [How to Compile Contract](./how_to_compile_contract.md) for instructions on how to compile contracts) +- Aztec Sandbox running (go to [Sandbox section](../getting_started/quickstart.md) for instructions on how to install and run the sandbox) ## Deploy @@ -29,7 +30,7 @@ Generate the typescript class: aztec codegen ./aztec-nargo/output/target/path -o src/artifacts ``` -This would create a typescript file like `Example.ts` in `./src/artifacts`. Read more on the [compiling page](how_to_compile_contract.md). +This would create a typescript file like `Example.ts` in `./src/artifacts`. Read more on the [compiling page](./how_to_compile_contract.md). You can use the `Contract` class to deploy a contract: diff --git a/docs/docs/guides/smart_contracts/testing_contracts/_category_.json b/docs/docs/guides/developer_guides/smart_contracts/testing_contracts/_category_.json similarity index 100% rename from docs/docs/guides/smart_contracts/testing_contracts/_category_.json rename to docs/docs/guides/developer_guides/smart_contracts/testing_contracts/_category_.json diff --git a/docs/docs/guides/smart_contracts/testing_contracts/index.md b/docs/docs/guides/developer_guides/smart_contracts/testing_contracts/testing.md similarity index 96% rename from docs/docs/guides/smart_contracts/testing_contracts/index.md rename to docs/docs/guides/developer_guides/smart_contracts/testing_contracts/testing.md index c0dd73b3f91..b6463a0f222 100644 --- a/docs/docs/guides/smart_contracts/testing_contracts/index.md +++ b/docs/docs/guides/developer_guides/smart_contracts/testing_contracts/testing.md @@ -1,5 +1,6 @@ --- -title: Testing Contracts +title: Testing Contracts in the TXE +tags: [contracts, tests] --- Aztec contracts can be tested in a variety of ways depending on the needs of a particular application and the complexity of the interactions they must support. @@ -35,7 +36,7 @@ So to summarize: ### Running TXE -If you have [the sandbox](../../../getting_started.md) installed, you can run TXE tests using: +If you have [the sandbox](../../getting_started/quickstart.md) installed, you can run TXE tests using: `aztec test` @@ -56,7 +57,7 @@ Since TXE tests are written in Noir and executed with `aztec-nargo`, they all ru `aztec-nr` provides an utility class called `TestEnvironment`, that should take care of the most common operations needed to setup contract testing. Setting up a new test environment with `TestEnvironment::new()` **will reset the current test's TXE state**. :::tip -You can find all of the methods available in the `TestEnvironment` [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/test/helpers/test_environment.nr). +You can find all of the methods available in the `TestEnvironment` [here (Github link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/test/helpers/test_environment.nr). ::: #include_code txe_test_increment /noir-projects/noir-contracts/contracts/counter_contract/src/main.nr rust diff --git a/docs/docs/guides/smart_contracts/writing_contracts/_category_.json b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/_category_.json similarity index 100% rename from docs/docs/guides/smart_contracts/writing_contracts/_category_.json rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/_category_.json diff --git a/docs/docs/guides/smart_contracts/writing_contracts/authwit.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/authwit.md similarity index 93% rename from docs/docs/guides/smart_contracts/writing_contracts/authwit.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/authwit.md index ea5d8f1dae3..dbcfd7e8a05 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/authwit.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/authwit.md @@ -1,6 +1,7 @@ --- title: Authentication Witness description: Developer Documentation to use Authentication Witness for authentication actions on Aztec. +tags: [accounts, authwit] --- This page introduces the authwit library and how you can use it in your Aztec.nr smart contracts. [Skip to the usage](#usage). @@ -9,13 +10,13 @@ For a guide on using authwit in Aztec.js, [read this](../../js_apps/authwit.md). ## Prerequisite reading -- [Authwit](../../../aztec/concepts/accounts/authwit.md) +- [Authwit](../../../../aztec/concepts/accounts/authwit.md) ## Introduction Authentication Witness is a scheme for authentication actions on Aztec, so users can allow third-parties (eg protocols or other users) to execute an action on their behalf. -How it works logically is explained in the [concepts](../../../aztec/concepts/accounts/authwit.md) but we will do a short recap here. +How it works logically is explained in the [concepts](../../../../aztec/concepts/accounts/authwit.md) but we will do a short recap here. An authentication witness is defined for a specific action, such as allowing a Defi protocol to transfer funds on behalf of the user. An action is here something that could be explained as `A is allowed to perform X operation on behalf of B` and we define it as a hash computed as such: @@ -83,19 +84,19 @@ Both return the value `0xabf64ad4` (`IS_VALID` selector) for a successful authen ## The `AuthWit` library. -As part of [Aztec.nr](https://aztec.nr), we are providing a library that can be used to implement authentication witness for your contracts. +As part of Aztec.nr, we are providing a library that can be used to implement authentication witness for your contracts. -This library also provides a basis for account implementations such that these can more easily implement authentication witness. For more on the wallets, see [writing an account contract](../../../tutorials/contract_tutorials/write_accounts_contract.md). +This library also provides a basis for account implementations such that these can more easily implement authentication witness. For our purposes here (not building a wallet), the most important part of the library is the `auth` utility which exposes a couple of helper methods for computing the action hash, retrieving witnesses, validating them and emitting the nullifier. ### General utilities -The primary general utility is the `compute_authwit_message_hash_from_call` function which computes the action hash from its components. This is useful for when you need to generate a hash that is not for the current call, such as when you want to update a public approval state value that is later used for [authentication in public](#updating-approval-state-in-noir). You can view the implementation of this function [here](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/authwit/src/auth.nr). +The primary general utility is the `compute_authwit_message_hash_from_call` function which computes the action hash from its components. This is useful for when you need to generate a hash that is not for the current call, such as when you want to update a public approval state value that is later used for [authentication in public](#updating-approval-state-in-noir). You can view the implementation of this function [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/authwit/src/auth.nr). #### TypeScript utilities -To make it convenient to compute the message hashes in TypeScript, the `aztec.js` package includes a `computeAuthWitMessageHash` function that you can use. Implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec.js/src/utils/authwit.ts). +To make it convenient to compute the message hashes in TypeScript, the `aztec.js` package includes a `computeAuthWitMessageHash` function that you can use. Implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec.js/src/utils/authwit.ts). ### Utilities for private calls @@ -166,7 +167,7 @@ With private functions covered, how can we use this in a public function? Well, Authenticating an action in the public domain is slightly different from the private domain, since we are executing a function on the auth registry contract to add the witness flag. As you might recall, this was to ensure that we don't need to call into the account contract from public, which is a potential DOS vector. -In the snippet below, this is done as a separate contract call, but can also be done as part of a batch as mentioned in the [Accounts concepts](../../../aztec/concepts/accounts/authwit.md#what-about-public). +In the snippet below, this is done as a separate contract call, but can also be done as part of a batch as mentioned in the [Accounts concepts](../../../../aztec/concepts/accounts/authwit.md#what-about-public). #include_code authwit_public_transfer_example /yarn-project/end-to-end/src/e2e_token_contract/transfer_public.test.ts typescript diff --git a/docs/docs/guides/smart_contracts/writing_contracts/call_functions.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/call_functions.md similarity index 65% rename from docs/docs/guides/smart_contracts/writing_contracts/call_functions.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/call_functions.md index f67aad33653..fcca446ddad 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/call_functions.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/call_functions.md @@ -1,12 +1,13 @@ --- title: Calling Other Functions sidebar_position: 2 +tags: [functions, contracts] --- -A contract is a collection of persistent [state variables](../../../aztec/concepts/storage/index.md), and [functions](../../../aztec/concepts/smart_contracts/functions/index.md) which may manipulate these variables. +A contract is a collection of persistent state variables and 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. @@ -28,7 +29,7 @@ contract MyContract { } ``` :::info A note for vanilla Noir devs -There is no [`main()`](https://noir-lang.org/docs/getting_started/project_breakdown/#mainnr) function within a Noir `contract` scope. More than one function can be an entrypoint. +There is no [`main()` (GitHub link)](https://noir-lang.org/docs/getting_started/project_breakdown/#mainnr) function within a Noir `contract` scope. More than one function can be an entrypoint. ::: -To understand how to call a function from another contract, follow the [crowdfunding tutorial](../../../tutorials/contract_tutorials/crowdfunding_contract.md). \ No newline at end of file +To understand how to call a function from another contract, follow the [crowdfunding tutorial](../../../../tutorials/codealong/contract_tutorials/crowdfunding_contract.md). diff --git a/docs/docs/guides/smart_contracts/writing_contracts/common_patterns/index.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/common_patterns/index.md similarity index 87% rename from docs/docs/guides/smart_contracts/writing_contracts/common_patterns/index.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/common_patterns/index.md index a44b376779a..fbf1f9e26f8 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/common_patterns/index.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/common_patterns/index.md @@ -3,7 +3,7 @@ title: Common Patterns sidebar_position: 7 --- -There are many common patterns have been devised by the Aztec core engineering team and the work of the external community as we build Aztec.nr contracts internally (see some of them [here](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/noir-contracts)). +There are many common patterns have been devised by the Aztec core engineering team and the work of the external community as we build Aztec.nr contracts internally (see some of them [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/noir-contracts)). This doc aims to summarize some of them! @@ -41,7 +41,7 @@ Note - you could also create a note and send it to the user. The problem is ther You can't read public storage in private domain. But nevertheless reading public storage is desirable. There are two ways to achieve the desired effect: -1. For public values that change infrequently, you can use [shared state](../../../../reference/smart_contract_reference/storage/shared_state.md). +1. For public values that change infrequently, you can use [shared state](../../../../../reference/developer_references/smart_contract_reference/storage/shared_state.md). 1. You pass the data as a parameter to your private method and later assert in public that the data is correct. E.g.: @@ -84,18 +84,18 @@ Let's say you have some storage in public and want to move them into the private So you have to create a custom note in the public domain that is not encrypted by some owner - we call such notes a "TransparentNote" since it is created in public, anyone can see the amount and the note is not encrypted by some owner. -This pattern is discussed in detail in [writing a token contract section in the shield() method](../../../../tutorials/contract_tutorials/token_contract.md#redeem_shield). +This pattern is discussed in detail in [the codealong token tutorial in the shield() method](../../../../../tutorials/codealong/contract_tutorials/token_contract.md#redeem_shield). ### Discovering my notes -When you send someone a note, the note hash gets added to the [note hash tree](../../../../protocol-specs/state/note-hash-tree.md). To spend the note, the receiver needs to get the note itself (the note hash preimage). There are two ways you can get a hold of your notes: +When you send someone a note, the note hash gets added to the note hash tree. To spend the note, the receiver needs to get the note itself (the note hash preimage). There are two ways you can get a hold of your notes: 1. When sending someone a note, use `encrypt_and_emit_note` (the function encrypts the log in such a way that only a recipient can decrypt it). PXE then tries to decrypt all the encrypted logs, and stores the successfully decrypted one. [More info here](../how_to_emit_event.md) 2. Manually using `pxe.addNote()` - If you choose to not emit logs to save gas or when creating a note in the public domain and want to consume it in private domain (`encrypt_and_emit_note` shouldn't be called in the public domain because everything is public), like in the previous section where we created a TransparentNote in public. #include_code pxe_add_note yarn-project/end-to-end/src/e2e_cheat_codes.test.ts typescript -In the token contract, TransparentNotes are stored in a set called "pending_shields" which is in storage slot 5tutorials/tutorials/contract_tutorials/token_contract.md#contract-storage) +In the token contract, TransparentNotes are stored in a set called "pending_shields" which is in storage slot 5tutorials/tutorials/codealong/contract_tutorials/token_contract.md#contract-storage) ### Revealing encrypted logs conditionally @@ -117,7 +117,7 @@ Hence, it's necessary to add a "randomness" field to your note to prevent such a ### L1 -- L2 interactions -Refer to [Token Portal tutorial on bridging tokens between L1 and L2](../../../../tutorials/contract_tutorials/advanced/token_bridge/index.md) and/or [Uniswap smart contract example that shows how to swap on L1 using funds on L2](../../../../reference/smart_contract_reference/examples/uniswap/index.md). Both examples show how to: +Refer to [Token Portal codealong tutorial on bridging tokens between L1 and L2](../../../../../tutorials/codealong/contract_tutorials/advanced/token_bridge/index.md) and/or [Uniswap smart contract example that shows how to swap on L1 using funds on L2](../../../../../tutorials/examples/uniswap/index.md). Both examples show how to: 1. L1 -> L2 message flow 2. L2 -> L1 message flow @@ -131,7 +131,7 @@ To send a note to someone, they need to have a key which we can encrypt the note There are several patterns here: 1. Give the contract a key and share it amongst all participants. This leaks privacy, as anyone can see all the notes in the contract. -2. `Unshield` funds into the contract - this is used in the [Uniswap smart contract example where a user sends private funds into a Uniswap Portal contract which eventually withdraws to L1 to swap on L1 Uniswap](../../../../reference/smart_contract_reference/examples/uniswap/index.md). This works like Ethereum - to achieve contract composability, you move funds into the public domain. This way the contract doesn't even need keys. +2. `Unshield` funds into the contract - this is used in the [Uniswap smart contract example where a user sends private funds into a Uniswap Portal contract which eventually withdraws to L1 to swap on L1 Uniswap](../../../../../tutorials/examples/uniswap/index.md). This works like Ethereum - to achieve contract composability, you move funds into the public domain. This way the contract doesn't even need keys. There are several other designs we are discussing through [in this discourse post](https://discourse.aztec.network/t/how-to-handle-private-escrows-between-two-parties/2440) but they need some changes in the protocol or in our demo contract. If you are interested in this discussion, please participate in the discourse post! @@ -153,6 +153,6 @@ PS: when calling from private to public, `msg_sender` is the contract address wh In the [Prevent the same user flow from happening twice using nullifier](#prevent-the-same-user-flow-from-happening-twice-using-nullifiers), we recommended using nullifiers. But what you put in the nullifier is also as important. -E.g. for a voting contract, if your nullifier simply emits just the `user_address`, then privacy can easily be leaked as nullifiers are deterministic (have no randomness), especially if there are few users of the contract. So you need some kind of randomness. You can add the user's secret key into the nullifier to add randomness. We call this "nullifier secrets" as explained [here](../../../../aztec/concepts/accounts/keys.md#nullifier-secrets). E.g.: +E.g. for a voting contract, if your nullifier simply emits just the `user_address`, then privacy can easily be leaked as nullifiers are deterministic (have no randomness), especially if there are few users of the contract. So you need some kind of randomness. You can add the user's secret key into the nullifier to add randomness. We call this "nullifier secrets" as explained [here](../../../../../aztec/concepts/accounts/keys.md#nullifier-keys). E.g.: #include_code nullifier /noir-projects/aztec-nr/value-note/src/value_note.nr rust diff --git a/docs/docs/guides/smart_contracts/writing_contracts/common_patterns/key_rotation.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/common_patterns/key_rotation.md similarity index 76% rename from docs/docs/guides/smart_contracts/writing_contracts/common_patterns/key_rotation.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/common_patterns/key_rotation.md index 9fb6fdca481..1a8a31e971a 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/common_patterns/key_rotation.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/common_patterns/key_rotation.md @@ -1,10 +1,11 @@ --- title: Key Rotation +tags: [accounts, keys] --- ## Prerequisite reading -- [Keys](../../../../aztec/concepts/accounts/keys.md) +- [Keys Concept](../../../../../aztec/concepts/accounts/keys.md) ## Introduction @@ -22,6 +23,6 @@ It is still possible to nullify the notes with the old nullifier key even after ## Glossary - `npk_m_hash`: master nullifying public key hash -- `nsk_app`: app nullifying secret key - the app-specific NSK (learn more about app-scoped keys [here](../../../../aztec/concepts/accounts/keys.md#scoped-keys)) +- `nsk_app`: app nullifying secret key - the app-specific NSK (learn more about app-scoped keys [here](../../../../../aztec/concepts/accounts/keys.md#scoped-keys)) - `nsk_hash`: nullifying secret key hash -- `ivpk_m`: incoming view public key (master) (learn more about IVPKs [here](../../../../aztec/concepts/accounts/keys.md#keys)) \ No newline at end of file +- `ivpk_m`: incoming view public key (master) (learn more about IVPKs [here](../../../../../aztec/concepts/accounts/keys.md#incoming-viewing-keys)) \ No newline at end of file diff --git a/docs/docs/guides/smart_contracts/writing_contracts/how_to_emit_event.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/how_to_emit_event.md similarity index 95% rename from docs/docs/guides/smart_contracts/writing_contracts/how_to_emit_event.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/how_to_emit_event.md index ab2a84333f0..97918ab49b5 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/how_to_emit_event.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/how_to_emit_event.md @@ -1,6 +1,7 @@ --- title: Emitting Events sidebar_position: 3 +tags: [contracts] --- Events in Aztec work similarly to Ethereum events in the sense that they are a way for contracts to communicate with the outside world. @@ -20,12 +21,12 @@ Unlike on Ethereum, there are 2 types of events supported by Aztec: [encrypted]( 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 Private Execution Environment (PXE) before encrypting the events for them. -First we need to get a hold of recipient's [complete address](../../../aztec/concepts/accounts/keys#complete-address). +First we need to get a hold of recipient's complete address. Below are some ways how we could instantiate it after getting the information in a string form from a recipient: #include_code instantiate-complete-address /yarn-project/circuits.js/src/structs/complete_address.test.ts rust -Then to register the recipient's complete address in PXE we would call `registerRecipient` PXE endpoint using [Aztec.js](../../../aztec/core_components.md#aztecjs): +Then to register the recipient's complete address in PXE we would call `registerRecipient` PXE endpoint using Aztec.js #include_code register-recipient /yarn-project/aztec.js/src/wallet/create_recipient.ts rust diff --git a/docs/docs/guides/smart_contracts/writing_contracts/how_to_pop_capsules.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/how_to_pop_capsules.md similarity index 97% rename from docs/docs/guides/smart_contracts/writing_contracts/how_to_pop_capsules.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/how_to_pop_capsules.md index 8ac6daa8369..5ba1ba6a226 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/how_to_pop_capsules.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/how_to_pop_capsules.md @@ -1,6 +1,7 @@ --- title: Using the popCapsule Oracle sidebar_position: 5 +tags: [functions, oracles] --- `popCapsule` is used for passing artbitrary data. We have not yet included this in Aztec.nr, so it is a bit more complex than the other oracles. You can follow this how-to: diff --git a/docs/docs/guides/smart_contracts/writing_contracts/how_to_prove_history.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/how_to_prove_history.md similarity index 91% rename from docs/docs/guides/smart_contracts/writing_contracts/how_to_prove_history.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/how_to_prove_history.md index c0805aecab8..45d862b7a39 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/how_to_prove_history.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/how_to_prove_history.md @@ -1,13 +1,14 @@ --- title: Using the Archive Tree sidebar_position: 4 +tags: [contracts] --- -The Aztec Protocol uses an append-only Merkle tree to store hashes of the headers of all previous blocks in the chain as its leaves. This is known as the Archive tree. You can learn more about how it works in the [concepts section](../../../aztec/concepts/storage/trees/index.md#archive-tree). +The Aztec Protocol uses an append-only Merkle tree to store hashes of the headers of all previous blocks in the chain as its leaves. This is known as the Archive tree. You can learn more about how it works in the [concepts section](../../../../aztec/concepts/storage/trees/index.md). This page is a quick introductory guide to creating historical proofs proofs from the archive tree. -For a reference, go [here](https://docs.aztec.network/reference/smart_contract_reference/aztec-nr/aztec/history/contract_inclusion). +For a reference, go [here](../../../../reference/developer_references/smart_contract_reference/aztec-nr/aztec/history/contract_inclusion.md). ## Inclusion and non-inclusion proofs @@ -80,4 +81,4 @@ You can also prove that a note was not nullified in a specified block by using ` ## Prove contract inclusion, public value inclusion, and use current state in lookups -To see what else you can do with historical proofs, check out the [reference](https://docs.aztec.network/reference/smart_contract_reference/aztec-nr/aztec/history/contract_inclusion) \ No newline at end of file +To see what else you can do with historical proofs, check out the [reference](../../../../reference/developer_references/smart_contract_reference/aztec-nr/aztec/history/contract_inclusion.md) diff --git a/docs/docs/guides/smart_contracts/writing_contracts/initializers.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/initializers.md similarity index 81% rename from docs/docs/guides/smart_contracts/writing_contracts/initializers.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/initializers.md index 38f6b390fe8..d350301d4f7 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/initializers.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/initializers.md @@ -1,6 +1,7 @@ --- title: Defining Initializer Functions sidebar_position: 1 +tags: [functions, contracts] --- This page explains how to write an initializer function, also known as a constructor. @@ -18,7 +19,7 @@ fn constructor(){ } ``` -## Choose whether your initializer is public or private +## Public or private Aztec supports both public and private initializers. Use the appropriate macro, for example for a private initializer: @@ -44,6 +45,6 @@ You can set multiple functions as an initializer function simply by annotating e Calling any one of the functions annotated with `#[aztec(initializer)]` will mark the contract as initialized. -See [this page of the protocol specs](../../../protocol-specs/contract-deployment/instances.md#initialization) for more info about what marking a function as initialized means. +See [this page of the protocol specs](../../../../protocol-specs/contract-deployment/instances.md#initialization) for more info about what marking a function as initialized means. -To see an initializer in action, check out the [Counter Contract Tutorial](../../../tutorials/contract_tutorials/counter_contract.md). +To see an initializer in action, follow the [Counter codealong tutorial](../../../../tutorials/codealong/contract_tutorials/counter_contract.md). diff --git a/docs/docs/guides/smart_contracts/writing_contracts/notes/address_note.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/address_note.md similarity index 86% rename from docs/docs/guides/smart_contracts/writing_contracts/notes/address_note.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/address_note.md index 2315511a7bc..8a2c8db47fc 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/notes/address_note.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/address_note.md @@ -1,5 +1,6 @@ --- title: Using Address Note in Aztec.nr +tags: [contracts, notes] --- Address notes hold one main property of the type `AztecAddress`. It also holds `npk_m_hash` and `randomness`, similar to other note types. @@ -37,6 +38,6 @@ In this example, `owner` is the `address` and the `npk_m_hash` of the donor was ## Learn more -- [Keys, including nullifier keys and outgoing viewer](../../../../aztec/concepts/accounts/keys.md) +- [Keys, including nullifier keys and outgoing viewer](../../../../../aztec/concepts/accounts/keys.md) - [How to write a custom note](./custom_note.md) -- [AddressNote reference](https://docs.aztec.network/reference/smart_contract_reference/aztec-nr/address-note/address_note) \ No newline at end of file +- [AddressNote reference](../../../../../reference/developer_references/smart_contract_reference/aztec-nr/address-note/address_note.md) diff --git a/docs/docs/guides/smart_contracts/writing_contracts/notes/custom_note.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/custom_note.md similarity index 95% rename from docs/docs/guides/smart_contracts/writing_contracts/notes/custom_note.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/custom_note.md index eb9716608ad..32edb7d5340 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/notes/custom_note.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/custom_note.md @@ -1,5 +1,6 @@ --- title: Using custom note types in Aztec.nr +tags: [contracts, notes] --- It may be useful to write a custom note type if you want to use a specific type of private data or struct that does not have a default implementation in Aztec.nr. If you create a note that uses a custom note type, you are able to nullify that note with one nullifier. This is more secure and less expensive than using multiple separate notes. @@ -42,4 +43,4 @@ If you are also planning to be able to access the data with a note in public sta ## Further reading -- [Macros reference](../../../../reference/smart_contract_reference/macros.md) \ No newline at end of file +- [Macros reference](../../../../../reference/developer_references/smart_contract_reference/macros.md) diff --git a/docs/docs/guides/smart_contracts/writing_contracts/notes/index.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/index.md similarity index 77% rename from docs/docs/guides/smart_contracts/writing_contracts/notes/index.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/index.md index 973156bb15e..b40f4be495e 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/notes/index.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/index.md @@ -1,6 +1,7 @@ --- title: Notes sidebar_position: 6 +tags: [contracts, notes] --- -Notes are the fundamental data structure in Aztec when working with private state. In this section there are guides about how to work with `AddressNote`, `ValueNote`, and custom notes in Aztec.nr. You can learn more about notes in the [concepts section](../../../../aztec/concepts/state_model/index.md). \ No newline at end of file +Notes are the fundamental data structure in Aztec when working with private state. In this section there are guides about how to work with `AddressNote`, `ValueNote`, and custom notes in Aztec.nr. You can learn more about notes in the [concepts section](../../../../../aztec/concepts/state_model/index.md#private-state). \ No newline at end of file diff --git a/docs/docs/guides/smart_contracts/writing_contracts/notes/value_note.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/value_note.md similarity index 92% rename from docs/docs/guides/smart_contracts/writing_contracts/notes/value_note.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/value_note.md index 47d4d1eb8c5..6cd82547c1a 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/notes/value_note.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/notes/value_note.md @@ -1,5 +1,6 @@ --- title: Using Value Notes in Aztec.nr +tags: [contracts, notes] --- ValueNotes hold one main property - a `value` - and have utils useful for manipulating this value, such as incrementing and decrementing it similarly to an integer. @@ -59,6 +60,6 @@ The `decrement` function works similarly except the `amount` is the number that ## Learn more -- [Keys, including nullifier keys and outgoing viewer](../../../../aztec/concepts/accounts/keys.md) +- [Keys, including nullifier keys and outgoing viewer](../../../../../aztec/concepts/accounts/keys.md) - [How to write a custom note](./custom_note.md) -- [ValueNote reference](https://docs.aztec.network/reference/smart_contract_reference/aztec-nr/value-note/value_note) \ No newline at end of file +- [ValueNote reference](../../../../../reference/developer_references/smart_contract_reference/aztec-nr/value-note/value_note.md) diff --git a/docs/docs/guides/smart_contracts/writing_contracts/portals/communicate_with_portal.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/portals/communicate_with_portal.md similarity index 92% rename from docs/docs/guides/smart_contracts/writing_contracts/portals/communicate_with_portal.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/portals/communicate_with_portal.md index 8a1594d05e2..8c497e3f41c 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/portals/communicate_with_portal.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/portals/communicate_with_portal.md @@ -1,10 +1,11 @@ --- title: Communicating with L1 +tags: [contracts, portals] --- -Is this your first time hearing the word `Portal`? Check out the [protocol spec](../../../../protocol-specs/l1-smart-contracts/index.md). +Is this your first time hearing the word `Portal`? You might want to check out the [protocol specs](../../../../../protocol-specs/l1-smart-contracts/index.md). -Follow the [token bridge tutorial](../../../../tutorials/contract_tutorials/advanced/token_bridge/index.md) for hands-on experience writing and deploying a Portal contract. +Follow the [token bridge tutorial](../../../../../tutorials/codealong/contract_tutorials/advanced/token_bridge/index.md) for hands-on experience writing and deploying a Portal contract. ## Passing data to the rollup @@ -18,7 +19,7 @@ When sending messages, we need to specify quite a bit of information beyond just | ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Recipient | `L2Actor` | The message recipient. This **MUST** match the rollup version and an Aztec contract that is **attached** to the contract making this call. If the recipient is not attached to the caller, the message cannot be consumed by it. | | Secret Hash | `field` (~254 bits) | A hash of a secret that is used when consuming the message on L2. Keep this preimage a secret to make the consumption private. To consume the message the caller must know the pre-image (the value that was hashed) - so make sure your app keeps track of the pre-images! Use `computeSecretHash` to compute it from a secret. | -| Content | `field` (~254 bits) | The content of the message. This is the data that will be passed to the recipient. The content is limited to be a single field. If the content is small enough it can just be passed along, otherwise it should be hashed and the hash passed along (you can use our [`Hash`](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/Hash.sol) utilities with `sha256ToField` functions) | +| Content | `field` (~254 bits) | The content of the message. This is the data that will be passed to the recipient. The content is limited to be a single field. If the content is small enough it can just be passed along, otherwise it should be hashed and the hash passed along (you can use our [`Hash` (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/Hash.sol) utilities with `sha256ToField` functions) | With all that information at hand, we can call the `sendL2Message` function on the Inbox. The function will return a `field` (inside `bytes32`) that is the hash of the message. This hash can be used as an identifier to spot when your message has been included in a rollup block. @@ -42,7 +43,7 @@ Note that while the `secret` and the `content` are both hashed, they are actuall ### Token bridge example -Computing the `content` must currently be done manually, as we are still adding a number of bytes utilities. A good example exists within the [Token bridge example](../../../../tutorials/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md#consume-the-l1-message). +Computing the `content` must currently be done manually, as we are still adding a number of bytes utilities. A good example exists within the [Token bridge example (codealong tutorial)](../../../../../tutorials/codealong/contract_tutorials/advanced/token_bridge/index.md). #include_code claim_public /noir-projects/noir-contracts/contracts/token_bridge_contract/src/main.nr rust @@ -182,5 +183,5 @@ Designated callers are enforced at the contract level for contracts that are not ## Examples of portals - Token bridge (Portal contract built for L1 -> L2, i.e., a non-native L2 asset) - - [Portal contract](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/test/portals/TokenPortal.sol) - - [Aztec contract](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/token_bridge_contract/src/main.nr) + - [Portal contract (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/test/portals/TokenPortal.sol) + - [Aztec contract (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-contracts/contracts/token_bridge_contract/src/main.nr) diff --git a/docs/docs/guides/smart_contracts/writing_contracts/portals/index.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/portals/index.md similarity index 100% rename from docs/docs/guides/smart_contracts/writing_contracts/portals/index.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/portals/index.md diff --git a/docs/docs/guides/smart_contracts/writing_contracts/storage/index.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/storage/index.md similarity index 73% rename from docs/docs/guides/smart_contracts/writing_contracts/storage/index.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/storage/index.md index c747ef508ef..022c0bbbe0d 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/storage/index.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/storage/index.md @@ -1,12 +1,13 @@ --- title: Declaring Storage +tags: [contracts, storage] --- On this page, you will learn how to define storage in your smart contract. -To learn more about how storage works in Aztec, read [the concepts](storage_slots.md). +To learn more about how storage works in Aztec, read [the concepts](./storage_slots.md). -[See the storage reference](../../../../aztec/concepts/storage/index.md). +[See the storage reference](../../../../../reference/developer_references/smart_contract_reference/storage/index.md). ```rust #[aztec(storage)] diff --git a/docs/docs/guides/smart_contracts/writing_contracts/storage/notes.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/storage/notes.md similarity index 71% rename from docs/docs/guides/smart_contracts/writing_contracts/storage/notes.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/storage/notes.md index 0a08f39705e..bea6aa7461b 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/storage/notes.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/storage/notes.md @@ -2,6 +2,7 @@ title: Writing Notes description: Core knowledge of Notes and how they work useful-for: dev +tags: [contracts, storage, notes] --- Most prominent blockchain networks don't have privacy at the protocol level. Aztec contracts can define public and private functions, that can read/write public and private state. @@ -21,11 +22,11 @@ This page will focus on how private variables are implemented with Notes and sto #### Side-note about execution Under the hood, the Aztec protocol handles some important details around public and private function calls. Calls between them are asynchronous due to different execution contexts (local execution vs. node execution). -A detailed explanation of the transaction lifecycle can be found [here](../../../../aztec/concepts/transactions.md#simple-example-of-the-private-transaction-lifecycle). +A detailed explanation of the transaction lifecycle can be found [here](../../../../../aztec/concepts/transactions.md#simple-example-of-the-private-transaction-lifecycle). ## Private state variables in Aztec -State variables in an Aztec contract are defined inside a struct specifically named `Storage`, and must satisfy the [Note Interface](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_interface.nr) and contain a [Note header](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_header.nr). +State variables in an Aztec contract are defined inside a struct specifically named `Storage`, and must satisfy the [Note Interface (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_interface.nr) and contain a [Note header (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_header.nr). The Note header struct contains the contract address which the value is effectively siloed to, a nonce to ensure unique Note hashes, and a storage "slot" (or ID) to associate multiple notes. @@ -33,7 +34,7 @@ A couple of things to unpack here: #### Storage "slot" -Storage slots are more literal for public storage, a place where a value is stored. For private storage, a storage slot is logical (more [here](../../../../aztec/concepts/storage/index.md#private-state-slots---slots-arent-real)). +Storage slots are more literal for public storage, a place where a value is stored. For private storage, a storage slot is logical (more [here](../../../../../aztec/concepts/storage/index.md#private-state-slots---slots-arent-real)). #### Silos @@ -52,7 +53,7 @@ A hash of a note is stored in the append-only note hash tree on the network so a #### Note Hash Tree -By virtue of being append only, notes are not edited. If two transactions amend a private value, multiple notes will be inserted into the tree (to the note hash tree and the [nullifier tree](../../../../protocol-specs/state/nullifier-tree.md)). The header will contain the same logical storage slot. +By virtue of being append only, notes are not edited. If two transactions amend a private value, multiple notes will be inserted into the tree to the note hash tree and the nullifier tree. The header will contain the same logical storage slot. ### Reading Notes @@ -82,9 +83,9 @@ To update a value, its previous note hash(es) are nullified. The new note value Some optional background resources on notes can be found here: -- [High level network architecture](../../../../aztec/core_components.md#high-level-network-architecture), specifically the Private Execution Environment -- [Transaction lifecycle (simple diagram)](../../../../aztec/concepts/transactions.md#simple-example-of-the-private-transaction-lifecycle) -- [Public and Private state](../../../../aztec/concepts/state_model/index.md) +- [High level network architecture](../../../../../aztec/overview.md), specifically the Private Execution Environment +- [Transaction lifecycle (simple diagram)](../../../../../aztec/concepts/transactions.md#simple-example-of-the-private-transaction-lifecycle) +- [Public and Private state](../../../../../aztec/concepts/state_model/index.md) Notes touch several core components of the protocol, but we will focus on a the essentials first. @@ -96,19 +97,19 @@ The way Aztec benefits from the Noir language is via three important components: - `noir contracts` - example Aztec contracts - `noir-protocol-circuits` - a crate containing essential circuits for the protocol (public circuits and private wrappers) -A lot of what we will look at will be in [aztec-nr/aztec/src/note](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note), specifically the lifecycle and note interface. +A lot of what we will look at will be in [aztec-nr/aztec/src/note (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note), specifically the lifecycle and note interface. Looking at the noir circuits in these components, you will see references to the distinction between public/private execution and state. ### Lifecycle functions -Inside the [lifecycle](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/lifecycle.nr) circuits we see the functions to create and destroy a note, implemented as insertions of note hashes and nullifiers respectively. This is helpful for regular private variables. +Inside the [lifecycle (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/lifecycle.nr) circuits we see the functions to create and destroy a note, implemented as insertions of note hashes and nullifiers respectively. This is helpful for regular private variables. We also see a function to create a note hash from the public context, a way of creating a private variable from a public call (run in the sequencer). This could be used in application contracts to give private digital assets to users. ### Note Interface functions -To see a [note_interface](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_interface.nr) implementation, we will look at a simple [ValueNote](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/value-note/src/value_note.nr). +To see a [note_interface (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_interface.nr) implementation, we will look at a simple [ValueNote GitHub link](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/value-note/src/value_note.nr). The interface is required to work within an Aztec contract's storage, and a ValueNote is a specific type of note to hold a number (as a `Field`). @@ -118,7 +119,7 @@ A few key functions in the note interface are around computing the note hash and In the ValueNote implementation you'll notice that it uses the `pedersen_hash` function. This is currently required by the protocol, but may be updated to another hashing function, like poseidon. -As a convenience, the outer [note/utils.nr](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/utils.nr) contains implementations of functions that may be needed in Aztec contracts, for example computing note hashes. +As a convenience, the outer [note/utils.nr (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/utils.nr) contains implementations of functions that may be needed in Aztec contracts, for example computing note hashes. #### Serialization and deserialization @@ -130,7 +131,7 @@ For example in ValueNote, the `serialize_content` function simply returns: the v ### Value as a sum of Notes We recall that multiple notes are associated with a "slot" (or ID), and so the value of a numerical note (like ValueNote) is the sum of each note's value. -The helper function in [balance_utils](https://github.com/AztecProtocol/aztec-packages/blob/#include_/noir-projects/aztec-nr/value-note/src/balance_utils.nr) implements this logic taking a `PrivateSet` of `ValueNotes`. +The helper function in [balance_utils (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_/noir-projects/aztec-nr/value-note/src/balance_utils.nr) implements this logic taking a `PrivateSet` of `ValueNotes`. A couple of things worth clarifying: @@ -139,7 +140,7 @@ A couple of things worth clarifying: ### Example - Notes in action -The Aztec.nr framework includes examples of high-level states [easy_private_uint](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/easy-private-state/src/easy_private_uint.nr) for use in contracts. +The Aztec.nr framework includes examples of high-level states [easy_private_uint (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/easy-private-state/src/easy_private_uint.nr) for use in contracts. The struct (`EasyPrivateUint`) contains a Context, Set of ValueNotes, and storage_slot (used when setting the Set). @@ -149,11 +150,11 @@ Notice how the `add` function shows the simplicity of appending a new note to al ### Apply -Try the [Token tutorial](../../../../tutorials/contract_tutorials/token_contract.md) to see what notes can achieve. In this section you will also find other tutorials using notes in different ways. +Try the [Token tutorial](../../../../../tutorials/codealong/contract_tutorials/token_contract.md) to see what notes can achieve. In this section you will also find other tutorials using notes in different ways. ### Further reading -- [Storage Trees](../../../../aztec/concepts/storage/trees/index.md) +- [Storage Trees](../../../../../aztec/concepts/storage/trees/index.md) - [Proof of prior notes](../how_to_prove_history.md) - public/private reading of public/private proof of state (public or private) If you're curious about any of the following related topics, search the documentation for... @@ -165,5 +166,5 @@ If you're curious about any of the following related topics, search the document ### References -- ["Stable" state variable](https://github.com/AztecProtocol/aztec-packages/issues/4130) -- [Code: Aztec-Patterns](https://github.com/defi-wonderland/aztec-patterns) +- ["Stable" state variable (GitHub link)](https://github.com/AztecProtocol/aztec-packages/issues/4130) +- [Code: Aztec-Patterns (GitHub link)](https://github.com/defi-wonderland/aztec-patterns) diff --git a/docs/docs/guides/smart_contracts/writing_contracts/storage/storage_slots.md b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/storage/storage_slots.md similarity index 87% rename from docs/docs/guides/smart_contracts/writing_contracts/storage/storage_slots.md rename to docs/docs/guides/developer_guides/smart_contracts/writing_contracts/storage/storage_slots.md index f8ae4561bf2..ba3c45fe4c6 100644 --- a/docs/docs/guides/smart_contracts/writing_contracts/storage/storage_slots.md +++ b/docs/docs/guides/developer_guides/smart_contracts/writing_contracts/storage/storage_slots.md @@ -1,8 +1,9 @@ --- title: Storage slots +tags: [contracts, storage] --- -From the description of storage slots [in the Concepts](storage_slots.md) you will get an idea around the logic of storage slots. In this section we will go into more detail and walk through an entire example of how storage slots are computed for private state to improve our storage slot intuition. Recall, that storage slots in the private domain is just a logical construct, and are not "actually" used for lookups, but rather just as a value to constrain against. +From the description of storage slots [in the Concepts](../../../../../aztec/concepts/storage/index.md#private-state-slots---slots-arent-real) you will get an idea around the logic of storage slots. In this section we will go into more detail and walk through an entire example of how storage slots are computed for private state to improve our storage slot intuition. Recall, that storage slots in the private domain is just a logical construct, and are not "actually" used for lookups, but rather just as a value to constrain against. For the case of the example, we will look at what is inserted into the note hashes tree when adding a note in the Token contract. Specifically, we are looking at the last part of the `transfer` function: diff --git a/docs/docs/guides/index.md b/docs/docs/guides/index.md new file mode 100644 index 00000000000..cf5cd9c93b6 --- /dev/null +++ b/docs/docs/guides/index.md @@ -0,0 +1,118 @@ +--- +id: index +sidebar_position: 0 +title: Guides +--- + +# Popular Guides + +Guides are step-by-step how-tos to achieve a specific goal. On this page you can find the most popular ones. You can also explore them all by checking out the sidebar. + +## Getting Started + +
+ + +

Quickstart

+ + + Get started on Aztec by installing the sandbox and playing with it + + +
+ +## Building smart contracts + +
+ + +

Compile a contract

+ + + Learn how to compile a smart contract and generate TypeScript bindings + + + + + +

Deploy a contract

+ + + Deploy a contract to a local Aztec sandbox + + + + + +

Testing Contracts

+ + + Write tests for your contracts and run them in the TXE + + + + + +

Communicate with L1

+ + + How to use portals to communicate with L1 from your contract + + +
+ +
+ View all smart contract guides +
+ +## JavaScript + +
+ + +

Send a transaction

+ + + Use Aztec.JS to send a transaction by calling a function on a smart contract + + + + + +

Testing

+ + + Write end-to-end tests in Javascript using Aztec.JS + + +
+ +
+ View all JavaScript guides +
+ +## Local environment + +
+ + +

Update your environment

+ + + Update all aspects of your Aztec environment, including the sandbox, aztec-nargo, Aztec.nr packages, and Aztec.js packages + + + + + +

Run more than one PXE

+ + + Test that your contracts can work with multiple interactions by running a second PXE + + +
+ +
+ View all local environment guides +
\ No newline at end of file diff --git a/docs/docs/reference/privacy_considerations.md b/docs/docs/guides/privacy_considerations.md similarity index 94% rename from docs/docs/reference/privacy_considerations.md rename to docs/docs/guides/privacy_considerations.md index d8b053ac169..059d230bd7f 100644 --- a/docs/docs/reference/privacy_considerations.md +++ b/docs/docs/guides/privacy_considerations.md @@ -1,6 +1,7 @@ --- title: Privacy Considerations sidebar_position: 5 +tags: [protocol, PXE] --- Privacy is important. @@ -52,7 +53,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 if not following recommended patterns. See [here](smart_contract_reference/portals/inbox.md) 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. ### Timing of transactions @@ -90,7 +91,7 @@ A 'Function Fingerprint' is any data which is exposed by a function to the outsi > Note: many of these were mentioned in the ["Crossing the private -> public boundary"](#crossing-the-private---public-boundary) section. -> Note: the transaction effects submitted to L1 is [encoded](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/Decoder.sol) but not garbled with other transactions: the distinct Tx Fingerprint of each tx can is publicly visible when a tx is submitted to the L2 tx pool. +> Note: the transaction effects submitted to L1 is [encoded (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/Decoder.sol) but not garbled with other transactions: the distinct Tx Fingerprint of each tx can is publicly visible when a tx is submitted to the L2 tx pool. #### Standardizing Fingerprints @@ -136,4 +137,4 @@ We're researching cryptographic ways to enable users to query any data privately Footnotes -[^1]: All txs should set the kernel circuit public inputs for all roots to _valid_, _up-to-date_ nonzero values, so as to mask which trees have _actually_ been read from. The Sandbox will eventually automate this (see this [issue](https://github.com/AztecProtocol/aztec-packages/issues/1676)). +[^1]: All txs should set the kernel circuit public inputs for all roots to _valid_, _up-to-date_ nonzero values, so as to mask which trees have _actually_ been read from. The Sandbox will eventually automate this (see this [issue (GitHub link)](https://github.com/AztecProtocol/aztec-packages/issues/1676)). diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx index df74423358a..b7a9e01a97b 100644 --- a/docs/docs/index.mdx +++ b/docs/docs/index.mdx @@ -5,9 +5,9 @@ displayed_sidebar: sidebar sidebar_position: 0 --- -# The World's Encrypted Ledger +# Aztec Documentation -## A Privacy-First L2 on Ethereum +## Aztec is a Privacy-First L2 on Ethereum On Ethereum today, everything is publicly visible, by everyone. In the real world, people enjoy privacy. Aztec brings privacy to Ethereum. @@ -36,11 +36,11 @@ Aztec is: ### Learn 📚 -Start on the [Technical Overview page](aztec/core_components.md) to read about how Aztec works. +Start on the [Technical Overview page](aztec/overview.md) to read about how Aztec works. ### Build 🧑‍💻 -Go to the [Getting Started section](getting_started.md) of the developer docs to get your hands dirty and start developing on Aztec. +Go to the [Getting Started section](guides/developer_guides/getting_started/quickstart.md) of the developer docs to get your hands dirty and start developing on Aztec. #### Go deeper 🔬 @@ -48,4 +48,4 @@ Check out the [Awesome Aztec repo](https://github.com/AztecProtocol/awesome-azte Clone the [Aztec Starter repo](https://github.com/AztecProtocol/aztec-starter) to get a minimal project set up with Sandbox (local developer network), a simple contract and a test suite. -Jump into one of the [tutorials](tutorials/contract_tutorials/private_voting_contract.md) to learn how to build more complex applications on Aztec. +Jump into one of the [tutorials](tutorials/index.md) to learn how to build more complex applications on Aztec. diff --git a/docs/docs/reference/common_errors/_category_.json b/docs/docs/reference/developer_references/common_errors/_category_.json similarity index 100% rename from docs/docs/reference/common_errors/_category_.json rename to docs/docs/reference/developer_references/common_errors/_category_.json diff --git a/docs/docs/reference/common_errors/aztecnr-errors.md b/docs/docs/reference/developer_references/common_errors/aztecnr-errors.md similarity index 87% rename from docs/docs/reference/common_errors/aztecnr-errors.md rename to docs/docs/reference/developer_references/common_errors/aztecnr-errors.md index 093e0c0ffd7..e76d9206355 100644 --- a/docs/docs/reference/common_errors/aztecnr-errors.md +++ b/docs/docs/reference/developer_references/common_errors/aztecnr-errors.md @@ -1,8 +1,9 @@ --- title: Aztec.nr Errors +tags: [contracts] --- -This section contains some errors that you may encounter when writing and compiling contracts in Aztec.nr. If you run into an error that is not listed here, please [create an issue](https://github.com/AztecProtocol/aztec-packages/issues/new). +This section contains some errors that you may encounter when writing and compiling contracts in Aztec.nr. If you run into an error that is not listed here, please [create an issue (GitHub link)](https://github.com/AztecProtocol/aztec-packages/issues/new). #### `Aztec dependency not found. Please add aztec as a dependency in your Nargo.toml` @@ -16,7 +17,7 @@ You can learn more about dependencies and their paths [here](../smart_contract_r #### `backend has encountered an error` -This is likely due to a version mismatch or bad install of barretenberg. Try [reinstalling nargo](guides/local_env/versions-updating.md#updating) or uninstalling barretenberg: +This is likely due to a version mismatch or bad install of barretenberg. Try [reinstalling nargo](../../../guides/developer_guides/local_env/versions-updating.md#updating-aztec-nargo) or uninstalling barretenberg: ```bash nargo backend uninstall acvm-backend-barretenberg @@ -26,7 +27,7 @@ It will then reinstall when you compile. #### `Oracle callback {} not found` & `Oracle callback pedersenHash not found` -This can occasionally happen when there are breaking releases. Make sure that your dependencies in `Nargo.toml` are [updated to the latest release](../smart_contract_reference/dependencies.md). +This can occasionally happen when there are breaking releases. Make sure that your dependencies in `Nargo.toml` are [updated to the latest release](../../../guides/developer_guides/local_env/versions-updating.md#dependency-versions). #### `error: Failed constraint: 'Public state writes only supported in public functions` @@ -47,7 +48,7 @@ This error occurs when you are trying to interact with a smart contract via an P To execute a transaction, the PXE needs to know the complete address of a contract and contract artifacts. -To address the error, add the contract to the PXE by calling [`pxe.addContracts(...)`](../../aztec/concepts/pxe/index.md#addcontracts). +To address the error, add the contract to the PXE by calling [`pxe.addContracts(...)`](../../../aztec/concepts/pxe/index.md). #### `Simulation error: No public key registered for address 0x0. Register it by calling pxe.registerRecipient(...) or pxe.registerAccount(...)` @@ -71,4 +72,4 @@ To address the error, register the account by calling `server.registerAccount(.. You may encounter this error when trying to send a transaction that is using an invalid contract. The contract may compile without errors and you only encounter this when sending the transaction. -This error may arise when function parameters are not properly formatted, when trying to "double-spend" a note, or it may indicate that there is a bug deeper in the stack (e.g. a bug in the Aztec.nr library or deeper). If you hit this error, double check your contract implementation, but also consider [opening an issue](https://github.com/AztecProtocol/aztec-packages/issues/new). +This error may arise when function parameters are not properly formatted, when trying to "double-spend" a note, or it may indicate that there is a bug deeper in the stack (e.g. a bug in the Aztec.nr library or deeper). If you hit this error, double check your contract implementation, but also consider [opening an issue (GitHub link)](https://github.com/AztecProtocol/aztec-packages/issues/new). diff --git a/docs/docs/reference/common_errors/sandbox-errors.md b/docs/docs/reference/developer_references/common_errors/sandbox-errors.md similarity index 81% rename from docs/docs/reference/common_errors/sandbox-errors.md rename to docs/docs/reference/developer_references/common_errors/sandbox-errors.md index 16f9930de57..2e9aed08ee5 100644 --- a/docs/docs/reference/common_errors/sandbox-errors.md +++ b/docs/docs/reference/developer_references/common_errors/sandbox-errors.md @@ -1,5 +1,6 @@ --- title: Aztec Sandbox Errors +tags: [sandbox] --- import Disclaimer from '@site/src/components/Disclaimers/\_wip_disclaimer.mdx'; @@ -14,7 +15,7 @@ This section contains a list of errors you may encounter when using Aztec Sandbo ### Kernel Circuits -We have several versions of public and private kernels as explained in [our circuits section](../../aztec/concepts/circuits/index.md). Certain things are only possible in certain versions of the circuits. So always ensure that the right version is being used for proof generation. For example, there is a specific version of the public kernel that only works if the previous kernel iteration was a private kernel. Similarly there is one that only works if the previous kernel was public. +We have several versions of public and private kernels as explained in [the circuits section in the concepts](../../../aztec/concepts/circuits/index.md). Certain things are only possible in certain versions of the circuits. So always ensure that the right version is being used for proof generation. For example, there is a specific version of the public kernel that only works if the previous kernel iteration was a private kernel. Similarly there is one that only works if the previous kernel was public. Remember that for each function call (i.e. each item in the call stack), there is a new kernel iteration that gets run. @@ -37,7 +38,7 @@ You cannot execute a public Aztec.nr function in the private kernel #### 2011 - PRIVATE_KERNEL\_\_UNSUPPORTED_OP -You are trying to do something that is currently unsupported in the private kernel. If this is a blocker feel free to open up an issue on our monorepo [aztec3-packages](https://github.com/AztecProtocol/aztec3-packages/tree/master) or reach out to us on discord +You are trying to do something that is currently unsupported in the private kernel. If this is a blocker feel free to open up an issue on our monorepo [aztec-packages (GitHub link)](https://github.com/AztecProtocol/aztec3-packages/tree/master) or reach out to us on discord Note that certain operations are unsupported on certain versions of the private kernel. Eg static calls are allowed for all but the initial iteration of the private kernel (which initializes the kernel for subsequent function calls). @@ -79,7 +80,7 @@ But for non transient reads, we do a merkle membership check. Reads are done at #### 3001 - PUBLIC_KERNEL\_\_UNSUPPORTED_OP -You are trying to do something that is currently unsupported in the public kernel. If this is a blocker feel free to open up an issue on our monorepo [aztec3-packages](https://github.com/AztecProtocol/aztec3-packages/tree/master) or reach out to us on discord +You are trying to do something that is currently unsupported in the public kernel. If this is a blocker feel free to open up an issue on our monorepo [aztec-packages (GitHub link)](https://github.com/AztecProtocol/aztec3-packages/tree/master) or reach out to us on discord #### 3002 - PUBLIC_KERNEL\_\_PRIVATE_FUNCTION_NOT_ALLOWED @@ -87,7 +88,7 @@ Calling a private Aztec.nr function in a public kernel is not allowed. #### 3005 - PUBLIC_KERNEL\_\_NON_EMPTY_PRIVATE_CALL_STACK -Public functions are executed after all the private functions are (see [private-public execution](../../aztec/concepts/smart_contracts/communication/public_private_calls.md)). As such, private call stack must be empty when executing in the public kernel. +Public functions are executed after all the private functions are (see [private-public execution](../../../aztec/smart_contracts/communication/public_private_calls.md)). As such, private call stack must be empty when executing in the public kernel. #### 3011 - PUBLIC_KERNEL\_\_CALCULATED_PRIVATE_CALL_HASH_AND_PROVIDED_PRIVATE_CALL_HASH_MISMATCH @@ -131,17 +132,17 @@ For static calls, no new note hashes or nullifiers can be added to the state. ### Rollup circuit errors -These are errors that occur when kernel proofs (transaction proofs) are sent to the rollup circuits to create an L2 block. See [rollup circuits](../../aztec/concepts/circuits/index.md) for more information. +These are errors that occur when kernel proofs (transaction proofs) are sent to the rollup circuits to create an L2 block. See [rollup circuits](../../../aztec/concepts/circuits/rollup_circuits/index.md) for more information. #### 4007 - BASE\_\_INVALID_CHAIN_ID -The L1 chain ID you used in your proof generation (for your private transaction) is different to what the rollup circuits expected. Double check against the global variables passed to noir and the config set in [Aztec's rollup contract](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/Rollup.sol) which are [read in by sequencer](https://github.com/AztecProtocol/aztec3-packages/blob/master/yarn-project/sequencer-client/src/global_variable_builder/global_builder.ts#L32) and subsequently passed in as inputs to the base rollup. When the sequencer submits the block to the rollup contracts, this is again sanity checked so ensure this is the same everywhere. +The L1 chain ID you used in your proof generation (for your private transaction) is different to what the rollup circuits expected. Double check against the global variables passed to noir and the config set in [Aztec's rollup contract (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/Rollup.sol) which are [read in by sequencer GitHub link](https://github.com/AztecProtocol/aztec3-packages/blob/master/yarn-project/sequencer-client/src/global_variable_builder/global_builder.ts#L32) and subsequently passed in as inputs to the base rollup. When the sequencer submits the block to the rollup contracts, this is again sanity checked so ensure this is the same everywhere. #### 4008 - BASE\_\_INVALID_VERSION Same as [section 4007](#4007---base__invalid_chain_id) except the `version` refers to the version of the Aztec L2 instance. -Some scary bugs like `4003 - BASE__INVALID_NULLIFIER_SUBTREE` and `4004 - BASE__INVALID_NULLIFIER_RANGE` which are to do malformed nullifier trees (see [Indexed Merkle Trees](../../aztec/concepts/storage/trees/indexed_merkle_tree.mdx)) etc may seem unrelated at a glance, but at a closer look may be because of some bug in an application's Aztec.nr code. Same is true for certain instances of `7008 - MEMBERSHIP_CHECK_FAILED`. +Some scary bugs like `4003 - BASE__INVALID_NULLIFIER_SUBTREE` and `4004 - BASE__INVALID_NULLIFIER_RANGE` which are to do malformed nullifier trees (see [Indexed Merkle Trees](../../../aztec/concepts/storage/trees/indexed_merkle_tree.mdx)) etc may seem unrelated at a glance, but at a closer look may be because of some bug in an application's Aztec.nr code. Same is true for certain instances of `7008 - MEMBERSHIP_CHECK_FAILED`. ### Generic circuit errors @@ -161,7 +162,7 @@ Circuits work by having a fixed size array. As such, we have limits on how many - too many transient read requests in one tx - too many transient read request membership witnesses in one tx -You can have a look at our current constants/limitations in [constants.nr](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-protocol-circuits/crates/types/src/constants.nr) +You can have a look at our current constants/limitations in [constants.nr (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/noir-protocol-circuits/crates/types/src/constants.nr) #### 7008 - MEMBERSHIP_CHECK_FAILED @@ -172,7 +173,7 @@ Users may create a proof against a historical state in Aztec. The rollup circuit - using invalid historical L1 to L2 message data tree state - inserting a subtree into the greater tree - we make a smaller merkle tree of all the new note hashes/nullifiers etc that were created in a transaction or in a rollup and add it to the bigger state tree. Before inserting, we do a merkle membership check to ensure that the index to insert at is indeed an empty subtree (otherwise we would be overwriting state). This can happen when `next_available_leaf_index` in the state tree's snapshot is wrong (it is fetched by the sequencer from the archiver). The error message should reveal which tree is causing this issue - - nullifier tree related errors - The nullifier tree uses an [Indexed Merkle Tree](../../aztec/concepts/storage/trees/indexed_merkle_tree.mdx). It requires additional data from the archiver to know which is the nullifier in the tree that is just below the current nullifier before it can perform batch insertion. If the low nullifier is wrong, or the nullifier is in incorrect range, you may receive this error. + - nullifier tree related errors - The nullifier tree uses an [Indexed Merkle Tree](../../../aztec/concepts/storage/trees/indexed_merkle_tree.mdx). It requires additional data from the archiver to know which is the nullifier in the tree that is just below the current nullifier before it can perform batch insertion. If the low nullifier is wrong, or the nullifier is in incorrect range, you may receive this error. --- @@ -190,7 +191,7 @@ Users may create a proof against a historical state in Aztec. The rollup circuit - "\$\{treeName\} tree next available leaf index mismatch" - validating a tree's root is not enough. It also checks that the `next_available_leaf_index` is as expected. This is the next index we can insert new values into. Note that for the public data tree, this test is skipped since as it is a sparse tree unlike the others. -- "Public call stack size exceeded" - In Aztec, the sequencer executes all enqueued public functions in a transaction (to prevent race conditions - see [private-public execution](../../aztec/concepts/smart_contracts/communication/public_private_calls.md)). This error says there are too many public functions requested. +- "Public call stack size exceeded" - In Aztec, the sequencer executes all enqueued public functions in a transaction (to prevent race conditions - see [private-public execution](../../../aztec/smart_contracts/communication/public_private_calls.md)). This error says there are too many public functions requested. - "Array size exceeds target length" - happens if you add more items than allowed by the constants set due to our circuit limitations (eg sending too many L2 to L1 messages or creating a function that exceeds the call stack length or returns more values than what Aztec.nr functions allow) @@ -198,4 +199,4 @@ Users may create a proof against a historical state in Aztec. The rollup circuit ## L1 Aztec Contract Errors -Aztec's L1 contracts use custom errors in solidity. While it saves gas, it has a side effect of making it harder to decode when things go wrong. If you get an error when submitting an L2Block into our rollup contract or when interacting with our Inbox/Outbox contracts, you can use the [Errors.sol library](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/Errors.sol) to match the hex encoded error to the error name. +Aztec's L1 contracts use custom errors in solidity. While it saves gas, it has a side effect of making it harder to decode when things go wrong. If you get an error when submitting an L2Block into our rollup contract or when interacting with our Inbox/Outbox contracts, you can use the [Errors.sol library (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/Errors.sol) to match the hex encoded error to the error name. diff --git a/docs/docs/reference/debugging.md b/docs/docs/reference/developer_references/debugging.md similarity index 87% rename from docs/docs/reference/debugging.md rename to docs/docs/reference/developer_references/debugging.md index e3d23b37404..12fab8f69ba 100644 --- a/docs/docs/reference/debugging.md +++ b/docs/docs/reference/developer_references/debugging.md @@ -11,7 +11,7 @@ You can log statements from Aztec.nr contracts that will show ups in the Sandbox ### Import `debug_log` -Import the [`debug_log`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/debug_log.nr) dependency from Aztec oracles: +Import the [`debug_log` (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/debug_log.nr) dependency from Aztec oracles: ```rust use dep::aztec::oracle::debug_log::{ debug_log }; diff --git a/docs/docs/aztec/limitations.md b/docs/docs/reference/developer_references/limitations.md similarity index 88% rename from docs/docs/aztec/limitations.md rename to docs/docs/reference/developer_references/limitations.md index f38e7084c15..cb13ddf4779 100644 --- a/docs/docs/aztec/limitations.md +++ b/docs/docs/reference/developer_references/limitations.md @@ -1,6 +1,7 @@ --- title: Limitations sidebar_position: 6 +tags: [sandbox] --- The Aztec Sandbox and the Aztec Smart Contract Library are **prototypes**, and should be treated as such. They've been released early, to gather feedback on the capabilities of the protocol and user experiences. @@ -30,11 +31,11 @@ Help shape and define: - 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 [initializer functions](../guides/smart_contracts/writing_contracts/initializers.md). + - 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. - 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](concepts/smart_contracts/functions/context). -- The initial `msg_sender` is 0, which can be problematic for some contracts, see [function visibility](concepts/smart_contracts/functions/visibility.md). + - 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. +- The initial `msg_sender` is 0, which can be problematic for some contracts. - 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 note hashes, nullifiers and calls that are supported by a transaction, see [circuit limitations](#circuit-limitations). @@ -53,7 +54,7 @@ That's right, the Sandbox doesn't actually generate or verify any zk-SNARKs yet! The main goal of the Sandbox is to enable developers to experiment with building apps, and hopefully to provide feedback. We want the developer experience to be as fast as possible, much like how Ethereum developers use Ganache or Anvil to get super-fast block times, instead of the slow-but-realistic 12-second block times that they'll encounter in production. A fast Sandbox enables fast testing, which enables developers to iterate quickly. -That's not to say a super-fast proving system isn't being worked on [as we speak](roadmap/cryptography_roadmap.md). +That's not to say a super-fast proving system isn't being worked on [as we speak](../../aztec/roadmap/cryptography_roadmap.md). #### What are the consequences? @@ -172,11 +173,11 @@ This will be patched in the near future, but unfortunately, app developers might ### New Privacy Standards are required -There are many [patterns](../reference/privacy_considerations.md) which can leak privacy, even on Aztec. Standards haven't been developed yet, to encourage best practices when designing private smart contracts. +There are many [patterns](../../guides/privacy_considerations.md) which can leak privacy, even on Aztec. Standards haven't been developed yet, to encourage best practices when designing private smart contracts. #### What are the consequences? -For example, until community standards are developed to reduce the uniqueness of ['Tx Fingerprints'](../reference/privacy_considerations.md#function-fingerprints-and-tx-fingerprints) app developers might accidentally forfeit some function privacy. +For example, until community standards are developed to reduce the uniqueness of ['Tx Fingerprints'](../../guides/privacy_considerations.md#function-fingerprints-and-tx-fingerprints) app developers might accidentally forfeit some function privacy. ## Circuit limitations @@ -192,7 +193,7 @@ Here are the current constants: #### What are the consequences? -When you write an Aztec.nr [function](concepts/smart_contracts/functions), there will be upper bounds on the following: +When you write an Aztec.nr function, there will be upper bounds on the following: - The number of public state reads and writes; - The number of note reads and nullifications; @@ -208,13 +209,13 @@ Not only are there limits on a _per function_ basis, there are also limits on a **In particular, these _per-transaction_ limits will limit transaction call stack depths** in the Sandbox. That means if a function call results in a cascade of nested function calls, and each of those function calls outputs lots of state reads and writes, or logs (etc.), then all of that accumulated output data might exceed the per-transaction limits that we currently have. This would cause such transactions to fail. -There are plans to relax all of this rigidity, by providing many 'sizes' of [kernel circuit](concepts/circuits), and introducing a 'bus' to ferry varying lengths of data between kernel iterations. But that'll all take some time. +There are plans to relax all of this rigidity, by providing many 'sizes' of kernel circuit, and introducing a 'bus' to ferry varying lengths of data between kernel iterations. But that'll all take some time. > **In the mean time**, if you encounter a per-transaction limit when testing, and you're feeling adventurous, you could 'hack' the Sandbox to increase the limits. See here (TODO: link) for a guide. **However**, the limits cannot be increased indefinitely. So although we do anticipate that we'll be able to increase them a little bit, don't go mad and provide yourself with 1 million state transitions per transaction. That would be as unrealistic as artificially increasing Ethereum gas limits to 1 trillion. ### Circuits Processing Order Differs from Execution Order -Each function call is represented by a circuit with a dedicated zero-knowledge proof of its execution. The [private kernel circuit](concepts/circuits/kernels/private_kernel.md) is in charge of stitching all these proofs together to produce a zero-knowledge proof that the whole execution of all function calls within a transaction is correct. In doing so, the processing order differs from the execution order. Firstly, the private kernel has to handle one function call in its entirety at a time because a zk proof cannot be verified partially. This property alone makes it impossible for the ordering of kernel circuit validation to match the order in which the functions of the transaction were executed. Secondly, the private kernel processes function calls in a stack-based order, i.e., after having processed a function call, it processes all direct child function calls in an order which is the reverse of the execution order. +Each function call is represented by a circuit with a dedicated zero-knowledge proof of its execution. The private kernel circuit is in charge of stitching all these proofs together to produce a zero-knowledge proof that the whole execution of all function calls within a transaction is correct. In doing so, the processing order differs from the execution order. Firstly, the private kernel has to handle one function call in its entirety at a time because a zk proof cannot be verified partially. This property alone makes it impossible for the ordering of kernel circuit validation to match the order in which the functions of the transaction were executed. Secondly, the private kernel processes function calls in a stack-based order, i.e., after having processed a function call, it processes all direct child function calls in an order which is the reverse of the execution order. Note that there is no plan to change this in the future. @@ -242,10 +243,10 @@ Transaction output elements such as notes in encrypted logs, note hashes (commit ### Chopped Transient Notes are still Emitted in Logs -A note which is created and nullified during the very same transaction is called transient. Such a note is chopped by the [private kernel circuit](concepts/circuits/kernels/private_kernel.md) and is never stored in any persistent data tree. +A note which is created and nullified during the very same transaction is called transient. Such a note is chopped by the private kernel circuit and is never stored in any persistent data tree. -For the time being, such chopped notes are still emitted through encrypted logs (which is the communication channel to transmit notes). When a log containing a chopped note is processed, a warning will be logged about a decrypted note which does not exist in data tree. We [improved](https://github.com/AztecProtocol/aztec-packages/issues/1603) error logging to help identify such an occurrence. However, this might be a source of confusion. -This issue is tracked in ticket [#1641](https://github.com/AztecProtocol/aztec-packages/issues/1641). +For the time being, such chopped notes are still emitted through encrypted logs (which is the communication channel to transmit notes). When a log containing a chopped note is processed, a warning will be logged about a decrypted note which does not exist in data tree. We [improved (GitHub link)](https://github.com/AztecProtocol/aztec-packages/issues/1603) error logging to help identify such an occurrence. However, this might be a source of confusion. +This issue is tracked in ticket [#1641 (GitHub link)](https://github.com/AztecProtocol/aztec-packages/issues/1641). ### Note Terminology: Note Commitments and Note Hashes @@ -253,4 +254,4 @@ The notes or UTXOs in Aztec need to be compressed before they are added to the t ## There's more -See the [GitHub issues](https://github.com/AztecProtocol/aztec-packages/issues) for all known bugs fixes and features currently being worked on. +See the [GitHub issues (GitHub link)](https://github.com/AztecProtocol/aztec-packages/issues) for all known bugs fixes and features currently being worked on. diff --git a/docs/docs/reference/sandbox_reference/cheat_codes.md b/docs/docs/reference/developer_references/sandbox_reference/cheat_codes.md similarity index 98% rename from docs/docs/reference/sandbox_reference/cheat_codes.md rename to docs/docs/reference/developer_references/sandbox_reference/cheat_codes.md index 00c408bda8d..ccf52eddb82 100644 --- a/docs/docs/reference/sandbox_reference/cheat_codes.md +++ b/docs/docs/reference/developer_references/sandbox_reference/cheat_codes.md @@ -1,5 +1,6 @@ --- title: Cheat Codes +tags: [sandbox] --- import Disclaimer from "@site/src/components/Disclaimers/\_wip_disclaimer.mdx"; @@ -10,7 +11,7 @@ To help with testing, the sandbox is shipped with a set of cheatcodes. Cheatcodes allow you to change the time of the Aztec block, load certain state or more easily manipulate Ethereum instead of having to write dedicated RPC calls to anvil or hardhat. :::info Prerequisites -If you aren't familiar with [Anvil](https://book.getfoundry.sh/anvil/), we recommend reading up on that since Aztec Sandbox uses Anvil as the local Ethereum instance. +If you aren't familiar with [Anvil (Foundry)](https://book.getfoundry.sh/anvil/), we recommend reading up on that since Aztec Sandbox uses Anvil as the local Ethereum instance. ::: ### Aims diff --git a/docs/docs/reference/sandbox_reference/cli_reference.md b/docs/docs/reference/developer_references/sandbox_reference/cli_reference.md similarity index 99% rename from docs/docs/reference/sandbox_reference/cli_reference.md rename to docs/docs/reference/developer_references/sandbox_reference/cli_reference.md index 1747303700b..dd5200742bc 100644 --- a/docs/docs/reference/sandbox_reference/cli_reference.md +++ b/docs/docs/reference/developer_references/sandbox_reference/cli_reference.md @@ -1,5 +1,6 @@ --- title: CLI Reference +tags: [sandbox] --- :::warning diff --git a/docs/docs/reference/sandbox_reference/index.md b/docs/docs/reference/developer_references/sandbox_reference/index.md similarity index 85% rename from docs/docs/reference/sandbox_reference/index.md rename to docs/docs/reference/developer_references/sandbox_reference/index.md index 8511fb8bc58..b67c867d7b5 100644 --- a/docs/docs/reference/sandbox_reference/index.md +++ b/docs/docs/reference/developer_references/sandbox_reference/index.md @@ -1,5 +1,6 @@ --- title: Sandbox Reference +tags: [sandbox] sidebar_position: 0 --- @@ -15,4 +16,4 @@ The current sandbox does not generate or verify proofs, but provides a working e ## Command line tools -Aztec-nargo and aztec CLI are command-line tool allowing you to compile smart contracts. See the [compiling contracts](../../guides/smart_contracts/how_to_compile_contract.md) page for more information. \ No newline at end of file +Aztec-nargo and aztec CLI are command-line tool allowing you to compile smart contracts. See the [compiling contracts guide](../../../guides/developer_guides/smart_contracts/how_to_compile_contract.md) for more information. diff --git a/docs/docs/reference/sandbox_reference/sandbox-reference.md b/docs/docs/reference/developer_references/sandbox_reference/sandbox-reference.md similarity index 95% rename from docs/docs/reference/sandbox_reference/sandbox-reference.md rename to docs/docs/reference/developer_references/sandbox_reference/sandbox-reference.md index 0820b19833c..999bd18c7c4 100644 --- a/docs/docs/reference/sandbox_reference/sandbox-reference.md +++ b/docs/docs/reference/developer_references/sandbox_reference/sandbox-reference.md @@ -1,10 +1,11 @@ --- title: Sandbox Reference +tags: [sandbox] --- :::tip -For a quick start, follow the [guide](../../getting_started.md) to install the sandbox. +For a quick start, follow the [guide](../../../guides/developer_guides/getting_started/quickstart.md) to install the sandbox. ::: @@ -106,7 +107,7 @@ To help with testing, the sandbox is shipped with a set of cheatcodes. Cheatcodes allow you to change the time of the Aztec block, load certain state or more easily manipulate Ethereum instead of having to write dedicated RPC calls to anvil or hardhat. -You can find the cheat code reference [here](cheat_codes.md). +You can find the cheat code reference [here](./cheat_codes.md). ## Contracts @@ -154,4 +155,4 @@ UniswapContractArtifact > Source code: /yarn-project/end-to-end/src/composed/cli_docs_sandbox.test.ts#L95-L118 -You can see all of our example contracts in the monorepo [here](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/noir-contracts/contracts). +You can see all of our example contracts in the monorepo [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/noir-contracts/contracts). diff --git a/docs/docs/reference/smart_contract_reference/_category_.json b/docs/docs/reference/developer_references/smart_contract_reference/_category_.json similarity index 100% rename from docs/docs/reference/smart_contract_reference/_category_.json rename to docs/docs/reference/developer_references/smart_contract_reference/_category_.json diff --git a/docs/docs/reference/smart_contract_reference/contract_artifact.md b/docs/docs/reference/developer_references/smart_contract_reference/contract_artifact.md similarity index 99% rename from docs/docs/reference/smart_contract_reference/contract_artifact.md rename to docs/docs/reference/developer_references/smart_contract_reference/contract_artifact.md index 8c47f55d714..9c9fbbce73c 100644 --- a/docs/docs/reference/smart_contract_reference/contract_artifact.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/contract_artifact.md @@ -1,5 +1,6 @@ --- title: "Contract Artifact Reference" +tags: [contracts] --- After compiling a contract you'll get a Contract Artifact file, that contains the data needed to interact with a specific contract, including its name, functions that can be executed, and the interface and code of those functions. Since private functions are not published in the Aztec network, you'll need this artifact file to be able to call private functions of contracts. diff --git a/docs/docs/reference/smart_contract_reference/dependencies.md b/docs/docs/reference/developer_references/smart_contract_reference/dependencies.md similarity index 82% rename from docs/docs/reference/smart_contract_reference/dependencies.md rename to docs/docs/reference/developer_references/smart_contract_reference/dependencies.md index 95232193a9f..d2d7842ca61 100644 --- a/docs/docs/reference/smart_contract_reference/dependencies.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/dependencies.md @@ -1,5 +1,6 @@ --- title: Importing Aztec.nr +tags: [contracts] sidebar_position: 5 --- @@ -19,7 +20,7 @@ This is the core Aztec library that is required for every Aztec.nr smart contrac authwit = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/aztec-nr/authwit"} ``` -This allows you to use authentication witnesses in your contract. Find more about its usage [here](../../guides/smart_contracts/writing_contracts/authwit.md). +This allows you to use authentication witnesses in your contract. Read a guide of how to use it [here](../../../guides/developer_guides/smart_contracts/writing_contracts/authwit.md). ## Address note @@ -35,7 +36,7 @@ This is a library for utilizing notes that hold addresses. Find it on [GitHub](h easy_private_state = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/aztec-nr/easy-private-state" } ``` -This is an abstraction library for using private variables like [`EasyPrivateUint`](https://github.com/AztecProtocol/aztec-packages/blob/6c20b45993ee9cbd319ab8351e2722e0c912f427/noir-projects/aztec-nr/easy-private-state/src/easy_private_state.nr#L17). +This is an abstraction library for using private variables like [`EasyPrivateUint` (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/6c20b45993ee9cbd319ab8351e2722e0c912f427/noir-projects/aztec-nr/easy-private-state/src/easy_private_state.nr#L17). ## Protocol Types @@ -51,4 +52,4 @@ This library contains types that are used in the Aztec protocol. Find it on [Git value_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/aztec-nr/value-note" } ``` -This is a library for a note that stores one arbitrary value. You can see an example of how it might be used in the [token contract tutorial](../../tutorials/contract_tutorials/token_contract.md). +This is a library for a note that stores one arbitrary value. You can see an example of how it might be used in the [token contract codealong tutorial](../../../tutorials/codealong/contract_tutorials/token_contract.md). diff --git a/docs/docs/reference/smart_contract_reference/globals.md b/docs/docs/reference/developer_references/smart_contract_reference/globals.md similarity index 100% rename from docs/docs/reference/smart_contract_reference/globals.md rename to docs/docs/reference/developer_references/smart_contract_reference/globals.md diff --git a/docs/docs/reference/smart_contract_reference/macros.md b/docs/docs/reference/developer_references/smart_contract_reference/macros.md similarity index 75% rename from docs/docs/reference/smart_contract_reference/macros.md rename to docs/docs/reference/developer_references/smart_contract_reference/macros.md index 91798ffbcd2..a68b305ddc0 100644 --- a/docs/docs/reference/smart_contract_reference/macros.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/macros.md @@ -1,19 +1,20 @@ --- title: Aztec macros sidebar_position: 6 +tags: [contracts, functions] --- ## All Aztec macros In addition to the function macros in Noir, Aztec also has its own macros for specific functions. An Aztec contract function can be annotated with more than 1 macro. -It is also worth mentioning Noir's `unconstrained` function type [here](https://noir-lang.org/docs/noir/concepts/unconstrained/). +It is also worth mentioning Noir's `unconstrained` function type [here (Noir docs page)](https://noir-lang.org/docs/noir/concepts/unconstrained/). - `#[aztec(public)]` or `#[aztec(private)]` - Whether the function is to be executed from a public or private context (see Further Reading) - `#[aztec(initializer)]` - If one or more functions are marked as an initializer, then one of them must be called before any non-initilizer functions - `#[aztec(noinitcheck)]` - The function is able to be called before an initializer (if one exists) -- `#[aztec(view)]` - Makes calls to the function static (see also [Static calls](../../../../protocol-specs/calls/static-calls)) +- `#[aztec(view)]` - Makes calls to the function static (see also [Static calls in the protocol spec](../../../protocol-specs/calls/static-calls.md)) - `#[aztec(internal)]` - Function can only be called from within the contract - `#[aztec(note)]` - Creates a custom note ## Further reading -[How do Aztec macros work?](../../aztec/concepts/smart_contracts/functions/inner_workings.md) +[How do Aztec macros work? (Concepts)](../../../aztec/smart_contracts/functions/inner_workings.md) diff --git a/docs/docs/reference/smart_contract_reference/portals/_category_.json b/docs/docs/reference/developer_references/smart_contract_reference/portals/_category_.json similarity index 100% rename from docs/docs/reference/smart_contract_reference/portals/_category_.json rename to docs/docs/reference/developer_references/smart_contract_reference/portals/_category_.json diff --git a/docs/docs/reference/smart_contract_reference/portals/data_structures.md b/docs/docs/reference/developer_references/smart_contract_reference/portals/data_structures.md similarity index 89% rename from docs/docs/reference/smart_contract_reference/portals/data_structures.md rename to docs/docs/reference/developer_references/smart_contract_reference/portals/data_structures.md index f7a87619edb..662e409c124 100644 --- a/docs/docs/reference/smart_contract_reference/portals/data_structures.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/portals/data_structures.md @@ -4,7 +4,7 @@ title: Data Structures The `DataStructures` are structs that we are using throughout the message infrastructure and registry. -**Links**: [Implementation](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/DataStructures.sol). +**Links**: [Implementation (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/DataStructures.sol). ## `L1Actor` @@ -40,7 +40,7 @@ A message that is sent from L1 to L2. | `sender` | `L1Actor` | The actor on L1 that is sending the message. | | `recipient` | `L2Actor` | The actor on L2 that is to receive the message. | | `content` | `field (~254 bits)` | The field element containing the content to be sent to L2. | -| `secretHash` | `field (~254 bits)` | The hash of a secret pre-image that must be known to consume the message on L2. Use [`computeSecretHash`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec.js/src/utils/secrets.ts) to compute it from a secret. | +| `secretHash` | `field (~254 bits)` | The hash of a secret pre-image that must be known to consume the message on L2. Use [`computeSecretHash` (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec.js/src/utils/secrets.ts) to compute it from a secret. | ## `L2ToL1Message` diff --git a/docs/docs/reference/smart_contract_reference/portals/inbox.md b/docs/docs/reference/developer_references/smart_contract_reference/portals/inbox.md similarity index 77% rename from docs/docs/reference/smart_contract_reference/portals/inbox.md rename to docs/docs/reference/developer_references/smart_contract_reference/portals/inbox.md index 3a33a1dbf06..d742d17578b 100644 --- a/docs/docs/reference/smart_contract_reference/portals/inbox.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/portals/inbox.md @@ -1,10 +1,11 @@ --- title: Inbox +tags: [portals, contracts] --- The `Inbox` is a contract deployed on L1 that handles message passing from L1 to the rollup (L2) -**Links**: [Interface](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/interfaces/messagebridge/IInbox.sol), [Implementation](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/messagebridge/Inbox.sol). +**Links**: [Interface (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/interfaces/messagebridge/IInbox.sol), [Implementation (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/messagebridge/Inbox.sol). ## `sendL2Message()` @@ -16,8 +17,8 @@ Sends a message from L1 to L2. | Name | Type | Description | | -------------- | ------- | ----------- | | Recipient | `L2Actor` | The recipient of the message. This **MUST** match the rollup version and an Aztec contract that is **attached** to the contract making this call. If the recipient is not attached to the caller, the message cannot be consumed by it. | -| Content | `field` (~254 bits) | The content of the message. This is the data that will be passed to the recipient. The content is limited to be a single field for rollup purposes. If the content is small enough it can just be passed along, otherwise it should be hashed and the hash passed along (you can use our [`Hash`](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/Hash.sol) utilities with `sha256ToField` functions) | -| Secret Hash | `field` (~254 bits) | A hash of a secret that is used when consuming the message on L2. Keep this preimage a secret to make the consumption private. To consume the message the caller must know the pre-image (the value that was hashed) - so make sure your app keeps track of the pre-images! Use [`computeSecretHash`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec.js/src/utils/secrets.ts) to compute it from a secret. | +| Content | `field` (~254 bits) | The content of the message. This is the data that will be passed to the recipient. The content is limited to be a single field for rollup purposes. If the content is small enough it can just be passed along, otherwise it should be hashed and the hash passed along (you can use our [`Hash` (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/Hash.sol) utilities with `sha256ToField` functions) | +| Secret Hash | `field` (~254 bits) | A hash of a secret that is used when consuming the message on L2. Keep this preimage a secret to make the consumption private. To consume the message the caller must know the pre-image (the value that was hashed) - so make sure your app keeps track of the pre-images! Use [`computeSecretHash` (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec.js/src/utils/secrets.ts) to compute it from a secret. | | ReturnValue | `bytes32` | The message hash, used as an identifier | #### Edge cases diff --git a/docs/docs/reference/smart_contract_reference/portals/outbox.md b/docs/docs/reference/developer_references/smart_contract_reference/portals/outbox.md similarity index 91% rename from docs/docs/reference/smart_contract_reference/portals/outbox.md rename to docs/docs/reference/developer_references/smart_contract_reference/portals/outbox.md index daf37b473a4..2c0e1b9b1f1 100644 --- a/docs/docs/reference/smart_contract_reference/portals/outbox.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/portals/outbox.md @@ -1,10 +1,11 @@ --- title: Outbox +tags: [portals, contracts] --- The `Outbox` is a contract deployed on L1 that handles message passing from the rollup and to L1. -**Links**: [Interface](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/interfaces/messagebridge/IOutbox.sol), [Implementation](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/messagebridge/Outbox.sol). +**Links**: [Interface (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/interfaces/messagebridge/IOutbox.sol), [Implementation (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/messagebridge/Outbox.sol). ## `insert()` diff --git a/docs/docs/reference/smart_contract_reference/portals/registry.md b/docs/docs/reference/developer_references/smart_contract_reference/portals/registry.md similarity index 90% rename from docs/docs/reference/smart_contract_reference/portals/registry.md rename to docs/docs/reference/developer_references/smart_contract_reference/portals/registry.md index 2c1b561ba7a..7de03b9354f 100644 --- a/docs/docs/reference/smart_contract_reference/portals/registry.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/portals/registry.md @@ -1,10 +1,11 @@ --- title: Registry +tags: [portals, contracts] --- The registry is a contract deployed on L1, that contains addresses for the `Rollup`, `Inbox` and `Outbox`. It also keeps track of the different versions that have been deployed and let you query prior deployments easily. -**Links**: [Interface](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/interfaces/messagebridge/IRegistry.sol), [Implementation](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/messagebridge/Registry.sol). +**Links**: [Interface (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/interfaces/messagebridge/IRegistry.sol), [Implementation (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/messagebridge/Registry.sol). ## `numberOfVersions()` diff --git a/docs/docs/reference/smart_contract_reference/storage/_category_.json b/docs/docs/reference/developer_references/smart_contract_reference/storage/_category_.json similarity index 100% rename from docs/docs/reference/smart_contract_reference/storage/_category_.json rename to docs/docs/reference/developer_references/smart_contract_reference/storage/_category_.json diff --git a/docs/docs/reference/smart_contract_reference/storage/index.md b/docs/docs/reference/developer_references/smart_contract_reference/storage/index.md similarity index 80% rename from docs/docs/reference/smart_contract_reference/storage/index.md rename to docs/docs/reference/developer_references/smart_contract_reference/storage/index.md index f0a436c2e66..1ca6e302063 100644 --- a/docs/docs/reference/smart_contract_reference/storage/index.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/storage/index.md @@ -4,8 +4,8 @@ title: Storage Smart contracts rely on storage, acting as the persistent memory on the blockchain. In Aztec, because of its hybrid, privacy-first architecture, the management of this storage is more complex than other blockchains like Ethereum. -To learn how to define a storage struct, read [this guide](../../../guides/smart_contracts/writing_contracts/storage/index.md). -To learn more about storage slots, read [this explainer](../../../guides/smart_contracts/writing_contracts/storage/storage_slots.md). +To learn how to define a storage struct, read [this guide](../../../../guides/developer_guides/smart_contracts/writing_contracts/storage/index.md). +To learn more about storage slots, read [this explainer in the Concepts section](../../../../aztec/concepts/storage/index.md). You control this storage in Aztec using a struct annotated with `#[aztec(storage)]`. This struct serves as the housing unit for all your smart contract's state variables - the data it needs to keep track of and maintain. @@ -24,7 +24,7 @@ On this and the following pages in this section, you’ll learn: ## The `Context` parameter -Aztec contracts have three different modes of execution: [private](../../../aztec/glossary/call_types.md#private-execution), [public](../../../aztec/glossary/call_types.md#public-execution) and [top-level unconstrained](../../../aztec/glossary/call_types.md#top-level-unconstrained). How storage is accessed depends on the execution mode: for example, `PublicImmutable` can be read in all execution modes but only initialized in public, while `PrivateMutable` is entirely unavailable in public. +Aztec contracts have three different modes of execution: private, public, and top-level unconstrained. How storage is accessed depends on the execution mode: for example, `PublicImmutable` can be read in all execution modes but only initialized in public, while `PrivateMutable` is entirely unavailable in public. Aztec.nr prevents developers from calling functions unavailable in the current execution mode via the `context` variable that is injected into all contract functions. Its type indicates the current execution mode: @@ -57,15 +57,15 @@ A `map` is a state variable that "maps" a key to a value. It can be used with pr In Aztec.nr, keys are always `Field`s, or types that can be serialized as Fields, and values can be any type - even other maps. `Field`s are finite field elements, but you can think of them as integers. ::: -It includes a [`Context`](../../../aztec/concepts/smart_contracts/functions/context.md) to specify the private or public domain, a `storage_slot` to specify where in storage the map is stored, and a `start_var_constructor` which tells the map how it should operate on the underlying type. This includes how to serialize and deserialize the type, as well as how commitments and nullifiers are computed for the type if it's private. +It includes a `Context` to specify the private or public domain, a `storage_slot` to specify where in storage the map is stored, and a `start_var_constructor` which tells the map how it should operate on the underlying type. This includes how to serialize and deserialize the type, as well as how commitments and nullifiers are computed for the type if it's private. -You can view the implementation in the Aztec.nr library [here](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr). +You can view the implementation in the Aztec.nr library [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr). You can have multiple `map`s in your contract that each have a different underlying note type, due to note type IDs. These are identifiers for each note type that are unique within a contract. ### `new` -When declaring the storage for a map, we use the `Map::new()` constructor. As seen below, this takes the `storage_slot` and the `start_var_constructor` along with the [`Context`](../../../aztec/concepts/smart_contracts/functions/context.md). +When declaring the storage for a map, we use the `Map::new()` constructor. As seen below, this takes the `storage_slot` and the `start_var_constructor` along with the `Context`. We will see examples of map constructors for public and private variables in later sections. @@ -105,6 +105,6 @@ require(minters[msg.sender], "caller is not minter"); ## Concepts mentioned -- [State Model](../../../aztec/concepts/state_model/index.md) -- [Public-private execution](../../../aztec/concepts/smart_contracts/communication/public_private_calls.md) -- [Function Contexts](../../../aztec/concepts/smart_contracts/functions/context.md) +- [State Model](../../../../aztec/concepts/state_model/index.md) +- [Public-private execution](../../../../aztec/smart_contracts/communication/public_private_calls.md) +- [Function Contexts](../../../../aztec/smart_contracts/functions/context.md) diff --git a/docs/docs/reference/smart_contract_reference/storage/private_state.md b/docs/docs/reference/developer_references/smart_contract_reference/storage/private_state.md similarity index 87% rename from docs/docs/reference/smart_contract_reference/storage/private_state.md rename to docs/docs/reference/developer_references/smart_contract_reference/storage/private_state.md index 7560e14f03d..c8aa400f0ad 100644 --- a/docs/docs/reference/smart_contract_reference/storage/private_state.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/storage/private_state.md @@ -4,15 +4,15 @@ title: Private State On this page we will look at how to manage private state in Aztec contracts. We will look at how to declare private state, how to read and write to it, and how to use it in your contracts. -For a higher level overview of the state model in Aztec, see the [hybrid state model](../../../aztec/concepts/state_model/index.md) page. +For a higher level overview of the state model in Aztec, see the [hybrid state model](../../../../aztec/concepts/state_model/index.md) page. ## Overview 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 an [encrypted log](../../../guides/smart_contracts/writing_contracts/how_to_emit_event.md#encrypted-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 an encrypted log, or offchain via web2, or completely offline: it's up to the app developer. -Aztec private state follows a [utxo](https://en.wikipedia.org/wiki/Unspent_transaction_output)-based model. That is, a private state's current value is represented as one or many [notes](../../../aztec/concepts/storage/trees/index.md). +Aztec private state follows a [UTXO](https://en.wikipedia.org/wiki/Unspent_transaction_output)-based model. That is, a private state's current value is represented as one or many notes. To greatly simplify the experience of writing private state, Aztec.nr provides three different types of private state variable: @@ -70,7 +70,7 @@ Interestingly, if a developer requires a private state to be modifiable by users PrivateMutable (formerly known as `Singleton`) is a private state variable that is unique in a way. When a PrivateMutable is initialized, a note is created to represent its value. And the way to update the value is to destroy the current note, and create a new one with the updated value. -Like for public state, we define the struct to have context and a storage slot. You can view the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/state_vars/private_mutable.nr). +Like for public state, we define the struct to have context and a storage slot. You can view the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/state_vars/private_mutable.nr). An example of `PrivateMutable` usage in the account contracts is keeping track of public keys. The `PrivateMutable` is added to the `Storage` struct as follows: @@ -102,7 +102,7 @@ Extend on what happens if you try to use non-initialized state. ### `is_initialized` -An unconstrained method to check whether the PrivateMutable has been initialized or not. It takes an optional owner and returns a boolean. You can view the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/private_mutable.nr). +An unconstrained method to check whether the PrivateMutable has been initialized or not. It takes an optional owner and returns a boolean. You can view the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/private_mutable.nr). #include_code private_mutable_is_initialized /noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr rust @@ -134,7 +134,7 @@ Functionally similar to [`get_note`](#get_note), but executed in unconstrained f ## `PrivateImmutable` -`PrivateImmutable` (formerly known as `ImmutableSingleton`) represents a unique private state variable that, as the name suggests, is immutable. Once initialized, its value cannot be altered. You can view the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/private_immutable.nr). +`PrivateImmutable` (formerly known as `ImmutableSingleton`) represents a unique private state variable that, as the name suggests, is immutable. Once initialized, its value cannot be altered. You can view the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/private_immutable.nr). ### `new` @@ -160,7 +160,7 @@ Once initialized, an PrivateImmutable's value remains unchangeable. This method ### `is_initialized` -An unconstrained method to check if the PrivateImmutable has been initialized. Takes an optional owner and returns a boolean. You can find the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/private_immutable.nr). +An unconstrained method to check if the PrivateImmutable has been initialized. Takes an optional owner and returns a boolean. You can find the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/private_immutable.nr). ### `get_note` @@ -182,9 +182,9 @@ Functionally similar to `get_note`, but executed unconstrained and can be used b `PrivateSet` is used for managing a collection of notes. All notes in a `PrivateSet` are of the same `NoteType`. But whether these notes all belong to one entity, or are accessible and editable by different entities, is up to the developer. The set is a collection of notes inserted into the data-tree, but notes are never removed from the tree itself, they are only nullified. -You can view the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/set.nr). +You can view the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/set.nr). -And can be added to the `Storage` struct as follows. Here adding a set for a custom note, the TransparentNote (useful for [public -> private communication](../../../guides/smart_contracts/writing_contracts/call_functions.md). +And can be added to the `Storage` struct as follows. Here adding a set for a custom note, the TransparentNote (useful for public -> private communication). #include_code storage-set-declaration /noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr rust @@ -200,13 +200,13 @@ We can initialize the set as follows: Allows us to modify the storage by inserting a note into the `PrivateSet`. -A hash of the note will be generated, and inserted into the note hash tree, allowing us to later use in contract interactions. Recall that the content of the note should be shared with the owner to allow them to use it, as mentioned this can be done via an [encrypted log](../../../guides/smart_contracts/writing_contracts/how_to_emit_event.md#encrypted-events), or offchain via web2, or completely offline. +A hash of the note will be generated, and inserted into the note hash tree, allowing us to later use in contract interactions. Recall that the content of the note should be shared with the owner to allow them to use it, as mentioned this can be done via an encrypted log or offchain via web2, or completely offline. #include_code insert /noir-projects/aztec-nr/easy-private-state/src/easy_private_uint.nr rust ### `insert_from_public` -The `insert_from_public` allow public function to insert notes into private storage. This is very useful when we want to support private function calls that have been initiated in public, such as shielding in the [example token contract](../../../tutorials/contract_tutorials/token_contract.md#shield). +The `insert_from_public` allow public function to insert notes into private storage. This is very useful when we want to support private function calls that have been initiated in public, such as shielding in the [token contract codealong tutorial](../../../../tutorials/codealong/contract_tutorials/token_contract.md). The usage is similar to using the `insert` method with the difference that this one is called in public functions. @@ -226,11 +226,11 @@ An example of how to use this operation is visible in the `easy_private_state`: This function returns the notes the account has access to. -The kernel circuits are constrained to a maximum number of notes this function can return at a time. Check [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-protocol-circuits/crates/types/src/constants.nr) and look for `MAX_NOTE_HASH_READ_REQUESTS_PER_CALL` for the up-to-date number. +The kernel circuits are constrained to a maximum number of notes this function can return at a time. Check [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-protocol-circuits/crates/types/src/constants.nr) and look for `MAX_NOTE_HASH_READ_REQUESTS_PER_CALL` for the up-to-date number. Because of this limit, we should always consider using the second argument `NoteGetterOptions` to limit the number of notes we need to read and constrain in our programs. This is quite important as every extra call increases the time used to prove the program and we don't want to spend more time than necessary. -An example of such options is using the [filter_notes_min_sum](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/value-note/src/filter.nr) to get "enough" notes to cover a given value. Essentially, this function will return just enough notes to cover the amount specified such that we don't need to read all our notes. For users with a lot of notes, this becomes increasingly important. +An example of such options is using the [filter_notes_min_sum (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/value-note/src/filter.nr) to get "enough" notes to cover a given value. Essentially, this function will return just enough notes to cover the amount specified such that we don't need to read all our notes. For users with a lot of notes, this becomes increasingly important. #include_code get_notes /noir-projects/aztec-nr/easy-private-state/src/easy_private_uint.nr rust @@ -240,7 +240,7 @@ Functionally similar to [`get_notes`](#get_notes), but executed unconstrained an #include_code view_notes /noir-projects/aztec-nr/value-note/src/balance_utils.nr rust -There's also a limit on the maximum number of notes that can be returned in one go. To find the current limit, refer to [this file](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/constants.nr) and look for `MAX_NOTES_PER_PAGE`. +There's also a limit on the maximum number of notes that can be returned in one go. To find the current limit, refer to [this file (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/constants.nr) and look for `MAX_NOTES_PER_PAGE`. The key distinction is that this method is unconstrained. It does not perform a check to verify if the notes actually exist, which is something the [`get_notes`](#get_notes) method does under the hood. Therefore, it should only be used in an unconstrained contract function. @@ -248,9 +248,9 @@ This function requires a `NoteViewerOptions`. The `NoteViewerOptions` is essenti ## `NoteGetterOptions` -`NoteGetterOptions` encapsulates a set of configurable options for filtering and retrieving a selection of notes from a [data oracle](../../../aztec/concepts/smart_contracts/oracles/index.md). Developers can design instances of `NoteGetterOptions`, to determine how notes should be filtered and returned to the functions of their smart contracts. +`NoteGetterOptions` encapsulates a set of configurable options for filtering and retrieving a selection of notes from a data oracle. Developers can design instances of `NoteGetterOptions`, to determine how notes should be filtered and returned to the functions of their smart contracts. -You can view the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_getter_options.nr). +You can view the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_getter_options.nr). ### `selects: BoundedVec, N>` diff --git a/docs/docs/reference/smart_contract_reference/storage/public_state.md b/docs/docs/reference/developer_references/smart_contract_reference/storage/public_state.md similarity index 77% rename from docs/docs/reference/smart_contract_reference/storage/public_state.md rename to docs/docs/reference/developer_references/smart_contract_reference/storage/public_state.md index 69b5a960fb8..61208e17cc2 100644 --- a/docs/docs/reference/smart_contract_reference/storage/public_state.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/storage/public_state.md @@ -4,7 +4,7 @@ title: Public State On this page we will look at how to manage public state in Aztec contracts. We will look at how to declare public state, how to read and write to it, and how to use it in your contracts. -For a higher level overview of the state model in Aztec, see the [state model](../../../aztec/concepts/state_model/index.md) page. +For a higher level overview of the state model in Aztec, see the [state model](../../../../aztec/concepts/state_model/index.md) concepts page. ## `PublicMutable` @@ -13,19 +13,19 @@ The `PublicMutable` (formerly known as `PublicState`) struct is generic over the #include_code serialize /noir-projects/noir-protocol-circuits/crates/types/src/traits.nr rust #include_code deserialize /noir-projects/noir-protocol-circuits/crates/types/src/traits.nr rust -The struct contains a `storage_slot` which, similar to Ethereum, is used to figure out _where_ in storage the variable is located. Notice that while we don't have the exact same [state model](../../../aztec/concepts/state_model/index.md) as EVM chains it will look similar from the contract developers point of view. +The struct contains a `storage_slot` which, similar to Ethereum, is used to figure out _where_ in storage the variable is located. Notice that while we don't have the exact same state model as EVM chains it will look similar from the contract developers point of view. -You can find the details of `PublicMutable` in the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/public_mutable.nr). +You can find the details of `PublicMutable` in the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/public_mutable.nr). For a version of `PublicMutable` that can also be read in private, head to [`SharedMutable`](./shared_state.md#sharedmutable). :::info -An example using a larger struct can be found in the [lending example](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/noir-contracts/contracts/lending_contract)'s use of an [`Asset`](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/lending_contract/src/asset.nr). +An example using a larger struct can be found in the [lending example (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/noir-contracts/contracts/lending_contract)'s use of an [`Asset` (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/lending_contract/src/asset.nr). ::: ### `new` -When declaring the storage for `T` as a persistent public storage variable, we use the `PublicMutable::new()` constructor. As seen below, this takes the `storage_slot` and the `serialization_methods` as arguments along with the [`Context`](../../../aztec/concepts/smart_contracts/functions/context.md), which in this case is used to share interface with other structures. You can view the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/public_mutable.nr). +When declaring the storage for `T` as a persistent public storage variable, we use the `PublicMutable::new()` constructor. As seen below, this takes the `storage_slot` and the `serialization_methods` as arguments along with the `Context`, which in this case is used to share interface with other structures. You can view the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/public_mutable.nr). #### Single value example @@ -75,7 +75,7 @@ We have a `write` method on the `PublicMutable` struct that takes the value to w Just like the `PublicMutable` it is generic over the variable type `T`. The type `MUST` implement Serialize and Deserialize traits. -You can find the details of `PublicImmutable` in the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/public_immutable.nr). +You can find the details of `PublicImmutable` in the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/public_immutable.nr). ### `new` diff --git a/docs/docs/reference/smart_contract_reference/storage/shared_state.md b/docs/docs/reference/developer_references/smart_contract_reference/storage/shared_state.md similarity index 97% rename from docs/docs/reference/smart_contract_reference/storage/shared_state.md rename to docs/docs/reference/developer_references/smart_contract_reference/storage/shared_state.md index a981de01ddd..d30597935f0 100644 --- a/docs/docs/reference/smart_contract_reference/storage/shared_state.md +++ b/docs/docs/reference/developer_references/smart_contract_reference/storage/shared_state.md @@ -54,7 +54,7 @@ This prevents the network-wide privacy set from being split between transactions ## `SharedMutable` -`SharedMutable` is a shared state variable for mutable state. It provides capabilities to read the same state both in private and public, and to schedule value changes after a delay. You can view the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/shared_mutable/shared_mutable.nr). +`SharedMutable` is a shared state variable for mutable state. It provides capabilities to read the same state both in private and public, and to schedule value changes after a delay. You can view the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/shared_mutable/shared_mutable.nr). Unlike other state variables, `SharedMutable` receives not only a type parameter for the underlying datatype, but also a `DELAY` type parameter with the value change delay as a number of blocks. @@ -110,7 +110,7 @@ Like most state variables, `SharedImmutable` is generic over the variable type ` #include_code storage-shared-immutable-declaration /noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr rust -You can find the details of `SharedImmutable` in the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/shared_immutable.nr). +You can find the details of `SharedImmutable` in the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/shared_immutable.nr). ### `initialize` diff --git a/docs/docs/reference/index.md b/docs/docs/reference/index.md new file mode 100644 index 00000000000..714e945f3b9 --- /dev/null +++ b/docs/docs/reference/index.md @@ -0,0 +1,64 @@ +--- +title: References +sidebar_position: 0 +--- + +# References + +Welcome to the References section! In this section you will find reference material for developing on Aztec Protocol. + +This page lists popular references. Please see the sidebar for them all. + + +## Popular + +### Smart contracts + +
+ + + +

Storage

+ + + A detailed reference for storage types + + + + + +

Portals

+ + + A detailed reference for working with portals and L1/L2 communication + + + +
+ +### Others + +
+ + + +

Common Sandbox Errors

+ + + Help debug your sandbox environment + + + + + +

CLI reference

+ + + A full list of commands for working with the Aztec CLI + + +
+ + diff --git a/docs/docs/tutorials/aztecjs-getting-started.md b/docs/docs/tutorials/codealong/aztecjs-getting-started.md similarity index 95% rename from docs/docs/tutorials/aztecjs-getting-started.md rename to docs/docs/tutorials/codealong/aztecjs-getting-started.md index ff99ce941f8..d4b9966e08a 100644 --- a/docs/docs/tutorials/aztecjs-getting-started.md +++ b/docs/docs/tutorials/codealong/aztecjs-getting-started.md @@ -7,7 +7,7 @@ import Image from "@theme/IdealImage"; In this guide, we will retrieving the Sandbox and deploy a pre-written contract to it using Aztec.js. -This guide assumes you have followed the [quickstart](../getting_started.md). +This guide assumes you have followed the [quickstart](../../guides/developer_guides/getting_started/quickstart.md). ## Prerequisites @@ -131,7 +131,7 @@ The sandbox is preloaded with multiple accounts so you don't have to sit and cre #include_code load_accounts /yarn-project/end-to-end/src/composed/e2e_sandbox_example.test.ts typescript -An explanation on accounts on Aztec can be found [here](../aztec/concepts/index.md). +An explanation on accounts on Aztec can be found [here](../../aztec/concepts/accounts/index.md). ## Deploy a contract @@ -239,7 +239,7 @@ Now lets transfer some funds from Alice to Bob by calling the `transfer` functio 1. The sender. 2. The recipient. 3. The quantity of tokens to be transferred. -4. The nonce for the [authentication witness](../aztec/concepts/index.md#authorizing-actions), or 0 if msg.sender equal sender. +4. The nonce for the [authentication witness](../../aztec/concepts/accounts/index.md#authorizing-actions), or 0 if msg.sender equal sender. Here is the Typescript code to call the `transfer` function, add this to your `index.ts` at the bottom of the `main` function: @@ -336,15 +336,15 @@ Our complete output should now be something like: token Bob's balance 10543 +43ms ``` -That's it! We have successfully deployed a token contract to an instance of the Aztec network and mined private state-transitioning transactions. We have also queried the resulting state all via the interfaces provided by the contract. To see exactly what has happened here, you can learn about the transaction flow [on the Concepts page here](../aztec/concepts/transactions.md). +That's it! We have successfully deployed a token contract to an instance of the Aztec network and mined private state-transitioning transactions. We have also queried the resulting state all via the interfaces provided by the contract. To see exactly what has happened here, you can learn about the transaction flow [on the Concepts page here](../../aztec/concepts/transactions.md). ## Next Steps ### Build a fullstack Aztec project -Follow the dapp tutorial on the [next page](./simple_dapp/index.md). +Follow the [dapp tutorial](./simple_dapp/index.md). ### Optional: Learn more about concepts mentioned here -- [Authentication witness](../aztec/concepts/accounts/authwit.md) -- [Functions under the hood](../aztec/concepts/smart_contracts/functions/inner_workings.md) \ No newline at end of file +- [Authentication witness](../../aztec/concepts/accounts/authwit.md) +- [Functions under the hood](../../aztec/smart_contracts/functions/inner_workings.md) diff --git a/docs/docs/tutorials/contract_tutorials/_category_.json b/docs/docs/tutorials/codealong/contract_tutorials/_category_.json similarity index 81% rename from docs/docs/tutorials/contract_tutorials/_category_.json rename to docs/docs/tutorials/codealong/contract_tutorials/_category_.json index a9fa3a1b962..852419cf559 100644 --- a/docs/docs/tutorials/contract_tutorials/_category_.json +++ b/docs/docs/tutorials/codealong/contract_tutorials/_category_.json @@ -1,6 +1,6 @@ { "label": "Contract Tutorials", - "position": 0, + "position": 1, "collapsible": true, "collapsed": true } diff --git a/docs/docs/tutorials/contract_tutorials/advanced/_category_.json b/docs/docs/tutorials/codealong/contract_tutorials/advanced/_category_.json similarity index 100% rename from docs/docs/tutorials/contract_tutorials/advanced/_category_.json rename to docs/docs/tutorials/codealong/contract_tutorials/advanced/_category_.json diff --git a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/0_setup.md b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/0_setup.md similarity index 97% rename from docs/docs/tutorials/contract_tutorials/advanced/token_bridge/0_setup.md rename to docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/0_setup.md index 42a082ffdce..0af6c030071 100644 --- a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/0_setup.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/0_setup.md @@ -15,9 +15,9 @@ We recommend going through this setup to fully understand where things live. ## Prerequisites -- [node v18+](https://github.com/tj/n) +- [node v18+ (GitHub link)](https://github.com/tj/n) - [docker](https://docs.docker.com/) -- [Aztec sandbox](../../../../getting_started.md) - you should have this running before starting the tutorial +- [Aztec sandbox](../../../../../guides/developer_guides/getting_started/quickstart.md) - you should have this running before starting the tutorial Start the sandbox diff --git a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/1_depositing_to_aztec.md b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/1_depositing_to_aztec.md similarity index 100% rename from docs/docs/tutorials/contract_tutorials/advanced/token_bridge/1_depositing_to_aztec.md rename to docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/1_depositing_to_aztec.md diff --git a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md similarity index 99% rename from docs/docs/tutorials/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md rename to docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md index a9897a29979..aa7a7e4ac2d 100644 --- a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md @@ -52,6 +52,6 @@ If the content hashes were constructed similarly for `mint_private` and `mint_pu While we mint the tokens on L2, we _still don’t actually mint them to a certain address_. Instead we continue to pass the `secret_hash_for_redeeming_minted_notes` like we did on L1. This means that a user could reveal their secret for L2 message consumption for anyone to mint tokens on L2 but they can redeem these notes at a later time. **This enables a paradigm where an app can manage user’s secrets for L2 message consumption on their behalf**. **The app or any external party can also mint tokens on the user’s behalf should they be comfortable with leaking the secret for L2 Message consumption.** This doesn’t leak any new information to the app because their smart contract on L1 knew that a user wanted to move some amount of tokens to L2. The app still doesn’t know which address on L2 the user wants these notes to be in, but they can mint tokens nevertheless on their behalf. -To mint tokens privately, `claim_private` calls an internal function `_call_mint_on_token()` which then calls [token.mint_private()](../../token_contract.md#redeem_shield). +To mint tokens privately, `claim_private` calls an internal function `_call_mint_on_token()` which then calls [token.mint_private()](../../token_contract.md#mint_private). In the next step we will see how we can cancel a message. diff --git a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/3_withdrawing_to_l1.md b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/3_withdrawing_to_l1.md similarity index 97% rename from docs/docs/tutorials/contract_tutorials/advanced/token_bridge/3_withdrawing_to_l1.md rename to docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/3_withdrawing_to_l1.md index 6d66f2a1bef..a0c1b508212 100644 --- a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/3_withdrawing_to_l1.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/3_withdrawing_to_l1.md @@ -17,7 +17,7 @@ For this to work we import the `get_withdraw_content_hash` helper function from The `exit_to_l1_public` function enables anyone to withdraw their L2 tokens back to L1 publicly. This is done by burning tokens on L2 and then creating an L2->L1 message. 1. Like with our deposit function, we need to create the L2 to L1 message. The content is the _amount_ to burn, the recipient address, and who can execute the withdraw on the L1 portal on behalf of the user. It can be `0x0` for anyone, or a specified address. -2. `context.message_portal()` passes this content to the [kernel circuit](../../../../aztec/concepts/circuits/kernels/public_kernel.md) which creates the proof for the transaction. The kernel circuit then adds the sender (the L2 address of the bridge + version of aztec) and the recipient (the portal to the L2 address + the chain ID of L1) under the hood, to create the message which gets added as part of the transaction data published by the sequencer and is stored in the outbox for consumption. +2. `context.message_portal()` passes this content to the kernel circuit which creates the proof for the transaction. The kernel circuit then adds the sender (the L2 address of the bridge + version of aztec) and the recipient (the portal to the L2 address + the chain ID of L1) under the hood, to create the message which gets added as part of the transaction data published by the sequencer and is stored in the outbox for consumption. 3. The `context.message_portal()` takes the recipient and content as input, and will insert a message into the outbox. We set the recipient to be the portal address read from storage of the contract. 4. Finally, you also burn the tokens on L2! Note that it burning is done at the end to follow the check effects interaction pattern. Note that the caller has to first approve the bridge contract to burn tokens on its behalf. Refer to [burn_public function on the token contract](../../token_contract.md#authorizing-token-spends). - We burn the tokens from the `msg_sender()`. Otherwise, a malicious user could burn someone else’s tokens and mint tokens on L1 to themselves. One could add another approval flow on the bridge but that might make it complex for other applications to call the bridge. diff --git a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/4_typescript_glue_code.md b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/4_typescript_glue_code.md similarity index 95% rename from docs/docs/tutorials/contract_tutorials/advanced/token_bridge/4_typescript_glue_code.md rename to docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/4_typescript_glue_code.md index 7d0a03592a7..674be65f37d 100644 --- a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/4_typescript_glue_code.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/4_typescript_glue_code.md @@ -168,9 +168,9 @@ Note - you might have a jest error at the end of each test saying "expected 1-2 ### Follow a more detailed Aztec.js tutorial -Follow the tutorial on the [next page](../../../aztecjs-getting-started.md). +Follow the tutorial [here](../../../aztecjs-getting-started.md). ### Optional: Learn more about concepts mentioned here -- [Portals (protocol specs)](../../../../protocol-specs/l1-smart-contracts/index.md) -- [Functions under the hood (concepts)](../../../../aztec/concepts/smart_contracts/functions/inner_workings.md) \ No newline at end of file +- [Portals (protocol specs)](../../../../../protocol-specs/l1-smart-contracts/index.md) +- [Functions under the hood (concepts)](../../../../../aztec/smart_contracts/functions/inner_workings.md) diff --git a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/index.md b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/index.md similarity index 98% rename from docs/docs/tutorials/contract_tutorials/advanced/token_bridge/index.md rename to docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/index.md index f38ea62322b..8b3873c5a91 100644 --- a/docs/docs/tutorials/contract_tutorials/advanced/token_bridge/index.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/advanced/token_bridge/index.md @@ -5,7 +5,7 @@ sidebar_position: 2 import Image from "@theme/IdealImage"; -In this tutorial, we will learn how to build the entire flow of a cross-chain token using portals. If this is your first time hearing the word portal, you’ll want to read [this page in the protocol specs](../../../../protocol-specs/l1-smart-contracts/index.md). +In this tutorial, we will learn how to build the entire flow of a cross-chain token using portals. If this is your first time hearing the word portal, you’ll want to read [this page in the protocol specs](../../../../../protocol-specs/l1-smart-contracts/index.md). ## A refresher on Portals diff --git a/docs/docs/tutorials/contract_tutorials/counter_contract.md b/docs/docs/tutorials/codealong/contract_tutorials/counter_contract.md similarity index 93% rename from docs/docs/tutorials/contract_tutorials/counter_contract.md rename to docs/docs/tutorials/codealong/contract_tutorials/counter_contract.md index 887954c9cba..85109d46668 100644 --- a/docs/docs/tutorials/contract_tutorials/counter_contract.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/counter_contract.md @@ -5,11 +5,9 @@ sidebar_position: 0 In this guide, we will create our first Aztec.nr smart contract. We will build a simple private counter. This contract will get you started with the basic setup and syntax of Aztec.nr, but doesn't showcase the awesome stuff Aztec is capable of. -If you already have some experience with Noir and want to build a cooler contract that utilizes both private and public state, you might want to check out the [token contract tutorial instead](../../tutorials/contract_tutorials/token_contract.md). - ## Prerequisites -- You have followed the [quickstart](../../getting_started.md) +- You have followed the [quickstart](../../../guides/developer_guides/getting_started/quickstart.md) - Running Aztec Sandbox ## Set up a project @@ -160,4 +158,4 @@ Follow the private voting contract tutorial on the [next page](./private_voting_ ### Optional: Learn more about concepts mentioned here - - [Functions and annotations like `#[aztec(private)]`](../../aztec/concepts/smart_contracts/functions/index.md) \ No newline at end of file + - [Functions and annotations like `#[aztec(private)]`](../../../aztec/smart_contracts/functions/inner_workings.md) diff --git a/docs/docs/tutorials/contract_tutorials/crowdfunding_contract.md b/docs/docs/tutorials/codealong/contract_tutorials/crowdfunding_contract.md similarity index 82% rename from docs/docs/tutorials/contract_tutorials/crowdfunding_contract.md rename to docs/docs/tutorials/codealong/contract_tutorials/crowdfunding_contract.md index 9c5dcfd260f..2c7953a8dae 100644 --- a/docs/docs/tutorials/contract_tutorials/crowdfunding_contract.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/crowdfunding_contract.md @@ -26,9 +26,7 @@ Along the way you will: ### Install tools -Please ensure that the you already have [Installed the Sandbox](../../getting_started.md). - -And if using VSCode, see [here](../../getting_started.md#install-noir-lsp-recommended) to install Noir LSP, where you'll benefit from syntax highlighting, profiling, and more. +Please ensure that the you already have [Installed the Sandbox](../../../guides/developer_guides/getting_started/quickstart.md) ### Create an Aztec project @@ -103,7 +101,7 @@ Inside the Crowdfunding contract definition, use the dependency that defines the use dep::aztec::protocol_types::address::AztecAddress; ``` -The `aztec::protocol_types` can be browsed [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-protocol-circuits/crates/types/src). And like rust dependencies, the relative path inside the dependency corresponds to `address::AztecAddress`. +The `aztec::protocol_types` can be browsed [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-protocol-circuits/crates/types/src). And like rust dependencies, the relative path inside the dependency corresponds to `address::AztecAddress`. #### Storage @@ -111,7 +109,7 @@ To retain the initializer parameters in the contract's Storage, we'll need to de #include_code storage /noir-projects/noir-contracts/contracts/crowdfunding_contract/src/main.nr rust -The `ValueNote` type is in the top-level of the Aztec.nr framework, namely [noir-projects/aztec-nr](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/value-note/src/value_note.nr). Like before, you'll need to add the crate to Nargo.toml +The `ValueNote` type is in the top-level of the Aztec.nr framework, namely [noir-projects/aztec-nr (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/value-note/src/value_note.nr). Like before, you'll need to add the crate to Nargo.toml --- @@ -175,10 +173,6 @@ token = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_ With the dependency already `use`d at the start of the contract, the token contract can be called to make the transfer from msg sender to this contract. -:::note -The user must have authorised this action, example use of `createAuthWit` in 'full donor flow' test [here](../../../../yarn-project/end-to-end/src/e2e_crowdfunding_and_claim.test.ts). -::: - #### Creating and storing a private receipt note The last thing to do is create a new value note and add it to the `donation_receipts`. So the full donation function is now @@ -208,7 +202,7 @@ You should be able to compile successfully with `aztec-nargo compile`. For comparison, the full Crowdfunding contract can be found [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-contracts/contracts/crowdfunding_contract). If a new token wishes to honour donors with free tokens based on donation amounts, this is possible via the donation_receipts (a `PrivateSet`). -See [claim_contract](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-contracts/contracts/claim_contract). +See [claim_contract (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-contracts/contracts/claim_contract). ## Next steps @@ -218,9 +212,7 @@ Follow the account contract tutorial on the [next page](./write_accounts_contrac ### Optional: Learn more about concepts mentioned here - - [Initializer functions](../../guides/smart_contracts/writing_contracts/initializers.md) - - [Versions](https://docs.aztec.network/developers/versions-updating). - - [Private Global Variables](https://docs.aztec.network/developers/contracts/references/globals#private-global-variables) - - [Authorizing actions](../../aztec/concepts/accounts/index.md#authorizing-actions) - - [Unencrypted logs](https://docs.aztec.network/developers/contracts/writing_contracts/events/emit_event#unencrypted-events) - - [Common dependencies](https://docs.aztec.network/developers/contracts/resources/dependencies) + - [Initializer functions](../../../guides/developer_guides/smart_contracts/writing_contracts/initializers.md) + - [Versions](../../../guides/developer_guides/local_env/versions-updating.md). + - [Authorizing actions](../../../aztec/concepts/accounts/index.md#authorizing-actions) + - [Unencrypted logs](../../../guides/developer_guides/smart_contracts/writing_contracts/how_to_emit_event.md#call-emit_unencrypted_log) diff --git a/docs/docs/tutorials/contract_tutorials/private_voting_contract.md b/docs/docs/tutorials/codealong/contract_tutorials/private_voting_contract.md similarity index 91% rename from docs/docs/tutorials/contract_tutorials/private_voting_contract.md rename to docs/docs/tutorials/codealong/contract_tutorials/private_voting_contract.md index 8eab842357a..e348f36350d 100644 --- a/docs/docs/tutorials/contract_tutorials/private_voting_contract.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/private_voting_contract.md @@ -21,7 +21,7 @@ To keep things simple, we won't create ballots or allow for delegate voting. ## Prerequisites -- You have followed the [quickstart](../../getting_started.md) to install `aztec-nargo` and `aztec`. +- You have followed the [quickstart](../../../guides/developer_guides/getting_started/quickstart.md) to install `aztec-nargo` and `aztec`. - Running Aztec Sandbox ## Set up a project @@ -129,7 +129,7 @@ The first thing we do here is assert that the vote has not ended. The code after the assertion will only run if the assertion is true. In this snippet, we read the current vote tally at the `candidate`, add 1 to it, and write this new number to the `candidate`. The `Field` element allows us to use `+` to add to an integer. :::warning -Refer to [common patterns](../../guides/smart_contracts/writing_contracts/common_patterns/key_rotation.md) for more information about key rotation and considerations. +Refer to [common patterns (Guides section)](../../../guides/developer_guides/smart_contracts/writing_contracts/common_patterns/key_rotation.md) for more information about key rotation and considerations. ::: ## Getting the number of votes @@ -176,7 +176,7 @@ Follow the crowdfunding contracts tutorial on the [next page](./crowdfunding_con ### Optional: Learn more about concepts mentioned here - - [Unconstrained functions](../../aztec/concepts/pxe/acir_simulator.md#unconstrained-functions). - - [Oracles](../../aztec/concepts/smart_contracts/oracles/index.md) - - [Nullifier secrets](../../aztec/concepts/accounts/keys.md#nullifier-secrets). - - [How to deploy a contract to the sandbox](../../guides/smart_contracts/how_to_deploy_contract.md) \ No newline at end of file + - [Unconstrained functions](../../../aztec/smart_contracts/functions/index.md). + - [Oracles](../../../aztec/smart_contracts/oracles/index.md) + - [Nullifier secrets](../../../aztec/concepts/accounts/keys.md#nullifier-secrets). + - [How to deploy a contract to the sandbox](../../../guides/developer_guides/smart_contracts/how_to_deploy_contract.md) diff --git a/docs/docs/tutorials/contract_tutorials/token_contract.md b/docs/docs/tutorials/codealong/contract_tutorials/token_contract.md similarity index 90% rename from docs/docs/tutorials/contract_tutorials/token_contract.md rename to docs/docs/tutorials/codealong/contract_tutorials/token_contract.md index f3d58d4490f..05920373366 100644 --- a/docs/docs/tutorials/contract_tutorials/token_contract.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/token_contract.md @@ -21,11 +21,7 @@ We are going to start with a blank project and fill in the token contract source ## Requirements -You will need to have `aztec-nargo` installed in order to compile Aztec.nr contracts. See the [sandbox reference](../../reference/sandbox_reference/index.md) for installation instructions. - -You should also install the [Noir Language Support extension](https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir) for VS Code. - -Check the [Dev Tools section](https://github.com/noir-lang/awesome-noir#dev-tools) of the awesome-noir repo for language support for additional editors (Vim, emacs, tree-sitter, etc). +You will need to have `aztec-nargo` installed in order to compile Aztec.nr contracts. ## Project setup @@ -142,13 +138,13 @@ We are importing: ### Types files -We are also importing types from a `types.nr` file, which imports types from the `types` folder. You can view them [here](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/token_contract/src). +We are also importing types from a `types.nr` file, which imports types from the `types` folder. You can view them [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/token_contract/src). The main thing to note from this types folder is the `TransparentNote` definition. This defines how the contract moves value from the public domain into the private domain. It is similar to the `value_note` that we imported, but with some modifications namely, instead of a defined nullifier key, it allows anyone that can produce the pre-image to the stored `secret_hash` to spend the note. ### Note on private state -Private state in Aztec is all [UTXOs](../../aztec/concepts/storage/index.md). +Private state in Aztec is all [UTXOs](../../../aztec/concepts/storage/index.md). ## Contract Storage @@ -212,7 +208,7 @@ The function returns 1 to indicate successful execution. This public function allows an account approved in the public `minters` mapping to create new private tokens that can be claimed by anyone that has the pre-image to the `secret_hash`. -First, public storage is initialized. Then it checks that the `msg_sender` is an approved minter. Then a new `TransparentNote` is created with the specified `amount` and `secret_hash`. You can read the details of the `TransparentNote` in the `types.nr` file [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-contracts/contracts/token_contract/src/types.nr#L61). The `amount` is added to the existing public `total_supply` and the storage value is updated. Then the new `TransparentNote` is added to the `pending_shields` using the `insert_from_public` function, which is accessible on the `PrivateSet` type. Then it's ready to be claimed by anyone with the `secret_hash` pre-image using the `redeem_shield` function. It returns `1` to indicate successful execution. +First, public storage is initialized. Then it checks that the `msg_sender` is an approved minter. Then a new `TransparentNote` is created with the specified `amount` and `secret_hash`. You can read the details of the `TransparentNote` in the `types.nr` file [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-contracts/contracts/token_contract/src/types.nr#L61). The `amount` is added to the existing public `total_supply` and the storage value is updated. Then the new `TransparentNote` is added to the `pending_shields` using the `insert_from_public` function, which is accessible on the `PrivateSet` type. Then it's ready to be claimed by anyone with the `secret_hash` pre-image using the `redeem_shield` function. It returns `1` to indicate successful execution. #include_code mint_private /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust @@ -265,7 +261,7 @@ Storage is referenced as `storage.variable`. This private function enables an account to move tokens from a `TransparentNote` in the `pending_shields` mapping to a `TokenNote` in private `balances`. The `TokenNote` will be associated with a nullifier key, so any account that knows this key can spend this note. -Going through the function logic, first the `secret_hash` is generated from the given secret. This ensures that only the entity possessing the secret can use it to redeem the note. Following this, a `TransparentNote` is retrieved from the set, using the provided amount and secret. The note is subsequently removed from the set, allowing it to be redeemed only once. The recipient's private balance is then increased using the `increment` helper function from the `value_note` [library](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/value-note/src/utils.nr). +Going through the function logic, first the `secret_hash` is generated from the given secret. This ensures that only the entity possessing the secret can use it to redeem the note. Following this, a `TransparentNote` is retrieved from the set, using the provided amount and secret. The note is subsequently removed from the set, allowing it to be redeemed only once. The recipient's private balance is then increased using the `increment` helper function from the `value_note` [library (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/value-note/src/utils.nr). The function returns `1` to indicate successful execution. @@ -355,13 +351,13 @@ Unconstrained functions are similar to `view` functions in Solidity in that they #### `balance_of_private` -A getter function for checking the private balance of the provided Aztec account. Note that the [Private Execution Environment (PXE)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/yarn-project/pxe) must have `ivsk` ([incoming viewing secret key](../../aztec/concepts/accounts/keys.md##incoming-viewing-keys)) in order to decrypt the notes. +A getter function for checking the private balance of the provided Aztec account. Note that the [Private Execution Environment (PXE) (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/yarn-project/pxe) must have `ivsk` ([incoming viewing secret key](../../../aztec/concepts/accounts/keys.md#incoming-viewing-keys)) in order to decrypt the notes. #include_code balance_of_private /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust ## Compiling -Now that the contract is complete, you can compile it with `aztec-nargo`. See the [Sandbox reference page](../../reference/sandbox_reference/index.md) for instructions on setting it up. +Now that the contract is complete, you can compile it with `aztec-nargo`. See the [Sandbox reference page](../../../reference/developer_references/sandbox_reference/index.md) for instructions on setting it up. Run the following command in the directory where your `Nargo.toml` file is located: @@ -379,7 +375,7 @@ aztec codegen target -o src/artifacts ### Token Bridge Contract -The [token bridge tutorial](advanced/token_bridge/index.md) is a great follow up to this one. +The [token bridge tutorial](./advanced/token_bridge/index.md) is a great follow up to this one. It builds on the Token contract described here and goes into more detail about Aztec contract composability and Ethereum (L1) and Aztec (L2) cross-chain messaging. @@ -387,7 +383,7 @@ It builds on the Token contract described here and goes into more detail about A - Review [the end to end tests (Github link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/end-to-end/src/e2e_token_contract/) for reference. - [Commitments (Wikipedia link)](https://en.wikipedia.org/wiki/Commitment_scheme) -- [Nullifiers](../../aztec/concepts/storage/trees/index.md#nullifier-tree) -- [Contract Communication](../../aztec/concepts/smart_contracts/communication/index.md). -- [Contract Storage](../../aztec/concepts/storage/index.md) -- [Authwit](../../aztec/concepts/accounts/authwit.md) +- [Nullifiers](../../../aztec/concepts/storage/trees/index.md#nullifier-tree) +- [Contract Communication](../../../aztec/smart_contracts/communication/index.md). +- [Contract Storage](../../../aztec/concepts/storage/index.md) +- [Authwit](../../../aztec/concepts/accounts/authwit.md) diff --git a/docs/docs/tutorials/contract_tutorials/write_accounts_contract.md b/docs/docs/tutorials/codealong/contract_tutorials/write_accounts_contract.md similarity index 90% rename from docs/docs/tutorials/contract_tutorials/write_accounts_contract.md rename to docs/docs/tutorials/codealong/contract_tutorials/write_accounts_contract.md index a8c4219af96..89e0d382293 100644 --- a/docs/docs/tutorials/contract_tutorials/write_accounts_contract.md +++ b/docs/docs/tutorials/codealong/contract_tutorials/write_accounts_contract.md @@ -17,13 +17,13 @@ You will learn: Writing your own account contract allows you to define the rules by which user transactions are authorized and paid for, as well as how user keys are managed (including key rotation and recovery). In other words, writing an account contract lets you make the most out of account abstraction in the Aztec network. -It is highly recommended that you understand how an [account](../../aztec/concepts/accounts/index.md) is defined in Aztec, as well as the differences between privacy and authentication [keys](../../aztec/concepts/accounts/keys.md). You will also need to know how to write a contract in Noir, as well as some basic [Typescript](https://www.typescriptlang.org/). +It is highly recommended that you understand how an [account](../../../aztec/concepts/accounts/index.md) is defined in Aztec, as well as the differences between privacy and authentication [keys](../../../aztec/concepts/accounts/keys.md). You will also need to know how to write a contract in Noir, as well as some basic [Typescript](https://www.typescriptlang.org/). For this tutorial, we will write an account contract that uses Schnorr signatures for authenticating transaction requests. Every time a transaction payload is passed to this account contract's `entrypoint` function, the account contract requires a valid Schnorr signature, whose signed message matches the transaction payload, and whose signer matches the account contract owner's public key. If the signature fails, the transaction will fail. -For the sake of simplicity, we will hardcode the signing public key into the contract, but you could store it [in a private note](../../aztec/concepts/accounts/keys.md#using-a-private-note), [in an immutable note](../../aztec/concepts/accounts/keys.md#using-an-immutable-private-note), or [on a separate keystore](../../aztec/concepts/accounts/keys.md#using-a-separate-keystore), to mention a few examples. +For the sake of simplicity, we will hardcode the signing public key into the contract, but you could store it [in a private note](../../../aztec/concepts/accounts/keys.md#using-a-private-note), [in an immutable note](../../../aztec/concepts/accounts/keys.md#using-an-immutable-private-note), or [on a separate keystore](../../../aztec/concepts/accounts/keys.md#using-a-separate-keystore), to mention a few examples. ## Contract @@ -85,7 +85,7 @@ More signing schemes are available in case you want to experiment with other typ Let's try creating a new account backed by our account contract, and interact with a simple token contract to test it works. -To create and deploy the account, we will use the `AccountManager` class, which takes an instance of an Private Execution Environment (PXE), a [privacy private key](../../aztec/concepts/accounts/keys.md#incoming-viewing-keys), and an instance of our `AccountContract` class: +To create and deploy the account, we will use the `AccountManager` class, which takes an instance of an Private Execution Environment (PXE), a [privacy private key](../../../aztec/concepts/accounts/keys.md#incoming-viewing-keys), and an instance of our `AccountContract` class: #include_code account-contract-deploy yarn-project/end-to-end/src/guides/writing_an_account_contract.test.ts typescript @@ -111,6 +111,6 @@ Follow the token contract tutorial on the [next page](./token_contract.md) and l - [ECDSA signer account contract (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/noir-contracts/contracts/ecdsa_account_contract/src/main.nr) - [Schnorr signer account contract (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/schnorr_account_contract) -- [Account abstraction](../../aztec/concepts/accounts/index.md#what-is-account-abstraction) -- [Authentication witness](../../aztec/concepts/accounts/authwit.md) -- [Fee abstraction](../../protocol-specs/gas-and-fees/tx-setup-and-teardown.md). +- [Account abstraction](../../../aztec/concepts/accounts/index.md#what-is-account-abstraction) +- [Authentication witness](../../../aztec/concepts/accounts/authwit.md) +- [Fee abstraction](../../../protocol-specs/gas-and-fees/tx-setup-and-teardown.md). diff --git a/docs/docs/tutorials/simple_dapp/0_project_setup.md b/docs/docs/tutorials/codealong/simple_dapp/0_project_setup.md similarity index 100% rename from docs/docs/tutorials/simple_dapp/0_project_setup.md rename to docs/docs/tutorials/codealong/simple_dapp/0_project_setup.md diff --git a/docs/docs/tutorials/simple_dapp/1_pxe_service.md b/docs/docs/tutorials/codealong/simple_dapp/1_pxe_service.md similarity index 81% rename from docs/docs/tutorials/simple_dapp/1_pxe_service.md rename to docs/docs/tutorials/codealong/simple_dapp/1_pxe_service.md index 784beaa81e2..43a30472225 100644 --- a/docs/docs/tutorials/simple_dapp/1_pxe_service.md +++ b/docs/docs/tutorials/codealong/simple_dapp/1_pxe_service.md @@ -2,9 +2,9 @@ PXE is a component of the Aztec Protocol that provides a private execution environment for your application. -As an app developer, the [PXE](../../aztec/concepts/pxe/index.md) interface provides you with access to the user's accounts and their private state, as well as a connection to the network for accessing public global state. +As an app developer, the PXE interface provides you with access to the user's accounts and their private state, as well as a connection to the network for accessing public global state. -During the Sandbox phase, this role is fulfilled by the [Aztec Sandbox](../../reference/sandbox_reference/index.md), which runs a local PXE and an Aztec Node, both connected to a local Ethereum development node like Anvil. +During the Sandbox phase, this role is fulfilled by the [Aztec Sandbox](../../../reference/developer_references/sandbox_reference/index.md), which runs a local PXE and an Aztec Node, both connected to a local Ethereum development node like Anvil. The Sandbox also includes a set of pre-initialized accounts that you can use from your app. In this section, we'll connect to the Sandbox from our project. diff --git a/docs/docs/tutorials/simple_dapp/2_contract_deployment.md b/docs/docs/tutorials/codealong/simple_dapp/2_contract_deployment.md similarity index 87% rename from docs/docs/tutorials/simple_dapp/2_contract_deployment.md rename to docs/docs/tutorials/codealong/simple_dapp/2_contract_deployment.md index 34d56026835..4b7738a8ac6 100644 --- a/docs/docs/tutorials/simple_dapp/2_contract_deployment.md +++ b/docs/docs/tutorials/codealong/simple_dapp/2_contract_deployment.md @@ -3,7 +3,7 @@ To add contracts to your application, we'll start by creating a new `aztec-nargo` project. We'll then compile the contracts, and write a simple script to deploy them to our Sandbox. :::info -Follow the instructions [here](../../reference/sandbox_reference/index.md) to install `aztec-nargo` if you haven't done so already. +Follow the instructions [here](../../../reference/developer_references/sandbox_reference/index.md) to install `aztec-nargo` if you haven't done so already. ::: ## Initialize Aztec project @@ -30,7 +30,7 @@ Last, copy-paste the code from the `Token` contract into `contracts/token/main.n ### Helper files -The `Token` contract also requires some helper files. You can view the files [here](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/token_contract/src). Copy the `types.nr` and the `types` folder into `contracts/token/src`. +The `Token` contract also requires some helper files. You can view the files [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/token_contract/src). Copy the `types.nr` and the `types` folder into `contracts/token/src`. ## Compile your contract @@ -69,7 +69,7 @@ We import the contract artifacts we have generated plus the dependencies we'll n Note that the token's `_initialize()` method expects an `owner` address to mint an initial set of tokens to. We are using the first account from the Sandbox for this. :::info -If you are using the generated typescript classes, you can drop the generic `ContractDeployer` in favor of using the `deploy` method of the generated class, which will automatically load the artifact for you and type-check the constructor arguments. SEe the [How to deploy a contract](../../guides/smart_contracts/how_to_deploy_contract.md) page for more info. +If you are using the generated typescript classes, you can drop the generic `ContractDeployer` in favor of using the `deploy` method of the generated class, which will automatically load the artifact for you and type-check the constructor arguments. SEe the [How to deploy a contract](../../../guides/developer_guides/smart_contracts/how_to_deploy_contract.md) page for more info. ::: Run the snippet above as `node src/deploy.mjs`, and you should see the following output, along with a new `addresses.json` file in your project root: diff --git a/docs/docs/tutorials/simple_dapp/3_contract_interaction.md b/docs/docs/tutorials/codealong/simple_dapp/3_contract_interaction.md similarity index 91% rename from docs/docs/tutorials/simple_dapp/3_contract_interaction.md rename to docs/docs/tutorials/codealong/simple_dapp/3_contract_interaction.md index db1ce5b5964..af7efd5e2b9 100644 --- a/docs/docs/tutorials/simple_dapp/3_contract_interaction.md +++ b/docs/docs/tutorials/codealong/simple_dapp/3_contract_interaction.md @@ -11,7 +11,7 @@ Let's start by showing our user's private balance for the token across their acc #include_code balance_of_private noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust :::info -Note that this function will only return a valid response for accounts registered in the Private eXecution Environment (PXE), since it requires access to the [user's private state](../../aztec/concepts/wallets/index.md#private-state). In other words, you cannot query the private balance of another user for the token contract. +Note that this function will only return a valid response for accounts registered in the Private eXecution Environment (PXE), since it requires access to the [user's private state](../../../aztec/concepts/wallets/index.md#private-state). In other words, you cannot query the private balance of another user for the token contract. ::: To do this, let's first initialize a new `Contract` instance using `aztec.js` that represents our deployed token contracts. Create a new `src/contracts.mjs` file with the imports for our artifacts and other dependencies: @@ -95,12 +95,12 @@ At the time of this writing, there are no events emitted when new private notes ## Working with public state -While [private and public state](../../aztec/concepts/state_model/index.md) are fundamentally different, the API for working with private and public functions and state from `aztec.js` is equivalent. To query the balance in public tokens for our user accounts, we can just call the `balance_of_public` view function in the contract: +While [private and public state](../../../aztec/concepts/state_model/index.md) are fundamentally different, the API for working with private and public functions and state from `aztec.js` is equivalent. To query the balance in public tokens for our user accounts, we can just call the `balance_of_public` view function in the contract: #include_code showPublicBalances yarn-project/end-to-end/src/sample-dapp/index.mjs javascript :::info -Since this we are working with pubic balances, we can now query the balance for any address, not just those registered in our local PXE. We can also send funds to addresses for which we don't know their [public encryption key](../../aztec/concepts/accounts/keys.md#encryption-keys). +Since this we are working with pubic balances, we can now query the balance for any address, not just those registered in our local PXE. We can also send funds to addresses for which we don't know their [public encryption key](../../../aztec/concepts/accounts/keys.md#encryption-keys). ::: Here, since the token contract does not mint any initial funds upon deployment, the balances for all of our user's accounts will be zero. diff --git a/docs/docs/tutorials/simple_dapp/4_testing.md b/docs/docs/tutorials/codealong/simple_dapp/4_testing.md similarity index 90% rename from docs/docs/tutorials/simple_dapp/4_testing.md rename to docs/docs/tutorials/codealong/simple_dapp/4_testing.md index 4261eb8a75b..e6f89bbf86e 100644 --- a/docs/docs/tutorials/simple_dapp/4_testing.md +++ b/docs/docs/tutorials/codealong/simple_dapp/4_testing.md @@ -14,7 +14,7 @@ Start by installing our test runner, in this case jest: yarn add -D jest ``` -We'll need to [install and run the Sandbox](../../reference/sandbox_reference/index.md#installation). +We'll need to [install and run the Sandbox](../../../reference/developer_references/sandbox_reference/sandbox-reference.md). ## Test setup @@ -67,4 +67,4 @@ yarn node --experimental-vm-modules $(yarn bin jest) --testRegex '.*\.test\.mjs$ ## Next steps -Now that you have finished the tutorial, you can learn more about [writing contracts with Noir](../../aztec/concepts/smart_contracts/index.md) or read about the [fundamental concepts behind Aztec Network](../../aztec/core_components.md). +Now that you have finished the tutorial, you can learn more about [writing contracts with Noir](../../../aztec/smart_contracts_overview.md) or read about the [fundamental concepts behind Aztec Network](../../../aztec/overview.md). diff --git a/docs/docs/tutorials/simple_dapp/index.md b/docs/docs/tutorials/codealong/simple_dapp/index.md similarity index 89% rename from docs/docs/tutorials/simple_dapp/index.md rename to docs/docs/tutorials/codealong/simple_dapp/index.md index 82f4b18a583..3300cca55a6 100644 --- a/docs/docs/tutorials/simple_dapp/index.md +++ b/docs/docs/tutorials/codealong/simple_dapp/index.md @@ -4,7 +4,7 @@ title: Dapp Tutorial In this tutorial we'll go through the steps for building a simple application that interacts with the Aztec Sandbox. We'll be building a console application using Javascript and NodeJS, but you may reuse the same concepts here for a web-based app. All Aztec libraries are written in Typescript and fully typed, so you can use Typescript instead of Javascript to make the most out of its type checker. -This tutorial will focus on environment setup, including creating accounts and deployments, as well as interacting with your contracts. It will not cover [how to write contracts in Noir](../../aztec/concepts/smart_contracts/index.md). +This tutorial will focus on environment setup, including creating accounts and deployments, as well as interacting with your contracts. It will not cover [how to write contracts in Noir](../../../aztec/smart_contracts_overview.md). The full code for this tutorial is [available on the `aztec-packages` repository](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/end-to-end/src/sample-dapp). @@ -12,7 +12,7 @@ The full code for this tutorial is [available on the `aztec-packages` repository - Linux or OSX environment - [NodeJS](https://nodejs.org/) 18 or higher -- [Aztec Sandbox](../../getting_started.md) +- [Aztec Sandbox](../../../guides/developer_guides/getting_started/quickstart.md) ## Prerequisites diff --git a/docs/docs/reference/smart_contract_reference/examples/_category_.json b/docs/docs/tutorials/examples/_category_.json similarity index 100% rename from docs/docs/reference/smart_contract_reference/examples/_category_.json rename to docs/docs/tutorials/examples/_category_.json diff --git a/docs/docs/reference/smart_contract_reference/examples/uniswap/_category_.json b/docs/docs/tutorials/examples/uniswap/_category_.json similarity index 100% rename from docs/docs/reference/smart_contract_reference/examples/uniswap/_category_.json rename to docs/docs/tutorials/examples/uniswap/_category_.json diff --git a/docs/docs/reference/smart_contract_reference/examples/uniswap/e2e_tests.md b/docs/docs/tutorials/examples/uniswap/e2e_tests.md similarity index 100% rename from docs/docs/reference/smart_contract_reference/examples/uniswap/e2e_tests.md rename to docs/docs/tutorials/examples/uniswap/e2e_tests.md diff --git a/docs/docs/reference/smart_contract_reference/examples/uniswap/index.md b/docs/docs/tutorials/examples/uniswap/index.md similarity index 88% rename from docs/docs/reference/smart_contract_reference/examples/uniswap/index.md rename to docs/docs/tutorials/examples/uniswap/index.md index 91dd4fe0194..c4fc55b539f 100644 --- a/docs/docs/reference/smart_contract_reference/examples/uniswap/index.md +++ b/docs/docs/tutorials/examples/uniswap/index.md @@ -15,7 +15,7 @@ The flow will be: 2. We create an L2 → L1 message to swap on L1 3. On L1, the user gets their input tokens, consumes the swap message, and executes the swap 4. The user deposits the “output” tokens to the output token portal so it can be deposited into L2 -5. We will assume that token portals and token bridges for the input and output tokens must exist. These are what we built in the [token bridge tutorial](../../../../tutorials/contract_tutorials/advanced/token_bridge/0_setup.md). +5. We will assume that token portals and token bridges for the input and output tokens must exist. These are what we built in the [token bridge tutorial](../../codealong/contract_tutorials/advanced/token_bridge/index.md). The execution of swap on L1 should be designed such that any 3rd party can execute the swap on behalf of the user. This helps maintain user privacy by not requiring links between L1 and L2 activity. @@ -27,5 +27,5 @@ This reference will cover: This diagram describes the private flow. -This code works alongside a token portal that you can learn to build [in this tutorial](../../../../tutorials/contract_tutorials/advanced/token_bridge/0_setup.md). +This code works alongside a token portal that you can learn to build [in this codealong tutorial](../../codealong/contract_tutorials/advanced/token_bridge/index.md). diff --git a/docs/docs/reference/smart_contract_reference/examples/uniswap/l1_contract.md b/docs/docs/tutorials/examples/uniswap/l1_contract.md similarity index 90% rename from docs/docs/reference/smart_contract_reference/examples/uniswap/l1_contract.md rename to docs/docs/tutorials/examples/uniswap/l1_contract.md index cbb164b26f6..6eb246a7c18 100644 --- a/docs/docs/reference/smart_contract_reference/examples/uniswap/l1_contract.md +++ b/docs/docs/tutorials/examples/uniswap/l1_contract.md @@ -3,7 +3,7 @@ title: L1 contracts (EVM) sidebar_position: 2 --- -This page goes over the code in the L1 contract for Uniswap, which works alongside a [token portal](../../../../tutorials/contract_tutorials/advanced/token_bridge/index.md). +This page goes over the code in the L1 contract for Uniswap, which works alongside a [token portal (codealong tutorial)](../../codealong/contract_tutorials/advanced/token_bridge/index.md). ## Setup @@ -26,7 +26,7 @@ This page goes over the code in the L1 contract for Uniswap, which works alongsi To incentivize the sequencer to pick up this message, we pass a fee to the deposit message. -You can find the corresponding function on the [L2 contracts page](l2_contract.md#public-swap). +You can find the corresponding function on the [L2 contracts page](./l2_contract.md#public-swap). ## Private swap @@ -34,4 +34,4 @@ This works very similarly to the public flow. #include_code solidity_uniswap_swap_private l1-contracts/test/portals/UniswapPortal.sol solidity -You can find the corresponding function on the [L2 contracts page](l2_contract.md#private-swap). +You can find the corresponding function on the [L2 contracts page](./l2_contract.md#private-swap). diff --git a/docs/docs/reference/smart_contract_reference/examples/uniswap/l2_contract.md b/docs/docs/tutorials/examples/uniswap/l2_contract.md similarity index 88% rename from docs/docs/reference/smart_contract_reference/examples/uniswap/l2_contract.md rename to docs/docs/tutorials/examples/uniswap/l2_contract.md index 3ead8d76254..da656ec2b2c 100644 --- a/docs/docs/reference/smart_contract_reference/examples/uniswap/l2_contract.md +++ b/docs/docs/tutorials/examples/uniswap/l2_contract.md @@ -3,7 +3,7 @@ title: L2 Contracts (Aztec) sidebar_position: 1 --- -This page goes over the code in the L2 contract for Uniswap, which works alongside a [token bridge](../../../../tutorials/contract_tutorials/advanced/token_bridge/0_setup.md). +This page goes over the code in the L2 contract for Uniswap, which works alongside a [token bridge (codealong tutorial)](../../codealong/contract_tutorials/advanced/token_bridge/index.md). ## Main.nr @@ -17,11 +17,11 @@ We just need to store the portal address for the token that we want to swap. #include_code swap_public noir-projects/noir-contracts/contracts/uniswap_contract/src/main.nr rust -1. We check that `msg.sender()` has appropriate approval to call this on behalf of the sender by constructing an authwit message and checking if `from` has given the approval (read more about authwit [here](../../../../aztec/concepts/accounts/authwit.md)). +1. We check that `msg.sender()` has appropriate approval to call this on behalf of the sender by constructing an authwit message and checking if `from` has given the approval (read more about authwit [here](../../../aztec/concepts/accounts/authwit.md)). 2. We fetch the underlying aztec token that needs to be swapped. 3. We transfer the user’s funds to the Uniswap contract. Like with Ethereum, the user must have provided approval to the Uniswap contract to do so. The user must provide the nonce they used in the approval for transfer, so that Uniswap can send it to the token contract, to prove it has appropriate approval. 4. Funds are added to the Uniswap contract. -5. Uniswap must exit the input tokens to L1. For this it has to approve the bridge to burn its tokens on its behalf and then actually exit the funds. We call the [`exit_to_l1_public()` method on the token bridge](../../../../tutorials/contract_tutorials/advanced/token_bridge/index.md). We use the public flow for exiting since we are operating on public state. +5. Uniswap must exit the input tokens to L1. For this it has to approve the bridge to burn its tokens on its behalf and then actually exit the funds. We call the [`exit_to_l1_public()` method on the token bridge](../../codealong/contract_tutorials/advanced/token_bridge/index.md). We use the public flow for exiting since we are operating on public state. 6. It is not enough for us to simply emit a message to withdraw the funds. We also need to emit a message to display our swap intention. If we do not do this, there is nothing stopping a third party from calling the Uniswap portal with their own parameters and consuming our message. So the Uniswap portal (on L1) needs to know: @@ -36,7 +36,7 @@ The Uniswap portal must first withdraw the input tokens, then check that the swa - The address on L2 which must receive the output tokens (remember this is public flow) - The secret hash for consume the L1 to L2 message. Since this is the public flow the preimage doesn’t need to be a secret. -You can find the corresponding function on the [L1 contracts page](l1_contract.md). +You can find the corresponding function on the [L1 contracts page](./l1_contract.md). ### Private swap @@ -84,6 +84,6 @@ So you emitted a message to withdraw input tokens to L1 and a message to swap. T You still need to "claim" these swapped funds on L2. -In the public flow, you can call [`claim_public()`](../../../../tutorials/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md) on the output token bridge which consumes the deposit message and mints your assets. +In the public flow, you can call [`claim_public()`](../../codealong/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md) on the output token bridge which consumes the deposit message and mints your assets. -In the private flow, you can choose to leak your secret for L1 → L2 message consumption to let someone mint the notes on L2 (by calling [`claim_private()`](../../../../tutorials/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md) on the output token bridge) and then you can later redeem these notes to yourself by presenting the preimage to `secret_hash_for_redeeming_minted_notes` and calling the `redeem_shield()` method on the token contract. \ No newline at end of file +In the private flow, you can choose to leak your secret for L1 → L2 message consumption to let someone mint the notes on L2 (by calling [`claim_private()`](../../codealong/contract_tutorials/advanced/token_bridge/2_minting_on_aztec.md) on the output token bridge) and then you can later redeem these notes to yourself by presenting the preimage to `secret_hash_for_redeeming_minted_notes` and calling the `redeem_shield()` method on the token contract. diff --git a/docs/docs/tutorials/index.md b/docs/docs/tutorials/index.md new file mode 100644 index 00000000000..541dcee83eb --- /dev/null +++ b/docs/docs/tutorials/index.md @@ -0,0 +1,112 @@ +--- +id: index +sidebar_position: 0 +title: Tutorials and Examples +--- + +# Code-Along Tutorials and Examples + +In this section, you will find two things: code-along tutorials and code examples of Aztec applications. + +Tutorials will teach you how to build a full application or smart contract locally. Examples are not intended for you to replicate locally as they have more complex setups, but can be useful for exploring what you can do with Aztec. + +This page includes the most popular tutorials in order of increasing complexity. Explore the sidebar for more! + +## Code-Along Tutorials + +### Beginner: Write your first smart contract + +
+ + +

Simple counter contract

+ + + Follow this tutorial to build, compile and deploy your first Aztec smart contract - a simple private counter + + +
+ + +### Intermediate: Write increasingly more complex contracts + +It is recommended to follow these in order. + +
+ + +

Simple private voting contract

+ + + Build a contract with hybrid state and calling public functions from private + + + + + +

Crowdfunding contract

+ + + A more complex contract that interacts with other contracts + + + + + +

Token contract with hybrid state

+ + + A very complex contract for a token that can move across public & private state and be transferred to others + + + + + +

Accounts contract

+ + + A simple accounts contract that will teach you about account abstraction in Aztec + + +
+ + + +## Examples + +
+ + +

Interacting with L1 Uniswap from L2 Aztec

+ + + An example app inspired by Aztec Connect that allows users to swap publicly & privately on L1 Uniswap from Aztec + + + + + + + + +

Card game contract ↗️

+ + + A set of contracts that allow players to take turns playing cards + + +
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index be1b316d126..f46a98abadf 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -131,7 +131,7 @@ const config = { entryPoints: ["../yarn-project/circuit-types/src/interfaces/pxe.ts"], tsconfig: "../yarn-project/circuit-types/tsconfig.json", entryPointStrategy: "expand", - out: "reference/aztecjs/pxe", + out: "reference/developer_references/aztecjs/pxe", readme: "none", sidebar: { categoryLabel: "Private Execution Environment (PXE)", @@ -149,7 +149,7 @@ const config = { ], tsconfig: "../yarn-project/aztec.js/tsconfig.json", entryPointStrategy: "resolve", - out: "reference/aztecjs/aztec-js", + out: "reference/developer_references/aztecjs/aztec-js", readme: "none", sidebar: { categoryLabel: "Aztec.js", @@ -170,7 +170,7 @@ const config = { ], tsconfig: "../yarn-project/accounts/tsconfig.json", entryPointStrategy: "resolve", - out: "reference/aztecjs/accounts", + out: "reference/developer_references/aztecjs/accounts", readme: "none", sidebar: { categoryLabel: "Accounts", @@ -219,15 +219,111 @@ const config = { items: [ { type: "doc", - docId: "index", + docId: "aztec/overview", position: "left", - label: "Aztec Protocol", + label: "Concepts", }, { type: "docSidebar", - sidebarId: "protocolSpecSidebar", + sidebarId: "guidesSidebar", position: "left", - label: "Protocol Specification", + label: "Guides", + }, + { + type: "docSidebar", + sidebarId: "tutorialsSidebar", + position: "left", + label: "Examples", + }, + { + type: "docSidebar", + sidebarId: "referenceSidebar", + position: "left", + label: "References", + }, + { + type: "dropdown", + label: "Resources", + position: "left", + items: [ + { + type: "html", + value: 'GitHub', + className: "dropdown-subtitle", + }, + { + to: "https://github.com/AztecProtocol/aztec-packages", + label: "Aztec Monorepo", + target: "_blank", + rel: "noopener noreferrer", + className: "github-item", + }, + { + to: "https://github.com/AztecProtocol/aztec-nr", + label: "Aztec.nr", + target: "_blank", + rel: "noopener noreferrer", + className: "github-item", + }, + { + to: "https://github.com/AztecProtocol/awesome-aztec", + label: "Awesome Aztec", + target: "_blank", + rel: "noopener noreferrer", + className: "github-item", + }, + { + type: "html", + value: 'Other Docs', + className: "dropdown-subtitle", + }, + { + to: "/migration_notes", + label: "Migration Notes", + className: "no-external-icon", + }, + { + to: "/aztec_connect_sunset", + label: "Aztec Connect Sunset", + className: "no-external-icon", + }, + { + type: "docSidebar", + sidebarId: "protocolSpecSidebar", + target: "_blank", + label: "Protocol Specification", + }, + { + type: "docSidebar", + sidebarId: "roadmapSidebar", + target: "_blank", + label: "Roadmap", + }, + { + to: "https://noir-lang.org/docs", + label: "Noir docs", + target: "_blank", + rel: "noopener noreferrer", + }, + { + type: "html", + value: 'Support', + className: "dropdown-subtitle", + }, + { + to: "https://airtable.com/appMhZd7lsZS3v27R/pagxWYAHYYrnrrXmm/form", + label: "Join community", + target: "_blank", + rel: "noopener noreferrer", + }, + { + to: "https://twitter.com/aztecprotocol", + label: "X/Twitter", + target: "_blank", + rel: "noopener noreferrer", + className: "twitter-item", + }, + ], }, ], }, @@ -243,7 +339,7 @@ const config = { }, { label: "Developer Quickstart", - to: "/getting_started", + to: "/guides/developer_guides/getting_started/quickstart", }, { label: "Aztec.nr", @@ -263,7 +359,7 @@ const config = { href: "https://discord.gg/DgWG2DBMyB", }, { - label: "Twitter", + label: "X/Twitter", href: "https://twitter.com/aztecnetwork", }, { @@ -293,8 +389,9 @@ const config = { copyright: `Copyright © ${new Date().getFullYear()} Aztec, built with Docusaurus, powered by Netlify.`, }, prism: { - theme: lightTheme, - darkTheme: darkTheme, + theme: themes.nightOwlLight, + darkTheme: themes.shadesOfPurple, + // darkTheme: themes.dracula, // https://prismjs.com/#supported-languages // Commented-out languages exists in `node_modules/prismjs/components/` so I'm not sure why they don't work. additionalLanguages: [ @@ -306,7 +403,6 @@ const config = { // "typescript", "json", // "bash", - // "solidity", "toml", "markdown", "docker", diff --git a/docs/netlify.toml b/docs/netlify.toml index 9dc2eb71d85..d1aef404fb3 100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@ -1,18 +1,18 @@ [[redirects]] from = "/developers/tutorials/*" - to = "/tutorials/contract_tutorials/private_voting_contract" + to = "/tutorials/codealong/contract_tutorials/private_voting_contract" [[redirects]] from = "/developers/sandbox/*" - to = "/reference/sandbox_reference" + to = "/reference/developer_references/sandbox_reference" [[redirects]] from = "/developers/contracts/*" - to = "/reference/smart_contract_reference" + to = "/reference/developer_references/smart_contract_reference" [[redirects]] from = "/dev_docs/*" - to = "/getting_started" + to = "/guides/developer_guides/getting_started/quickstart" [[redirects]] from = "/aztec/cryptography/cryptography-roadmap" diff --git a/docs/scripts/clean.sh b/docs/scripts/clean.sh index da22dfd276e..8d27b2091b4 100755 --- a/docs/scripts/clean.sh +++ b/docs/scripts/clean.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash rm -rf 'processed-docs' 'processed-docs-cache' -rm -rf docs/reference/aztecjs 'docs/reference/smart_contract_reference/aztec-nr' +rm -rf 'docs/reference/developer_references/aztecjs' 'docs/reference/developer_references/smart_contract_reference/aztec-nr' docusaurus clear diff --git a/docs/scripts/move_processed.sh b/docs/scripts/move_processed.sh index 8a29b13a16e..b841f2e5eb1 100755 --- a/docs/scripts/move_processed.sh +++ b/docs/scripts/move_processed.sh @@ -1,4 +1,4 @@ #!/usr/bin/env bash -echo "label: \"AztecJS\"" > ./docs/reference/aztecjs/_category_.yml -mv ./docs/reference/aztecjs ./processed-docs/reference/aztecjs -mv ./docs/reference/smart_contract_reference/aztec-nr ./processed-docs/reference/smart_contract_reference/aztec-nr +echo "label: \"AztecJS\"" > ./docs/reference/developer_references/aztecjs/_category_.yml +mv ./docs/reference/developer_references/aztecjs ./processed-docs/reference/developer_references/aztecjs +mv ./docs/reference/developer_references/smart_contract_reference/aztec-nr ./processed-docs/reference/developer_references/smart_contract_reference/aztec-nr diff --git a/docs/sidebars.js b/docs/sidebars.js index b5b0a8fe385..b6b2d2537c0 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -6,49 +6,154 @@ const path = require("path"); /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ export default { sidebar: [ + + { + type: "html", + value: 'Aztec Protocol', + className: "sidebar-title", + }, + { + type: "doc", + id: "aztec/overview", + label: "What is Aztec?", + }, { type: "category", - label: "Aztec", - link: { type: "doc", id: "aztec" }, - items: [{ type: "autogenerated", dirName: "aztec" }], + label: "Concepts", + items: [{ type: "autogenerated", dirName: "aztec/concepts" }], + }, + { + type: "html", + value: 'Network', + className: "sidebar-title", + }, + { + type: "doc", + id: "aztec/network_overview", + label: "Network Overview", + }, + { + type: "category", + label: "Network Infrastructure", + items: [{ type: "autogenerated", dirName: "aztec/network" }], + }, + { + type: "html", + value: 'Smart Contracts', + className: "sidebar-title", + }, + { + type: "doc", + id: "aztec/smart_contracts_overview", + label: "What are Smart Contracts?", + }, + { + type: "category", + label: "Technical Details", + items: [{ type: "autogenerated", dirName: "aztec/smart_contracts" }], + }, + { + type: "html", + value: '', }, { type: "doc", id: "vision", }, + { + type: "doc", + label: "Building in Public", + id: "aztec" + }, + + ], + + guidesSidebar: [ + { + type: "doc", + label: "Popular Guides", + id: "guides/index" + }, + { + type: "html", + value: 'Developer Guides', + className: "sidebar-title", + }, + { + type: "autogenerated", + dirName: "guides/developer_guides" + }, { type: "html", value: '', }, { - type: "category", - label: "Getting Started", - link: { type: "doc", id: "getting_started" }, - items: [{ type: "autogenerated", dirName: "getting_started" }], + type: "doc", + label: "Privacy Considerations", + id: "guides/privacy_considerations" }, + ], + tutorialsSidebar: [ { - type: "category", - label: "Tutorials", - items: [{ type: "autogenerated", dirName: "tutorials" }], + type: "doc", + label: "Tutorials and Examples", + id: "tutorials/index" }, { - type: "category", - label: "Guides", - items: [{ type: "autogenerated", dirName: "guides" }], + type: "html", + value: 'Code-along Tutorials', + className: "sidebar-title", }, { - type: "category", - label: "Reference", - items: [{ type: "autogenerated", dirName: "reference" }], + type: "autogenerated", + dirName: "tutorials/codealong" + }, + { + type: "html", + value: 'Examples', + className: "sidebar-title", + }, + { + type: "autogenerated", + dirName: "tutorials/examples" + }, + ], + + referenceSidebar: [ + { + type: "doc", + label: "References", + id: "reference/index" + }, + { + type: "html", + value: 'Developer References', + className: "sidebar-title", + }, + { + type: "autogenerated", + dirName: "reference/developer_references" + }, + { + type: "doc", + id: "migration_notes", }, { type: "html", value: '', }, - { type: "doc", id: "migration_notes" }, - { type: "doc", id: "aztec_connect_sunset" }, + { + type: "doc", + id: "aztec_connect_sunset", + }, ], + roadmapSidebar: [ + { + type: "autogenerated", + dirName: "aztec/roadmap" + }, + ], protocolSpecSidebar: [ "protocol-specs/intro", { diff --git a/docs/src/components/Disclaimers/_wip_disclaimer.mdx b/docs/src/components/Disclaimers/_wip_disclaimer.mdx index 597f226dc5f..61f31593ea5 100644 --- a/docs/src/components/Disclaimers/_wip_disclaimer.mdx +++ b/docs/src/components/Disclaimers/_wip_disclaimer.mdx @@ -5,7 +5,7 @@ :::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](/aztec/limitations) for details of known Aztec protocol and Aztec Sandbox limitations. +Please see [here](/reference/developer_references/limitations) for details of known Aztec protocol and Aztec Sandbox limitations. If you would like to help us build Aztec: diff --git a/docs/src/components/TutorialCard/CardBody/index.js b/docs/src/components/TutorialCard/CardBody/index.js new file mode 100644 index 00000000000..e2ea76c5eef --- /dev/null +++ b/docs/src/components/TutorialCard/CardBody/index.js @@ -0,0 +1,19 @@ +import React from 'react'; +import clsx from 'clsx'; + +const CardBody = ({ + className, + style, + children, +}) => { + return ( +
+ {children} +
+ ); +} + +export default CardBody; \ No newline at end of file diff --git a/docs/src/components/TutorialCard/CardFooter/index.js b/docs/src/components/TutorialCard/CardFooter/index.js new file mode 100644 index 00000000000..2828f610962 --- /dev/null +++ b/docs/src/components/TutorialCard/CardFooter/index.js @@ -0,0 +1,44 @@ +import React, { CSSProperties } from 'react'; +import clsx from 'clsx'; +const CardFooter = ({ + className, + style, + children, + textAlign, + variant, + italic = false , + noDecoration = false, + transform, + breakWord = false, + truncate = false, + weight, +}) => { + const text = textAlign ? `text--${textAlign}` :''; + const textColor = variant ? `text--${variant}` : ''; + const textItalic = italic ? 'text--italic' : ''; + const textDecoration = noDecoration ? 'text-no-decoration' : ''; + const textType = transform ? `text--${transform}` : ''; + const textBreak = breakWord ? 'text--break' : ''; + const textTruncate = truncate ? 'text--truncate' : ''; + const textWeight = weight ? `text--${weight}` : ''; + return ( +
+ {children} +
+ ); +} +export default CardFooter; \ No newline at end of file diff --git a/docs/src/components/TutorialCard/CardHeader/index.js b/docs/src/components/TutorialCard/CardHeader/index.js new file mode 100644 index 00000000000..e8a81543e0e --- /dev/null +++ b/docs/src/components/TutorialCard/CardHeader/index.js @@ -0,0 +1,44 @@ +import React, { CSSProperties } from 'react'; // CSSProperties allows inline styling with better type checking. +import clsx from 'clsx'; // clsx helps manage conditional className names in a clean and concise manner. +const CardHeader = ({ + className, // classNamees for the container card + style, // Custom styles for the container card + children, // Content to be included within the card + textAlign, + variant, + italic = false , + noDecoration = false, + transform, + breakWord = false, + truncate = false, + weight, +}) => { + const text = textAlign ? `text--${textAlign}` :''; + const textColor = variant ? `text--${variant}` : ''; + const textItalic = italic ? 'text--italic' : ''; + const textDecoration = noDecoration ? 'text-no-decoration' : ''; + const textType = transform ? `text--${transform}` : ''; + const textBreak = breakWord ? 'text--break' : ''; + const textTruncate = truncate ? 'text--truncate' : ''; + const textWeight = weight ? `text--${weight}` : ''; + return ( +
+ {children} +
+ ); +} +export default CardHeader; \ No newline at end of file diff --git a/docs/src/components/TutorialCard/CardImage/index.js b/docs/src/components/TutorialCard/CardImage/index.js new file mode 100644 index 00000000000..731fc074d70 --- /dev/null +++ b/docs/src/components/TutorialCard/CardImage/index.js @@ -0,0 +1,20 @@ +import React, { CSSProperties } from 'react'; +import clsx from 'clsx'; +import useBaseUrl from '@docusaurus/useBaseUrl'; // Import the useBaseUrl function from Docusaurus +const CardImage = ({ + className, + style, + cardImageUrl, + alt, + title, +}) => { + const generatedCardImageUrl = useBaseUrl(cardImageUrl); + return ( + {alt} + ) +} +export default CardImage; \ No newline at end of file diff --git a/docs/src/components/TutorialCard/index.js b/docs/src/components/TutorialCard/index.js new file mode 100644 index 00000000000..6fc607772c4 --- /dev/null +++ b/docs/src/components/TutorialCard/index.js @@ -0,0 +1,35 @@ +import React from 'react'; +import clsx from 'clsx'; +import Link from '@docusaurus/Link'; + +const Card = ({ + className, + style, + children, + shadow, + link, +}) => { + const cardShadow = shadow ? `item shadow--${shadow}` : ''; + + const cardContent = ( +
+ {children} +
+ ); + + if (link) { + return ( + + {cardContent} + + ); + } + + return cardContent; +}; + +export default Card; \ No newline at end of file diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 9b8e22def40..07c07791dfa 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -7,23 +7,99 @@ /* You can override the default Infima variables here. */ :root { --ifm-font-family-base: "Plain-Regular"; + --ifm-color-primary: #8C7EFF; + --ifm-color-primary-dark: #6e5bff; + --ifm-color-primary-darker: #5f4aff; + --ifm-color-primary-darkest: #3216ff; + --ifm-color-primary-light: #aaa1ff; + --ifm-color-primary-lighter: #b9b2ff; + --ifm-color-primary-lightest: #e6e3ff; + --ifm-code-font-size: 95%; + --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); + --ifm-link-color: #8C7EFF; + --ifm-menu-color-active: #8C7EFF; + --ifm-navbar-link-hover-color: #8C7EFF; } +[data-theme="light"] .alert--danger { + --ifm-alert-background-color: #ffd1cb; + --ifm-alert-background-color-highlight: #ffbab1; + --ifm-alert-foreground-color: rgb(66,69,73); + --ifm-alert-border-color: #ff7764; +} + +[data-theme="dark"] .alert--danger { + --ifm-alert-background-color: #962a1c; + --ifm-alert-background-color-highlight: #cf5545; + --ifm-alert-foreground-color: white; + --ifm-alert-border-color: #cf5545; +} + +[data-theme="light"] .alert--warning { + --ifm-alert-background-color: #ffe2b1; + --ifm-alert-background-color-highlight: #ffd998; + --ifm-alert-foreground-color: rgb(66,69,73); + --ifm-alert-border-color: #ffc564; +} + +[data-theme="dark"] .alert--warning { + --ifm-alert-background-color: #5b4b2f; + --ifm-alert-background-color-highlight: #8a6a32; + --ifm-alert-foreground-color: white; + --ifm-alert-border-color: #8a6a32; +} + +[data-theme="light"] .alert--info { + --ifm-alert-background-color: #d8e0fd; + --ifm-alert-background-color-highlight: #c0cdfc; + --ifm-alert-foreground-color: rgb(66,69,73); + --ifm-alert-border-color: #466CF7; +} + +[data-theme="dark"] .alert--info { + --ifm-alert-background-color: #2d2a55; + --ifm-alert-background-color-highlight: #514b99; + --ifm-alert-foreground-color: white; + --ifm-alert-border-color: #514b99 +} + +[data-theme="light"] .alert--secondary { + --ifm-alert-background-color: #d8e0fd; + --ifm-alert-background-color-highlight: #c0cdfc; + --ifm-alert-foreground-color: rgb(66,69,73); + --ifm-alert-border-color: #466CF7; +} + +[data-theme="dark"] .alert--secondary { + --ifm-alert-background-color: #2d2a55; + --ifm-alert-background-color-highlight: #514b99; + --ifm-alert-foreground-color: white; + --ifm-alert-border-color: #514b99; +} + +[data-theme="light"] .alert--success { + --ifm-alert-background-color: #ccf0e3; + --ifm-alert-background-color-highlight: #b8ead8; + --ifm-alert-foreground-color: rgb(66,69,73); + --ifm-alert-border-color: #31A67B; +} + +[data-theme="dark"] .alert--success { + --ifm-alert-background-color: #34584a; + --ifm-alert-background-color-highlight: #69b799; + --ifm-alert-foreground-color:white; + --ifm-alert-border-color: #69b799; +} + + [data-theme="light"] { - --ifm-color-primary: #9f3fff; - --ifm-color-primary-dark: #8f1fff; - --ifm-color-primary-darker: #870fff; - --ifm-color-primary-darkest: #6f00df; - --ifm-color-primary-light: #af5fff; - --ifm-color-primary-lighter: #b76fff; - --ifm-color-primary-lightest: #cf9eff; - --ifm-breadcrumb-item-background-active: #e9ddf7; + --ifm-background-color: #ffffff; + --ifm-navbar-background-color: #ffffff; + --ifm-footer-background-color: #ffffff; --ifm-menu-color: #2f1f49; - /* --ifm-menu-color-background-active: #e9ddf7; */ - background: #f6fbfc; + --ifm-breadcrumb-item-background-active: #EEEDF1; color: #2f1f49; } -/* For readability concerns, you should choose a lighter palette in dark mode. */ [data-theme="dark"] { --ifm-color-primary: #9ba5e9; --ifm-color-primary-dark: #7b88e2; @@ -52,16 +128,20 @@ } [data-theme="light"] .navbar { - background-color: #f6fbfc; + background-color: #fcfbfc; } [data-theme="light"] .footer { - --ifm-footer-background-color: #f6fbfc; + --ifm-footer-background-color: #fcfbfc; --ifm-footer-color: #2f1f49; --ifm-footer-link-color: #2f1f49; --ifm-footer-title-color: #2f1f49; } +[data-theme="dark"] .card { + background-color: #321E4C; +} + [data-theme="light"] { /* --docusaurus-highlighted-code-line-bg: rgb(72, 77, 91); */ --docusaurus-highlighted-code-line-bg: rgba(230, 211, 238, 0.75); @@ -74,6 +154,40 @@ --docusaurus-highlighted-code-line-bg: rgb(72, 77, 91); } +[data-theme="light"] h1, [data-theme="light"] h2 { + color: #321E4C; +} + +[data-theme="light"] h3, [data-theme="light"] h4, [data-theme="light"] h5, [data-theme="light"] h6 { + color: #514167 +} + +ul li::marker { + color: #8C7EFF; +} + +a { + color: #8C7EFF; +} + +/* Style for tip admonitions */ +.admonition-tip { + background-color: rgba(49, 166, 123, 0.1); + border-left-color: #31A67B; +} + +.admonition-tip .admonition-icon svg { + fill: #31A67B; +} + +.admonition-warning, .admonition-danger { + background-color: rgba(255, 119, 100, 0.1); + border-left-color: #FF7764; +} + +.admonition-warning .admonition-icon svg, .admonition-danger .admonition-icon svg { + fill: #FF7764; +} .code-block-error-line { background-color: #f0000038; display: block; @@ -140,3 +254,154 @@ html[data-theme="dark"] .sidebar-divider { display: flex; justify-content: center; } + +.navbar .dropdown__link { + display: flex; + align-items: center; +} + +.navbar .dropdown__link::after { + content: '\2197'; + margin-left: 5px; +} + +.header-github-link:hover { + opacity: 0.6; +} + +.header-github-link::before { + content: ''; + width: 24px; + height: 24px; + display: flex; + background: url('../../static/img/logos/github_light_mode.svg') no-repeat; +} + +[data-theme='dark'] .header-github-link::before { + background: url('../../static/img/logos/github_dark_mode.svg') no-repeat; +} + +.dropdown-subtitle { + display: block; + padding: 0.5rem 1rem; + font-weight: bold; + color: var(--ifm-color-primary); + font-size: 0.9rem; +} + +.github-item { + display: flex; + align-items: center; +} + +.github-item::before { + content: ''; + width: 16px; + height: 16px; + margin-right: 0.5rem; + background: url('../../static/img/logos/github_light_mode.svg') + no-repeat; +} + +.twitter-item { + display: flex; + align-items: center; +} + +.twitter-item::before { + content: ''; + width: 16px; + height: 16px; + margin-right: 0.5rem; + background: url('../../static/img/logos/x.svg') + no-repeat; +} + +.navbar__item.dropdown .dropdown__menu { + padding: 0.5rem 0; + box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05); + border-radius: 0.375rem; + min-width: 200px; +} + +.navbar__item.dropdown .dropdown__link { + padding: 0.5rem 1.5rem; +} + +.dropdown-subtitle { + display: block; + padding: 0.5rem 1.5rem; + font-weight: bold; + color: var(--ifm-color-primary); + font-size: 0.9rem; +} + +.twitter-item { + display: flex; + align-items: center; +} + +.navbar .dropdown__link::after { + content: '\2197'; + margin-left: 5px; +} + +.navbar .dropdown__link.no-external-icon::after { + content: none; +} + +.navbar__item.dropdown .dropdown__link:hover { + background-color: var(--ifm-color-emphasis-200); +} + +.sidebar-title { + padding: 0.2rem 0.2rem; + margin-top: 0.2rem; +} + +.card-container { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); + gap: 1rem; + margin-bottom: 1rem; +} + +.card-container.full-width { + grid-template-columns: 1fr; +} + +@media (min-width: 769px) { + .card-container:not(.full-width) { + grid-template-columns: repeat(2, 1fr); + } +} + +.card-link-wrapper { + display: contents; +} + +.card { + display: flex; + flex-direction: column; + height: 100%; + transition: all 0.3s ease; +} + +.card:hover { + transform: scale(1.02); +} + +.card__body { + flex: 1; +} + +.view-all-link { + text-align: right; + margin-bottom: 2rem; +} + +.view-all-link a { + font-size: 0.9rem; + color: var(--ifm-color-primary); + text-decoration: none; +} \ No newline at end of file diff --git a/docs/src/preprocess/generate_aztecnr_reference.js b/docs/src/preprocess/generate_aztecnr_reference.js index b0902590663..7d0a3396a42 100644 --- a/docs/src/preprocess/generate_aztecnr_reference.js +++ b/docs/src/preprocess/generate_aztecnr_reference.js @@ -323,7 +323,7 @@ function processFiles(baseDir, outputBaseDir) { let baseDir = path.resolve(__dirname, "../../../noir-projects/aztec-nr"); let outputBaseDir = path.resolve( __dirname, - "../../docs/reference/smart_contract_reference/aztec-nr" + "../../docs/reference/developer_references/smart_contract_reference/aztec-nr" ); console.log(outputBaseDir); processFiles(baseDir, outputBaseDir); diff --git a/docs/src/theme/MDXComponents.js b/docs/src/theme/MDXComponents.js index 28e247751f4..3397b1d0a67 100644 --- a/docs/src/theme/MDXComponents.js +++ b/docs/src/theme/MDXComponents.js @@ -2,6 +2,11 @@ import React from "react"; import MDXComponents from "@theme-original/MDXComponents"; import Version, { AztecPackagesVersion } from "@site/src/components/Version"; import CodeBlock from "@theme/CodeBlock"; +import Card from '@site/src/components/TutorialCard'; +import CardBody from '@site/src/components/TutorialCard/CardBody'; +import CardFooter from '@site/src/components/TutorialCard/CardFooter'; +import CardHeader from '@site/src/components/TutorialCard/CardHeader'; +import CardImage from '@site/src/components/TutorialCard/CardImage'; // https://docusaurus.io/docs/markdown-features/react#mdx-component-scope export default { @@ -9,4 +14,11 @@ export default { Version, AztecPackagesVersion, CodeBlock, + Card, + CardHeader, + CardBody, + CardFooter, + CardImage, }; + + diff --git a/docs/static/img/logos/github_dark_mode.svg b/docs/static/img/logos/github_dark_mode.svg new file mode 100644 index 00000000000..09f6f4e86a3 --- /dev/null +++ b/docs/static/img/logos/github_dark_mode.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/static/img/logos/github_light_mode.svg b/docs/static/img/logos/github_light_mode.svg new file mode 100644 index 00000000000..d2219c5a8bb --- /dev/null +++ b/docs/static/img/logos/github_light_mode.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file diff --git a/docs/static/img/logos/x.svg b/docs/static/img/logos/x.svg new file mode 100644 index 00000000000..9a3386346c3 --- /dev/null +++ b/docs/static/img/logos/x.svg @@ -0,0 +1,3 @@ + + + \ No newline at end of file