diff --git a/docs/docs/developers/aztecjs/guides/call_view_function.md b/docs/docs/developers/aztecjs/guides/call_view_function.md new file mode 100644 index 000000000000..5fda30f7f2d0 --- /dev/null +++ b/docs/docs/developers/aztecjs/guides/call_view_function.md @@ -0,0 +1,15 @@ +--- +title: How to Call a View Function +--- + +This guide explains how to call a `view` function using [Aztec.js](../main.md). + +To do this from the CLI, go [here](../../sandbox/references/cli-commands.md#calling-an-unconstrained-view-function). + +```typescript +import { Contract } from "@aztec/aztec.js"; + +const contract = await Contract.at(contractAddress, MyContractArtifact, wallet); +const balance = await contract.methods.getBalance(wallet.getAddress()).view(); +console.log(`Account balance is ${balance}`); +``` diff --git a/docs/docs/developers/aztecjs/guides/create_account.md b/docs/docs/developers/aztecjs/guides/create_account.md new file mode 100644 index 000000000000..bf0913cba441 --- /dev/null +++ b/docs/docs/developers/aztecjs/guides/create_account.md @@ -0,0 +1,21 @@ +--- +title: How to Create a New Account +--- + +This guide explains how to create a new account using [Aztec.js](../main.md). + +To do this from the CLI, go [here](../../sandbox/references/cli-commands.md#creating-accounts). + +```typescript +import { getSchnorrAccount } from "@aztec/aztec.js"; +import { GrumpkinPrivateKey } from "@aztec/circuit-types"; + +const encryptionPrivateKey = GrumpkinPrivateKey.random(); +const signingPrivateKey = GrumpkinPrivateKey.random(); +const wallet = getSchnorrAccount( + pxe, + encryptionPrivateKey, + signingPrivateKey +).waitDeploy(); +console.log(`New account deployed at ${wallet.getAddress()}`); +``` \ No newline at end of file diff --git a/docs/docs/developers/aztecjs/guides/deploy_contract.md b/docs/docs/developers/aztecjs/guides/deploy_contract.md new file mode 100644 index 000000000000..499af437a946 --- /dev/null +++ b/docs/docs/developers/aztecjs/guides/deploy_contract.md @@ -0,0 +1,18 @@ +--- +title: How to Deploy a Contract +--- + +This guide explains how to deploy a smart contract using [Aztec.js](../main.md). + +To do this from the CLI, go [here](../../sandbox/references/cli-commands.md#deploying-a-token-contract). + +```typescript +import { Contract } from "@aztec/aztec.js"; + +const contract = await Contract.deploy(wallet, MyContractArtifact, [ + ...constructorArgs, +]) + .send() + .deployed(); +console.log(`Contract deployed at ${contract.address}`); +``` \ No newline at end of file diff --git a/docs/docs/developers/aztecjs/guides/send_transaction.md b/docs/docs/developers/aztecjs/guides/send_transaction.md new file mode 100644 index 000000000000..8cebd8edd616 --- /dev/null +++ b/docs/docs/developers/aztecjs/guides/send_transaction.md @@ -0,0 +1,20 @@ +--- +title: How to Send a Transaction +--- + +This guide explains how to send a transaction using [Aztec.js](../main.md). + +To do this from the CLI, go [here](../../sandbox/references/cli-commands.md#sending-a-transaction). + +```typescript +import { Contract } from "@aztec/aztec.js"; + +const contract = await Contract.at(contractAddress, MyContractArtifact, wallet); +const tx = await contract.methods + .transfer(amount, recipientAddress) + .send() + .wait(); +console.log( + `Transferred ${amount} to ${recipientAddress} on block ${tx.blockNumber}` +); +``` \ No newline at end of file diff --git a/docs/docs/developers/aztecjs/main.md b/docs/docs/developers/aztecjs/main.md index 531754b2992d..6e75dd7e4a9f 100644 --- a/docs/docs/developers/aztecjs/main.md +++ b/docs/docs/developers/aztecjs/main.md @@ -2,64 +2,23 @@ title: Aztec.js --- -If you are looking for the API reference, go [here](../../apis/aztec-js/index.md). +If you are looking for the Aztec.js API reference, go [here](../../apis/aztec-js/index.md). ## Introduction - Aztec.js is a library that provides APIs for managing accounts and interacting with contracts on the Aztec network. It communicates with the [Private eXecution Environment (PXE)](https://docs.aztec.network/apis/pxe/interfaces/PXE) through a `PXE` implementation, allowing developers to easily register new accounts, deploy contracts, view functions, and send transactions. -## Usage - -### Create a new account - -```typescript -import { getSchnorrAccount } from "@aztec/aztec.js"; -import { GrumpkinPrivateKey } from "@aztec/circuit-types"; - -const encryptionPrivateKey = GrumpkinPrivateKey.random(); -const signingPrivateKey = GrumpkinPrivateKey.random(); -const wallet = getSchnorrAccount( - pxe, - encryptionPrivateKey, - signingPrivateKey -).waitDeploy(); -console.log(`New account deployed at ${wallet.getAddress()}`); -``` - -### Deploy a contract - -```typescript -import { Contract } from "@aztec/aztec.js"; - -const contract = await Contract.deploy(wallet, MyContractArtifact, [ - ...constructorArgs, -]) - .send() - .deployed(); -console.log(`Contract deployed at ${contract.address}`); -``` - -### Send a transaction +## Guides -```typescript -import { Contract } from "@aztec/aztec.js"; +- [How to create a new account](./guides/create_account.md) +- [How to deploy a smart contract](./guides/deploy_contract.md) +- [How to send a transaction](./guides/send_transaction.md) +- [How to call a view function](./guides/call_view_function.md) -const contract = await Contract.at(contractAddress, MyContractArtifact, wallet); -const tx = await contract.methods - .transfer(amount, recipientAddress) - .send() - .wait(); -console.log( - `Transferred ${amount} to ${recipientAddress} on block ${tx.blockNumber}` -); -``` +## References -### Call a view function +- [Aztec.js Reference](../../apis/aztec-js/index.md) +- [Accounts Reference](../../apis/accounts/index.md) -```typescript -import { Contract } from "@aztec/aztec.js"; +## Tutorials -const contract = await Contract.at(contractAddress, MyContractArtifact, wallet); -const balance = await contract.methods.getBalance(wallet.getAddress()).view(); -console.log(`Account balance is ${balance}`); -``` +- [An example of testing with Aztec.js](../tutorials/testing.md) diff --git a/docs/docs/developers/contracts/abi.md b/docs/docs/developers/contracts/abi.md deleted file mode 100644 index fe493910cec7..000000000000 --- a/docs/docs/developers/contracts/abi.md +++ /dev/null @@ -1,22 +0,0 @@ -# Aztec Function ABIs - -Discuss: -- Public Inputs ABIs for functions. -- Args & args hashes -- return values and return values hashes -- etc. - - -## Limitations - -### Num reads and writes - -### Num function calls - -### Num logs - -### Num key pair validations - -### No gas or fees yet - -(See also [Limitations](../limitations/main.md)) \ No newline at end of file diff --git a/docs/docs/developers/contracts/artifacts.md b/docs/docs/developers/contracts/compiling_contracts/artifacts.md similarity index 100% rename from docs/docs/developers/contracts/artifacts.md rename to docs/docs/developers/contracts/compiling_contracts/artifacts.md diff --git a/docs/docs/developers/contracts/compiling.md b/docs/docs/developers/contracts/compiling_contracts/how_to_compile_contract.md similarity index 88% rename from docs/docs/developers/contracts/compiling.md rename to docs/docs/developers/contracts/compiling_contracts/how_to_compile_contract.md index 58c805006ece..6acdef15c664 100644 --- a/docs/docs/developers/contracts/compiling.md +++ b/docs/docs/developers/contracts/compiling_contracts/how_to_compile_contract.md @@ -1,6 +1,8 @@ -# Compiling contracts +--- +title: How to compile a contract +--- -Once you have written a [contract](../contracts/main.md) in Aztec.nr, you will need to compile it into an [artifact](./artifacts.md) in order to use it. +Once you have written a [contract](../main.md) in Aztec.nr, you will need to compile it into an [artifact](./artifacts.md) in order to use it. In this guide we will cover how to do so, both using the CLI and programmatically. @@ -10,7 +12,7 @@ We'll also cover how to generate a helper [TypeScript interface](#typescript-int To compile a contract using the Aztec's build of nargo. -Run the `aztec-nargo compile` command within your [contract project folder](./layout.md#directory-structure), which is the one that contains the `Nargo.toml` file: +Run the `aztec-nargo compile` command within your [contract project folder](../writing_contracts/layout.md), which is the one that contains the `Nargo.toml` file: ```bash aztec-nargo compile @@ -111,11 +113,11 @@ export class TokenContract extends ContractBase { } ``` -Read more about interacting with contracts using `aztec.js` [here](../getting_started/aztecjs-getting-started.md). +Read more about interacting with contracts using `aztec.js` [here](../../getting_started/aztecjs-getting-started.md). ### Aztec.nr interfaces -An Aztec.nr contract can [call a function](./syntax/functions/main.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/functions/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 can generate contract 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. For each contract, two interface structs are generated: one to be used from private functions with a `PrivateContext`, and one to be used from open functions with a `PublicContext`. @@ -209,7 +211,7 @@ impl TokenPublicContextInterface { } ``` -Read more about how to use the Aztec.nr interfaces [here](./syntax/functions/main.md). +Read more about how to use the Aztec.nr interfaces [here](../writing_contracts/functions/main.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. @@ -217,7 +219,7 @@ At the moment, the compiler generates these interfaces from already compiled ABI ## Next steps -Once you have compiled your contracts, you can use the generated artifacts via the `Contract` class in the `aztec.js` package to deploy and interact with them, or rely on the type-safe typescript classes directly. Alternatively, use the CLI [to deploy](../../developers/cli/main.md#deploying-a-token-contract) and [interact](../../developers/cli/main.md#sending-a-transaction) with them. +Once you have compiled your contracts, you can use the generated artifacts via the `Contract` class in the `aztec.js` package to deploy and interact with them, or rely on the type-safe typescript classes directly. Alternatively, use the CLI [to deploy](../../sandbox/references/cli-commands.md#deploying-a-token-contract) and [interact](../../sandbox/references/cli-commands.md#calling-an-unconstrained-view-function) with them. -import Disclaimer from "../../misc/common/\_disclaimer.mdx"; +import Disclaimer from "../../../misc/common/\_disclaimer.mdx"; diff --git a/docs/docs/developers/contracts/deploying.md b/docs/docs/developers/contracts/deploying_contracts/how_to_deploy_contract.md similarity index 85% rename from docs/docs/developers/contracts/deploying.md rename to docs/docs/developers/contracts/deploying_contracts/how_to_deploy_contract.md index ec9d88ef1f44..9da2f49e057f 100644 --- a/docs/docs/developers/contracts/deploying.md +++ b/docs/docs/developers/contracts/deploying_contracts/how_to_deploy_contract.md @@ -1,12 +1,16 @@ +--- +title: How to deploy a contract +--- + # Deploying contracts -Once you have [compiled](./compiling.md) your contracts you can proceed to deploying them using the aztec-cli or using aztec.js which is a Typescript client to interact with the sandbox. +Once you have [compiled](../compiling_contracts/how_to_compile_contract.md) your contracts you can proceed to deploying them using the aztec-cli or using aztec.js which is a Typescript client to interact with the sandbox. ## Prerequisites -- `aztec-cli` and `aztec-nargo` installed (go to [CLI main section](../cli/main.md) for installation instructions) -- contract artifacts ready (go to [Compiling contracts section](./compiling.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) +- `aztec-cli` and `aztec-nargo` installed (go to [Sandbox and CLI section](../../sandbox/main.md) for installation instructions) +- contract artifacts ready (go to [How to Compile Contract](../compiling_contracts/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 @@ -39,7 +43,7 @@ Generate the typescript class: aztec-cli codegen ./aztec-nargo/output/target/path -o src/artifacts --ts ``` -This would create a typescript file like `Example.ts` in `./src/artifacts`. Read more on the [compiling page](./compiling.md). +This would create a typescript file like `Example.ts` in `./src/artifacts`. Read more on the [compiling page](../compiling_contracts/how_to_compile_contract.md). Now you can import it to easily deploy and interact with the contract. @@ -84,7 +88,7 @@ Its arguments are `PXE` client and contract constructor arguments. Additionally the `.send()` method can have a few optional arguments too, which are specified in an optional object: -- `portalContract?: EthAddress`: The L1 portal address to link the contract to. See the section on [Portals to learn more about them](./portals/main.md). +- `portalContract?: EthAddress`: The L1 portal address to link the contract to. See the section on [Portals to learn more about them](../writing_contracts/portals/portals.md). - `contractAddressSalt?: Fr`: A salt which is one of the inputs when computing a contract address of the contract to be deployed. By default is set to a random value. Set it, if you need a deterministic contract address (same functionality as Ethereum's `CREATE2` opcode). diff --git a/docs/docs/developers/contracts/main.md b/docs/docs/developers/contracts/main.md index 40f7a53af9d8..37af0bb5c9f9 100644 --- a/docs/docs/developers/contracts/main.md +++ b/docs/docs/developers/contracts/main.md @@ -1,6 +1,10 @@ -import DocCardList from '@theme/DocCardList'; +--- +title: Smart Contracts +--- -# Aztec.nr +This section is a collection of how-to guides and references for building smart contracts with Aztec.nr. + +If you are looking for an overview of how smart contracts work, head to the [Concepts section](../../learn/concepts/smart_contracts/main.md). ## What is Aztec.nr? @@ -8,7 +12,7 @@ import DocCardList from '@theme/DocCardList'; ## Nomenclature -[**Noir**](https://noir-lang.org/) is a domain specific language for creating and verifying proofs. It's design choices are influenced heavily by Rust. +[**Noir**](https://noir-lang.org/) is a domain specific language for creating and verifying proofs. Its design choices are influenced heavily by Rust. A **smart contract** is just a collection of persistent state variables, and a collection of functions which may edit those state variables. @@ -20,7 +24,7 @@ An **Aztec smart contract** is a smart contract with **private** state variables ## Install aztec-nargo -To write an Aztec.nr contract, you need to the compiler, `aztec-nargo` which is installed when you install the sandbox. See install instructions [here](../cli/sandbox-reference.md). +To write an Aztec.nr contract, you need to the compiler, `aztec-nargo` which is installed when you install the sandbox. See install instructions [here](../sandbox/references/sandbox-reference.md). :::info For those coming from vanilla Noir, the version used for aztec.nr is tracked separately to nargo for vanilla Noir. Be sure to use `aztec-nargo` to compile your contracts. @@ -44,7 +48,7 @@ There are a number of tools to make writing Aztec.nr contracts in Noir more plea ## Tutorials -See the [Token Contract tutorial](../tutorials/writing_token_contract.md) for more info on getting set up to write contracts. +See the [Private Voting tutorial](../tutorials/writing_private_voting_contract.md) for more info on getting set up to write contracts. ## Learn more diff --git a/docs/docs/developers/contracts/syntax/globals.md b/docs/docs/developers/contracts/references/globals.md similarity index 100% rename from docs/docs/developers/contracts/syntax/globals.md rename to docs/docs/developers/contracts/references/globals.md diff --git a/docs/docs/developers/contracts/syntax/historical_access/history_lib_reference.md b/docs/docs/developers/contracts/references/history_lib_reference.md similarity index 95% rename from docs/docs/developers/contracts/syntax/historical_access/history_lib_reference.md rename to docs/docs/developers/contracts/references/history_lib_reference.md index 6e9a02ff22f9..5928a54275b5 100644 --- a/docs/docs/developers/contracts/syntax/historical_access/history_lib_reference.md +++ b/docs/docs/developers/contracts/references/history_lib_reference.md @@ -18,7 +18,11 @@ Note inclusion proves that a note existed (its hash was included in a note hash | block_number | u32 | Block number for proving note's existence | | context | PrivateContext | Private context | -`prove_note_inclusion` takes 2 parameters: +## prove_note_commitment_inclusion + +A **commitment**, also referred to as a **note hash** is a public acknowledgment of the existence of a note without revealing the content of the note. You can learn more about how to compress a note to a note hash [here](../../../learn/concepts/storage/trees/main.md#example-note). + +`prove_note_commitment_inclusion` takes 2 parameters: | Name | Type | Description | |-----------------|------------------------|-----------------------------------------------------| diff --git a/docs/docs/developers/contracts/portals/data_structures.md b/docs/docs/developers/contracts/references/portals/data_structures.md similarity index 100% rename from docs/docs/developers/contracts/portals/data_structures.md rename to docs/docs/developers/contracts/references/portals/data_structures.md diff --git a/docs/docs/developers/contracts/portals/inbox.md b/docs/docs/developers/contracts/references/portals/inbox.md similarity index 100% rename from docs/docs/developers/contracts/portals/inbox.md rename to docs/docs/developers/contracts/references/portals/inbox.md diff --git a/docs/docs/developers/contracts/portals/outbox.md b/docs/docs/developers/contracts/references/portals/outbox.md similarity index 100% rename from docs/docs/developers/contracts/portals/outbox.md rename to docs/docs/developers/contracts/references/portals/outbox.md diff --git a/docs/docs/developers/contracts/portals/registry.md b/docs/docs/developers/contracts/references/portals/registry.md similarity index 100% rename from docs/docs/developers/contracts/portals/registry.md rename to docs/docs/developers/contracts/references/portals/registry.md diff --git a/docs/docs/developers/contracts/references/slow_updates_tree.md b/docs/docs/developers/contracts/references/slow_updates_tree.md new file mode 100644 index 000000000000..552530edeb7f --- /dev/null +++ b/docs/docs/developers/contracts/references/slow_updates_tree.md @@ -0,0 +1,123 @@ +--- +title: Slow Updates Tree +--- + +## Struct `SlowMap` + +### Overview +The `SlowMap` struct is used to interact with a slow updates tree deployed via the SlowTree smart contract. + +### Fields + +| Name | Type | Description | +|---------|-----------|---------------------------------| +| address | `Field` | The address of the SlowTree contract | + +## Functions + +### at + +Returns an instance of `SlowMap` at the specified address. + +**Parameters** + +| Name | Type | Description | +|----------|----------------|----------------------------| +| `address`| `AztecAddress` | The address of the SlowTree | + +**Return** + +| Name | Type | Description | +|-------|-----------|------------------------------| +| - | `SlowMap` | The `SlowMap` instance | + +**Example** + +#include_code slowmap_at yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +### initialize + +Initializes the `SlowMap`. + +**Parameters** + +| Name | Type | Description | +|-----------|-----------------|----------------------| +| `context` | `PublicContext` | The execution context | + +**Return** + +| Name | Type | Description | +|------|------|-------------| +| - | - | - | + +**Example** + +#include_code slowmap_initialize yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +### read_at_pub + +Reads a value at a specified index from a public function. + +**Parameters** + +| Name | Type | Description | +|-----------|-----------------|-----------------------| +| `context` | `PublicContext` | The execution context | +| `index` | `Field` | The index to read at | + +**Return** + +| Name | Type | Description | +|----------|--------|-----------------------| +| `result` | `Field`| The value at `index` | + +**Example** + +#include_code read_at_pub yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +### read_at + +Reads a value at a specified index from a private function. + +**Parameters** + +| Name | Type | Description | +|-----------|--------------------|------------------------| +| `context` | `PrivateContext` | The execution context | +| `index` | `Field` | The index to read at | + +**Return** + +| Name | Type | Description | +|----------|--------|-----------------------| +| `result` | `Field`| The value at `index` | + +**Example** + +#include_code slowmap_read_at yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +### update_at_private + +Updates a value at a specified index from a private function. Does not return anything. + +**Parameters** + +| Name | Type | Description | +|-------------|--------------------|------------------------| +| `context` | `PrivateContext` | The execution context | +| `index` | `Field` | The index to update | +| `new_value` | `Field` | The new value | + +**Example** + +#include_code get_and_update_private yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +## Updating from public + +This is not a method in the interface as it can be done using regular Aztec.nr public storage update syntax. + +**Example** + +#include_code write_slow_update_public yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + diff --git a/docs/docs/developers/contracts/references/storage/main.md b/docs/docs/developers/contracts/references/storage/main.md new file mode 100644 index 000000000000..d16a1d1d69f7 --- /dev/null +++ b/docs/docs/developers/contracts/references/storage/main.md @@ -0,0 +1,481 @@ +# Writing a token contract in Aztec.nr + +In this tutorial we will go through writing an L2 native token contract +for the Aztec Network, using the Aztec.nr contract libraries. It is recommended that you go through the [the introduction to contracts](../../main.md) and [setup instructions](../../setup.md) section before this tutorial to gain some familiarity with writing Aztec smart contracts. + +This tutorial is intended to help you get familiar with the Aztec.nr library, Aztec contract syntax and some of the underlying structure of the Aztec network. + +In this tutorial you will learn how to: + +- Write public functions that update public state +- Write private functions that update private state +- Implement access control on public and private functions +- Handle math operations safely +- Handle different private note types +- Pass data between private and public state + +We are going to start with a blank project and fill in the token contract source code defined on Github [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/noir-contracts/contracts/token_contract/src/main.nr), and explain what is being added as we go. + +## Requirements + +You will need to have `aztec-nargo` installed in order to compile Aztec.nr contracts. See the [sandbox reference](../../../sandbox/references/sandbox-reference.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). + +## Project setup + +Create a new directory called `token_contract_tutorial` + +```bash +mkdir token_contract_tutorial +``` + +inside that directory, create a `contracts` folder for the Aztec contracts. + +```bash +cd token_contract_tutorial && mkdir contracts && cd contracts +``` + +Create the following file structure + +```tree +. +└── contracts + ├── Nargo.toml + └── src + └── main.nr +``` + +Add the following content to Nargo.toml file: + +```toml +[package] +name = "token_contract" +authors = [""] +compiler_version = ">=0.18.0" +type = "contract" + +[dependencies] +aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" } +safe_math = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/safe-math"} +authwit={ git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/authwit"} +compressed_string = {git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/compressed-string"} +``` + +## Contract Interface + +```rust +contract Token { + #[aztec(private)] + fn constructor() {} + + #[aztec(public)] + fn set_admin(new_admin: AztecAddress) {} + + #[aztec(public)] + fn set_minter(minter: AztecAddress, approve: bool) {} + + #[aztec(public)] + fn mint_public(to: AztecAddress, amount: Field) -> Field {} + + #[aztec(public)] + fn mint_private(amount: Field, secret_hash: Field) -> Field {} + + #[aztec(public)] + fn shield(from: AztecAddress, amount: Field, secret_hash: Field, nonce: Field) -> Field {} + + #[aztec(public)] + fn transfer_public(from: AztecAddress, to: AztecAddress, amount: Field, nonce: Field) -> Field {} + + #[aztec(public)] + fn burn_public(from: AztecAddress, amount: Field, nonce: Field) -> Field {} + + // Private functions + + #[aztec(private)] + fn redeem_shield(to: AztecAddress, amount: Field, secret: Field) -> Field {} + + #[aztec(private)] + fn unshield(from: AztecAddress, to: AztecAddress, amount: Field, nonce: Field) -> Field {} + + #[aztec(private)] + fn transfer(from: AztecAddress, to: AztecAddress, amount: Field, nonce: Field) -> Field {} + + #[aztec(private)] + fn burn(from: AztecAddress, amount: Field, nonce: Field) -> Field {} + + // Internal functions below + + // Will be internal in the future + #[aztec(public)] + fn _initialize(new_admin: AztecAddress) {} + + #[aztec(public)] + internal fn _increase_public_balance(to: AztecAddress, amount: Field) {} + + #[aztec(public)] + internal fn _reduce_total_supply(amount: Field) {} + + // Unconstrained functions (read only) + + unconstrained fn admin() -> Field {} + + unconstrained fn is_minter(minter: AztecAddress) -> bool {} + + unconstrained fn total_supply() -> Field {} + + unconstrained fn balance_of_private(owner: AztecAddress) -> Field {} + + unconstrained fn balance_of_public(owner: AztecAddress) -> Field {} + + unconstrained fn compute_note_hash_and_nullifier(contract_address: Field, nonce: Field, storage_slot: Field, serialized_note: [Field; VALUE_NOTE_LEN]) -> [Field; 4] {} +} +``` + +This specifies the interface of the `Token` contract. Go ahead and copy and paste this interface into your `main.nr` file. + +Before we through the interface and implement each function, let's review the functions to get a sense of what the contract does. + +### Constructor interface + +There is a `constructor` function that will be executed once, when the contract is deployed, similar to the constructor function in Solidity. This is marked private, so the function logic will not be transparent. To execute public function logic in the constructor, this function will call `_initialize` (marked internal, more detail below). + +### Public functions + +These are functions that have transparent logic, will execute in a publicly verifiable context and can update public storage. + +- `set_admin` enables the admin to be updated +- `set_minter` enables accounts to be added / removed from the approved minter list +- `mint_public` enables tokens to be minted to the public balance of an account +- `mint_private` enables tokens to be minted to the private balance of an account (with some caveats we will dig into) +- `shield` enables tokens to be moved from a public balance to a private balance, not necessarily the same account (step 1 of a 2 step process) +- `transfer_public` enables users to transfer tokens from one account's public balance to another account's public balance +- `burn_public` enables users to burn tokens + +### Private functions + +These are functions that have private logic and will be executed on user devices to maintain privacy. The only data that is submitted to the network is a proof of correct execution, new data [commitments](https://en.wikipedia.org/wiki/Commitment_scheme) and [nullifiers](../../../../learn/concepts/storage/trees/main.md#nullifier-tree), so users will not reveal which contract they are interacting with or which function they are executing. The only information that will be revealed publicly is that someone executed a private transaction on Aztec. + +- `redeem_shield` enables accounts to claim tokens that have been made private via `mint_private` or `shield` by providing the secret +- `unshield` enables an account to send tokens from their private balance to any other account's public balance +- `transfer` enables an account to send tokens from their private balance to another account's private balance +- `burn` enables tokens to be burned privately + +### Internal functions + +Internal functions are functions that can only be called by the contract itself. These can be used when the contract needs to call one of it's public functions from one of it's private functions. + +- `_initialize` is a way to call a public function from the `constructor` (which is a private function) +- `_increase_public_balance` increases the public balance of an account when `unshield` is called +- `_reduce_total_supply` reduces the total supply of tokens when a token is privately burned + +To clarify, let's review some details of the Aztec transaction lifecycle, particularly how a transaction "moves through" these contexts. + +#### Execution contexts + +Transactions are initiated in the private context, then move to the L2 public context, then to the Ethereum L1 context. + +Step 1. Private Execution + +Users provide inputs and execute locally on a their device for privacy reasons. Outputs of the private execution are commitment and nullifier updates, a proof of correct execution and any return data to pass to the public execution context. + +Step 2. Public Execution + +This happens remotely by the sequencer, which takes inputs from the private execution and runs the public code in the network virtual machine, similar to any other public blockchain. + +Step 3. Ethereum execution + +Aztec transactions can pass data to Ethereum contracts through the rollup via the outbox. The data can consumed by Ethereum contracts at a later time, but this is not part of the transaction flow for an Aztec transaction. The technical details of this are beyond the scope of this tutorial, but we will cover them in an upcoming piece. + +### Unconstrained functions + +Unconstrained functions can be thought of as view functions from Solidity--they only return information from the contract storage or compute and return data without modifying contract storage. + +The `compute_note_hash_and_nullifier` function allows contract devs to specify how to compute notes and nullifiers. This must be included in every contract because it depends on the storage slots, which are defined when we set up storage. + +## Contract dependencies + +Before we can implement the functions, we need set up the contract storage, and before we do that we need to import the appropriate dependencies. + +:::info Copy required files + +We will be going over the code in `main.nr` [here](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/yarn-project/noir-contracts/contracts/token_contract/src). If you are following along and want to compile `main.nr` yourself, you need to add the other files in the directory as they contain imports that are used in `main.nr`. + +::: + +Just below the contract definition, add the following imports: + +#include_code imports /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +We are importing the Option type, items from the `value_note` library to help manage private value storage, note utilities, context (for managing private and public execution contexts), `state_vars` for helping manage state, `types` for data manipulation and `oracle` for help passing data from the private to public execution context. We also import the `auth` [library](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/aztec-nr/aztec/src/auth.nr) to handle token authorizations from [Account Contracts](../../../../learn/concepts/accounts/main.md). Check out the Account Contract with AuthWitness [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/noir-contracts/contracts/schnorr_single_key_account_contract/src/main.nr). + +[SafeU120](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/aztec-nr/safe-math/src/safe_u120.nr) is a library to do safe math operations on unsigned integers that protects against overflows and underflows. + +For more detail on execution contexts, see [Contract Communication](../../../../learn/concepts/communication/main). + +### 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/yarn-project/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 `owner`, 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](https://en.wikipedia.org/wiki/Unspent_transaction_output) under the hood. Handling UTXOs is largely abstracted away from developers, but there are some unique things for developers to be aware of when creating and managing private state in an Aztec contract. See [State Variables](../storage/main.md) to learn more about public and private state in Aztec. + +## Contract Storage + +Now that we have dependencies imported into our contract we can define the storage for the contract. + +Below the dependencies, paste the following Storage struct: + +#include_code storage_struct /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +Reading through the storage variables: + +- `admin` a single Field value stored in public state. A `Field` is basically an unsigned integer with a maximum value determined by the underlying cryptographic curve. +- `minters` is a mapping of Fields in public state. This will store whether an account is an approved minter on the contract. +- `balances` is a mapping of private balances. Private balances are stored in a `Set` of `ValueNote`s. The balance is the sum of all of an account's `ValueNote`s. +- `total_supply` is a Field value stored in public state and represents the total number of tokens minted. +- `pending_shields` is a `Set` of `TransparentNote`s stored in private state. What is stored publicly is a set of commitments to `TransparentNote`s. +- `public_balances` is a mapping field elements in public state and represents the publicly viewable balances of accounts. + +You can read more about it [here](../storage/main.md). + +## Functions + +Copy and paste the body of each function into the appropriate place in your project if you are following along. + +### Constructor + +In the source code, the constructor logic is commented out due to some limitations of the current state of the development. + +#include_code constructor /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +The constructor is a private function. There isn't any private state to set up in this function, but there is public state to set up. The `context` is a global variable that is available to private and public functions, but the available methods differ based on the context. You can see the implementation details [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/aztec-nr/aztec/src/context.nr). The `context.call_public_function` allows a private function to call a public function on any contract. In this case, the constructor is passing the `msg_sender` as the argument to the `_initialize` function, which is also defined in this contract. + +### Public function implementations + +Public functions are declared with the `#[aztec(public)]` macro above the function name like so: + +#include_code set_admin /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +As described in the [execution contexts section above](#execution-contexts), public function logic and transaction information is transparent to the world. Public functions update public state, but can be used to prepare data to be used in a private context, as we will go over below (e.g. see the [shield](#shield) function). + +Storage is referenced as `storage.variable`. + +#### `set_admin` + +After storage is initialized, the contract checks that the `msg_sender` is the `admin`. If not, the transaction will fail. If it is, the `new_admin` is saved as the `admin`. + +#include_code set_admin /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `set_minter` + +This function allows the `admin` to add or a remove a `minter` from the public `minters` mapping. It checks that `msg_sender` is the `admin` and finally adds the `minter` to the `minters` mapping. + +#include_code set_minter /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `mint_public` + +This function allows an account approved in the public `minters` mapping to create new public tokens owned by the provided `to` address. + +First, storage is initialized. Then the function checks that the `msg_sender` is approved to mint in the `minters` mapping. If it is, a new `SafeU120` value is created of the `amount` provided. The function reads the recipients public balance and then adds the amount to mint, saving the output as `new_balance`, then reads to total supply and adds the amount to mint, saving the output as `supply`. `new_balance` and `supply` are then written to storage. + +The function returns 1 to indicate successful execution. + +#include_code mint_public /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `mint_private` + +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/yarn-project/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 `Set` 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 /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `shield` + +This public function enables an account to stage tokens from it's `public_balance` to be claimed as a private `TransparentNote` by any account that has the pre-image to the `secret_hash`. + +First, storage is initialized. Then it checks whether the calling contract (`context.msg_sender`) matches the account that the funds will be debited from. + +##### Authorizing token spends + +If the `msg_sender` is **NOT** the same as the account to debit from, the function checks that the account has authorized the `msg_sender` contract to debit tokens on its behalf. This check is done by computing the function selector that needs to be authorized (in this case, the `shield` function), computing the hash of the message that the account contract has approved. This is a hash of the contract that is approved to spend (`context.msg_sender`), the token contract that can be spent from (`context.this_address()`), the `selector`, the account to spend from (`from.address`), the `amount`, the `secret_hash` and a `nonce` to prevent multiple spends. This hash is passed to `assert_valid_public_message_for` to ensure that the Account Contract has approved tokens to be spent on it's behalf. + +If the `msg_sender` is the same as the account to debit tokens from, the authorization check is bypassed and the function proceeds to update the account's `public_balance` and adds a new `TransparentNote` to the `pending_shields`. + +It returns `1` to indicate successful execution. + +#include_code shield /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `transfer_public` + +This public function enables public transfers between Aztec accounts. The sender's public balance will be debited the specified `amount` and the recipient's public balances will be credited with that amount. + +After storage is initialized, the [authorization flow specified above](#authorizing-token-spends) is checked. Then the sender and recipient's balances are updated and saved to storage using the `SafeU120` library. + +#include_code transfer_public /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `burn_public` + +This public function enables public burning (destroying) of tokens from the sender's public balance. + +After storage is initialized, the [authorization flow specified above](#authorizing-token-spends) is checked. Then the sender's public balance and the `total_supply` are updated and saved to storage using the `SafeU120` library. + +#include_code burn_public /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +### Private function implementations + +Private functions are declared with the `#[aztec(private)]` macro above the function name like so: + +```rust + #[aztec(private)] + fn redeem_shield( +``` + +As described in the [execution contexts section above](#execution-contexts), private function logic and transaction information is hidden from the world and is executed on user devices. Private functions update private state, but can pass data to the public execution context (e.g. see the [`unshield`](#unshield) function). + +Storage is referenced as `storage.variable`. + +#### `redeem_shield` + +This private function enables an account to move tokens from a `TransparentNote` in the `pending_shields` mapping to any Aztec account as a `ValueNote` in private `balances`. + +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/yarn-project/aztec-nr/value-note/src/utils.nr). + +The function returns `1` to indicate successful execution. + +#include_code redeem_shield /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `unshield` + +This private function enables un-shielding of private `ValueNote`s stored in `balances` to any Aztec account's `public_balance`. + +After initializing storage, the function checks that the `msg_sender` is authorized to spend tokens. See [the Authorizing token spends section](#authorizing-token-spends) above for more detail--the only difference being that `assert_valid_message_for` is modified to work specifically in the private context. After the authorization check, the sender's private balance is decreased using the `decrement` helper function for the `value_note` library. Then it stages a public function call on this contract ([`_increase_public_balance`](#_increase_public_balance)) to be executed in the [public execution phase](#execution-contexts) of transaction execution. `_increase_public_balance` is marked as an `internal` function, so can only be called by this token contract. + +The function returns `1` to indicate successful execution. + +#include_code unshield /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `transfer` + +This private function enables private token transfers between Aztec accounts. + +After initializing storage, the function checks that the `msg_sender` is authorized to spend tokens. See [the Authorizing token spends section](#authorizing-token-spends) above for more detail--the only difference being that `assert_valid_message_for` is modified to work specifically in the private context. After authorization, the function gets the current balances for the sender and recipient and decrements and increments them, respectively, using the `value_note` helper functions. + +#include_code transfer /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `burn` + +This private function enables accounts to privately burn (destroy) tokens. + +After initializing storage, the function checks that the `msg_sender` is authorized to spend tokens. Then it gets the sender's current balance and decrements it. Finally it stages a public function call to [`_reduce_total_supply`](#_reduce_total_supply). + +#include_code burn /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +### Internal function implementations + +Internal functions are functions that can only be called by this contract. The following 3 functions are public functions that are called from the [private execution context](#execution-contexts). Marking these as `internal` ensures that only the desired private functions in this contract are able to call them. Private functions defer execution to public functions because private functions cannot update public state directly. + +#### `_initialize` + +This function is called via the [constructor](#constructor). + +This function sets the creator of the contract (passed as `msg_sender` from the constructor) as the admin and makes them a minter. + +#include_code initialize /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `_increase_public_balance` + +This function is called from [`unshield`](#unshield). The account's private balance is decremented in `shield` and the public balance is increased in this function. + +#include_code increase_public_balance /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `_reduce_total_supply` + +This function is called from [`burn`](#burn). The account's private balance is decremented in `burn` and the public `total_supply` is reduced in this function. + +#include_code reduce_total_supply /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +### Unconstrained function implementations + +Unconstrained functions are similar to `view` functions in Solidity in that they only return information from the contract storage or compute and return data without modifying contract storage. + +#### `admin` + +A getter function for reading the public `admin` value. + +#include_code admin /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `is_minter` + +A getter function for checking the value of associated with a `minter` in the public `minters` mapping. + +#include_code is_minter /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `total_supply` + +A getter function for checking the token `total_supply`. + +#include_code total_supply /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `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 access to the `owner`s decryption keys in order to decrypt their notes. + +#include_code balance_of_private /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `balance_of_public` + +A getter function for checking the public balance of the provided Aztec account. + +#include_code balance_of_public /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +#### `compute_note_hash_and_nullifier` + +A getter function to compute the note hash and nullifier for notes in the contract's storage. + +This must be included in every contract because it depends on the storage slots, which are defined when we set up storage. + +#include_code compute_note_hash_and_nullifier /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +:::danger +If your contract works with storage (has Storage struct defined), you **MUST** include a `compute_note_hash_and_nullifier` function. +If you don't yet have any private state variables defined put there a placeholder function: + +#include_code compute_note_hash_and_nullifier_placeholder /yarn-project/noir-contracts/contracts/token_bridge_contract/src/main.nr rust +::: + +## Compiling + +Now that the contract is complete, you can compile it with `aztec-nargo`. See the [Sandbox reference page](../../../sandbox/references/sandbox-reference.md) for instructions on setting it up. + +Run the following command in the directory where your `Nargo.toml` file is located: + +```bash +aztec-nargo compile +``` + +Once your contract is compiled, optionally generate a typescript interface with the following command: + +```bash +aztec-cli codegen target -o src/artifacts --ts +``` + +## Next Steps + +### Testing + +Review the end to end tests for reference: + +https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/end-to-end/src/e2e_token_contract.test.ts + +### Token Bridge Contract + +The [token bridge tutorial](https://github.com/AztecProtocol/dev-rel/tree/main/tutorials/token-bridge) 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. \ No newline at end of file diff --git a/docs/docs/developers/contracts/syntax/storage/private_state.md b/docs/docs/developers/contracts/references/storage/private_state.md similarity index 97% rename from docs/docs/developers/contracts/syntax/storage/private_state.md rename to docs/docs/developers/contracts/references/storage/private_state.md index c60590612c12..ccc81c20cd4b 100644 --- a/docs/docs/developers/contracts/syntax/storage/private_state.md +++ b/docs/docs/developers/contracts/references/storage/private_state.md @@ -10,7 +10,7 @@ For a higher level overview of the state model in Aztec, see the [hybrid state m 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](../events.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](../../writing_contracts/events/emit_event.md#encrypted-events), 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](#notes). Each note is stored as an individual leaf in a utxo-based merkle tree: the [private state tree](../../../../learn/concepts/storage/trees/main.md). @@ -184,7 +184,7 @@ Set is used for managing a collection of notes. All notes in a Set are of the sa You can view the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/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](../functions/calling_functions.md#public---private)). +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](../../writing_contracts/functions/call_functions.md)). #include_code storage-set-declaration /yarn-project/noir-contracts/contracts/docs_example_contract/src/main.nr rust @@ -200,7 +200,7 @@ We can initialize the set as follows: Allows us to modify the storage by inserting a note into the set. -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](../events.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](../../writing_contracts/events/emit_event.md#encrypted-events), or offchain via web2, or completely offline. #include_code insert /yarn-project/aztec-nr/easy-private-state/src/easy_private_state.nr rust @@ -248,7 +248,7 @@ 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](../functions/oracles.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](../../writing_contracts/oracles/main.md). 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/yarn-project/aztec-nr/aztec/src/note/note_getter_options.nr). diff --git a/docs/docs/developers/contracts/syntax/storage/public_state.md b/docs/docs/developers/contracts/references/storage/public_state.md similarity index 94% rename from docs/docs/developers/contracts/syntax/storage/public_state.md rename to docs/docs/developers/contracts/references/storage/public_state.md index 87853bf379fd..68eeb5bfdc12 100644 --- a/docs/docs/developers/contracts/syntax/storage/public_state.md +++ b/docs/docs/developers/contracts/references/storage/public_state.md @@ -23,7 +23,7 @@ An example using a larger struct can be found in the [lending example](https://g ### `new` -When declaring the storage for `T` as a persistent public storage variable, we use the `PublicState::new()` constructor. As seen below, this takes the `storage_slot` and the [`Context`](../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/yarn-project/aztec-nr/aztec/src/state_vars/public_state.nr). +When declaring the storage for `T` as a persistent public storage variable, we use the `PublicState::new()` constructor. As seen below, this takes the `storage_slot` and the `serialization_methods` as arguments along with the [`Context`](../../writing_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/yarn-project/aztec-nr/aztec/src/state_vars/public_state.nr). #### Single value example diff --git a/docs/docs/developers/contracts/resources/common_patterns/authwit.md b/docs/docs/developers/contracts/resources/common_patterns/authwit.md index 0858b4cbebb8..40aed935b939 100644 --- a/docs/docs/developers/contracts/resources/common_patterns/authwit.md +++ b/docs/docs/developers/contracts/resources/common_patterns/authwit.md @@ -82,7 +82,7 @@ Both return the value `0xe86ab4ff` (`is_valid` selector) for a successful authen As part of [Aztec.nr](https://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](./../../../wallets/writing_an_account_contract.md). +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](../../writing_contracts/accounts/write_accounts_contract.md). 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. diff --git a/docs/docs/developers/contracts/resources/common_patterns/main.md b/docs/docs/developers/contracts/resources/common_patterns/main.md index 5d54f7b6e350..e19d9d14c762 100644 --- a/docs/docs/developers/contracts/resources/common_patterns/main.md +++ b/docs/docs/developers/contracts/resources/common_patterns/main.md @@ -95,7 +95,7 @@ This pattern is discussed in detail in [writing a token contract section in the When you send someone a note, the note hash gets added to the [note hash tree](../../../../learn/concepts/storage/trees/main.md#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 `emit_encrypted_log` (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](../../syntax/events.md) +1. When sending someone a note, use `emit_encrypted_log` (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](../../writing_contracts/events/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 (`emit_encrypted_log` 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 diff --git a/docs/docs/developers/contracts/resources/main.md b/docs/docs/developers/contracts/resources/main.md deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/docs/docs/developers/contracts/resources/style_guide.md b/docs/docs/developers/contracts/resources/style_guide.md deleted file mode 100644 index e69de29bb2d1..000000000000 diff --git a/docs/docs/developers/contracts/setup.md b/docs/docs/developers/contracts/setup.md index 1779e4deb3d4..482b7795383d 100644 --- a/docs/docs/developers/contracts/setup.md +++ b/docs/docs/developers/contracts/setup.md @@ -1,5 +1,5 @@ --- -title: Setup +title: How to setup a new contract project --- import { AztecPackagesVersion } from "@site/src/components/Version"; @@ -85,5 +85,5 @@ You are now ready to write your own contracts! ## Next Steps -- Read up about how to [write a contract](./syntax/main.md) OR -- Follow a [tutorial](../tutorials/main.md) +- Follow a [tutorial](../tutorials/main.md) OR +- Read more diff --git a/docs/docs/developers/contracts/syntax/constrain.md b/docs/docs/developers/contracts/syntax/constrain.md deleted file mode 100644 index eb529c1e3b16..000000000000 --- a/docs/docs/developers/contracts/syntax/constrain.md +++ /dev/null @@ -1,2 +0,0 @@ -Not sure what this one's for? -`assert`? diff --git a/docs/docs/developers/contracts/syntax/control_structure.md b/docs/docs/developers/contracts/syntax/control_structure.md deleted file mode 100644 index d3d0e57a6cfb..000000000000 --- a/docs/docs/developers/contracts/syntax/control_structure.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Control Structures ---- - -:::danger -Question: this feels like the wrong title for a section about how to call functions. 'Control structure' in my mind is "if/else", "for", "while". - -Can we not put "how to call functions" in the functions section? -::: - -# Function Calls - -## Private Function Calls - -## Public Function Calls - -## Private to Public Function Calls - -## Public to Private Function Calls diff --git a/docs/docs/developers/contracts/syntax/functions/calling_functions.md b/docs/docs/developers/contracts/syntax/functions/calling_functions.md deleted file mode 100644 index 4b24e32a9c25..000000000000 --- a/docs/docs/developers/contracts/syntax/functions/calling_functions.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Calling Functions from Other Functions ---- - -This page talks about how functions call other functions. For a more hands-on guide into calling functions from other functions, follow the [token tutorial](../../../tutorials/writing_token_contract.md). - -### Private -> Private - -In Aztec Private to Private function calls are handled by the [private kernel circuit](../../../../learn/concepts/circuits/kernels/private_kernel.md), and take place on the user's device. -Behind the scenes, the `Private Execution Environment (PXE)` (the beating heart of Aztec that runs in your wallet) will execute all of the functions in the desired order "simulating" them in sequence. For example, a very common use-case of private-to-private interaction is calling a private function on another contract from an `account contract` (Account contracts are a general concept, more information about them can be found [here](../../../wallets/writing_an_account_contract.md)). - -Take, for example, the following call stack: - -``` -AccountContract::entrypoint - |-> Foo::example_call - | -> Bar::nested_call - |-> Baz::example_call -``` - -In the example above the Account Contract has been instructed to call two external functions. In the first function all, to `Foo::example_call` a further nested call is performed to `Bar::nested_call`. Finally the Account Contract makes one last call to `Baz::example_call`. - -Lets further illustrate what these examples could look like - - - -```rust -// Foo contains a singular function that returns the result of Bar::nested_call -contract Foo { - #[aztec(private)] - fn example_call(input: Field) -> pub Field { - Bar::at().nested_call(input) - } -} - -// Bar contains a singular function that returns a `input + 1` -contract Bar { - #[aztec(private)] - fn nested_call(input: Field) -> pub Field { - input + 1 - } -} - -// Baz contains a singular function that simply returns `10` -contract Baz { - #[aztec(private)] - fn example_call() -> pub Field { - 10 - } -} -``` - -When simulating the following call stack, we can expect execution flow to continue procedurally. The simulator will begin at the account contract's entry point, find a call to `Foo::example_call`, then begin to execute the code there. When the simulator executes the code in contract `Foo`, it will find the further nested call to contract `Bar::nested_call`. It will execute the code in `Bar`, bringing the return value back to contract `Foo`. -The same process will be followed for contract `Baz`. - -So far the provided example is identical to other executions. Ethereum execution occurs in a similar way, during execution the EVM will execute instructions until it reaches an external call, where it will hop into a new context and execute code there, returning back when it is complete, bringing with it return values from the foreign execution. - -Aztec differs from Ethereum in that these function calls are really executing zk programs (or circuits). The account contract, contract `Foo`, `Bar` and `Baz` are all distinct circuits, which are not directly aware of one another in the way that Ethereum contracts are. How is it possible to use a value from contract `Bar` in contract `Foo`? `Foo` cannot guarantee claims about the execution of `Bar`. - -This is where the `kernel` circuit comes in. Once the execution of all of the contract functions has completed, it can prove the execution of each of them independently. It is the job of the `kernel` circuit to constrain that the input parameters in a cross function call are correct, as well as the return values. The kernel will constrain that the value returned from `Foo::example_call` is the same value that is returned from `Bar::nested_call`, it will also be able to guarantee the value returned by `Bar::nested_call` is the inputs to `Foo::example_call` + 1. - -The orchestration of these calls has an added benefit. All of the nested calls are **recursively proven**. This means that the kernel circuit essentially aggregates each of our function's execution proofs, resulting in one proof that proves all function execution. - - - -With this intuition in place, lets see how we actually perform the call. To make things easier, we can make a small struct that wraps the calls to something as seen in the token interface `burn` function below. This struct is providing us a clean way to call function, but we could also just call the function directly as it is done in this function. - -:::info -Note that the function selector is computed using Oracles, and that the first `Field` is wrapped in parenthesis. Structs are outlined in tuple-form for selector computation, so they are wrapped in parenthesis--e.g. `AztecAddress` becomes `(Field)`. -::: - -#include_code private_burn_interface /yarn-project/noir-contracts/contracts/token_bridge_contract/src/token_interface.nr rust - -Using this interface, we can then call it as seen below. All the way down at the bottom we can see that we are calling the `burn` function from the `token_interface` struct. - -The following snippet is from a token bridge that is burning the underlying token and creating a message for L1 to mint some assets to the `recipient` on Ethereum. - -#include_code exit_to_l1_private /yarn-project/noir-contracts/contracts/token_bridge_contract/src/main.nr rust - -### Public -> Public - -The public execution environment in Aztec takes place on the sequencer through a [Public VM](../../../../learn/concepts/hybrid_state/public_vm.md). This execution model is conceptually much simpler than the private transaction model as code is executed and proven on the sequencer. - -Using the same example code and call stack from the section [above](#private---private-function-calls), we will walk through how it gets executed in public. - -The first key difference is that public functions are not compiled to circuits, rather they are compiled to `Aztec Bytecode`. - -This bytecode is run by the sequencer in the `Aztec VM`, which is in turn proven by the [`Aztec VM circuit`](../../../../learn/concepts/hybrid_state/public_vm.md). -The mental model for public execution carries many of the same idea as are carried by Ethereum. Programs are compiled into a series of opcodes (known as bytecode). This bytecode is then executed. The extra step for the Aztec VM is that each opcode is then proven for correctness. - -Calling a public function from another public function is quite similar to what we saw for private to private, with the keyword private swapped for public. - -#include_code public_burn_interface /yarn-project/noir-contracts/contracts/token_bridge_contract/src/token_interface.nr rust -#include_code exit_to_l1_public /yarn-project/noir-contracts/contracts/token_bridge_contract/src/main.nr rust - -### Private -> Public - -As discussed above, private function execution and calls take place on the user's device, while public function execution and calls take place on a sequencer, in two different places at two different times. We can achieve composability between the two contexts via asynchronicity. Further reading can be found in the concepts [here](../../../../learn/concepts/communication/public_private_calls/main.md). - -Private function execution takes place on the users device, where it keeps track of any public function calls that have been made. Whenever private execution completes, and a kernel proof is produced, the transaction sent to the network will include all of the public calls that were dispatched. -When the sequencer receives the messages, it will execute the public parts of the transaction. - -As a consequence a private function _CANNOT_ accept a return value from a public function. It can only dispatch it. - -The code required to dispatch a public function call from a private function is similar to private-to-private calls. As an example, we will look at the token contract, where users can unshield assets from private to public domain. This is essentially a transfer from a private account to a public one (often used for depositing privately into DeFi etc). - -#include_code unshield /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust -#include_code increase_public_balance /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust - -As we can see above, in the code the private to public transaction flow looks very similar to the others in snippets, with the transaction data flow being a bit different behind the scenes. - - - -### Public -> Private - - -While we cannot directly call a private function from a public function, we can indirectly call it by adding a commitment to the note hash tree. This commitment can then be consumed by a private function later, to "finish" the execution. So while it is not practically a call, we can ensure that it could only happen as an effect of a public function call, which is still useful. - -In the snippet below, we insert a custom note, the transparent note, into the commitments tree from public such that it can later be consumed in private. - -#include_code shield /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust - -If you recall the `redeem_shield` from back in the [private function section](./public_private_unconstrained.md#private-functions), you might remember it removing a `TransparentNote` from `pending_shields`. This is the note that we just inserted from public! - -#include_code redeem_shield /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust - -When the note is removed, it emits a nullifier so that it cannot be used again. This nullifier is then added to the nullifier tree, and can be used to prove that the note was removed from the pending shields. Interestingly, we can generate the nullifier such that no-one who saw the public execution will know that it have been consumed. When sending messages between L1 and L2 in [portals](./../../../../learn/concepts/communication/cross_chain_calls.md) we are going to see this pattern again. - -:::danger -Something to be mindful of when inserting from public. Everyone can see the insertion and what happens in public, so if you are including a secret directly anyone would be able to see it. This is why the hash of the secret is used in the snippet above (`secret_hash`). -::: - diff --git a/docs/docs/developers/contracts/syntax/functions/constructor.md b/docs/docs/developers/contracts/syntax/functions/constructor.md deleted file mode 100644 index d0a9c7d0c3be..000000000000 --- a/docs/docs/developers/contracts/syntax/functions/constructor.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Constructor ---- -This page talks about declaring constructors in functions. - -For a more hands-on guide into declaring a constructor, follow the [private voting tutorial](../../../tutorials/writing_private_voting_contract.md). - -A special `constructor` function **must** be declared within a contract's scope. -- A constructor doesn't have a name, because its purpose is clear: to initialize contract state. -- In Aztec terminology, a constructor is always a '`private` function' (i.e. it cannot be a `public` function). -- A constructor behaves almost identically to any other function. It is just important for Aztec to be able to identify this function as special: it may only be called once, and will not be deployed as part of the contract. - -Although you can have a constructor that does nothing, you might want to do something with it, such as setting the deployer as an owner. - -#include_code constructor /yarn-project/noir-contracts/contracts/escrow_contract/src/main.nr rust diff --git a/docs/docs/developers/contracts/syntax/main.md b/docs/docs/developers/contracts/syntax/main.md deleted file mode 100644 index 73a6c7ffddca..000000000000 --- a/docs/docs/developers/contracts/syntax/main.md +++ /dev/null @@ -1,22 +0,0 @@ -import DocCardList from '@theme/DocCardList'; -import { AztecPackagesVersion } from "@site/src/components/Version"; - -# Aztec.nr Syntax - -[Noir](https://noir-lang.org/) is a language which is agnostic to proof systems and use cases. Rather than baking Aztec-specific keywords and smart contract types directly into Noir (which would break this agnosticism), we have developed a framework -- written in Noir -- whose types and methods provide rich smart contract semantics. - -On top of [Noir's stdlib](https://noir-lang.org/docs/noir/standard_library/cryptographic_primitives), we provide [Aztec.nr](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/aztec-nr) for writing contracts on Aztec. - -Aztec.nr contains abstractions which remove the need to understand the low-level Aztec protocol. Notably, it provides: - -- Public and private [state variable types](./storage/main.md) -- Some pre-designed notes -- Functions for [emitting](./events.md) encrypted and unencrypted logs -- [Oracle functions](./functions/oracles.md) for accessing: - - private state - - secrets -- Functions for communicating with [Ethereum L1](../portals/main.md) - -To setup a aztec-nr project, follow the [setup instructions](../setup.md) - - diff --git a/docs/docs/developers/contracts/syntax/slow_updates_tree.md b/docs/docs/developers/contracts/syntax/slow_updates_tree.md deleted file mode 100644 index 8449cdcf362f..000000000000 --- a/docs/docs/developers/contracts/syntax/slow_updates_tree.md +++ /dev/null @@ -1,264 +0,0 @@ ---- -title: Slow Updates Tree ---- - -Slow Updates Tree is a data structure that allows for historical public data to be accessed in both private and public domains. Read the high level overview in the [Communication section](../../../learn/concepts/communication/public_private_calls/slow_updates_tree.md). - -The slow updates tree works by having a current tree and a pending tree, and replacing the current tree with the pending tree after an epoch has passed. Public functions can read directly from the current tree, and private functions can perform a membership proof that values are part of a commitment to the current state of the tree. - -On this page you will learn: - -1. [The components involved in using the slow updates tree](slow_updates_tree.md#components-involved-in-implementing-a-slow-updates-tree) -2. [How you can integrate it into your own smart contract](slow_updates_tree.md#how-to-integrate-a-slow-updates-tree) -3. [An example of a token blacklisting contract that uses the slow updates tree](slow_updates_tree.md#exploring-an-example-integration-through-a-tokenblacklist-smart-contract) -4. [Interface Reference](slow_updates_tree.md#functions) - -# Components involved in implementing a slow updates tree - -There are generally 4 main components involved to make it easier to use a slow updates tree, with 3 already implemented by Aztec. This makes it easier to interact with a slow updates tree through a simple interface. These four components are: - -## Main smart contract - -This is the primary smart contract that will use the slow updates tree. In the example we use a [token with blacklisting features](slow_updates_tree.md#exploring-an-example-integration-through-a-tokenblacklist-smart-contract). - -## Interface - -This interface of the slow updates tree contract allows your contract to interact with the Slow Updates Tree contract. It provides methods for reading and updating values in the tree in both public and private contexts. You can find it [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/contracts/token_blacklist_contract/src/interfaces.nr). - -## SlowTree.nr contract - -This is a smart contract developed by Aztec that establishes and manages a slow updates tree structure. It allows developers to access and interact with the tree, such as reading and updating data. - -You can find it [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/contracts/slow_tree_contract). - -## SlowMap type - -This is a type in the Aztec.nr library that is utilized by the SlowTree contract. It defines the underlying data structure for the slow updates tree, and handles storing both the current and pending values for each data entry. - -You can find it [here](https://github.com/AztecProtocol/aztec-nr/blob/master/slow-updates-tree/src/slow_map.nr). - -The diagram below describes how these components work together. It does not contain all the functionality. - -```mermaid -graph TD - MSC[Main Smart Contract] --> INT[Interface] - STC --> SMT - - INT_RAP[read_at_pub] <--> STC_RAP[read_at_public] - INT_RA[read_at] <--> STC_RA[read_at] - INT_UAP[update_at_public] <--> STC_UAP[update_at_public] - INT_UA[update_at_private] <--> STC_UA[update_at_private] - - STC_RA <--> VMP[verify_membership_proof] - STC_UA <--> CR[compute_roots] - - subgraph INT[Interface] - INT_RAP - INT_UAP - INT_RA - INT_UA - end - - subgraph STC[SlowTree.nr] - STC_RAP - STC_UAP - STC_RA - STC_UA - end - - subgraph SMT[SlowMap Type] - Change{Epoch Over} -->|True| Current{Current} - Change -->|False| Pending{Pending} - Current --> Current1[Current Commitment 1] - Current --> CurrentM[Current Commitment M] - CurrentM --> Value1[Current Value 1] - CurrentM --> Value2[Current Value 2] - CurrentM --> ValueN[Current Value N] - Pending --> PendingM[Pending Commitment 1] - PendingM --> PValue1[Pending Value 1] - PendingM --> PValue2[Pending Value 2] - PendingM --> PValueN[Pending Value N] - end - - style INT fill:#fff,stroke:#333,stroke-width:1px - style STC fill:#fff,stroke:#333,stroke-width:1px - style SMT fill:#fff,stroke:#333,stroke-width:1px -``` - -# How to integrate a slow updates tree - -1. Copy the *SlowTree.nr* example and its dependencies, found [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/contracts/slow_tree_contract). Replace the constants with whatever you like and deploy it to your sandbox -2. Copy the *SlowMap interface* for easy interaction with your deployed SlowTree. Find it [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/contracts/token_blacklist_contract/src/interfaces.nr) -3. Import this interface into your contract - -#include_code interface yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -5. Store the SlowTree address in private storage as a FieldNote - -#include_code constructor yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -6. Store the SlowTree address in public storage and initialize an instance of SlowMap using this address - -#include_code write_slow_update_public yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -7. Now you can read and update from private functions: - -#include_code get_and_update_private yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -8. Or from public functions: - -#include_code get_public yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -View the [reference](slow_updates_tree.md#reference) for more information. - -## Exploring an example integration through a **`TokenBlacklist`** Smart Contract - -The `TokenBlacklist` contract is a token contract that does not allow blacklisted accounts to perform mints or transfers. In this section we will go through how this is achieved through the slow updates tree. - -You can find the full code for the TokenBlacklist smart contract [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/contracts/token_blacklist_contract). - -### Importing SlowMap - -The contract first imports the **`SlowMap`** interface: - -#include_code interface yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -This interface allows the contract to interact with its attached SlowTree. It abstracts these functions so they do not have to be implemented in the TokenBlacklist contract. - -### Constructor and initialization - -The contract's constructor takes the address of the slow updates contract: - -#include_code constructor yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -This initialization sets up the connection between the **`TokenBlacklist`** contract and a previously deployed SlowTree, allowing it to use the interface to directly interact with the SlowTree. - -### Private transfer function utilizing the slow updates tree - -In the private transfer function, the contract uses the interface to check if a user is blacklisted: - -#include_code transfer_private yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -Here, the contract reads the roles of the sender and recipient from the SlowTree using the **`read_at`** function in the interface. It checks if either party is blacklisted, and if so, the transaction does not go ahead. - -# Reference - -## Struct `SlowMap` - -### Overview -The `SlowMap` struct is used to interact with a slow updates tree deployed via the SlowTree smart contract. - -### Fields - -| Name | Type | Description | -|---------|-----------|---------------------------------| -| address | `Field` | The address of the SlowTree contract | - -## Functions - -### at - -Returns an instance of `SlowMap` at the specified address. - -**Parameters** - -| Name | Type | Description | -|----------|----------------|----------------------------| -| `address`| `AztecAddress` | The address of the SlowTree | - -**Return** - -| Name | Type | Description | -|-------|-----------|------------------------------| -| - | `SlowMap` | The `SlowMap` instance | - -**Example** - -#include_code slowmap_at yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -### initialize - -Initializes the `SlowMap`. - -**Parameters** - -| Name | Type | Description | -|-----------|-----------------|----------------------| -| `context` | `PublicContext` | The execution context | - -**Return** - -| Name | Type | Description | -|------|------|-------------| -| - | - | - | - -**Example** - -#include_code slowmap_initialize yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -### read_at_pub - -Reads a value at a specified index from a public function. - -**Parameters** - -| Name | Type | Description | -|-----------|-----------------|-----------------------| -| `context` | `PublicContext` | The execution context | -| `index` | `Field` | The index to read at | - -**Return** - -| Name | Type | Description | -|----------|--------|-----------------------| -| `result` | `Field`| The value at `index` | - -**Example** - -#include_code read_at_pub yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -### read_at - -Reads a value at a specified index from a private function. - -**Parameters** - -| Name | Type | Description | -|-----------|--------------------|------------------------| -| `context` | `PrivateContext` | The execution context | -| `index` | `Field` | The index to read at | - -**Return** - -| Name | Type | Description | -|----------|--------|-----------------------| -| `result` | `Field`| The value at `index` | - -**Example** - -#include_code slowmap_read_at yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -### update_at_private - -Updates a value at a specified index from a private function. Does not return anything. - -**Parameters** - -| Name | Type | Description | -|-------------|--------------------|------------------------| -| `context` | `PrivateContext` | The execution context | -| `index` | `Field` | The index to update | -| `new_value` | `Field` | The new value | - -**Example** - -#include_code get_and_update_private yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - -## Updating from public - -This is not a method in the interface as it can be done using regular Aztec.nr public storage update syntax. - -**Example** - -#include_code write_slow_update_public yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust - diff --git a/docs/docs/developers/contracts/syntax/storage/main.md b/docs/docs/developers/contracts/syntax/storage/main.md deleted file mode 100644 index d28110bdb878..000000000000 --- a/docs/docs/developers/contracts/syntax/storage/main.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -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. - -You control this storage in Aztec using the `Storage` struct. 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. - -These state variables come in two forms: public and private. Public variables are visible to anyone, and private variables remain hidden within the contract. - -Aztec.nr has a few abstractions to help define the type of data your contract holds. These include Singletons, ImmutableSingletons, Set, and Map. - -On this and the following pages in this section, you’ll learn: - -- How to manage a smart contract's storage structure -- The distinctions and applications of public and private state variables -- How to use Singleton, ImmutableSingleton, Set, and Map -- An overview of 'notes' and the UTXO model -- Practical implications of Storage in real smart contracts - In an Aztec.nr contract, storage is to be defined as a single struct, that contains both public and private state variables. - -## Public and private state variables - -Public state variables can be read by anyone, while private state variables can only be read by their owner (or people whom the owner has shared the decrypted data or note viewing key with). - -Public state follows the Ethereum style account model, where each contract has its own key-value datastore. Private state follows a UTXO model, where note contents (pre-images) are only known by the sender and those able to decrypt them - see ([state model](../../../../learn/concepts/hybrid_state/main.md) and [private/public execution](../../../../learn/concepts/communication/public_private_calls/main.md)) for more background. - -## Storage struct - -:::info -The struct **must** be called `Storage` for the Aztec.nr library to properly handle it (this will be relaxed in the future). -::: - -```rust -struct Storage { - // public state variables - // private state variables -} -``` - -:::danger -If your contract uses storage (has Storage struct defined), you **MUST** include a `compute_note_hash_and_nullifier` function to allow PXE to process encrypted events. See [encrypted events](../events.md#processing-encrypted-events) for more. - -If you don't yet have any private state variables defined you can use this placeholder function: - -#include_code compute_note_hash_and_nullifier_placeholder /yarn-project/noir-contracts/contracts/token_bridge_contract/src/main.nr rust -::: - -Since Aztec.nr is written in Noir, which is state-less, we need to specify how the storage struct should be initialized to read and write data correctly. In most cases, the initialization of the storage is handled by the Aztec.nr library, which creates a default implementation based on the provided `Storage` struct. - -:::danger -The automatic initialization has some limitations. Using any combination of the provided storage primitives (`PublicState`, `Singleton`, `ImmutableSingleton`, `Set`, `Map`, including nested ones) will ensure that the library will be able to handle it on its own. - -Custom structures are also supported as long as they are generic over `T`, where `T` implements `Serialize` and `Deserialize` in the case it represents public state and additionally `NoteInterface` for private state. -::: - -Custom initialization of the storage is also possible. This is done by specifying an `init` function that is run in functions that rely on reading or altering the state variables. This `init` function must declare the Storage struct with an instantiation defining how variables are accessed and manipulated. The function MUST be called `init` for the Aztec.nr library to properly handle it (this will be relaxed in the future). - -```rust -impl Storage { - fn init(context: Context) -> Self { - Storage { - // (public state variables)::new() - // (private state variables)::new() - } - } -} -``` - -If you have defined a `Storage` struct following this naming scheme, then it will be made available to you through the reserved `storage` keyword within your contract functions. - -:::warning Using slot `0` is not supported! -No storage values should be initialized at slot `0` - storage slots begin at `1`. This is a known issue that will be fixed in the future. -::: - -## Map - -A `map` is a state variable that "maps" a key to a value. It can be used with private or public storage variables. - -:::info -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`](../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. - -You can view the implementation in the Aztec.nr library [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec-nr/aztec/src/state_vars/map.nr). - -### `new` - -When declaring the storage for a map, we use the `Map::new()` constructor. This takes the `storage_slot` and the `start_var_constructor` along with the [`Context`](../context.md). - -We will see examples of map constructors for public and private variables in later sections. - -#### As private storage - -When declaring a mapping in private storage, we have to specify which type of Note to use. In the example below, we are specifying that we want to use the `Singleton` note type. - -In the Storage struct: - -#include_code storage-map-singleton-declaration /yarn-project/noir-contracts/contracts/docs_example_contract/src/main.nr rust - -#### Public Example - -When declaring a public mapping in Storage, we have to specify that the type is public by declaring it as `PublicState` instead of specifying a note type like with private storage above. - -In the Storage struct: - -#include_code storage_minters /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust - -### `at` - -When dealing with a Map, we can access the value at a given key using the `::at` method. This takes the key as an argument and returns the value at that key. - -This function behaves similarly for both private and public maps. An example could be if we have a map with `minters`, which is mapping addresses to a flag for whether they are allowed to mint tokens or not. - -#include_code read_minter /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust - -Above, we are specifying that we want to get the storage in the Map `at` the `msg_sender()`, read the value stored and check that `msg_sender()` is indeed a minter. Doing a similar operation in Solidity code would look like: - -```solidity -require(minters[msg.sender], "caller is not minter"); -``` - -## Further Reading - -- Managing [Public State](./public_state.md) -- Jump to the page on [Private State](./private_state.md) - -## Concepts mentioned - -- [Hybrid State Model](../../../../learn/concepts/hybrid_state/main.md) -- [Public-private execution](../../../../learn/concepts/communication/public_private_calls/main.md) -- [Function Contexts](../context.md) diff --git a/docs/docs/developers/contracts/testing_contracts/main.md b/docs/docs/developers/contracts/testing_contracts/main.md new file mode 100644 index 000000000000..39f54296b0ab --- /dev/null +++ b/docs/docs/developers/contracts/testing_contracts/main.md @@ -0,0 +1,9 @@ +--- +title: Testing Contracts +--- + +We are currently working on a Foundry-like tool for writing unit tests in Noir. + +For now, it is easier to write e2e tests using [Aztec.js](../../aztecjs/main.md). + +To make testing easier, the sandbox is shipped with cheat codes to easily test in different states. Read about them and find a list [here](../../sandbox/references/cheat_codes.md). \ No newline at end of file diff --git a/docs/docs/developers/contracts/workflow.md b/docs/docs/developers/contracts/workflow.md deleted file mode 100644 index bfce487749d4..000000000000 --- a/docs/docs/developers/contracts/workflow.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Contract Workflow ---- - -## Setup -[Set up your project](./setup.md) - -## Write - -[Write a contract](./syntax/main.md). - -## Compile - -[Compile a contract](./compiling.md). - -## Unit Tests - -[Test individual noir functions](https://noir-lang.org/docs/getting_started/tooling/testing). - -## Deploy - -[Deploy a contract](./deploying.md). - -## Integration Tests - -[Test a deployed contract](../testing/main.md) diff --git a/docs/docs/developers/wallets/writing_an_account_contract.md b/docs/docs/developers/contracts/writing_contracts/accounts/write_accounts_contract.md similarity index 77% rename from docs/docs/developers/wallets/writing_an_account_contract.md rename to docs/docs/developers/contracts/writing_contracts/accounts/write_accounts_contract.md index fdc46499755f..ec559fa25461 100644 --- a/docs/docs/developers/wallets/writing_an_account_contract.md +++ b/docs/docs/developers/contracts/writing_contracts/accounts/write_accounts_contract.md @@ -1,34 +1,36 @@ -# Writing an Account Contract +--- +title: How to write an accounts contract +--- -This tutorial will take you through the process of writing your own account contract in Noir, along with the Typescript glue code required for using it within a [wallet](./main.md). +This tutorial will take you through the process of writing your own account contract in Aztec.nr, along with the Typescript glue code required for using it within a wallet. You will learn: - How to write a custom account contract in Aztec.nr - The entrypoint function for transaction authentication and call execution - The AccountActions module and EntrypointPayload struct, necessary inclusions for any account contract -- Customizing authorization validation within the 'is_valid' function (using Schnorr signatures as an example) +- Customizing authorization validation within the `is_valid` function (using Schnorr signatures as an example) - Typescript glue code to format and authenticate transactions - Deploying and testing the account contract -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](../../learn/concepts/accounts/main.md#what-is-account-abstraction) in the Aztec network. +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](../../../../learn/concepts/accounts/main.md#what-is-account-abstraction) in the Aztec network. -It is highly recommended that you understand how an [account](../../learn/concepts/accounts/main.md) is defined in Aztec, as well as the differences between privacy and authentication [keys](../../learn/concepts/accounts/keys.md). You will also need to know how to write a [contract in Noir](../contracts/main.md), as well as some basic [Typescript](https://www.typescriptlang.org/). +It is highly recommended that you understand how an [account](../../../../learn/concepts/accounts/main.md) is defined in Aztec, as well as the differences between privacy and authentication [keys](../../../../learn/concepts/accounts/keys.md). You will also need to know how to write a [contract in Noir](../layout.md), 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. -> That is, every time a transaction payload is passed to this account contract's 'entrypoint' function, the account contract will demand 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. +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](../../learn/concepts/accounts/keys.md#using-a-private-note), [in an immutable note](../../learn/concepts/accounts/keys.md#using-an-immutable-private-note), or [on a separate keystore](../../learn/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](../../../../learn/concepts/accounts/keys.md#using-a-private-note), [in an immutable note](../../../../learn/concepts/accounts/keys.md#using-an-immutable-private-note), or [on a separate keystore](../../../../learn/concepts/accounts/keys.md#using-a-separate-keystore), to mention a few examples. ## The account contract -Let's start with the account contract itself in Aztec.nr. Create [a new Aztec.nr contract project](../contracts/main.md) that will contain a file with the code for the account contract, with a hardcoded public key: +Let's start with the account contract itself in Aztec.nr. Create [a new Aztec.nr contract project](../../main.md) that will contain a file with the code for the account contract, with a hardcoded public key: #include_code contract yarn-project/noir-contracts/contracts/schnorr_hardcoded_account_contract/src/main.nr rust :::info -You can use [the Aztec CLI](../cli/main.md) to generate a new keypair if you want to use a different one: +You can use [the Aztec CLI](../../../sandbox/main.md) to generate a new keypair if you want to use a different one: ```bash $ aztec-cli generate-private-key @@ -83,11 +85,11 @@ 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](../../learn/concepts/accounts/keys.md#privacy-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](../../../../learn/concepts/accounts/keys.md#privacy-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 -Note that we get a [`Wallet` instance](./main.md) out of the account, which we can use for initializing the token contract class after deployment, so any transactions sent to it are sent from our wallet. We can then send a transaction to it and check its effects: +Note that we get a [`Wallet` instance](../../../../learn/concepts/accounts/main.md#account-contracts-and-wallets) out of the account, which we can use for initializing the token contract class after deployment, so any transactions sent to it are sent from our wallet. We can then send a transaction to it and check its effects: #include_code account-contract-works yarn-project/end-to-end/src/guides/writing_an_account_contract.test.ts typescript @@ -98,3 +100,5 @@ To make sure that we are actually validating the provided signature in our accou #include_code account-contract-fails yarn-project/end-to-end/src/guides/writing_an_account_contract.test.ts typescript Lo and behold, we get `Error: Assertion failed: 'verification == true'` when running the snippet above, pointing to the line in our account contract where we verify the Schnorr signature. + + diff --git a/docs/docs/developers/contracts/syntax/events.md b/docs/docs/developers/contracts/writing_contracts/events/emit_event.md similarity index 90% rename from docs/docs/developers/contracts/syntax/events.md rename to docs/docs/developers/contracts/writing_contracts/events/emit_event.md index 234e978544f5..f0631f076e9b 100644 --- a/docs/docs/developers/contracts/syntax/events.md +++ b/docs/docs/developers/contracts/writing_contracts/events/emit_event.md @@ -1,5 +1,5 @@ --- -title: Events +title: How to emit an event --- Events in Aztec work similarly to Ethereum events in the sense that they are a way for contracts to communicate with the outside world. @@ -10,10 +10,12 @@ Aztec events are currently represented as raw data and are not ABI encoded. ABI encoded events are a feature that will be added in the future. ::: -Unlike on Ethereum, there are 2 types of events supported by Aztec: encrypted and unencrypted. +Unlike on Ethereum, there are 2 types of events supported by Aztec: [encrypted](#encrypted-events) and [unencrypted](#unencrypted-events). ## Encrypted Events +### Register a recipient + 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. Recipients can be registered using the Aztec CLI or Aztec.js: @@ -54,22 +56,26 @@ await pxe.registerRecipient(completeAddress); :::info -If a note recipient is one of the accounts inside the PXE, we don't need to register it as a recipient because we already have the public key available. You can register a recipient as shown [here](../deploying#deploying-private-token-contract) +If a note recipient is one of the accounts inside the PXE, we don't need to register it as a recipient because we already have the public key available. You can register a recipient as shown [here](../../deploying_contracts/how_to_deploy_contract.md) At this point the Sandbox only enables the emitting of encrypted note preimages through encrypted events. In the future we will allow emitting arbitrary information. (If you currently emit arbitrary information, PXE will fail to decrypt, process and store this data, so it will not be queryable). ::: -To emit encrypted logs first import the `emit_encrypted_log` utility function which wraps an [oracle](./functions/oracles.md): +### Import library + +To emit encrypted logs first import the `emit_encrypted_log` utility function which wraps an [oracle](../oracles/main.md): #include_code encrypted_import /yarn-project/aztec-nr/address-note/src/address_note.nr rust -Then you can call the function: +### Call emit_encrypted_log + +After importing, you can call the function: #include_code encrypted /yarn-project/aztec-nr/address-note/src/address_note.nr rust -### Processing Encrypted Events +### Successfully process the encrypted event One of the functions of the PXE is constantly loading encrypted logs from the `AztecNode` and decrypting them. When new encrypted logs are obtained, the PXE will try to decrypt them using the private encryption key of all the accounts registered inside PXE. @@ -95,17 +101,23 @@ They can be emitted by both public and private functions. :::danger - Emitting unencrypted events from private function is a significant privacy leak and it should be considered by the developer whether it is acceptable. -- Unencrypted events are currently **NOT** linked to the contract emitting them, so it is practically a [`debug_log`](./functions/oracles.md#a-few-useful-inbuilt-oracles). +- Unencrypted events are currently **NOT** linked to the contract emitting them, so it is practically a [`debug_log`](../oracles/main.md#a-few-useful-inbuilt-oracles). ::: +### Import library + To emit unencrypted logs first import the `emit_unencrypted_log` utility function inside your contract: #include_code unencrypted_import /yarn-project/noir-contracts/contracts/test_contract/src/main.nr rust -Then you can call the function: +### Call emit_unencrypted_log + +After importing, you can call the function: #include_code emit_unencrypted /yarn-project/noir-contracts/contracts/test_contract/src/main.nr rust +### Querying the unencrypted event + Once emitted, unencrypted events are stored in AztecNode and can be queried by anyone: diff --git a/docs/docs/developers/contracts/example-contract.md b/docs/docs/developers/contracts/writing_contracts/example_contract.md similarity index 94% rename from docs/docs/developers/contracts/example-contract.md rename to docs/docs/developers/contracts/writing_contracts/example_contract.md index 58eb023c5c77..692c8c21b97b 100644 --- a/docs/docs/developers/contracts/example-contract.md +++ b/docs/docs/developers/contracts/writing_contracts/example_contract.md @@ -1,5 +1,5 @@ --- -title: Example Aztec.nr Contract +title: What a contract looks like --- ## Example Aztec.nr Contract diff --git a/docs/docs/developers/contracts/writing_contracts/functions/call_functions.md b/docs/docs/developers/contracts/writing_contracts/functions/call_functions.md new file mode 100644 index 000000000000..b1f40b093106 --- /dev/null +++ b/docs/docs/developers/contracts/writing_contracts/functions/call_functions.md @@ -0,0 +1,38 @@ +--- +title: How to call functions from other functions +--- + +A contract is a collection of persistent [state variables](../../references/storage/main.md), and [functions](../functions/main.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 + +A contract may be declared and given a name using the `contract` keyword (see snippet below). By convention, contracts are named in `PascalCase`. + +```rust title="contract keyword" +// highlight-next-line +contract MyContract { + + // Imports + + // Storage + + // Functions +} +``` +:::info A note for vanilla Noir devs +There is no [`main()`](https://noir-lang.org/docs/getting_started/project_breakdown/#mainnr) function within a Noir `contract` scope. More than one function can be an entrypoint. +::: + +## Directory structure + +Here's a common layout for a basic Aztec.nr Contract project: + +```title="layout of an aztec contract project" +─── my_aztec_contract_project + ├── src + │ ├── main.nr <-- your contract + └── Nargo.toml <-- package and dependency management +``` + +- 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/writing_token_contract.md). diff --git a/docs/docs/developers/contracts/syntax/context.md b/docs/docs/developers/contracts/writing_contracts/functions/context.md similarity index 88% rename from docs/docs/developers/contracts/syntax/context.md rename to docs/docs/developers/contracts/writing_contracts/functions/context.md index eea03e8eb0f4..a9b5609cff01 100644 --- a/docs/docs/developers/contracts/syntax/context.md +++ b/docs/docs/developers/contracts/writing_contracts/functions/context.md @@ -1,14 +1,12 @@ --- title: Function Context -description: Documentation of Aztec's Private and Public execution contexts -hide_table_of_contents: false --- # The Function 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](../../../learn/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. +The context is an object that is made available within every function in `Aztec.nr`. As mentioned in the [kernel circuit documentation](../../../../learn/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,9 +18,8 @@ On this page, you'll learn - Elements like return values, read requests, new commitments, and nullifiers in transaction processing - Differences between the private and public contexts, especially the unique features and variables in the public context -## Two context's one API - -The `Aztec` blockchain contains two environments [public and private](../../../learn/concepts/hybrid_state/main.md). +## Two contexts, one API +The `Aztec` blockchain contains two environments [public and private](../../../../learn/concepts/hybrid_state/main.md). - Private, for private transactions taking place on user's devices. - Public, for public transactions taking place on the network's sequencers. @@ -64,7 +61,7 @@ The call context contains information about the current call being made: - This value is the address of the current context's contract address. This value will be the value of the current contract that is being executed except for when the current call is a delegate call (Warning: This is yet to be implemented). In this case the value will be that of the sending contract. 3. Portal Contract Address - - This value stores the current contract's linked [portal contract](../portals/main.md) address. As a quick recap, this value is the value of the contracts related ethereum l1 contract address, and will be the recipient of any messages that are created by this contract. + - This value stores the current contract's linked [portal contract](../portals/portals.md) address. As a quick recap, this value is the value of the contracts related ethereum l1 contract address, and will be the recipient of any messages that are created by this contract. 4. Flags - Furthermore there are a series of flags that are stored within the application context: - is_delegate_call: Denotes whether the current call is a delegate call. If true, then the storage contract address will be the address of the sender. @@ -99,7 +96,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](./functions/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#after-expansion) for more details. return_values : BoundedVec, @@ -131,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](../../../learn/concepts/communication/cross_chain_calls.md) on the execution of each rollup. +New L2 to L1 messages contains messages that are delivered to the [l1 outbox](../../../../learn/concepts/communication/cross_chain_calls.md) on the execution of each rollup. ## Public Context diff --git a/docs/docs/developers/contracts/syntax/functions/inner_workings.md b/docs/docs/developers/contracts/writing_contracts/functions/inner_workings.md similarity index 90% rename from docs/docs/developers/contracts/syntax/functions/inner_workings.md rename to docs/docs/developers/contracts/writing_contracts/functions/inner_workings.md index a1d6ce4fdd66..47f2316d2f51 100644 --- a/docs/docs/developers/contracts/syntax/functions/inner_workings.md +++ b/docs/docs/developers/contracts/writing_contracts/functions/inner_workings.md @@ -54,7 +54,7 @@ Inside the kernel circuits, the inputs to functions are reduced to a single valu **Creating the function's context.** #include_code context-example-context /yarn-project/noir-contracts/contracts/docs_example_contract/src/main.nr rust -Each Aztec function has access to a [context](../context.md) object. This object, although labelled a global variable, is created locally on a users' device. It is initialized from the inputs provided by the kernel, and a hash of the function's inputs. +Each Aztec function has access to a [context](../functions/context.md) object. This object, although labelled a global variable, is created locally on a users' device. It is initialized from the inputs provided by the kernel, and a hash of the function's inputs. #include_code context-example-context-return /yarn-project/noir-contracts/contracts/docs_example_contract/src/main.nr rust @@ -64,7 +64,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 /yarn-project/noir-contracts/contracts/docs_example_contract/src/main.nr rust -When a [`Storage` struct](../storage/main.md) 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](../storage/define_storage.md) 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. @@ -75,7 +75,7 @@ This function takes the application context, and converts it into the `PrivateCi ## Unconstrained functions -Defining a function as `unconstrained` tells Aztec to simulate it completely client-side in the [ACIR simulator](../../../../learn/concepts/pxe/acir_simulator.md) without generating proofs. They are useful for extracting information from a user through an [oracle](./oracles.md). +Defining a function as `unconstrained` tells Aztec to simulate it completely client-side in the [ACIR simulator](../../../../learn/concepts/pxe/acir_simulator.md) without generating proofs. They are useful for extracting information from a user through an [oracle](../oracles/main.md). When an unconstrained function is called, it prompts the ACIR simulator to @@ -93,4 +93,4 @@ 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](../../artifacts.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](../../compiling_contracts/artifacts.md) is the compiled output of the contract, and has information like the function signature, parameter types, and return types diff --git a/docs/docs/developers/contracts/syntax/functions/main.md b/docs/docs/developers/contracts/writing_contracts/functions/main.md similarity index 53% rename from docs/docs/developers/contracts/syntax/functions/main.md rename to docs/docs/developers/contracts/writing_contracts/functions/main.md index 17de123e35b4..8164067e8cba 100644 --- a/docs/docs/developers/contracts/syntax/functions/main.md +++ b/docs/docs/developers/contracts/writing_contracts/functions/main.md @@ -6,15 +6,27 @@ Functions serve as the building blocks of smart contracts. Functions can be eith For a more practical guide of using multiple types of functions, follow the [token tutorial](../../../tutorials/writing_token_contract.md). -Every smart contract has a private `constructor` function which is called when the contract is deployed. There are also special oracle functions, which can get data from outside of the smart contract. In the context of Aztec, oracles are often used to get user-provided inputs. - Currently, any function is "mutable" in the sense that it might alter state. In the future, we will support static calls, similarly to EVM. A static call is essentially a call that does not alter state (it keeps state static). +## Constructors + +Every smart contract has a private `constructor` function which is called when the contract is deployed. + +A special constructor function must be declared within a contract's scope. + +A constructor doesn't have a name, because its purpose is clear: to initialize contract state. +In Aztec terminology, a constructor is always a 'private function' (i.e. it cannot be a public function). +A constructor behaves almost identically to any other function. It is just important for Aztec to be able to identify this function as special: it may only be called once, and will not be deployed as part of the contract. + +## Oracles + +There are also special oracle functions, which can get data from outside of the smart contract. In the context of Aztec, oracles are often used to get user-provided inputs. + Explore this section to learn: - [How function visibility works in Aztec](./visibility.md) - [Public, private, and unconstrained functions](./public_private_unconstrained.md), and how to write them -- How [constructors](./constructor.md) work and remain private -- [Calling functions from within the same smart contract and from different contracts](./calling_functions.md), including calling private functions from private functions, public from public, and even private from public -- [Oracles](./oracles) and how Aztec smart contracts might use them +- How to write a [constructor](./write_constructor.md) +- [Calling functions from within the same smart contract and from different contracts](./call_functions.md), including calling private functions from private functions, public from public, and even private from public +- [Oracles](../oracles/main.md) and how Aztec smart contracts might use them - [How functions work under the hood](./inner_workings.md) \ No newline at end of file diff --git a/docs/docs/developers/contracts/syntax/functions/public_private_unconstrained.md b/docs/docs/developers/contracts/writing_contracts/functions/public_private_unconstrained.md similarity index 90% rename from docs/docs/developers/contracts/syntax/functions/public_private_unconstrained.md rename to docs/docs/developers/contracts/writing_contracts/functions/public_private_unconstrained.md index be2c97c27b37..935a958cd8e9 100644 --- a/docs/docs/developers/contracts/syntax/functions/public_private_unconstrained.md +++ b/docs/docs/developers/contracts/writing_contracts/functions/public_private_unconstrained.md @@ -12,13 +12,13 @@ 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](./context.md) available within the function's execution scope. #include_code set_minter /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust ## `Private` Functions -A private function operates on private information, and is executed by the user. 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#private-context-broken-down) available within the function's execution scope. +A private function operates on private information, and is executed by the user. 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. #include_code redeem_shield /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust diff --git a/docs/docs/developers/contracts/syntax/functions/visibility.md b/docs/docs/developers/contracts/writing_contracts/functions/visibility.md similarity index 100% rename from docs/docs/developers/contracts/syntax/functions/visibility.md rename to docs/docs/developers/contracts/writing_contracts/functions/visibility.md diff --git a/docs/docs/developers/contracts/writing_contracts/functions/write_constructor.md b/docs/docs/developers/contracts/writing_contracts/functions/write_constructor.md new file mode 100644 index 000000000000..868199b70154 --- /dev/null +++ b/docs/docs/developers/contracts/writing_contracts/functions/write_constructor.md @@ -0,0 +1,37 @@ +--- +title: How to write a constructor +--- + +This page explains how to write a constructor function. + +To learn more about constructors, read [this](./main.md#constructors). + +## Annotate with `#[aztec(private)]` + +Currently, all constructors in Aztec must be private. + +Define your constructor like so: + +```rust +#[aztec(private)] +fn constructor() +``` + +## Option 1: Empty constructor + +Your constructor does not need to do anything; you can leave it blank like so: + +```rust +#[aztec(private)] +fn constructor() {} +``` + +## Option 2: Constructor with logic + +Constructors are commonly used to set an admin, such as this example: + +#include_code constructor /yarn-project/noir-contracts/contracts/token_contract/src/main.nr rust + +Here, the constructor is calling a public function. It can also call a private function. Learn more about calling functions from functions [here](../functions/call_functions.md). + +To see constructors in action, check out the [Aztec.nr getting started guide](../../../getting_started/aztecnr-getting-started.md). \ No newline at end of file diff --git a/docs/docs/developers/contracts/syntax/historical_access/how_to_prove_history.md b/docs/docs/developers/contracts/writing_contracts/historical_data/archive_tree/how_to_prove_history.md similarity index 85% rename from docs/docs/developers/contracts/syntax/historical_access/how_to_prove_history.md rename to docs/docs/developers/contracts/writing_contracts/historical_data/archive_tree/how_to_prove_history.md index f5d91061ef08..4dc3711fbcd2 100644 --- a/docs/docs/developers/contracts/syntax/historical_access/how_to_prove_history.md +++ b/docs/docs/developers/contracts/writing_contracts/historical_data/archive_tree/how_to_prove_history.md @@ -1,17 +1,19 @@ --- -title: How to prove existence of historical notes and nullifiers +title: How to use the Arhive 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 an archive tree. You can learn more about how it works in the [concepts section](../../../../learn/concepts/storage/trees/main.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 an archive tree. You can learn more about how it works in the [concepts section](../../../../../learn/concepts/storage/trees/main.md#archive-tree). + +View the History lib reference [here](../../../references/history_lib_reference.md). # History library The history library allows you to prove any of the following at a given block height before the current height: -* [Note inclusion](./history_lib_reference.md#note-inclusion) -* [Nullifier inclusion](./history_lib_reference.md#nullifier-inclusion) -* [Note validity](./history_lib_reference.md#note-validity) -* [Existence of public value](./history_lib_reference.md#public-value-inclusion) -* [Contract inclusion](./history_lib_reference.md#contract-inclusion) +* Note inclusion +* Nullifier inclusion +* Note validity +* Existence of public value +* Contract inclusion Using this library, you can check that specific notes or nullifiers were part of Aztec network state at specific blocks. This can be useful for things such as: @@ -25,7 +27,7 @@ Using this library, you can check that specific notes or nullifiers were part of * Prove a note was included in a specified block * Create a nullifier and prove it was not included in a specified block -For a more extensive reference, go to [the reference page](./history_lib_reference.md). +For a more extensive reference, go to [the reference page](../../../references/history_lib_reference.md). ## 1. Import the `history` library from `aztec` @@ -92,4 +94,4 @@ You can also prove that a nullifier was not included in a specified block by usi ## Prove contract inclusion, public value inclusion, and use current state in lookups -To see what else you can do with the `history` library, check out the [reference](./history_lib_reference.md). +To see what else you can do with the `history` library, check out the [reference](../../../references/history_lib_reference.md). diff --git a/docs/docs/developers/contracts/writing_contracts/historical_data/slow_updates_tree/implement_slow_updates.md b/docs/docs/developers/contracts/writing_contracts/historical_data/slow_updates_tree/implement_slow_updates.md new file mode 100644 index 000000000000..ce6d4710ced4 --- /dev/null +++ b/docs/docs/developers/contracts/writing_contracts/historical_data/slow_updates_tree/implement_slow_updates.md @@ -0,0 +1,63 @@ +--- +title: How to implement a Slow Updates Tree +--- + +To learn more about the Slow Updates Tree, go [here](./main.md) + +On this page you will learn how to implement a slow updates tree into your contract, and an example of a token blacklisting contract that uses the slow updates tree. + +# How to implement a slow updates tree + +1. Copy the *SlowTree.nr* example and its dependencies, found [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/contracts/slow_tree_contract). Replace the constants with whatever you like and deploy it to your sandbox +2. Copy the *SlowMap interface* for easy interaction with your deployed SlowTree. Find it [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/contracts/token_blacklist_contract/src/interfaces.nr) +3. Import this interface into your contract + +#include_code interface yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +5. Store the SlowTree address in private storage as a FieldNote + +#include_code constructor yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +6. Store the SlowTree address in public storage and initialize an instance of SlowMap using this address + +#include_code write_slow_update_public yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +7. Now you can read and update from private functions: + +#include_code get_and_update_private yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +8. Or from public functions: + +#include_code get_public yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +View the [reference](../../../references/slow_updates_tree.md) for more information. + +## Exploring an example integration through a **`TokenBlacklist`** Smart Contract + +The `TokenBlacklist` contract is a token contract that does not allow blacklisted accounts to perform mints or transfers. In this section we will go through how this is achieved through the slow updates tree. + +You can find the full code for the TokenBlacklist smart contract [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/contracts/token_blacklist_contract). + +### Importing SlowMap + +The contract first imports the **`SlowMap`** interface: + +#include_code interface yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +This interface allows the contract to interact with its attached SlowTree. It abstracts these functions so they do not have to be implemented in the TokenBlacklist contract. + +### Constructor and initialization + +The contract's constructor takes the address of the slow updates contract: + +#include_code constructor yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +This initialization sets up the connection between the **`TokenBlacklist`** contract and a previously deployed SlowTree, allowing it to use the interface to directly interact with the SlowTree. + +### Private transfer function utilizing the slow updates tree + +In the private transfer function, the contract uses the interface to check if a user is blacklisted: + +#include_code transfer_private yarn-project/noir-contracts/contracts/token_blacklist_contract/src/main.nr rust + +Here, the contract reads the roles of the sender and recipient from the SlowTree using the **`read_at`** function in the interface. It checks if either party is blacklisted, and if so, the transaction does not go ahead. diff --git a/docs/docs/developers/contracts/writing_contracts/historical_data/slow_updates_tree/main.md b/docs/docs/developers/contracts/writing_contracts/historical_data/slow_updates_tree/main.md new file mode 100644 index 000000000000..6c40f80c4409 --- /dev/null +++ b/docs/docs/developers/contracts/writing_contracts/historical_data/slow_updates_tree/main.md @@ -0,0 +1,81 @@ +--- +title: Slow Updates Tree +--- + +Slow Updates Tree is a data structure that allows for historical public data to be accessed in both private and public domains. Read the high level overview in the [Communication section](../../../../../learn/concepts/communication/public_private_calls/slow_updates_tree.md). This page explains the components involved. + +If you want to integrate it in your contract, follow this [guide](../slow_updates_tree/implement_slow_updates.md). + +The slow updates tree works by having a current tree and a pending tree, and replacing the current tree with the pending tree after an epoch has passed. Public functions can read directly from the current tree, and private functions can perform a membership proof that values are part of a commitment to the current state of the tree. + +# Components involved in implementing a slow updates tree + +There are generally 4 main components involved to make it easier to use a slow updates tree, with 3 already implemented by Aztec. This makes it easier to interact with a slow updates tree through a simple interface. These four components are: + +## Main smart contract + +This is the primary smart contract that will use the slow updates tree. In the example we use a [token with blacklisting features](./implement_slow_updates.md#exploring-an-example-integration-through-a-tokenblacklist-smart-contract). + +## Interface + +This interface of the slow updates tree contract allows your contract to interact with the Slow Updates Tree contract. It provides methods for reading and updating values in the tree in both public and private contexts. You can find it [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/contracts/token_blacklist_contract/src/interfaces.nr). + +## SlowTree.nr contract + +This is a smart contract developed by Aztec that establishes and manages a slow updates tree structure. It allows developers to access and interact with the tree, such as reading and updating data. + +You can find it [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/contracts/slow_tree_contract). + +## SlowMap type + +This is a type in the Aztec.nr library that is utilized by the SlowTree contract. It defines the underlying data structure for the slow updates tree, and handles storing both the current and pending values for each data entry. + +You can find it [here](https://github.com/AztecProtocol/aztec-nr/blob/master/slow-updates-tree/src/slow_map.nr). + +The diagram below describes how these components work together. It does not contain all the functionality. + +```mermaid +graph TD + MSC[Main Smart Contract] --> INT[Interface] + STC --> SMT + + INT_RAP[read_at_pub] <--> STC_RAP[read_at_public] + INT_RA[read_at] <--> STC_RA[read_at] + INT_UAP[update_at_public] <--> STC_UAP[update_at_public] + INT_UA[update_at_private] <--> STC_UA[update_at_private] + + STC_RA <--> VMP[verify_membership_proof] + STC_UA <--> CR[compute_roots] + + subgraph INT[Interface] + INT_RAP + INT_UAP + INT_RA + INT_UA + end + + subgraph STC[SlowTree.nr] + STC_RAP + STC_UAP + STC_RA + STC_UA + end + + subgraph SMT[SlowMap Type] + Change{Epoch Over} -->|True| Current{Current} + Change -->|False| Pending{Pending} + Current --> Current1[Current Commitment 1] + Current --> CurrentM[Current Commitment M] + CurrentM --> Value1[Current Value 1] + CurrentM --> Value2[Current Value 2] + CurrentM --> ValueN[Current Value N] + Pending --> PendingM[Pending Commitment 1] + PendingM --> PValue1[Pending Value 1] + PendingM --> PValue2[Pending Value 2] + PendingM --> PValueN[Pending Value N] + end + + style INT fill:#fff,stroke:#333,stroke-width:1px + style STC fill:#fff,stroke:#333,stroke-width:1px + style SMT fill:#fff,stroke:#333,stroke-width:1px +``` \ No newline at end of file diff --git a/docs/docs/developers/contracts/layout.md b/docs/docs/developers/contracts/writing_contracts/layout.md similarity index 61% rename from docs/docs/developers/contracts/layout.md rename to docs/docs/developers/contracts/writing_contracts/layout.md index 48fbc9a7030f..d8bdd16387a6 100644 --- a/docs/docs/developers/contracts/layout.md +++ b/docs/docs/developers/contracts/writing_contracts/layout.md @@ -1,8 +1,8 @@ --- -title: Structure +title: Structure of a contract --- -A contract is a collection of persistent [state variables](./syntax/storage/main.md), and [functions](./syntax/functions/main.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. +A contract is a collection of persistent [state variables](../references/storage/main.md), and [functions](./functions/main.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 @@ -35,4 +35,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/writing_token_contract.md). +- You can review the structure of a complete contract in the token contract tutorial [here](../../tutorials/writing_token_contract.md). diff --git a/docs/docs/developers/contracts/syntax/oracles.md b/docs/docs/developers/contracts/writing_contracts/oracles/inbuilt_oracles.md similarity index 54% rename from docs/docs/developers/contracts/syntax/oracles.md rename to docs/docs/developers/contracts/writing_contracts/oracles/inbuilt_oracles.md index fa524a02bc8b..6f8a40b23bc3 100644 --- a/docs/docs/developers/contracts/syntax/oracles.md +++ b/docs/docs/developers/contracts/writing_contracts/oracles/inbuilt_oracles.md @@ -1,18 +1,12 @@ --- -title: Oracles +title: Inbuilt Oracles --- -On this page you will learn: - -1. [A list of inbuilt oracles](#inbuilt-oracles) -3. [How to use the debug_log oracle](#how-to-use-the-debug-oracle) -3. [How to use the auth_witness oracle](#how-to-use-the-auth_witness-oracle) -4. [How to use the pop_capsule oracle for arbitrary data](#how-to-use-the-popCapsule-oracle) -4. [Reference](#oracles-reference) +This page goes over all the oracles that are available in Aztec.nr. If you'd like to read more about what oracles are, check out [this page](../oracles/main.md). ## Inbuilt oracles -- [`debug_log`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/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](../../debugging/main.md). +- [`debug_log`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/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](../../../debugging/main.md#logging-in-aztecnr). - [`auth_witness`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/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/yarn-project/aztec-nr/aztec/src/oracle/get_l1_to_l2_message.nr) - Useful for application that receive messages from L1 to be consumed on L2, such as token bridges or other cross-chain applications. - [`notes`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/aztec-nr/aztec/src/oracle/notes.nr) - Provides a lot of functions related to notes, such as fetches notes from storage etc, used behind the scenes for value notes and other pre-build note implementations. @@ -20,30 +14,4 @@ On this page you will learn: Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/aztec-nr/aztec/src/oracle). -:::note -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](#how-to-use-the-pop_capsule-oracle). -::: - -## How to use the popCapsule oracle - -`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: - -### 1. Define the pop_capsule function - -In a new file on the same level as your `main.nr`, implement an unconstrained function that calls the pop_capsule oracle: - -#include_code pop_capsule yarn-project/noir-contracts/contracts/slow_tree_contract/src/capsule.nr rust - -### 2. Import this into your smart contract - -If it lies in the same directory as your smart contract, you can import it like this: - -#include_code import_pop_capsule yarn-project/noir-contracts/contracts/slow_tree_contract/src/main.nr rust - -### 3. Use it as any other oracle - -Now it becomes a regular oracle you can call like this: - -#include_code pop_capsule yarn-project/noir-contracts/contracts/slow_tree_contract/src/main.nr rust - - +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](./pop_capsule.md). \ No newline at end of file diff --git a/docs/docs/developers/contracts/syntax/functions/oracles.md b/docs/docs/developers/contracts/writing_contracts/oracles/main.md similarity index 97% rename from docs/docs/developers/contracts/syntax/functions/oracles.md rename to docs/docs/developers/contracts/writing_contracts/oracles/main.md index 28a57bed1d6b..673dbfce3896 100644 --- a/docs/docs/developers/contracts/syntax/functions/oracles.md +++ b/docs/docs/developers/contracts/writing_contracts/oracles/main.md @@ -4,7 +4,7 @@ title: Oracle Functions 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](../oracles.md). +Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](./pop_capsule.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. diff --git a/docs/docs/developers/contracts/writing_contracts/oracles/pop_capsule.md b/docs/docs/developers/contracts/writing_contracts/oracles/pop_capsule.md new file mode 100644 index 000000000000..f7d4c02c800c --- /dev/null +++ b/docs/docs/developers/contracts/writing_contracts/oracles/pop_capsule.md @@ -0,0 +1,29 @@ +--- +title: How to use the popCapsule oracle +--- + +On this page you will learn how to use the `popCapsule` oracle. To see what other oracles are available in Aztec.nr, go [here](./inbuilt_oracles.md). + +## How to use the popCapsule oracle + +`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: + +### 1. Define the pop_capsule function + +In a new file on the same level as your `main.nr`, implement an unconstrained function that calls the pop_capsule oracle: + +#include_code pop_capsule yarn-project/noir-contracts/contracts/slow_tree_contract/src/capsule.nr rust + +### 2. Import this into your smart contract + +If it lies in the same directory as your smart contract, you can import it like this: + +#include_code import_pop_capsule yarn-project/noir-contracts/contracts/slow_tree_contract/src/main.nr rust + +### 3. Use it as any other oracle + +Now it becomes a regular oracle you can call like this: + +#include_code pop_capsule yarn-project/noir-contracts/contracts/slow_tree_contract/src/main.nr rust + + diff --git a/docs/docs/developers/contracts/portals/main.md b/docs/docs/developers/contracts/writing_contracts/portals/communicate_with_portal.md similarity index 93% rename from docs/docs/developers/contracts/portals/main.md rename to docs/docs/developers/contracts/writing_contracts/portals/communicate_with_portal.md index 69142288e6d5..d2e62dedda1b 100644 --- a/docs/docs/developers/contracts/portals/main.md +++ b/docs/docs/developers/contracts/writing_contracts/portals/communicate_with_portal.md @@ -1,17 +1,14 @@ --- -title: Portals -description: Documentation of Aztec's Portals and Cross-chain communication. +title: Communicating with L1 --- -## What is a portal +Is this your first time hearing the word `Portal`? Check out the [concepts section](../../../../learn/concepts/communication/cross_chain_calls.md). -A portal is the point of contact between L1 and a specific contract on Aztec. For applications such as token bridges, this is the point where the tokens are held on L1 while used in L2. - -As outlined in [Communication](../../../learn/concepts/communication/cross_chain_calls.md), an Aztec L2 contract is linked to _ONE_ L1 address at time of deployment (specified by the developer). This L1 address is the only address that can send messages to that specific L2 contract, and the only address that can receive messages sent from the L2 contract to L1. Note, that a portal don't actually need to be a contract, it could be any address on L1. We say that an Aztec contract is attached to a portal. +Follow the [token bridge tutorial](../../../tutorials/token_portal/main.md) for hands-on experience writing and deploying a Portal contract. ## Passing data to the rollup -Whether it is tokens or other information being passed to the rollup, the portal should use the [`Inbox`](./inbox.md) to do it. +Whether it is tokens or other information being passed to the rollup, the portal should use the `Inbox` to do it. The `Inbox` can be seen as a mailbox to the rollup, portals put messages into the box, and the sequencers then decide which of these message they want to include in their blocks (each message has a fee attached to it, so there is a fee market here). @@ -100,17 +97,6 @@ As noted earlier, the portal contract should check that the sender is as expecte #include_code token_portal_withdraw l1-contracts/test/portals/TokenPortal.sol solidity -## How to deploy a contract with a portal - -- Deploy to L1 using Viem, Foundry or your preferred tool; -- Deploy to L2 passing in the address of the L1 portal as its portal contract; - ```typescript - const deploymentTx = Contract.deploy(wallet).send({ - portalContract: tokenPortalAddress, - }); - ``` -- Initialize l1 with l2 address for access control. - ## Considerations ### Structure of messages diff --git a/docs/docs/developers/contracts/writing_contracts/portals/deploy_with_portal.md b/docs/docs/developers/contracts/writing_contracts/portals/deploy_with_portal.md new file mode 100644 index 000000000000..2277e588facc --- /dev/null +++ b/docs/docs/developers/contracts/writing_contracts/portals/deploy_with_portal.md @@ -0,0 +1,14 @@ +--- +title: How to deploy a contract with a Portal +--- + +- Deploy to L1 using Viem, Foundry or your preferred tool; +- Deploy to L2 passing in the address of the L1 portal as its portal contract; + ```typescript + const deploymentTx = Contract.deploy(wallet).send({ + portalContract: tokenPortalAddress, + }); + ``` +- Initialize l1 with l2 address for access control. + +Follow the [token bridge tutorial](../../../tutorials/token_portal/main.md) for hands-on experience writing and deploying a Portal contract. \ No newline at end of file diff --git a/docs/docs/developers/contracts/writing_contracts/portals/portals.md b/docs/docs/developers/contracts/writing_contracts/portals/portals.md new file mode 100644 index 000000000000..642bad03eb4e --- /dev/null +++ b/docs/docs/developers/contracts/writing_contracts/portals/portals.md @@ -0,0 +1,7 @@ +--- +title: Portals +--- + +A portal is the point of contact between L1 and a specific contract on Aztec. For applications such as token bridges, this is the point where the tokens are held on L1 while used in L2. + +As outlined in [Communication](../../../../learn/concepts/communication/cross_chain_calls.md), an Aztec L2 contract is linked to _ONE_ L1 address at time of deployment (specified by the developer). This L1 address is the only address that can send messages to that specific L2 contract, and the only address that can receive messages sent from the L2 contract to L1. Note, that a portal don't actually need to be a contract, it could be any address on L1. We say that an Aztec contract is attached to a portal. diff --git a/docs/docs/developers/contracts/writing_contracts/storage/define_storage.md b/docs/docs/developers/contracts/writing_contracts/storage/define_storage.md new file mode 100644 index 000000000000..498042520514 --- /dev/null +++ b/docs/docs/developers/contracts/writing_contracts/storage/define_storage.md @@ -0,0 +1,47 @@ +--- +title: How to define contract 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](../../../../learn/concepts/storage/storage_slots.md). + +[See the storage reference](../../references/storage/main.md). + +:::info +The struct **must** be called `Storage` for the Aztec.nr library to properly handle it (this will be relaxed in the future). +::: + +```rust +struct Storage { + // public state variables + // private state variables +} +``` + +:::danger +If your contract uses storage (has Storage struct defined), you **MUST** include a `compute_note_hash_and_nullifier` function to allow PXE to process encrypted events. See [encrypted events](../events/emit_event.md#successfully-process-the-encrypted-event) for more. + +If you don't yet have any private state variables defined you can use this placeholder function: + +#include_code compute_note_hash_and_nullifier_placeholder /yarn-project/noir-contracts/contracts/token_bridge_contract/src/main.nr rust +::: + +Since Aztec.nr is written in Noir, which is state-less, we need to specify how the storage struct should be initialized to read and write data correctly. This is done by specifying an `init` function that is run in functions that rely on reading or altering the state variables. This `init` function must declare the Storage struct with an instantiation defining how variables are accessed and manipulated. The function MUST be called `init` for the Aztec.nr library to properly handle it (this will be relaxed in the future). + +```rust +impl Storage { + fn init(context: Context) -> Self { + Storage { + // (public state variables)::new() + // (private state variables)::new() + } + } +} +``` + +If you have defined a `Storage` struct following this naming scheme, then it will be made available to you through the reserved `storage` keyword within your contract functions. + +:::warning Using slot `0` is not supported! +No storage values should be initialized at slot `0` - storage slots begin at `1`. This is a known issue that will be fixed in the future. +::: diff --git a/docs/docs/developers/contracts/writing_contracts/storage/main.md b/docs/docs/developers/contracts/writing_contracts/storage/main.md new file mode 100644 index 000000000000..df4574040d1e --- /dev/null +++ b/docs/docs/developers/contracts/writing_contracts/storage/main.md @@ -0,0 +1,12 @@ +--- +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. + +You control this storage in Aztec using the Storage struct. 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. + +## Continue reading + +- Learn how to define a storage struct [here](./define_storage.md) +- View the storage reference with all variable types [here](../../references/storage/main.md) \ No newline at end of file diff --git a/docs/docs/developers/contracts/syntax/storage/storage_slots.md b/docs/docs/developers/contracts/writing_contracts/storage/storage_slots.md similarity index 100% rename from docs/docs/developers/contracts/syntax/storage/storage_slots.md rename to docs/docs/developers/contracts/writing_contracts/storage/storage_slots.md diff --git a/docs/docs/developers/getting_started/aztecjs-getting-started.md b/docs/docs/developers/getting_started/aztecjs-getting-started.md index d2f1fd6c2e61..1efb1b0742e4 100644 --- a/docs/docs/developers/getting_started/aztecjs-getting-started.md +++ b/docs/docs/developers/getting_started/aztecjs-getting-started.md @@ -1,5 +1,5 @@ --- -title: Getting Started with Aztec.js +title: An introduction to Aztec.js --- import Image from "@theme/IdealImage"; @@ -375,4 +375,4 @@ That's it! We have successfully deployed a token contract to an instance of the ## Next Steps -Learn more about writing Aztec.nr contracts in the [Aztec.nr getting started guide](./aztecnr-getting-started.md). +Learn more about writing Aztec.nr contracts on the [next page](./aztecnr-getting-started.md). diff --git a/docs/docs/developers/getting_started/aztecnr-getting-started.md b/docs/docs/developers/getting_started/aztecnr-getting-started.md index 5235e2942e43..0bd535ec764b 100644 --- a/docs/docs/developers/getting_started/aztecnr-getting-started.md +++ b/docs/docs/developers/getting_started/aztecnr-getting-started.md @@ -1,5 +1,5 @@ --- -title: Getting Started with Aztec.nr +title: Writing your first smart contract --- 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. @@ -80,7 +80,7 @@ Context gives us access to the environment information such as `msg.sender`. We `map::Map` -Map is a private state variable that functions like a dictionary, relating Fields to other state variables. You can learn more about it [here](../contracts/syntax/main.md). +Map is a private state variable that functions like a dictionary, relating Fields to other state variables. `value_note` @@ -102,7 +102,7 @@ Let’s create a `constructor` method to run on deployment that assigns an initi This function accesses the counts from storage. Then it assigns the passed initial counter to the `owner`'s counter privately using `at().add()`. -We have annotated this and other functions with `#[aztec(private)]` which are ABI macros so the compiler understands it will handle private inputs. Learn more about functions and annotations [here](../contracts/syntax/functions/main.md). +We have annotated this and other functions with `#[aztec(private)]` which are ABI macros so the compiler understands it will handle private inputs. Learn more about functions and annotations [here](../contracts/writing_contracts/functions/main.md). ## Incrementing our counter @@ -183,7 +183,7 @@ Partial Address: 0x211edeb823ef3e042e91f338d0d83d0c90606dba16f678c701d8bb64e64e2 Use one of these `address`es as the `owner`. You can either copy it or export. -To deploy the counter contract, [ensure the sandbox is running](../cli/sandbox-reference.md) and run this in the root of your Noir project: +To deploy the counter contract, [ensure the sandbox is running](../sandbox/references/sandbox-reference.md) and run this in the root of your Noir project: ```bash aztec-cli deploy contracts/counter/src/artifacts/Counter.json --args 100 0x2a0f32c34c5b948a7f9766f0c1aad70a86c0ee649f56208e936be4324d49b0b9 @@ -211,11 +211,11 @@ Now you can explore. **Interested in learning more about how Aztec works under the hood?** -Understand the high level architecture [here](../../learn/about_aztec/technical_overview.md). +Understand the high level architecture on the [Core Components page](../../learn/about_aztec/technical_overview.md). You can also explore Aztec's [hybrid state model](../../learn/concepts/hybrid_state/main.md) and [the lifecycle of a transaction](../../learn/concepts/transactions.md). -**Want to write more advanced smart contracts?** +**Want to write more contracts?** -Follow the token contract tutorial [here](../tutorials/writing_token_contract.md). +Follow the series of tutorials, starting with the private voting contract [here](../tutorials/writing_private_voting_contract.md). **Ready to dive into Aztec and Ethereum cross-chain communication?** diff --git a/docs/docs/developers/getting_started/main.md b/docs/docs/developers/getting_started/main.md index 0e6fa1844edf..4d18453d50aa 100644 --- a/docs/docs/developers/getting_started/main.md +++ b/docs/docs/developers/getting_started/main.md @@ -12,7 +12,7 @@ If this is your first time using Aztec, and you want to get started by learning ## Learn -If you want to read more about the high level concepts of Aztec before writing some code, head to the [Concepts section](../../learn/about_aztec/technical_overview.md). +If you want to read more about the high level concepts of Aztec before writing some code, head over to the [Core Components section](../../learn/about_aztec/technical_overview.md). ## In this section diff --git a/docs/docs/developers/getting_started/quickstart.md b/docs/docs/developers/getting_started/quickstart.md index a7f1f894916e..6f22059ce4f3 100644 --- a/docs/docs/developers/getting_started/quickstart.md +++ b/docs/docs/developers/getting_started/quickstart.md @@ -95,6 +95,6 @@ Congratulations! You are all set up with the Aztec sandbox! ## What's next? -To start writing your first Aztec.nr smart contract, go to the [next page](aztecnr-getting-started.md). +To deploy and interact with a contract using Aztec.js, go to the [next page](aztecnr-getting-started.md). -You can also dig more into the sandbox and CLI [here](../cli/main.md). +You can also dig more into the sandbox and CLI [here](../sandbox/main.md). diff --git a/docs/docs/developers/limitations/main.md b/docs/docs/developers/limitations/main.md index a2db0df2acfa..0147994b05aa 100644 --- a/docs/docs/developers/limitations/main.md +++ b/docs/docs/developers/limitations/main.md @@ -29,13 +29,13 @@ 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 [constructor](../contracts/syntax/functions/constructor.md). -- No static nor delegate calls (see [mutability](../contracts/syntax/functions/main.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, see [constructor](../contracts/writing_contracts/functions/write_constructor.md). +- No static nor delegate calls (see [mutability](../contracts/writing_contracts/functions/main.md)). - These values are unused in the call-context. - Beware that what you think of as a `view` could alter state ATM! Notably the account could alter state or re-enter whenever the account contract's `is_valid` function is called. - `msg_sender` is currently leaking when doing private -> public calls - - The `msg_sender` will always be set, if you call a public function from the private world, the `msg_sender` will be set to the private caller's address. See [function context](../contracts/syntax/context.md). -- The initial `msg_sender` is 0, which can be problematic for some contracts, see [function visibility](../contracts/syntax/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. See [function context](../contracts/writing_contracts/functions/context.md). +- The initial `msg_sender` is 0, which can be problematic for some contracts, see [function visibility](../contracts/writing_contracts/functions/visibility.md). - Unencrypted logs don't link to the contract that emitted it, so essentially just a `debug_log`` that you can match values against. - A note that is created and nullified in the same transaction will still emit an encrypted log. - A limited amount of new commitments, nullifiers and calls that are supported by a transaction, see [circuit limitations](#circuit-limitations). @@ -193,7 +193,7 @@ Here are the current constants: #### What are the consequences? -When you write an [Aztec.nr](../contracts/main.md) [function](../contracts/syntax/functions/main.md), there will be upper bounds on the following: +When you write an [Aztec.nr](../contracts/main.md) [function](../contracts/writing_contracts/functions/main.md), there will be upper bounds on the following: - The number of public state reads and writes; - The number of note reads and nullifications; diff --git a/docs/docs/developers/privacy/main.md b/docs/docs/developers/privacy/main.md index ab58316956a8..d7d2997df553 100644 --- a/docs/docs/developers/privacy/main.md +++ b/docs/docs/developers/privacy/main.md @@ -49,7 +49,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](../contracts/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. See [here](../contracts/references/portals/inbox.md) for more details. ### Timing of transactions diff --git a/docs/docs/developers/cli/blank_box.md b/docs/docs/developers/sandbox/guides/blank_box.md similarity index 93% rename from docs/docs/developers/cli/blank_box.md rename to docs/docs/developers/sandbox/guides/blank_box.md index 94ceb1d7eca8..6838786c1da1 100644 --- a/docs/docs/developers/cli/blank_box.md +++ b/docs/docs/developers/sandbox/guides/blank_box.md @@ -1,5 +1,5 @@ --- -title: Aztec Boxes +title: Run a blank Aztec Box --- This page will go over Aztec Boxes, which are full stack Aztec project templates that come with: @@ -16,11 +16,11 @@ There are also boxes that include a basic React interface (`blank-react`) and an ## Setup -See the Quickstart page for [requirements](../getting_started/quickstart.md#requirements), starting the local [Sandbox environment](../getting_started/quickstart.md#sandbox-installation) and [installing the CLI](../getting_started/quickstart#cli-installation). +See the Quickstart page for [requirements](../../getting_started/quickstart.md#requirements), starting the local [Sandbox environment](../../getting_started/quickstart.md#sandbox-installation) and [installing the CLI](../../getting_started/quickstart#cli-installation). Aztec Boxes use [yarn](https://classic.yarnpkg.com/) for package management, so if you want to follow along exactly, make sure you have it [installed](https://classic.yarnpkg.com/en/docs/install). -You will also need to install Aztec tooling to compile contracts. You can find instructions for installing the latest version [here](../cli/sandbox-reference.md). +You will also need to install Aztec tooling to compile contracts. You can find instructions for installing the latest version [here](../../sandbox/references/sandbox-reference.md). ## Getting the Box @@ -68,7 +68,7 @@ yarn ### Start the Sandbox -See the Quickstart for [installing and starting the Sandbox](../getting_started/quickstart.md#sandbox-installation). +See the Quickstart for [installing and starting the Sandbox](../../getting_started/quickstart.md#sandbox-installation). ### Start the frontend diff --git a/docs/docs/developers/cli/run_more_than_one_pxe_sandbox.md b/docs/docs/developers/sandbox/guides/run_more_than_one_pxe_sandbox.md similarity index 73% rename from docs/docs/developers/cli/run_more_than_one_pxe_sandbox.md rename to docs/docs/developers/sandbox/guides/run_more_than_one_pxe_sandbox.md index c53a082b3e1a..7961f659f7a4 100644 --- a/docs/docs/developers/cli/run_more_than_one_pxe_sandbox.md +++ b/docs/docs/developers/sandbox/guides/run_more_than_one_pxe_sandbox.md @@ -19,17 +19,11 @@ This removes any other arguments, allowing you to ensure an isolated environment In another terminal, run: ```bash -docker-compose run -e MODE=pxe -e PXE_PORT=8085 -e AZTEC_NODE_URL='http://aztec-aztec-1:8079' -e TEST_ACCOUNTS='false' -p 8085:8085 aztec +aztec start --pxe nodeUrl=http://aztec-aztec-1:8079 ``` -This does a few things: -* Starts in PXE mode -* Passes the current Aztec node URL -* Does not load new test accounts -* Sets a port to listen on -* Only runs Aztec PXE, not Ethereum This command uses the default ports, so they might need to be changed depending on yuor configuration. -You can learn more about custom commands in the [sandbox reference](./sandbox-reference.md). +You can learn more about custom commands in the [sandbox reference](../references/sandbox-reference.md). diff --git a/docs/docs/developers/cli/main.md b/docs/docs/developers/sandbox/main.md similarity index 96% rename from docs/docs/developers/cli/main.md rename to docs/docs/developers/sandbox/main.md index a10ff03e281d..f0f3bdd22c1b 100644 --- a/docs/docs/developers/cli/main.md +++ b/docs/docs/developers/sandbox/main.md @@ -38,4 +38,4 @@ The Aztec CLI is a command-line tool allowing you to interact directly with the It aims to provide all of the functionality required to deploy, and invoke contracts and query system state such as contract data, transactions and emitted logs. -Use `aztec-nargo` for compiling contracts. See the [compiling contracts](../contracts/compiling.md) page for more information. +Use `aztec-nargo` for compiling contracts. See the [compiling contracts](../contracts/compiling_contracts/how_to_compile_contract.md) page for more information. diff --git a/docs/docs/developers/testing/cheat_codes.md b/docs/docs/developers/sandbox/references/cheat_codes.md similarity index 99% rename from docs/docs/developers/testing/cheat_codes.md rename to docs/docs/developers/sandbox/references/cheat_codes.md index 834685210f8a..d9c04dddfd96 100644 --- a/docs/docs/developers/testing/cheat_codes.md +++ b/docs/docs/developers/sandbox/references/cheat_codes.md @@ -565,5 +565,5 @@ Keep up with the latest discussion and join the conversation in the [Aztec forum You can also use the above link to request more cheatcodes. -import Disclaimer from "../../misc/common/\_disclaimer.mdx"; +import Disclaimer from "../../../misc/common/\_disclaimer.mdx"; diff --git a/docs/docs/developers/cli/cli-commands.md b/docs/docs/developers/sandbox/references/cli-commands.md similarity index 94% rename from docs/docs/developers/cli/cli-commands.md rename to docs/docs/developers/sandbox/references/cli-commands.md index 83c107365d8f..6f8d13e965a2 100644 --- a/docs/docs/developers/cli/cli-commands.md +++ b/docs/docs/developers/sandbox/references/cli-commands.md @@ -37,15 +37,15 @@ The update command won't update the CLI itself. To update these follow the [upda ## Compile -You can find more information about compiling contracts [on this page](../contracts/compiling.md). +You can find more information about compiling contracts [on this page](../../contracts/compiling_contracts/how_to_compile_contract.md). ## Creating Accounts -The first thing we want to do is create a couple of accounts. We will use the `create-account` command which will generate a new private key for us, register the account on the sandbox, and deploy a simple account contract which [uses a single key for privacy and authentication](../../learn/concepts/accounts/keys.md): +The first thing we want to do is create a couple of accounts. We will use the `create-account` command which will generate a new private key for us, register the account on the sandbox, and deploy a simple account contract which [uses a single key for privacy and authentication](../../../learn/concepts/accounts/keys.md): #include_code create-account yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash -Once the account is set up, the CLI returns the resulting address, its privacy key, and partial address. You can read more about these [here](../../learn/concepts/accounts/keys.md#addresses-partial-addresses-and-public-keys). +Once the account is set up, the CLI returns the resulting address, its privacy key, and partial address. You can read more about these [here](../../../learn/concepts/accounts/keys.md#addresses-partial-addresses-and-public-keys). Save the Address and Private key as environment variables. We will be using them later. @@ -72,7 +72,7 @@ export ADDRESS2= ## Deploying a Token Contract -We will now deploy a token contract using the `deploy` command, and set an address of the admin via a constructor argument. You can find the contract we are deploying [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/contracts/token_contract/src/main.nr) (or write it for yourself in [this tutorial!](../tutorials/writing_token_contract.md)) +We will now deploy a token contract using the `deploy` command, and set an address of the admin via a constructor argument. You can find the contract we are deploying [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/contracts/token_contract/src/main.nr) (or write it for yourself in [this tutorial!](../../tutorials/writing_token_contract.md)) Make sure to replace this address with one of the two you created earlier. #include_code deploy yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash diff --git a/docs/docs/developers/cli/sandbox-reference.md b/docs/docs/developers/sandbox/references/sandbox-reference.md similarity index 96% rename from docs/docs/developers/cli/sandbox-reference.md rename to docs/docs/developers/sandbox/references/sandbox-reference.md index 8fb0866d3316..b1ed012f56cc 100644 --- a/docs/docs/developers/cli/sandbox-reference.md +++ b/docs/docs/developers/sandbox/references/sandbox-reference.md @@ -6,7 +6,7 @@ Here you will find a reference to everything available within the Sandbox. ## Installation -You can run the Sandbox using Docker. See the [Quickstart](../getting_started/quickstart.md#install-docker) for instructions on installing Docker. +You can run the Sandbox using Docker. See the [Quickstart](../../getting_started/quickstart.md#install-docker) for instructions on installing Docker. ### With Docker @@ -172,7 +172,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](../testing/cheat_codes.md). +You can find the cheat code reference [here](../../sandbox/references/cheat_codes.md). ## Contracts @@ -215,4 +215,4 @@ You can see all of our example contracts in the monorepo [here](https://github.c The sandbox is shipped with full-stack Aztec project templates, with example Aztec.nr contracts, testing scripts, and web interfaces. -You can read more information about how to use boxes [here](./blank_box.md). +You can read more information about how to use boxes [here](../guides/blank_box.md). diff --git a/docs/docs/developers/testing/main.md b/docs/docs/developers/testing/main.md deleted file mode 100644 index 5413e63cd3db..000000000000 --- a/docs/docs/developers/testing/main.md +++ /dev/null @@ -1,5 +0,0 @@ -import DocCardList from '@theme/DocCardList'; - -# Testing - - diff --git a/docs/docs/developers/tutorials/main.md b/docs/docs/developers/tutorials/main.md index c294167c9d2c..69dc1513793f 100644 --- a/docs/docs/developers/tutorials/main.md +++ b/docs/docs/developers/tutorials/main.md @@ -2,6 +2,46 @@ title: Tutorials --- -import DocCardList from '@theme/DocCardList'; +This section will guide you through all aspects of Aztec. You'll be building Aztec.nr contracts, writing tests with Aztec.js, and exploring more aspects of the sandbox on the way. - +It is recommended to follow them in order, beginning with the [private voting contract](writing_private_voting_contract.md) through to the [uniswap contract with e2e test](./uniswap/main.md). + +Here's an overview of what you'll learn in each: + +## Writing a private voting smart contract in Aztec.nr + +- Interacting with hybrid state in Aztec.nr +- Access control +- Writing custom nullifiers + +[Check it out](./writing_private_voting_contract.md). + +## Writing a token contract in Aztec.nr + +- More complex types and interactions in Aztec.nr +- How a real smart contract could look +- A theoretical look at cross-chain interactions + +[Check it out](./writing_token_contract.md). + +## Writing a DApp + +- How all the pieces of Aztec fit together +- Structuring an Aztec project + +[Check it out](./writing_dapp/main.md). + +## Build a Token Bridge + +- Public and private cross-chain communication with Ethereum +- More details into what the Sandbox is capable of + +[Check it out](./token_portal/main.md). + +## Swap on L1 Uniswap from L2 with Portals + +- A more complex example of cross-chain communication + +Note - this builds on the code previously written in the Token Bridge tutorial. + +[Check it out](./uniswap/main.md). diff --git a/docs/docs/developers/tutorials/testing.md b/docs/docs/developers/tutorials/testing.md index 3b19d4c3bb72..e0ec74a519ba 100644 --- a/docs/docs/developers/tutorials/testing.md +++ b/docs/docs/developers/tutorials/testing.md @@ -8,7 +8,7 @@ We will be using typescript to write our tests, and rely on the [`aztec.js`](htt ## A simple example -Let's start with a simple example for a test using the [Sandbox](../cli/sandbox-reference.md). We will create two accounts and deploy a token contract in a setup step, and then issue a transfer from one user to another. +Let's start with a simple example for a test using the [Sandbox](../sandbox/references/sandbox-reference.md). We will create two accounts and deploy a token contract in a setup step, and then issue a transfer from one user to another. #include_code sandbox-example /yarn-project/end-to-end/src/guides/dapp_testing.test.ts typescript @@ -17,7 +17,7 @@ This test sets up the environment by creating a client to the Private Execution Once we have this setup, the test itself is simple. We check the balance of the `recipient` user to ensure it has no tokens, send and await a deployment transaction, and then check the balance again to ensure it was increased. Note that all numeric values are represented as [native bigints](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) to avoid loss of precision. :::info -We are using the `Token` contract's typescript interface. Follow the [typescript interface section](../contracts/compiling.md#typescript-interfaces) to get type-safe methods for deploying and interacting with the token contract. +We are using the `Token` contract's typescript interface. Follow the [typescript interface section](../contracts/compiling_contracts/how_to_compile_contract.md#typescript-interfaces) to get type-safe methods for deploying and interacting with the token contract. ::: To run the test, first make sure the Sandbox is running on port 8080, and then [run your tests using jest](https://jestjs.io/docs/getting-started#running-from-command-line). Your test should pass, and you should see the following output in the Sandbox logs, where each chunk corresponds to a transaction. Note how this test run has a total of four transactions: two for deploying the account contracts for the `owner` and `recipient`, another for deploying the token contract, and a last one for actually executing the transfer. @@ -148,7 +148,7 @@ In the near future, transactions where a public function call fails will get min 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().view()`. Bear in mind that directly accessing contract storage will break any kind of encapsulation. -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](../contracts/syntax/storage/main.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`](./../testing/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](../contracts/writing_contracts/storage/main.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`](../sandbox/references/cheat_codes.md) utility class: #include_code calc-slot /yarn-project/end-to-end/src/guides/dapp_testing.test.ts typescript @@ -170,7 +170,7 @@ We can query the Private eXecution Environment (PXE) for all notes encrypted for ### Logs -Last but not least, we can check the logs of [events](../contracts/syntax/events.md) emitted by our contracts. Contracts in Aztec can emit both [encrypted](../contracts/syntax/events.md#encrypted-events) and [unencrypted](../contracts/syntax/events.md#unencrypted-events) events. +Last but not least, we can check the logs of [events](../contracts/writing_contracts/events/emit_event.md) emitted by our contracts. Contracts in Aztec can emit both [encrypted](../contracts/writing_contracts/events/emit_event.md#encrypted-events) and [unencrypted](../contracts/writing_contracts/events/emit_event.md#unencrypted-events) events. :::info At the time of this writing, only unencrypted events can be queried directly. Encrypted events are always assumed to be encrypted notes. @@ -184,7 +184,7 @@ We can query the PXE for the unencrypted logs emitted in the block where our tra ## Cheats -The [`CheatCodes`](./../testing/cheat_codes.md) class, which we used for [calculating the storage slot above](#state), also includes a set of cheat methods for modifying the chain state that can be handy for testing. +The [`CheatCodes`](../sandbox/references/cheat_codes.md) class, which we used for [calculating the storage slot above](#state), also includes a set of cheat methods for modifying the chain state that can be handy for testing. ### Set next block timestamp diff --git a/docs/docs/developers/tutorials/token_portal/main.md b/docs/docs/developers/tutorials/token_portal/main.md index 5739d5b81aa2..b4f629f2934b 100644 --- a/docs/docs/developers/tutorials/token_portal/main.md +++ b/docs/docs/developers/tutorials/token_portal/main.md @@ -4,7 +4,7 @@ title: Build a Token Bridge 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](../../contracts/portals/main). +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](../../../learn/concepts/communication/cross_chain_calls.md). ## A refresher on Portals diff --git a/docs/docs/developers/tutorials/writing_dapp/contract_deployment.md b/docs/docs/developers/tutorials/writing_dapp/contract_deployment.md index b55ebcac2c28..ab3c33912e9f 100644 --- a/docs/docs/developers/tutorials/writing_dapp/contract_deployment.md +++ b/docs/docs/developers/tutorials/writing_dapp/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](../../cli/sandbox-reference.md) to install `aztec-nargo` if you haven't done so already. +Follow the instructions [here](../../sandbox/references/sandbox-reference.md) to install `aztec-nargo` if you haven't done so already. ::: ## Initialize Aztec project @@ -35,7 +35,7 @@ The `Token` contract also requires some helper files. You can view the files [he ## Compile your contract -We'll now use `aztec-nargo` to [compile](../../contracts/compiling.md) our project. If you haven't installed aztec-nargo and aztec-cli already, it comes with the sandbox, so you can install it via the [Sandbox install command](../../cli/sandbox-reference.md#installation). +We'll now use `aztec-nargo` to [compile](../../contracts/compiling_contracts/how_to_compile_contract.md) our project. If you haven't installed aztec-nargo and aztec-cli already, it comes with the sandbox, so you can install it via the [Sandbox install command](../../sandbox/references/sandbox-reference.md#installation). Now run the following from your contract folder (containing Nargo.toml): diff --git a/docs/docs/developers/tutorials/writing_dapp/main.md b/docs/docs/developers/tutorials/writing_dapp/main.md index 95cedf910bb7..d4fbb7dd0d60 100644 --- a/docs/docs/developers/tutorials/writing_dapp/main.md +++ b/docs/docs/developers/tutorials/writing_dapp/main.md @@ -13,7 +13,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/quickstart.md) -- [Aztec CLI](../../cli/main.md) +- [Aztec CLI](../../sandbox/main.md) - [Nargo](../../contracts/setup.md) for building contracts ## Prerequisites diff --git a/docs/docs/developers/tutorials/writing_dapp/pxe_service.md b/docs/docs/developers/tutorials/writing_dapp/pxe_service.md index 38a54700c6ae..a29ad6971c1e 100644 --- a/docs/docs/developers/tutorials/writing_dapp/pxe_service.md +++ b/docs/docs/developers/tutorials/writing_dapp/pxe_service.md @@ -4,7 +4,7 @@ PXE is a component of the Aztec Protocol that provides a private execution envir As an app developer, the [PXE](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/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](../../cli/sandbox-reference.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](../../sandbox/references/sandbox-reference.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/developers/tutorials/writing_dapp/testing.md b/docs/docs/developers/tutorials/writing_dapp/testing.md index 6e835783d3d7..51065b0ff870 100644 --- a/docs/docs/developers/tutorials/writing_dapp/testing.md +++ b/docs/docs/developers/tutorials/writing_dapp/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](../../cli/sandbox-reference.md#installation). +We'll need to [install and run the Sandbox](../../sandbox/references/sandbox-reference.md#installation). ## Test setup diff --git a/docs/docs/developers/tutorials/writing_private_voting_contract.md b/docs/docs/developers/tutorials/writing_private_voting_contract.md index a7c73f713154..57efa5c7066c 100644 --- a/docs/docs/developers/tutorials/writing_private_voting_contract.md +++ b/docs/docs/developers/tutorials/writing_private_voting_contract.md @@ -131,7 +131,7 @@ Create a private function called `cast_vote`: In this function, we do not create a nullifier with the address directly. This would leak privacy as it would be easy to reverse-engineer. We must add some randomness or some form of secret, like [nullifier secrets](../../learn/concepts/accounts/keys.md#nullifier-secrets). -To do this, we make an [oracle call](../contracts/syntax/functions/oracles.md) to fetch the caller's secret key, hash it to create a nullifier, and push the nullifier to Aztec. The `secret.high` and `secret.low` values here refer to how we divide a large [Grumpkin scalar](https://github.com/AztecProtocol/aztec-packages/blob/7fb35874eae3f2cad5cb922282a619206573592c/noir/noir_stdlib/src/grumpkin_scalar.nr) value into its higher and lower parts. This allows for faster cryptographic computations so our hash can still be secure but is calculated faster. +To do this, we make an [oracle call](../contracts/writing_contracts/oracles/main.md) to fetch the caller's secret key, hash it to create a nullifier, and push the nullifier to Aztec. The `secret.high` and `secret.low` values here refer to how we divide a large [Grumpkin scalar](https://github.com/AztecProtocol/aztec-packages/blob/7fb35874eae3f2cad5cb922282a619206573592c/noir/noir_stdlib/src/grumpkin_scalar.nr) value into its higher and lower parts. This allows for faster cryptographic computations so our hash can still be secure but is calculated faster. After pushing the nullifier, we update the `tally` to reflect this vote. As we know from before, a private function cannot update public state directly, so we are calling a public function. @@ -187,7 +187,7 @@ This will create a new directory called `target` and a JSON artifact inside it. aztec-cli codegen target -o src/artifacts --ts ``` -Once it is compiled you can [deploy](../contracts/deploying.md) it to the sandbox. Ensure your [sandbox is running](../cli/sandbox-reference.md) and run this in the same dir as before: +Once it is compiled you can [deploy](../contracts/deploying_contracts/how_to_deploy_contract.md) it to the sandbox. Ensure your [sandbox is running](../sandbox/references/sandbox-reference.md) and run this in the same dir as before: ```bash aztec-cli deploy ./target/private_voting-Voting.json --args $ADMIN_ADDRESS @@ -217,7 +217,7 @@ aztec-cli call get_vote --contract-artifact ./target/private_voting-Voting.json This should return `1n`. -You can follow this pattern to test `end_vote()` and access control of other functions. Find more information about calling functions from the CLI [here](../cli/cli-commands.md). +You can follow this pattern to test `end_vote()` and access control of other functions. Find more information about calling functions from the CLI [here](../sandbox/references/cli-commands.md). ## Next steps diff --git a/docs/docs/developers/tutorials/writing_token_contract.md b/docs/docs/developers/tutorials/writing_token_contract.md index cde563647adc..fe35268ac32e 100644 --- a/docs/docs/developers/tutorials/writing_token_contract.md +++ b/docs/docs/developers/tutorials/writing_token_contract.md @@ -18,7 +18,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](../cli/sandbox-reference.md) for installation instructions. +You will need to have `aztec-nargo` installed in order to compile Aztec.nr contracts. See the [sandbox reference](../sandbox/references/sandbox-reference.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. @@ -223,7 +223,7 @@ The main thing to note from this types folder is the `TransparentNote` definitio ### Note on private state -Private state in Aztec is all [UTXOs](https://en.wikipedia.org/wiki/Unspent_transaction_output) under the hood. Handling UTXOs is largely abstracted away from developers, but there are some unique things for developers to be aware of when creating and managing private state in an Aztec contract. See [State Variables](../contracts/syntax/storage/main.md) to learn more about public and private state in Aztec. +Private state in Aztec is all [UTXOs](https://en.wikipedia.org/wiki/Unspent_transaction_output) under the hood. Handling UTXOs is largely abstracted away from developers, but there are some unique things for developers to be aware of when creating and managing private state in an Aztec contract. See [State Variables](../contracts/writing_contracts/storage/main.md) to learn more about public and private state in Aztec. ## Contract Storage @@ -242,7 +242,7 @@ Reading through the storage variables: - `pending_shields` is a `Set` of `TransparentNote`s stored in private state. What is stored publicly is a set of commitments to `TransparentNote`s. - `public_balances` is a mapping field elements in public state and represents the publicly viewable balances of accounts. -You can read more about it [here](../contracts/syntax/storage/main.md). +You can read more about it [here](../contracts/writing_contracts/storage/main.md). ## Functions @@ -452,7 +452,7 @@ If you don't yet have any private state variables defined put there a placeholde ## Compiling -Now that the contract is complete, you can compile it with `aztec-nargo`. See the [Sandbox reference page](../cli/sandbox-reference.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](../sandbox/references/sandbox-reference.md) for instructions on setting it up. Run the following command in the directory where your `Nargo.toml` file is located: diff --git a/docs/docs/developers/updating.md b/docs/docs/developers/updating.md index 6e9a3b47d571..73eb2549a384 100644 --- a/docs/docs/developers/updating.md +++ b/docs/docs/developers/updating.md @@ -19,7 +19,7 @@ cd your/aztec/project aztec-cli 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](../developers/cli/sandbox-reference.md). +The sandbox must be running for the update command to work. Make sure it is [installed and running](../developers/sandbox/references/sandbox-reference.md). 3. Refer [Migration Notes](../misc/migration_notes.md) on any breaking changes that might affect your dapp diff --git a/docs/docs/developers/wallets/architecture.md b/docs/docs/developers/wallets/architecture.md index 3d010fd32670..bd9d6beeb6de 100644 --- a/docs/docs/developers/wallets/architecture.md +++ b/docs/docs/developers/wallets/architecture.md @@ -1,4 +1,14 @@ -# Architecture +--- +title: Architecture +--- + +This page talks about the architecture of a wallet in Aztec. + +To get an overview about wallets in Aztec, [go here](./main.md). + +To learn how to write an accounts contract, [go here](../contracts/writing_contracts/accounts/write_accounts_contract.md). + +To create a schnorr account in the sandbox, [go here](./creating_schnorr_accounts.md). 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. @@ -18,7 +28,7 @@ The account interface is used for creating an _execution request_ out of one or #include_code account-interface yarn-project/aztec.js/src/account/interface.ts typescript -Refer to the page on [writing an account contract](./writing_an_account_contract.md) for an example on how to implement this interface. +Refer to the page on [writing an account contract](../contracts/writing_contracts/accounts/write_accounts_contract.md) for an example on how to implement this interface. ## PXE interface diff --git a/docs/docs/developers/wallets/creating_schnorr_accounts.md b/docs/docs/developers/wallets/creating_schnorr_accounts.md index 636bf8df4af6..1ac1443ace64 100644 --- a/docs/docs/developers/wallets/creating_schnorr_accounts.md +++ b/docs/docs/developers/wallets/creating_schnorr_accounts.md @@ -60,4 +60,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](./writing_an_account_contract.md) leveraging our account abstraction +Check out our section on [Writing your own Account Contract](../contracts/writing_contracts/accounts/write_accounts_contract.md) leveraging our account abstraction diff --git a/docs/docs/developers/wallets/main.md b/docs/docs/developers/wallets/main.md index 6e458d8241db..c12288e5478f 100644 --- a/docs/docs/developers/wallets/main.md +++ b/docs/docs/developers/wallets/main.md @@ -1,4 +1,12 @@ -# Wallets +--- +title: Wallets +--- + +In this page we will cover the main responsibilities of a wallet in the Aztec network. + +Refer to [_writing an account contract_](../contracts/writing_contracts/accounts/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. Wallets are the applications through which users manage their accounts. Users rely on wallets to browse through their accounts, monitor their balances, and create new accounts. Wallets also store seed phrases and private keys, or interact with external keystores such as hardware wallets. @@ -6,13 +14,11 @@ Wallets also provide an interface for dapps. Dapps may request access to see the In addition to these usual responsibilities, wallets in Aztec also need to track private state. This implies keeping a local database of all private notes encrypted for any of the user's accounts, so dapps and contracts can query the user's private state. Aztec wallets are also responsible for producing local proofs of execution for private functions. -In this page we will cover the main responsibilities of a wallet in the Aztec network. Refer to [_writing an account contract_](./writing_an_account_contract.md) for a tutorial on how to write a contract to back a user's account, or to [_wallet architecture](./architecture.md) for an overview of its architecture and a reference on the interface a wallet must implement. - ## Account setup The first step for any wallet is to let the user set up their [accounts](../../learn/concepts/accounts/main.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](./writing_an_account_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](../contracts/writing_contracts/accounts/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). 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](../../learn/concepts/accounts/keys.md#addresses-partial-addresses-and-public-keys) 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. diff --git a/docs/docs/learn/concepts/accounts/keys.md b/docs/docs/learn/concepts/accounts/keys.md index 5802996cf5e7..63cd27b0f3ab 100644 --- a/docs/docs/learn/concepts/accounts/keys.md +++ b/docs/docs/learn/concepts/accounts/keys.md @@ -14,7 +14,7 @@ This is a snippet of our Schnorr Account contract implementation, which uses Sch #include_code entrypoint /yarn-project/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](../../../developers/wallets/writing_an_account_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](../../../developers/contracts/writing_contracts/accounts/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. Here are a few ideas on how to store them, each with their pros and cons. diff --git a/docs/docs/learn/concepts/accounts/main.md b/docs/docs/learn/concepts/accounts/main.md index 3ad582656373..903442f51769 100644 --- a/docs/docs/learn/concepts/accounts/main.md +++ b/docs/docs/learn/concepts/accounts/main.md @@ -1,4 +1,6 @@ -# Accounts +--- +title: Accounts +--- **Every account in Aztec is a smart contract** which defines the rules for whether a transaction is or is not valid. This allows implementing different schemes for transaction signing, nonce management, and fee payments. However, encryption and nullifying keys, which are specific to private blockchains, are still enshrined at the protocol level. @@ -68,7 +70,7 @@ def entryPoint(payload): enqueueCall(to, data, value, gasLimit); ``` -Read more about how to write an account contract [here](../../../developers/wallets/writing_an_account_contract.md). +Read more about how to write an account contract [here](../../../developers/contracts/writing_contracts/accounts/write_accounts_contract.md). ### Account contracts and wallets diff --git a/docs/docs/learn/concepts/communication/public_private_calls/slow_updates_tree.md b/docs/docs/learn/concepts/communication/public_private_calls/slow_updates_tree.md index a7459932f07c..64ced6272fd3 100644 --- a/docs/docs/learn/concepts/communication/public_private_calls/slow_updates_tree.md +++ b/docs/docs/learn/concepts/communication/public_private_calls/slow_updates_tree.md @@ -70,4 +70,4 @@ Developers are used to instant state updates, so the Slow Updates Tree might tak ## Dive into the code -For a code walkthrough of how a token blacklist contract can use a slow updates tree, read [this](../../../../developers/contracts/syntax/slow_updates_tree.md). \ No newline at end of file +For a code walkthrough of how a token blacklist contract can use a slow updates tree, read [this](../../../../developers/contracts/writing_contracts/historical_data/slow_updates_tree/implement_slow_updates.md). \ No newline at end of file diff --git a/docs/docs/learn/concepts/hybrid_state/main.md b/docs/docs/learn/concepts/hybrid_state/main.md index 2c540f2a0777..20493fab3d04 100644 --- a/docs/docs/learn/concepts/hybrid_state/main.md +++ b/docs/docs/learn/concepts/hybrid_state/main.md @@ -43,4 +43,4 @@ This is achieved with two main features: ## Further reading -Read more about how to leverage the Aztec state model in Aztec contracts [here](../../../developers/contracts/syntax/storage/main.md). +Read more about how to leverage the Aztec state model in Aztec contracts [here](../../../developers/contracts/writing_contracts/storage/main.md). diff --git a/docs/docs/learn/concepts/pxe/acir_simulator.md b/docs/docs/learn/concepts/pxe/acir_simulator.md index 0b7947732054..3927f094e2ab 100644 --- a/docs/docs/learn/concepts/pxe/acir_simulator.md +++ b/docs/docs/learn/concepts/pxe/acir_simulator.md @@ -14,7 +14,7 @@ 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](../../../developers/contracts/syntax/functions/oracles.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](../../../developers/contracts/writing_contracts/oracles/main.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. diff --git a/docs/docs/learn/concepts/pxe/main.md b/docs/docs/learn/concepts/pxe/main.md index 028aaf12081a..25993ced2140 100644 --- a/docs/docs/learn/concepts/pxe/main.md +++ b/docs/docs/learn/concepts/pxe/main.md @@ -62,9 +62,9 @@ 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](../../../developers/contracts/syntax/functions/oracles.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 [functions section](../../../developers/contracts/writing_contracts/oracles/main.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](../../../developers/cli/run_more_than_one_pxe_sandbox.md) -* [Use in-built oracles including oracles for arbitrary data](../../../developers/contracts/syntax/oracles.md) \ No newline at end of file +* [Run more than one PXE on your local machine](../../../developers/sandbox/guides/run_more_than_one_pxe_sandbox.md) +* [Use in-built oracles including oracles for arbitrary data](../../../developers/contracts/writing_contracts/oracles/pop_capsule.md) \ No newline at end of file diff --git a/docs/docs/learn/concepts/storage/storage_slots.md b/docs/docs/learn/concepts/storage/storage_slots.md index 80013ecd1569..3aff76c895d2 100644 --- a/docs/docs/learn/concepts/storage/storage_slots.md +++ b/docs/docs/learn/concepts/storage/storage_slots.md @@ -62,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](./../../../developers/contracts/syntax/storage/storage_slots.md). +For an example of this see [developer documentation storage slots](../../../developers/contracts/writing_contracts/storage/main.md). diff --git a/docs/docs/learn/concepts/storage/trees/main.md b/docs/docs/learn/concepts/storage/trees/main.md index af58086e10f4..672e3b0aac0a 100644 --- a/docs/docs/learn/concepts/storage/trees/main.md +++ b/docs/docs/learn/concepts/storage/trees/main.md @@ -211,7 +211,7 @@ HistoricalAccessTree --- Header ``` -It can also be used to find information about notes, public state, and contracts that were included in a certain block using [inclusion and non-inclusion proofs](../../../../developers/contracts/syntax/historical_access/how_to_prove_history.md). +It can also be used to find information about notes, public state, and contracts that were included in a certain block using [inclusion and non-inclusion proofs](../../../../developers/contracts/writing_contracts/historical_data/archive_tree/how_to_prove_history.md). ## Trees of valid Kernel/Rollup circuit Verification Keys diff --git a/docs/sidebars.js b/docs/sidebars.js index 88dc7f7bd73a..a779fdf94ace 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -22,7 +22,7 @@ const sidebars = { // ABOUT AZTEC { - type: "html", + type: "html", className: "sidebar-title", value: "LEARN", defaultStyle: true, @@ -254,93 +254,194 @@ const sidebars = { type: "category", link: { type: "doc", - id: "developers/cli/main", + id: "developers/sandbox/main", }, items: [ - "developers/cli/cli-commands", - "developers/cli/sandbox-reference", - "developers/cli/run_more_than_one_pxe_sandbox", + { + label: "Guides", + type: "category", + items: [ + "developers/sandbox/guides/blank_box", + "developers/sandbox/guides/run_more_than_one_pxe_sandbox", + "developers/wallets/creating_schnorr_accounts", + ], + }, + { + label: "References", + type: "category", + items: [ + "developers/sandbox/references/cli-commands", + "developers/sandbox/references/sandbox-reference", + "developers/sandbox/references/cheat_codes", + { + label: "PXE Reference", + type: "doc", + id: "apis/pxe/interfaces/PXE", + }, + ], + + }, + ], }, { - label: "Aztec.nr Contracts", + label: "Smart Contracts", type: "category", link: { type: "doc", id: "developers/contracts/main", }, items: [ - "developers/contracts/workflow", "developers/contracts/setup", - "developers/contracts/layout", { - label: "Syntax", + label: "Writing Contracts", type: "category", - link: { - type: "doc", - id: "developers/contracts/syntax/main", - }, items: [ + "developers/contracts/writing_contracts/layout", + "developers/contracts/writing_contracts/example_contract", + { + label: "Functions and Constructors", + type: "category", + link: { + type: "doc", + id: "developers/contracts/writing_contracts/functions/main", + }, + items: [ + "developers/contracts/writing_contracts/functions/context", + "developers/contracts/writing_contracts/functions/public_private_unconstrained", + "developers/contracts/writing_contracts/functions/visibility", + "developers/contracts/writing_contracts/functions/call_functions", + "developers/contracts/writing_contracts/functions/write_constructor", + "developers/contracts/writing_contracts/functions/inner_workings", + ], + }, { label: "Storage", type: "category", link: { type: "doc", - id: "developers/contracts/syntax/storage/main", + id: "developers/contracts/writing_contracts/storage/main", + }, + items: [ + "developers/contracts/writing_contracts/storage/define_storage", + "developers/contracts/writing_contracts/storage/storage_slots", + ], + }, + { + label: "Accounts and Account Contracts", + type: "category", + items: [ + "developers/contracts/writing_contracts/accounts/write_accounts_contract", + + ], + }, + { + label: "Events", + type: "category", + items: [ + "developers/contracts/writing_contracts/events/emit_event", + ], + }, + { + label: "Oracles", + type: "category", + link: { + type: "doc", + id: "developers/contracts/writing_contracts/oracles/main", }, items: [ - "developers/contracts/syntax/storage/private_state", - "developers/contracts/syntax/storage/public_state", - "developers/contracts/syntax/storage/storage_slots", + "developers/contracts/writing_contracts/oracles/inbuilt_oracles", + "developers/contracts/writing_contracts/oracles/pop_capsule", ], }, - "developers/contracts/syntax/events", { - label: "Functions", + label: "Portals", type: "category", link: { type: "doc", - id: "developers/contracts/syntax/functions/main", + id: "developers/contracts/writing_contracts/portals/portals", }, items: [ - "developers/contracts/syntax/functions/public_private_unconstrained", - "developers/contracts/syntax/functions/visibility", - "developers/contracts/syntax/functions/constructor", - "developers/contracts/syntax/functions/calling_functions", - "developers/contracts/syntax/functions/oracles", - "developers/contracts/syntax/functions/inner_workings", + "developers/contracts/writing_contracts/portals/deploy_with_portal", + "developers/contracts/writing_contracts/portals/communicate_with_portal", ], }, - "developers/contracts/syntax/oracles", { - label: "Proving Historical Blockchain Data", + label: "Historical Data", type: "category", items: [ - "developers/contracts/syntax/historical_access/how_to_prove_history", - "developers/contracts/syntax/historical_access/history_lib_reference", + { + label: "Historical Blockchain Data (Archive Tree)", + type: "category", + link: { + type: "doc", + id: "developers/contracts/writing_contracts/historical_data/slow_updates_tree/main", + }, + items: [ + "developers/contracts/writing_contracts/historical_data/archive_tree/how_to_prove_history", + ], + }, ], }, - "developers/contracts/syntax/slow_updates_tree", - - "developers/contracts/syntax/context", - "developers/contracts/syntax/globals", + { + label: "Access public data from private state (Slow Updates Tree)", + type: "category", + link: { + type: "doc", + id: "developers/contracts/writing_contracts/historical_data/slow_updates_tree/main", + }, + items: [ + "developers/contracts/writing_contracts/historical_data/slow_updates_tree/implement_slow_updates", + ], + }, + ], }, - "developers/contracts/compiling", - "developers/contracts/deploying", - "developers/contracts/artifacts", { - label: "Portals", + label: "Compiling Contracts", type: "category", - link: { - type: "doc", - id: "developers/contracts/portals/main", - }, items: [ - "developers/contracts/portals/data_structures", - "developers/contracts/portals/registry", - "developers/contracts/portals/inbox", - "developers/contracts/portals/outbox", + "developers/contracts/compiling_contracts/how_to_compile_contract", + "developers/contracts/compiling_contracts/artifacts", + ], + }, + { + label: "Deploying Contracts", + type: "category", + items: [ + "developers/contracts/deploying_contracts/how_to_deploy_contract", + ], + }, + "developers/contracts/testing_contracts/main", + { + label: "References", + type: "category", + items: [ + "developers/contracts/references/globals", + { + label: "Storage Reference", + type: "category", + link: { + type: "doc", + id: "developers/contracts/references/storage/main", + }, + items: [ + "developers/contracts/references/storage/private_state", + "developers/contracts/references/storage/public_state" + ], + }, + { + label: "Portals Reference", + type: "category", + items: [ + "developers/contracts/references/portals/data_structures", + "developers/contracts/references/portals/inbox", + "developers/contracts/references/portals/outbox", + "developers/contracts/references/portals/registry", + ], + }, + "developers/contracts/references/history_lib_reference", + "developers/contracts/references/slow_updates_tree", ], }, { @@ -386,8 +487,39 @@ const sidebars = { { label: "Aztec.js", - type: "doc", - id: "developers/aztecjs/main", + type: "category", + link: { + type: "doc", + id: "developers/aztecjs/main", + }, + items: [ + { + label: "Guides", + type: "category", + items: [ + "developers/aztecjs/guides/create_account", + "developers/aztecjs/guides/deploy_contract", + "developers/aztecjs/guides/send_transaction", + "developers/aztecjs/guides/call_view_function", + ], + }, + { + label: "References", + type: "category", + items: [ + { + label: "Aztec.js", + type: "category", + items: [{ dirName: "apis/aztec-js", type: "autogenerated" }], + }, + { + label: "Accounts", + type: "category", + items: [{ dirName: "apis/accounts", type: "autogenerated" }], + }, + ], + }, + ], }, { label: "Debugging", @@ -406,16 +538,6 @@ const sidebars = { type: "doc", id: "developers/updating", }, - - { - label: "Testing", - type: "category", - link: { - type: "doc", - id: "developers/testing/main", - }, - items: ["developers/testing/cheat_codes"], - }, { label: "Wallets", type: "category", @@ -425,8 +547,6 @@ const sidebars = { }, items: [ "developers/wallets/architecture", - "developers/wallets/writing_an_account_contract", - "developers/wallets/creating_schnorr_accounts", ], }, @@ -438,28 +558,6 @@ const sidebars = { "developers/privacy/main", "developers/limitations/main", - { - label: "API Reference", - type: "category", - items: [ - { - label: "Private Execution Environment (PXE)", - type: "doc", - id: "apis/pxe/interfaces/PXE", - }, - { - label: "Aztec.js", - type: "category", - items: [{ dirName: "apis/aztec-js", type: "autogenerated" }], - }, - { - label: "Accounts", - type: "category", - items: [{ dirName: "apis/accounts", type: "autogenerated" }], - }, - ], - }, - { type: "html", value: '',