From 4992d5b59bb73e8f14fc14963a89c9c97268f773 Mon Sep 17 00:00:00 2001 From: Rahul Kothari Date: Thu, 21 Sep 2023 22:44:08 +0100 Subject: [PATCH] chore(docs): incorporate docs feedback (#2434) First up - most things are just copy-paste so don't fret! **Breaking changes:** * Create a section on Tutorials and move everything there * Only have two things in Getting started - it is getting started after all! It should have a quickstart and interacting w sandbox * Delete aztec.nr setup * Move the token tutorial into /tutorials/ **Changes:** Make updates proposed in #2431 * Sandbox getting started - * is slightly cleaner and shorter. Santiago mentioned we should just use the preloaded contracts. * And add links to the code repo at the top! * Fix e2e_sandbox_examples.test.ts appropriately. * Contracts: * make the main page better and point to tutorials. Fix link (would tell people to install nargo from Noir website) * Create a section on setting up -> can delete getting started this way. * make syntax/main cleaner to focus only on syntax and remove wrong references to it * Wallets: * section on creation * cli -> no more a folder. Just a page * sandbox errors -> no more a folder. Just a page New docs - image --------- Co-authored-by: Josh Crites Co-authored-by: josh crites --- docs/docs/about_aztec/overview.mdx | 2 +- .../concepts/advanced/contract_creation.md | 2 +- docs/docs/dev_docs/cli/cli.md | 144 ------------------ docs/docs/dev_docs/cli/main.md | 135 +++++++++++++++- docs/docs/dev_docs/contracts/compiling.md | 2 +- docs/docs/dev_docs/contracts/deploying.md | 4 +- docs/docs/dev_docs/contracts/layout.md | 2 +- docs/docs/dev_docs/contracts/main.md | 11 +- docs/docs/dev_docs/contracts/setup.md | 95 ++++++++++++ docs/docs/dev_docs/contracts/syntax/main.md | 23 +-- docs/docs/dev_docs/contracts/workflow.md | 3 + .../getting_started/noir_contracts.md | 88 ----------- .../dev_docs/getting_started/quickstart.md | 7 +- docs/docs/dev_docs/getting_started/sandbox.md | 99 +++++------- docs/docs/dev_docs/sandbox/main.md | 9 -- .../main.md} | 0 docs/docs/dev_docs/testing/testing.md | 2 +- docs/docs/dev_docs/tutorials/main.md | 3 + .../writing_dapp}/contract_deployment.md | 2 +- .../writing_dapp}/contract_interaction.md | 0 .../writing_dapp}/main.md | 4 +- .../writing_dapp}/project_setup.md | 0 .../writing_dapp}/rpc_server.md | 2 +- .../writing_dapp}/testing.md | 2 +- .../writing_token_contract.md} | 12 +- .../wallets/creating_schnorr_accounts.md | 60 ++++++++ docs/netlify.toml | 38 ++++- docs/sidebars.js | 91 +++++------ .../src/e2e_sandbox_example.test.ts | 122 +++++++++------ yarn-project/noir-contracts/README.md | 2 +- 30 files changed, 507 insertions(+), 459 deletions(-) delete mode 100644 docs/docs/dev_docs/cli/cli.md create mode 100644 docs/docs/dev_docs/contracts/setup.md delete mode 100644 docs/docs/dev_docs/getting_started/noir_contracts.md delete mode 100644 docs/docs/dev_docs/sandbox/main.md rename docs/docs/dev_docs/{sandbox/common_errors.md => sandbox_errors/main.md} (100%) create mode 100644 docs/docs/dev_docs/tutorials/main.md rename docs/docs/dev_docs/{dapps/tutorials => tutorials/writing_dapp}/contract_deployment.md (97%) rename docs/docs/dev_docs/{dapps/tutorials => tutorials/writing_dapp}/contract_interaction.md (100%) rename docs/docs/dev_docs/{dapps/tutorials => tutorials/writing_dapp}/main.md (92%) rename docs/docs/dev_docs/{dapps/tutorials => tutorials/writing_dapp}/project_setup.md (100%) rename docs/docs/dev_docs/{dapps/tutorials => tutorials/writing_dapp}/rpc_server.md (87%) rename docs/docs/dev_docs/{dapps/tutorials => tutorials/writing_dapp}/testing.md (96%) rename docs/docs/dev_docs/{getting_started/token_contract_tutorial.md => tutorials/writing_token_contract.md} (97%) create mode 100644 docs/docs/dev_docs/wallets/creating_schnorr_accounts.md diff --git a/docs/docs/about_aztec/overview.mdx b/docs/docs/about_aztec/overview.mdx index 8c291ba3747..0e38c8a1dbd 100644 --- a/docs/docs/about_aztec/overview.mdx +++ b/docs/docs/about_aztec/overview.mdx @@ -52,7 +52,7 @@ Contributors to Aztec uphold many of the values of the Ethereum community -- bui Noir is a domain specific programming language for writing zero knowledge circuits. On Aztec a smart contract is a collection of circuits that developers write using Noir. -You can find more information and resources for learning about Noir smart contracts on [this page](../dev_docs/getting_started/noir_contracts.md). +You can find more information and resources for learning about Noir smart contracts on [this page](../dev_docs/contracts/main.md). ## Cryptography diff --git a/docs/docs/concepts/advanced/contract_creation.md b/docs/docs/concepts/advanced/contract_creation.md index 2b9f66499ea..9e054f5eacb 100644 --- a/docs/docs/concepts/advanced/contract_creation.md +++ b/docs/docs/concepts/advanced/contract_creation.md @@ -327,4 +327,4 @@ Adds initial public state variables to the public data tree. ## Further reading -To see how to deploy a contract in practice, check out the [dapp development tutorial](../../dev_docs/dapps/tutorials/main.md). +To see how to deploy a contract in practice, check out the [dapp development tutorial](../../dev_docs/tutorials/writing_dapp/main.md). diff --git a/docs/docs/dev_docs/cli/cli.md b/docs/docs/dev_docs/cli/cli.md deleted file mode 100644 index 4e238b9e1d3..00000000000 --- a/docs/docs/dev_docs/cli/cli.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: CLI Tutorial ---- - -## Introduction - -The Aztec CLI is a tool designed to enable a user to interact with the Aztec Network. - -This tutorial will use the Aztec Sandbox so you should first set it up by following [the Aztec Sandbox instructions](../getting_started/quickstart.md). - -## Requirements - -You should also have [node.js](https://nodejs.org/en/download) installed with version >= 18. - -To install the Aztec CLI run: - -```bash -npm install -g @aztec/cli -``` - -Or if you use yarn: - -```bash -yarn global add @aztec/cli -``` - -Then verify that it is installed with: - -```bash -aztec-cli -h -``` - -## I have the Sandbox running, now what? - -Lets first establish that we are able to communicate with the Sandbox. Most commands will require the url to the Sandbox, which defaults in the CLI to `http://localhost:8080`. You can override this as an option with each command or by setting `AZTEC_RPC_HOST` environment variable. - -To test communication with the Sandbox, let's run the command: - -#include_code block-number yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash - -You should see the current block number (1) printed to the screen! - -## Contracts - -We have shipped a number of example contracts in the `@aztec/noir-contracts` npm package. This is included with the cli by default so you are able to use these contracts to test with. To get a list of the names of the contracts run: - -#include_code example-contracts yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash - -You can see all of our example contracts in the monorepo [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/src/contracts). - -In the following sections there will be commands that require contracts as options. You can either specify the full directory path to the contract abi, or you can use the name of one of these examples as the option value. This will become clearer later on. - -## 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](../../concepts/foundation/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](../../concepts/foundation/accounts/keys.md#addresses-partial-addresses-and-public-keys). - -Save the Address and Private key as environment variables. We will be using them later. - -```bash -export ADDRESS=
-export PRIVATE_KEY= -``` - -Alternatively, we can also manually generate a private key and use it for creating the account, either via a `-k` option or by setting the `PRIVATE_KEY` environment variable. - -#include_code create-account-from-private-key yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash - -For all commands that require a user's private key, the CLI will look for the `PRIVATE_KEY` environment variable in absence of an optional argument. - -Let's double check that the accounts have been registered with the sandbox using the `get-accounts` command: - -#include_code get-accounts yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash - -You will see a that a number of accounts exist that we did not create. The Sandbox initialises itself with 3 default accounts. Save one of the printed accounts (not the one that you generated above) in an environment variable. We will use it later. - -```bash -export ADDRESS2= -``` - -## Deploying a Token Contract - -We will now deploy the private token contract using the `deploy` command, minting 1000000 initial tokens to address `0x175310d40cd3412477db1c2a2188efd586b63d6830115fbb46c592a6303dbf6c`. 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 - -Save the contract address as an environment variable. We will use it later. - -```bash -export CONTRACT_ADDRESS= -``` - -:::info -If you use a different address in the constructor above, you will get an error when running the deployment. This is because you need to register an account in the sandbox before it can receive private notes. When you create a new account, it gets automatically registered. Alternatively, you can register an account you do not own along with its public key using the `register-recipient` command. -::: - -This command takes 1 mandatory positional argument which is the path to the contract ABI file in a JSON format (e.g. `contracts/target/PrivateToken.json`). -Alternatively you can pass the name of an example contract as exported by `@aztec/noir-contracts` (run `aztec-cli example-contracts` to see the full list of contracts available). - -The command takes a few optional arguments while the most important one is: - -- `--args` - Arguments to the constructor of the contract. In this case we have minted 1000000 initial tokens to the aztec address 0x20d3321707d53cebb168568e25c5c62a853ae1f0766d965e00d6f6c4eb05d599. - -The CLI tells us that the contract was successfully deployed. We can use the `check-deploy` command to verify that a contract has been successfully deployed to that address: - -#include_code check-deploy yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash - -## Calling a View Method - -When we deployed the token contract, an initial supply of tokens was minted to the address provided in the constructor. We can now query the `getBalance()` method on the contract to retrieve the balance of that address. Make sure to replace the `contract-address` with the deployment address you got from the previous command, and the `args` with the account you used in the constructor. - -#include_code call yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash - -The `call` command calls a read-only method on a contract, one that will not generate a transaction to be sent to the network. The arguments here are: - -- `--args` - The address for which we want to retrieve the balance. -- `--contract-abi` - The abi of the contract we are calling. -- `--contract-address` - The address of the deployed contract - -As you can see from the result, this address has a balance of 1000000, as expected. When using the Sandbox, you are able to query the balance of any account that has been created in the system, even the accounts created by default. You may wonder why this is, as you haven't provided the private keys for these accounts. The Sandbox contains a component known as the AztecRPCServer. When an account is created, this component stores the provided encryption private key and is able to read the account's private state meaning that the Sandbox can report the balance of any of it's accounts. More information about the account model can be found [here](../../concepts/foundation/accounts/main.md). - -## Sending a Transaction - -We can now send a transaction to the network. We will transfer funds from the owner of the initial minted tokens to our other account. For this we will use the `send` command, which expects as arguments the quantity of tokens to be transferred, the sender's address, and the recipient's address. Make sure to replace all addresses in this command with the ones for your run. - -#include_code send yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash - -We called the `transfer` function of the contract and provided these arguments: - -- `--args` - The list of arguments to the function call. -- `--contract-abi` - The abi of the contract to call. -- `--contract-address` - The deployed address of the contract to call. -- `--private-key` - The private key of the sender - -The command output tells us the details of the transaction such as its hash and status. We can use this hash to query the receipt of the transaction at a later time: - -#include_code get-tx-receipt yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash - -Let's now call `getBalance()` on each of our accounts and we should see updated values: - -#include_code calls yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash diff --git a/docs/docs/dev_docs/cli/main.md b/docs/docs/dev_docs/cli/main.md index 1236ed75bf5..3bcf02ead78 100644 --- a/docs/docs/dev_docs/cli/main.md +++ b/docs/docs/dev_docs/cli/main.md @@ -2,7 +2,7 @@ title: Aztec CLI --- -## What is the Aztec CLI? +## Introduction The Aztec CLI is a command-line tool allowing the user to interact directly with the Aztec Network. @@ -10,14 +10,139 @@ It aims to provide all of the functionality required to deploy and invoke contra ## Requirements -The Aztec CLI is provided as an npm package containing an installed binary. It can be installed by using: +You should have [node.js](https://nodejs.org/en/download) installed with version >= 18. -`yarn global add @aztec/cli` +To install the Aztec CLI run: + +```bash +npm install -g @aztec/cli +``` + +Or if you use yarn: + +```bash +yarn global add @aztec/cli +``` + +Then verify that it is installed with: + +```bash +aztec-cli -h +``` Once installed it is invoked via: `aztec-cli [options] [command]` -## Getting Started +## I have the Sandbox running, now what? + +Lets first establish that we are able to communicate with the Sandbox. Most commands will require the url to the Sandbox, which defaults in the CLI to `http://localhost:8080`. You can override this as an option with each command or by setting `AZTEC_RPC_HOST` environment variable. + +To test communication with the Sandbox, let's run the command: + +#include_code block-number yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash + +You should see the current block number (1) printed to the screen! + +## Contracts + +We have shipped a number of example contracts in the `@aztec/noir-contracts` npm package. This is included with the cli by default so you are able to use these contracts to test with. To get a list of the names of the contracts run: + +#include_code example-contracts yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash + +You can see all of our example contracts in the monorepo [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/src/contracts). + +In the following sections there will be commands that require contracts as options. You can either specify the full directory path to the contract abi, or you can use the name of one of these examples as the option value. This will become clearer later on. + +## 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](../../concepts/foundation/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](../../concepts/foundation/accounts/keys.md#addresses-partial-addresses-and-public-keys). + +Save the Address and Private key as environment variables. We will be using them later. + +```bash +export ADDRESS=
+export PRIVATE_KEY= +``` + +Alternatively, we can also manually generate a private key and use it for creating the account, either via a `-k` option or by setting the `PRIVATE_KEY` environment variable. + +#include_code create-account-from-private-key yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash + +For all commands that require a user's private key, the CLI will look for the `PRIVATE_KEY` environment variable in absence of an optional argument. + +Let's double check that the accounts have been registered with the sandbox using the `get-accounts` command: + +#include_code get-accounts yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash + +You will see a that a number of accounts exist that we did not create. The Sandbox initialises itself with 3 default accounts. Save one of the printed accounts (not the one that you generated above) in an environment variable. We will use it later. + +```bash +export ADDRESS2= +``` + +## Deploying a Token Contract + +We will now deploy the private token contract using the `deploy` command, minting 1000000 initial tokens to address `0x175310d40cd3412477db1c2a2188efd586b63d6830115fbb46c592a6303dbf6c`. 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 + +Save the contract address as an environment variable. We will use it later. + +```bash +export CONTRACT_ADDRESS= +``` + +:::info +If you use a different address in the constructor above, you will get an error when running the deployment. This is because you need to register an account in the sandbox before it can receive private notes. When you create a new account, it gets automatically registered. Alternatively, you can register an account you do not own along with its public key using the `register-recipient` command. +::: + +This command takes 1 mandatory positional argument which is the path to the contract ABI file in a JSON format (e.g. `contracts/target/PrivateToken.json`). +Alternatively you can pass the name of an example contract as exported by `@aztec/noir-contracts` (run `aztec-cli example-contracts` to see the full list of contracts available). + +The command takes a few optional arguments while the most important one is: + +- `--args` - Arguments to the constructor of the contract. In this case we have minted 1000000 initial tokens to the aztec address 0x20d3321707d53cebb168568e25c5c62a853ae1f0766d965e00d6f6c4eb05d599. + +The CLI tells us that the contract was successfully deployed. We can use the `check-deploy` command to verify that a contract has been successfully deployed to that address: + +#include_code check-deploy yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash + +## Calling a View Method + +When we deployed the token contract, an initial supply of tokens was minted to the address provided in the constructor. We can now query the `getBalance()` method on the contract to retrieve the balance of that address. Make sure to replace the `contract-address` with the deployment address you got from the previous command, and the `args` with the account you used in the constructor. + +#include_code call yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash + +The `call` command calls a read-only method on a contract, one that will not generate a transaction to be sent to the network. The arguments here are: + +- `--args` - The address for which we want to retrieve the balance. +- `--contract-abi` - The abi of the contract we are calling. +- `--contract-address` - The address of the deployed contract + +As you can see from the result, this address has a balance of 1000000, as expected. When using the Sandbox, you are able to query the balance of any account that has been created in the system, even the accounts created by default. You may wonder why this is, as you haven't provided the private keys for these accounts. The Sandbox contains a component known as the AztecRPCServer. When an account is created, this component stores the provided encryption private key and is able to read the account's private state meaning that the Sandbox can report the balance of any of it's accounts. More information about the account model can be found [here](../../concepts/foundation/accounts/main.md). + +## Sending a Transaction + +We can now send a transaction to the network. We will transfer funds from the owner of the initial minted tokens to our other account. For this we will use the `send` command, which expects as arguments the quantity of tokens to be transferred, the sender's address, and the recipient's address. Make sure to replace all addresses in this command with the ones for your run. + +#include_code send yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash + +We called the `transfer` function of the contract and provided these arguments: + +- `--args` - The list of arguments to the function call. +- `--contract-abi` - The abi of the contract to call. +- `--contract-address` - The deployed address of the contract to call. +- `--private-key` - The private key of the sender + +The command output tells us the details of the transaction such as its hash and status. We can use this hash to query the receipt of the transaction at a later time: + +#include_code get-tx-receipt yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash + +Let's now call `getBalance()` on each of our accounts and we should see updated values: -To get up and running with the Aztec CLI head over to the [getting start page](./cli.md). +#include_code calls yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash diff --git a/docs/docs/dev_docs/contracts/compiling.md b/docs/docs/dev_docs/contracts/compiling.md index 071a7b56bec..e9c62495470 100644 --- a/docs/docs/dev_docs/contracts/compiling.md +++ b/docs/docs/dev_docs/contracts/compiling.md @@ -145,7 +145,7 @@ The compiler exposes the following functions: ## 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](../../dev_docs/cli/cli.md#deploying-a-token-contract) and [interact](../../dev_docs/cli/cli.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](../../dev_docs/cli/main.md#deploying-a-token-contract) and [interact](../../dev_docs/cli/main.md#sending-a-transaction) with them. import Disclaimer from "../../misc/common/\_disclaimer.mdx"; diff --git a/docs/docs/dev_docs/contracts/deploying.md b/docs/docs/dev_docs/contracts/deploying.md index 7b2fd05163e..a2e5795a8f9 100644 --- a/docs/docs/dev_docs/contracts/deploying.md +++ b/docs/docs/dev_docs/contracts/deploying.md @@ -4,8 +4,8 @@ Once you have [compiled](./compiling.md) your contracts you can proceed to deplo ## Prerequisites - aztec-cli installed (go to [CLI main section](../cli/main.md) for installation instructions) -- contract artifacts ready (go to [Compiling contracts section](../contracts/compiling.md) for instructions on how to compile contracts) -- aztec-sandbox running (go to [Sandbox section](../sandbox/main.md) for instructions on how to install and run the sandbox) +- 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/sandbox.md) for instructions on how to install and run the sandbox) ## Deploy diff --git a/docs/docs/dev_docs/contracts/layout.md b/docs/docs/dev_docs/contracts/layout.md index 50832159f1a..c7943e6d817 100644 --- a/docs/docs/dev_docs/contracts/layout.md +++ b/docs/docs/dev_docs/contracts/layout.md @@ -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/modules_packages_crates/crates_and_packages). -- You can review the structure of a complete contract in the token contract tutorial [here](../getting_started/token_contract_tutorial.md). +- 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/dev_docs/contracts/main.md b/docs/docs/dev_docs/contracts/main.md index e6c83b59bae..24eb96e379c 100644 --- a/docs/docs/dev_docs/contracts/main.md +++ b/docs/docs/dev_docs/contracts/main.md @@ -20,15 +20,20 @@ An **Aztec smart contract** is a smart contract with **private** state variables ## Install Noir -To write an Aztec.nr contract, you need to write Noir, and to write Noir, you need to [install Nargo](https://noir-lang.org/getting_started/nargo_installation). +To write an Aztec.nr contract, you need to write Noir, which requires a build tool called Nargo: + + +:::info +For those coming from vanilla Noir, the nargo version used for aztec.nr is tracked seaprately to nargo for vanilla noir, so be sure to use the nargo version shown above +::: ## Install Noir tooling There are a number of tools to make writing Aztec.nr contracts more pleasant. See [here](https://github.com/noir-lang/awesome-noir#get-coding). -## Quickstart +## Tutorials -See the [contracts quickstart](../getting_started/noir_contracts.md) for more info on getting set up to write contracts. +See the [Standard Token Contract tutorial](../tutorials/writing_token_contract.md) for more info on getting set up to write contracts. ## Learn more diff --git a/docs/docs/dev_docs/contracts/setup.md b/docs/docs/dev_docs/contracts/setup.md new file mode 100644 index 00000000000..0501e90195e --- /dev/null +++ b/docs/docs/dev_docs/contracts/setup.md @@ -0,0 +1,95 @@ +--- +title: Setup +--- + +import { AztecPackagesVersion } from "@site/src/components/Version"; + +## Introduction + +This guide explains the set up required to write a contract using the Aztec.nr library. + +:::info Prerequisite reading +If you haven't read about [Aztec.nr](./main.md), we recommend going there first. +::: + +### Dependencies + +#### `nargo` + +Nargo is Noir's build tool. On your terminal, run: + + + +#### Aztec Sandbox + +You need to setup the [Aztec sandbox](../getting_started/sandbox.md). + + + +## Set up for aztec.nr contracts + +1. Inside the yarn project you created from the [Sanbox page](../getting_started/sandbox.md), create a sub-folder where the contracts will reside. + +```bash +mkdir contracts +``` + +All contract projects will reside within this folder. Note that contracts don't actually have to live here and this is just a style choice. + +2. Next, create a noir project using nargo by running the following in the terminal from the `contracts` folder + +```bash +cd contracts +nargo new --contract example_contract +``` + +This creates `example_contract` directory within contracts which is a noir project with: + +- a Nargo.toml (which is the manifest file of the project) at `example_contract/Nargo.toml`. +- a main.nr file (the file where our contract will reside) at `example_contract/src/main.nr`. + +Your folder should look like: + +```tree +. +|-contracts +| |--example_contract +| | |--src +| | | |--main.nr +| | |--Nargo.toml +|-src +| |--index.ts +``` + +Before writing the contracts, we must add the aztec.nr library. This adds smart contract utility functions for interacting with the Aztec network. + +3. Finally, add relevant aztec-nr dependencies that you might use such as `aztec.nr`, `value_note` and `safe_math` libraries. + +Open Nargo.toml that is in the `contracts/example_contract` folder, and add the dependency section as follows + +```toml +[package] +name = "example_contract" +authors = [""] +compiler_version = "0.1" +type = "contract" + +[dependencies] +# Framework import +aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" } + +# Utility dependencies +value_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/value-note"} +safe_math = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/safe-math"} +``` + +:::info +Note: currently the dependency name **_MUST_** be `aztec`. The framework expects this namespace to be available when compiling into contracts. This limitation may be removed in the future. +::: + +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) diff --git a/docs/docs/dev_docs/contracts/syntax/main.md b/docs/docs/dev_docs/contracts/syntax/main.md index 124e271e7ee..59c7d8a7f7b 100644 --- a/docs/docs/dev_docs/contracts/syntax/main.md +++ b/docs/docs/dev_docs/contracts/syntax/main.md @@ -1,4 +1,5 @@ import DocCardList from '@theme/DocCardList'; +import { AztecPackagesVersion } from "@site/src/components/Version"; # Aztec.nr Syntax @@ -16,26 +17,6 @@ Aztec.nr contains abstractions which remove the need to understand the low-level - secrets - Functions for communicating with [Ethereum L1](../portals/main.md) -To import Aztec.nr into your Aztec contract project, simply include it as a dependency. For example: - -```toml -[package] -name = "token_contract" -authors = [""] -compiler_version = "0.1" -type = "contract" - -[dependencies] -# Framework import -aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" } - -# Utility dependencies -value_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/value-note"} -safe_math = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/safe-math"} -``` - -:::info -Note: currently the dependency name ***MUST*** be `aztec`. The framework expects this namespace to be available when compiling into contracts. This limitation may be removed in the future. -::: +To setup a aztec-nr project, follow the [setup instructions](../setup.md) diff --git a/docs/docs/dev_docs/contracts/workflow.md b/docs/docs/dev_docs/contracts/workflow.md index eb4641cbc8d..f0d9bbe1b9d 100644 --- a/docs/docs/dev_docs/contracts/workflow.md +++ b/docs/docs/dev_docs/contracts/workflow.md @@ -2,6 +2,9 @@ title: Contract Workflow --- +## Setup +[Set up your project](./setup.md) + ## Write [Write a contract](./syntax/main.md). diff --git a/docs/docs/dev_docs/getting_started/noir_contracts.md b/docs/docs/dev_docs/getting_started/noir_contracts.md deleted file mode 100644 index d05a4cafbb4..00000000000 --- a/docs/docs/dev_docs/getting_started/noir_contracts.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Aztec.nr Contracts Quickstart ---- - -## Introduction - -This guide explains the set up required to write a contract using the Aztec.nr library; then deploy it to the sandbox. Aztec.nr is a library on top of [Noir](https://noir-lang.org/) that can be used to write smart contracts for Aztec. Since Noir files use the `.nr` extension, we are calling this library "Aztec.nr". - -:::info Prerequisite reading -If you haven't read [Aztec Sandbox](./sandbox.md), we recommend going there first. -::: - -### Dependencies - -#### `nargo` - -Nargo is Noir's build tool. On your terminal, run: - - - -#### Aztec Sandbox - -You need to setup the [Aztec sandbox](./sandbox.md). - - - -## Set up for aztec.nr contracts - -1. Inside the yarn project you created from the [Aztec.js](./sandbox.md) page, create a sub-folder where the contracts will reside. - -```bash -mkdir contracts -``` - -All contract projects will reside within this folder. Note that contracts don't actually have to live here and this is just a style choice. - -2. Next, create a noir project using nargo by running the following in the terminal from the `contracts` folder - -```bash -cd contracts -nargo new example_contract -``` - -This creates a noir project with a Nargo.toml (which is the manifest file of the project). This file is found at `example_contract/src/main.nr`, where we will write our contract. - -Your folder should look like: - -``` -. -|-contracts -| |--example_contract -| | |--src -| | | |--main.nr -|-src -| |--index.ts -``` - -Before writing the contracts, we must add the aztec.nr library. This adds smart contract utility functions for interacting with the Aztec network. - -3. Add aztec.nr library as a dependency to your noir project. Open Nargo.toml that is in the `contracts/example_contract` folder, and add the dependency section as follows: - -```toml -[package] -name = "example_contract" -authors = [""] -compiler_version = "0.1" -type = "contract" - -[dependencies] -aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" } -``` - -:::note -You may need to update your dependencies depending on the contract that you are writing. For example, the token contract [imports more](../getting_started/token_contract_tutorial#project-setup). -::: - -You are now ready to write your own contracts! - -You can replace the content of the generated file `example_contract/src/main.nr` with your contract code. - -## Next Steps - -- You can learn more about writing contracts from the [Contracts section](../contracts/main.md). -- You can find more example Aztec contracts [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/src/contracts). -- Consider going through the [token contract tutorial](./token_contract_tutorial.md) for a deep dive on writing more advanced Aztec contracts and an introduction to some of the concepts that underpin the Aztec network architecture. -- After writing the contract, you have to compile it. Details can be found [here](../contracts/compiling.md). -- After compiling, you can deploy your contract to the Aztec network. Relevant instructions and explanations can be found [here](../contracts/deploying.md). -- Thereafter, you can interact with the contracts similar to how it was shown in the the [Creating and submitting transactions section on the Sandbox page](./sandbox.md#creating-and-submitting-transactions). diff --git a/docs/docs/dev_docs/getting_started/quickstart.md b/docs/docs/dev_docs/getting_started/quickstart.md index f75879a0a74..51e0233b0d5 100644 --- a/docs/docs/dev_docs/getting_started/quickstart.md +++ b/docs/docs/dev_docs/getting_started/quickstart.md @@ -87,7 +87,7 @@ The default accounts that come with sandbox will likely change over time. Save t #include_code declare-accounts yarn-project/end-to-end/src/guides/up_quick_start.sh bash -Start by deploying a token contract. After it is deployed, we check that the deployment succeeded, export the deployment address to use in future commands and then call the `_initialize` function. For more detail on how the token contract works, see the [token contract tutorial](./token_contract_tutorial). +Start by deploying a token contract. After it is deployed, we check that the deployment succeeded, export the deployment address to use in future commands and then call the `_initialize` function. For more detail on how the token contract works, see the [token contract tutorial](../tutorials/writing_token_contract.md). #include_code deploy yarn-project/end-to-end/src/guides/up_quick_start.sh bash @@ -97,7 +97,7 @@ Note that the deployed contract address is exported, so we can use it as `$CONTR Alice is set up as the contract admin and token minter in the `_initialize` function. Let's get Alice some private tokens. -We need to export the `SECRET` and `SECRET_HASH` values in order to privately mint tokens. Private tokens are claimable by anyone with the pre-image to a provided hash, see more about how the token contract works in the [token contract tutorial](./token_contract_tutorial.md). Once the tokens have been minted, Alice can claim them with the `redeem_shield` function. After this, Alice should have 1000 tokens in their private balance. +We need to export the `SECRET` and `SECRET_HASH` values in order to privately mint tokens. Private tokens are claimable by anyone with the pre-image to a provided hash, see more about how the token contract works in the [token contract tutorial](../tutorials/writing_token_contract.md). Once the tokens have been minted, Alice can claim them with the `redeem_shield` function. After this, Alice should have 1000 tokens in their private balance. #include_code mint-private yarn-project/end-to-end/src/guides/up_quick_start.sh bash @@ -116,4 +116,5 @@ Aztec's Layer 2 network is a fully programmable combined private/public ZK rollu - Aztec Node - Aggregates all of the 'backend' services necessary for the building and publishing of rollups. - Aztec RPC Server - Normally residing with the end client, this decrypts and stores a client's private state, executes simulations and submits transactions to the Aztec Node. - [Aztec.js](./sandbox) - Aztec's client library for interacting with the Aztec RPC Server (think Ethers.js). -- [Write your own contracts](./noir_contracts.md) +- [Aztec.nr](../contracts/main.md) - Aztec's smart contract framework + diff --git a/docs/docs/dev_docs/getting_started/sandbox.md b/docs/docs/dev_docs/getting_started/sandbox.md index 32a66353747..b6159100400 100644 --- a/docs/docs/dev_docs/getting_started/sandbox.md +++ b/docs/docs/dev_docs/getting_started/sandbox.md @@ -8,18 +8,24 @@ import Image from "@theme/IdealImage"; The Aztec Sandbox aims to provide a local development system against which you can build and test Aztec.nr contracts in a fast, safe, and free environment. +:::info +For a quickstart checkout [the Quickstart section](./quickstart.md) +::: + Here we will walkthrough the process of retrieving the Sandbox, installing the client libraries and using it to deploy and use a fully private token contract on the Aztec network using Aztec.js. -## What do you need? +You can find the [complete tutorial code here](https://github.com/AztecProtocol/dev-rel/tree/main/tutorials/sandbox-tutorial/token). + +## Prerequisites - Node.js >= v18 - Docker and Docker Compose (Docker Desktop under WSL2 on windows) That's it... -## Ok, so how do I try it out? +## Install the Sandbox -You can just curl the site like this: +In your terminal: ```sh /bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" @@ -36,17 +42,15 @@ Within a few seconds the Sandbox should be up and running! -## I have the Sandbox running, show me how to use it - -We will deploy a token contract, and send tokens privately, using the Sandbox. You can see the final result of the [tutorial code here](https://github.com/AztecProtocol/dev-rel/tree/main/tutorials/sandbox-tutorial/token), if you don't want to follow along, copy and pasting the example code. +## Project setup -Writing the contract itself is out of scope for this tutorial, so we will use a Token Contract which has been pre-supplied as an example. See [here](../contracts/main.md) for more information on how to write contracts for Aztec. +We will deploy a pre-compiled token contract, and send tokens privately, using the Sandbox. -The following should work for MacOS, Linux or even WSL2 Ubuntu under Windows. +:::info +If you don't want to follow along and copy pasting step-by-step, the full code repository is available [here](https://github.com/AztecProtocol/dev-rel/tree/main/tutorials/sandbox-tutorial/token) +::: -Let's create an empty project called `token`. If you are familiar with setting up Typescript projects then you can skip to step 6. - -Although both `yarn` and `npm` would work, this example uses `yarn`. Open the terminal and do the following +We will create a `yarn` project called `token` (although npm works fine too). If you are familiar with setting up Javascript/Typescript projects then you can skip to step 6. 1. Ensure node version is 18 or higher by running @@ -59,22 +63,22 @@ node -v ```sh mkdir token cd token -yarn init +yarn init -yp ``` -1. Create a `src` folder inside your new `token` directory: +3. Create a `src` folder inside your new `token` directory: ```sh mkdir src ``` -4. Add typescript to the yarn project +4. Add necessary yarn packages (and optionally add typescript too) ```sh -yarn add typescript @types/node --dev +yarn add @aztec/aztec.js @aztec/noir-contracts typescript @types/node ``` -Add a `tsconfig.json` file into the project root, here is an example: +5. [Optional] If creating a typescript file, add a `tsconfig.json` file into the project root, here is an example: ```json { @@ -102,7 +106,7 @@ Add a `tsconfig.json` file into the project root, here is an example: } ``` -5. Add a `scripts` section to `package.json` and set `"type": "module"`: +6. Update `package.json` - Add a `scripts` section to `package.json` and set `"type": "module"`: ```json { @@ -119,20 +123,22 @@ Add a `tsconfig.json` file into the project root, here is an example: "clean": "rm -rf ./dest tsconfig.tsbuildinfo", "start": "yarn build && DEBUG='token' node ./dest/index.js" }, - "devDependencies": { - "@types/node": "^20.4.9", - "typescript": "^5.1.6" + "dependencies": { + "@aztec/aztec.js": "^0.7.10", + "@aztec/noir-contracts": "^0.7.10", + "@types/node": "^20.6.3", + "typescript": "^5.2.2" } } ``` -6. Next, install Aztec related dependencies +7. Next, install Aztec related dependencies ```sh yarn add @aztec/aztec.js @aztec/noir-contracts ``` -7. Create an `index.ts` file in the `src` directory with the following sandbox connection setup: +8. Create an `index.ts` file in the `src` directory with the following sandbox connection setup: ```ts #include_code imports /yarn-project/end-to-end/src/e2e_sandbox_example.test.ts raw @@ -144,7 +150,9 @@ async function main() { main(); ``` -8. Finally, run the package: +9. Finally, run the package: + +In the project root, run ```sh yarn start @@ -166,48 +174,21 @@ A successful run should show: Great! The Sandbox is running and we are able to interact with it. -## Account Creation/Deployment - -The next step is to create some accounts. An in-depth explaining about accounts on aztec can be found [here](../../concepts/foundation/accounts/main.md). But creating an account on the Sandbox does 2 things: +## Accounts -1. Deploys an account contract -- representing you -- allowing you to perform actions on the network (deploy contracts, call functions etc). -2. Adds your encryption keys to the RPC Server allowing it to decrypt and manage your private state. +The sandbox is preloaded with multiple accounts so you don't have to sit and create them. Let's load these accounts -Continue with adding the following to the `index.ts` file in our example: +#include_code load_accounts /yarn-project/end-to-end/src/e2e_sandbox_example.test.ts typescript -#include_code Accounts /yarn-project/end-to-end/src/e2e_sandbox_example.test.ts typescript +An explanation on accounts on Aztec can be found [here](../../concepts/foundation/accounts/main.md). -Running `yarn start` should now output: - -``` - token Aztec Sandbox Info { - version: 1, - chainId: 31337, - rollupAddress: EthAddress { - buffer: - }, - client: 'aztec-rpc@0.1.0', - compatibleNargoVersion: '0.11.1-aztec.0' - } - token Creating accounts using schnorr signers... +3ms - token Created Alice's account at 0x1509b252...0027 +10s - token Created Bob's account at 0x031862e8...e7a3 +0ms -``` - -That might seem like a lot to digest but it can be broken down into the following steps: - -1. We create 2 `Account` objects in Typescript. This object heavily abstracts away the mechanics of configuring and deploying an account contract and setting up a 'wallet' for signing transactions. If you aren't interested in building new types of account contracts or wallets then you don't need to be too concerned with it. In this example we have constructed account contracts and corresponding wallets that sign/verify transactions using schnorr signatures. -2. We wait for the deployment of the 2 account contracts to complete. -3. We retrieve the expected account addresses from the `Account` objects and ensure that they are present in the set of account addresses registered on the Sandbox. - -Note, we use the `getRegisteredAccounts` API to verify that the addresses computed as part of the -account contract deployment have been successfully added to the Sandbox. - -If you were looking at your terminal that is running the Sandbox you should have seen a lot of activity. This is because the Sandbox will have simulated the deployment of both contracts, executed the private kernel circuit for each before submitted 2 transactions to the pool. The sequencer will have picked them up and inserted them into a rollup and executed the recursive rollup circuits before publishing the rollup to Anvil. Once this has completed, the rollup is retrieved and pulled down to the internal RPC Server so that any new account state can be decrypted. +If you want more accounts, you can find instructions in the [Account creation section](../wallets/creating_schnorr_accounts.md). ## Token Contract Deployment -Now that we have our accounts setup, let's move on to deploy our private token contract. Add this to `index.ts` below the code you added earlier: +Writing a contract from scratch is beyond the scope of this page. Feel free to look at the [Token contract tutorial](../tutorials/writing_token_contract.md) or the section on aztec-noir contracts [here](../contracts/main.md) + +Now that we have our accounts loaded, let's move on to deploy our pre-compiled token contract. Add this to `index.ts` below the code you added earlier: #include_code Deployment /yarn-project/end-to-end/src/e2e_sandbox_example.test.ts typescript @@ -369,4 +350,4 @@ You can find the [complete tutorial code here](https://github.com/AztecProtocol/ Here we showed how to interact with the sandbox, but didn't go into details on how to write your own contract or any relevant setup needed for it. -You can find more information about writing Aztec contracts [here](./noir_contracts.md) and refer to the [Contracts section](../contracts/main.md) on syntax, compiling, deploying and interacting with how to start writing contracts. +You can find more information about writing Aztec contracts [here](../contracts/main.md) on syntax, compiling, deploying and interacting with how to start writing contracts. diff --git a/docs/docs/dev_docs/sandbox/main.md b/docs/docs/dev_docs/sandbox/main.md deleted file mode 100644 index 66d4e60c755..00000000000 --- a/docs/docs/dev_docs/sandbox/main.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Aztec Sandbox ---- - -## What is the Aztec Sandbox? - -The Aztec Sandbox is local development system against which you can build and test Aztec.nr contracts in a fast, safe, and free environment. - -For a complete walk-through deploying and using a private contract with the Sandbox and CLI, see our [quickstart](../getting_started/quickstart). diff --git a/docs/docs/dev_docs/sandbox/common_errors.md b/docs/docs/dev_docs/sandbox_errors/main.md similarity index 100% rename from docs/docs/dev_docs/sandbox/common_errors.md rename to docs/docs/dev_docs/sandbox_errors/main.md diff --git a/docs/docs/dev_docs/testing/testing.md b/docs/docs/dev_docs/testing/testing.md index d8bdf31adbe..8ae02751cdb 100644 --- a/docs/docs/dev_docs/testing/testing.md +++ b/docs/docs/dev_docs/testing/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](../sandbox/main.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](../getting_started/sandbox.md#install-the-sandbox). 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 diff --git a/docs/docs/dev_docs/tutorials/main.md b/docs/docs/dev_docs/tutorials/main.md new file mode 100644 index 00000000000..da6889b6fc8 --- /dev/null +++ b/docs/docs/dev_docs/tutorials/main.md @@ -0,0 +1,3 @@ +import DocCardList from '@theme/DocCardList'; + + diff --git a/docs/docs/dev_docs/dapps/tutorials/contract_deployment.md b/docs/docs/dev_docs/tutorials/writing_dapp/contract_deployment.md similarity index 97% rename from docs/docs/dev_docs/dapps/tutorials/contract_deployment.md rename to docs/docs/dev_docs/tutorials/writing_dapp/contract_deployment.md index 36972b19fc7..033f155ccfd 100644 --- a/docs/docs/dev_docs/dapps/tutorials/contract_deployment.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/contract_deployment.md @@ -3,7 +3,7 @@ To add contracts to your application, we'll start by creating a new `nargo` project. We'll then compile the contracts, and write a simple script to deploy them to our Sandbox. :::info -Follow the instructions [here](../../getting_started/noir_contracts.md) to install `nargo` if you haven't done so already. +Follow the instructions [here](../../contracts/setup.md) to install `nargo` if you haven't done so already. ::: ## Initialise nargo project diff --git a/docs/docs/dev_docs/dapps/tutorials/contract_interaction.md b/docs/docs/dev_docs/tutorials/writing_dapp/contract_interaction.md similarity index 100% rename from docs/docs/dev_docs/dapps/tutorials/contract_interaction.md rename to docs/docs/dev_docs/tutorials/writing_dapp/contract_interaction.md diff --git a/docs/docs/dev_docs/dapps/tutorials/main.md b/docs/docs/dev_docs/tutorials/writing_dapp/main.md similarity index 92% rename from docs/docs/dev_docs/dapps/tutorials/main.md rename to docs/docs/dev_docs/tutorials/writing_dapp/main.md index 0685ab032a3..e62d4730127 100644 --- a/docs/docs/dev_docs/dapps/tutorials/main.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/main.md @@ -13,8 +13,8 @@ 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/sandbox.md) -- [Aztec CLI](../../cli/cli.md) -- [Nargo](../../getting_started/noir_contracts.md) for building contracts +- [Aztec CLI](../../cli/main.md) +- [Nargo](../../contracts/setup.md) for building contracts ## Prerequisites diff --git a/docs/docs/dev_docs/dapps/tutorials/project_setup.md b/docs/docs/dev_docs/tutorials/writing_dapp/project_setup.md similarity index 100% rename from docs/docs/dev_docs/dapps/tutorials/project_setup.md rename to docs/docs/dev_docs/tutorials/writing_dapp/project_setup.md diff --git a/docs/docs/dev_docs/dapps/tutorials/rpc_server.md b/docs/docs/dev_docs/tutorials/writing_dapp/rpc_server.md similarity index 87% rename from docs/docs/dev_docs/dapps/tutorials/rpc_server.md rename to docs/docs/dev_docs/tutorials/writing_dapp/rpc_server.md index 4df09e27b9e..23767890cb9 100644 --- a/docs/docs/dev_docs/dapps/tutorials/rpc_server.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/rpc_server.md @@ -2,7 +2,7 @@ As an app developer, the [Aztec RPC Server](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/aztec-rpc) 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](../../sandbox/main.md), which runs a local RPC Server and an Aztec Node, both connected to a local Ethereum development node like Anvil. The Sandbox also includes a set of pre-initialised accounts that you can use from your app. +During the Sandbox phase, this role is fulfilled by the [Aztec Sandbox](../../getting_started/sandbox.md), which runs a local RPC Server and an Aztec Node, both connected to a local Ethereum development node like Anvil. The Sandbox also includes a set of pre-initialised 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/dev_docs/dapps/tutorials/testing.md b/docs/docs/dev_docs/tutorials/writing_dapp/testing.md similarity index 96% rename from docs/docs/dev_docs/dapps/tutorials/testing.md rename to docs/docs/dev_docs/tutorials/writing_dapp/testing.md index 24da56dbf84..7083e22a658 100644 --- a/docs/docs/dev_docs/dapps/tutorials/testing.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/testing.md @@ -56,4 +56,4 @@ yarn node --experimental-vm-modules $(yarn bin jest) --testRegex '.*\.test\.mjs$ ## Next steps -Now that you have finished the tutorial, you can learn more about [writing contracts with Noir](../../contracts/main.md), check out the [Sandbox's architecture](../../sandbox/main.md), or read about the [fundamental concepts behind Aztec Network](../../../concepts/foundation/main.md). +Now that you have finished the tutorial, you can learn more about [writing contracts with Noir](../../contracts/main.md) or read about the [fundamental concepts behind Aztec Network](../../../concepts/foundation/main.md). diff --git a/docs/docs/dev_docs/getting_started/token_contract_tutorial.md b/docs/docs/dev_docs/tutorials/writing_token_contract.md similarity index 97% rename from docs/docs/dev_docs/getting_started/token_contract_tutorial.md rename to docs/docs/dev_docs/tutorials/writing_token_contract.md index 64a61a5faae..018592b978f 100644 --- a/docs/docs/dev_docs/getting_started/token_contract_tutorial.md +++ b/docs/docs/dev_docs/tutorials/writing_token_contract.md @@ -1,7 +1,7 @@ -# Token Contract Tutorial +# Writing a Standard token contract in Aztec.nr In this tutorial we will go through writing a standard 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](./noir_contracts) section before this tutorial to gain some familiarity with writing Aztec smart contracts. +for the Aztec Network, using the Aztec.nr contract libraries. It is recommended that you go through the [the introduction to contracts](../contracts/main.md) and [setup instructions](../contracts/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. @@ -14,7 +14,7 @@ In this tutorial you will learn how to: - 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 code defined [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr), and explain what is being added as we go. +We are going to start with a blank project and fill in the token contract source code defined [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr), and explain what is being added as we go. ## Requirements @@ -22,7 +22,7 @@ You will need to install nargo, the Noir build too. if you are familiar with Rus -If you've already installed the `aztec-cli`, as described in the quickstart [here](./quickstart#cli), you can check which version of Noir is compatible with your version of the CLI and sandbox by running: +If you've already installed the `aztec-cli`, as described in the quickstart [here](../getting_started/quickstart.md#cli), you can check which version of Noir is compatible with your version of the CLI and sandbox by running: ```bash aztec-cli get-node-info @@ -65,7 +65,7 @@ cd token_contract_tutorial && mkdir contracts && cd contracts Create a new Noir project using nargo. ```bash -nargo init --name token_contract +nargo new --contract token_contract ``` Your project should look like this: @@ -486,7 +486,7 @@ This must be included in every contract because it depends on the storage slots, ## Compiling -Now that the contract is complete, you should be able to compile it with the `aztec-cli`. See the [CLI page](../cli/cli.md) for instructions on setting it up. +Now that the contract is complete, you should be able to compile it with the `aztec-cli`. See the [CLI page](../cli/main.md) for instructions on setting it up. ```bash aztec-cli compile /path/to/token_contracts_folder diff --git a/docs/docs/dev_docs/wallets/creating_schnorr_accounts.md b/docs/docs/dev_docs/wallets/creating_schnorr_accounts.md new file mode 100644 index 00000000000..ea9e1cda5f5 --- /dev/null +++ b/docs/docs/dev_docs/wallets/creating_schnorr_accounts.md @@ -0,0 +1,60 @@ +--- +title: Creating Schnorr Accounts +--- + +## Introduction + +This section shows how to create schnorr account wallets on the Aztec Sandbox. + +An in-depth explaining about accounts on aztec can be found [here](../../concepts/foundation/accounts/main.md). But creating an account on the Sandbox does 2 things: + +1. Deploys an account contract -- representing you -- allowing you to perform actions on the network (deploy contracts, call functions etc). +2. Adds your encryption keys to the RPC Server allowing it to decrypt and manage your private state. + +## Pre-requisites + +Have a running Sandbox and a repository that interacts with it as explained [here](../getting_started/sandbox.md). + +Let's assume you have a file `src/index.ts` from the example used in the Sandbox page. + +## Create accounts on the sandbox + +1. Import relevant modules: + +#include_code imports /yarn-project/end-to-end/src/e2e_sandbox_example.test.ts typescript + +2. Code to create an account. You must run this inside of a function: + +#include_code create_accounts /yarn-project/end-to-end/src/e2e_sandbox_example.test.ts typescript + +3. Running `yarn start` should now output: + +``` + token Aztec Sandbox Info { + version: 1, + chainId: 31337, + rollupAddress: EthAddress { + buffer: + }, + client: 'aztec-rpc@0.1.0', + compatibleNargoVersion: '0.11.1-aztec.0' + } + token Creating accounts using schnorr signers... +3ms + token Created Alice's account at 0x1509b252...0027 +10s + token Created Bob's account at 0x031862e8...e7a3 +0ms +``` + +That might seem like a lot to digest but it can be broken down into the following steps: + +1. We create 2 `Account` objects in Typescript. This object heavily abstracts away the mechanics of configuring and deploying an account contract and setting up a 'wallet' for signing transactions. If you aren't interested in building new types of account contracts or wallets then you don't need to be too concerned with it. In this example we have constructed account contracts and corresponding wallets that sign/verify transactions using schnorr signatures. +2. We wait for the deployment of the 2 account contracts to complete. +3. We retrieve the expected account addresses from the `Account` objects and ensure that they are present in the set of account addresses registered on the Sandbox. + +Note, we use the `getRegisteredAccounts` API to verify that the addresses computed as part of the +account contract deployment have been successfully added to the Sandbox. + +If you were looking at your terminal that is running the Sandbox you should have seen a lot of activity. This is because the Sandbox will have simulated the deployment of both contracts, executed the private kernel circuit for each before submitted 2 transactions to the pool. The sequencer will have picked them up and inserted them into a rollup and executed the recursive rollup circuits before publishing the rollup to Anvil. Once this has completed, the rollup is retrieved and pulled down to the internal RPC Server so that any new account state can be decrypted. + +## Next Steps + +Check out our section on [Writing your own Account Contract](./writing_an_account_contract.md) leveraging our account abstraction diff --git a/docs/netlify.toml b/docs/netlify.toml index 478b38843c9..96e8a4fbc88 100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@ -56,7 +56,43 @@ [[redirects]] from = "/dev_docs/getting_started/cli" - to = "/dev_docs/cli" + to = "/dev_docs/cli/main" + +[[redirects]] + from = "/dev_docs/getting_started/noir_contracts" + to = "/dev_docs/contracts/main" + +[[redirects]] + from = "/dev_docs/getting_started/token_contract_tutorial" + to = "/dev_docs/tutorials/writing_token_contract" + +[[redirects]] + from = "/dev_docs/sandbox/main" + to = "/dev_docs/getting_started/sandbox" + +[[redirects]] + from = "/dev_docs/dapps/tutorials/main" + to = "/dev_docs/tutorials/writing_dapp/main" + +[[redirects]] + from = "/dev_docs/dapps/tutorials/project_setup" + to = "/dev_docs/tutorials/writing_dapp/project_setup" + +[[redirects]] + from = "/dev_docs/dapps/tutorials/contract_deployment" + to = "/dev_docs/tutorials/writing_dapp/contract_deployment" + +[[redirects]] + from = "/dev_docs/dapps/tutorials/contract_interaction" + to = "/dev_docs/tutorials/writing_dapp/contract_interaction" + +[[redirects]] + from = "/dev_docs/dapps/tutorials/rpc_server" + to = "/dev_docs/tutorials/writing_dapp/rpc_server" + +[[redirects]] + from = "/dev_docs/dapps/tutorials/testing" + to = "/dev_docs/tutorials/writing_dapp/testing" [[redirects]] from = "/aztec/cryptography/cryptography-roadmap" diff --git a/docs/sidebars.js b/docs/sidebars.js index 9b4ac8d3111..230c1a5b0ff 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -196,8 +196,33 @@ const sidebars = { items: [ "dev_docs/getting_started/quickstart", "dev_docs/getting_started/sandbox", - "dev_docs/getting_started/noir_contracts", - "dev_docs/getting_started/token_contract_tutorial", + ], + }, + + { + label: "Tutorials", + type: "category", + link: { + type: "doc", + id: "dev_docs/tutorials/main", + }, + items: [ + "dev_docs/tutorials/writing_token_contract", + { + label: "Writing a DApp", + type: "category", + link: { + type: "doc", + id: "dev_docs/tutorials/writing_dapp/main", + }, + items: [ + "dev_docs/tutorials/writing_dapp/project_setup", + "dev_docs/tutorials/writing_dapp/rpc_server", + "dev_docs/tutorials/writing_dapp/contract_deployment", + "dev_docs/tutorials/writing_dapp/contract_interaction", + "dev_docs/tutorials/writing_dapp/testing", + ], + }, ], }, @@ -210,6 +235,7 @@ const sidebars = { }, items: [ "dev_docs/contracts/workflow", + "dev_docs/contracts/setup", "dev_docs/contracts/layout", { label: "Syntax", @@ -227,6 +253,9 @@ const sidebars = { "dev_docs/contracts/syntax/globals", ], }, + "dev_docs/contracts/compiling", + "dev_docs/contracts/deploying", + "dev_docs/contracts/artifacts", { label: "Portals", type: "category", @@ -241,9 +270,6 @@ const sidebars = { "dev_docs/contracts/portals/outbox", ], }, - "dev_docs/contracts/compiling", - "dev_docs/contracts/deploying", - "dev_docs/contracts/artifacts", // { // label: "Resources", // type: "category", @@ -283,58 +309,7 @@ const sidebars = { ], }, - { - label: "Sandbox", - type: "category", - link: { - type: "doc", - id: "dev_docs/sandbox/main", - }, - items: ["dev_docs/sandbox/common_errors"], - }, - - { - label: "CLI", - type: "category", - link: { - type: "doc", - id: "dev_docs/cli/main", - }, - items: ["dev_docs/cli/cli"], - }, - { - label: "DApp Development", - type: "category", - items: [ - // { - // label: "API", - // type: "category", - // link: { - // type: "doc", - // id: "dev_docs/dapps/api/main", - // }, - // items: [ - // "dev_docs/dapps/api/aztec_rpc", - // "dev_docs/dapps/api/contract_interaction", - // ], - // }, - { - label: "Tutorials", - type: "category", - link: { - type: "doc", - id: "dev_docs/dapps/tutorials/main", - }, - items: [ - "dev_docs/dapps/tutorials/project_setup", - "dev_docs/dapps/tutorials/rpc_server", - "dev_docs/dapps/tutorials/contract_deployment", - "dev_docs/dapps/tutorials/contract_interaction", - "dev_docs/dapps/tutorials/testing", - ], - }, - ], - }, + "dev_docs/cli/main", { label: "Testing", @@ -356,6 +331,7 @@ const sidebars = { items: [ "dev_docs/wallets/architecture", "dev_docs/wallets/writing_an_account_contract", + "dev_docs/wallets/creating_schnorr_accounts", ], }, @@ -364,6 +340,7 @@ const sidebars = { type: "category", items: [], },*/ + "dev_docs/sandbox_errors/main", "dev_docs/privacy/main", "dev_docs/limitations/main", diff --git a/yarn-project/end-to-end/src/e2e_sandbox_example.test.ts b/yarn-project/end-to-end/src/e2e_sandbox_example.test.ts index eddee6de9d6..0cf0115d8b8 100644 --- a/yarn-project/end-to-end/src/e2e_sandbox_example.test.ts +++ b/yarn-project/end-to-end/src/e2e_sandbox_example.test.ts @@ -6,6 +6,7 @@ import { createAztecRpcClient, createDebugLogger, getSchnorrAccount, + getSandboxAccountsWallets, waitForSandbox, } from '@aztec/aztec.js'; import { GrumpkinScalar } from '@aztec/circuits.js'; @@ -34,54 +35,19 @@ describe('e2e_sandbox_example', () => { expect(typeof nodeInfo.chainId).toBe('number'); expect(typeof nodeInfo.rollupAddress).toBe('object'); - // docs:start:Accounts - ////////////// CREATE SOME ACCOUNTS WITH SCHNORR SIGNERS ////////////// - // Creates new accounts using an account contract that verifies schnorr signatures - // Returns once the deployment transactions have settled - const createSchnorrAccounts = async (numAccounts: number, aztecRpc: AztecRPC) => { - const accountManagers = Array(numAccounts) - .fill(0) - .map(() => - getSchnorrAccount( - aztecRpc, - GrumpkinScalar.random(), // encryption private key - GrumpkinScalar.random(), // signing private key - ), - ); - return await Promise.all( - accountManagers.map(async x => { - await x.waitDeploy({}); - return x; - }), - ); - }; - - // Create 2 accounts and wallets to go with each - logger(`Creating accounts using schnorr signers...`); - const accounts = await createSchnorrAccounts(2, aztecRpc); - - ////////////// VERIFY THE ACCOUNTS WERE CREATED SUCCESSFULLY ////////////// - - const [alice, bob] = (await Promise.all(accounts.map(x => x.getCompleteAddress()))).map(x => x.address); - - // Verify that the accounts were deployed - const registeredAccounts = (await aztecRpc.getRegisteredAccounts()).map(x => x.address); - for (const [account, name] of [ - [alice, 'Alice'], - [bob, 'Bob'], - ] as const) { - if (registeredAccounts.find(acc => acc.equals(account))) { - logger(`Created ${name}'s account at ${account.toShortString()}`); - continue; - } - logger(`Failed to create account for ${name}!`); - } - // docs:end:Accounts - - // check that alice and bob are in registeredAccounts - expect(registeredAccounts.find(acc => acc.equals(alice))).toBeTruthy(); - expect(registeredAccounts.find(acc => acc.equals(bob))).toBeTruthy(); - + // For the sandbox quickstart we just want to show them preloaded accounts (since it is a quickstart) + // We show creation of accounts in a later test + + // docs:start:load_accounts + ////////////// LOAD SOME ACCOUNTS FROM THE SANDBOX ////////////// + // The sandbox comes with a set of created accounts. Load them + const accounts = await getSandboxAccountsWallets(aztecRpc); + const alice = accounts[0].getAddress(); + const bob = accounts[1].getAddress(); + logger(`Loaded alice's account at ${alice.toShortString()}`); + logger(`Loaded bob's account at ${bob.toShortString()}`); + // docs:end:load_accounts + // docs:start:Deployment ////////////// DEPLOY OUR TOKEN CONTRACT ////////////// @@ -92,7 +58,7 @@ describe('e2e_sandbox_example', () => { const contract = await TokenContract.deploy(aztecRpc).send().deployed(); // Create the contract abstraction and link to Alice's wallet for future signing - const tokenContractAlice = await TokenContract.at(contract.address, await accounts[0].getWallet()); + const tokenContractAlice = await TokenContract.at(contract.address, accounts[0]); // Initialize the contract and add Bob as a minter await tokenContractAlice.methods._initialize(alice).send().wait(); @@ -116,7 +82,7 @@ describe('e2e_sandbox_example', () => { // Bob wants to mint some funds, the contract is already deployed, create an abstraction and link it his wallet // Since we already have a token link, we can simply create a new instance of the contract linked to Bob's wallet - const tokenContractBob = tokenContractAlice.withWallet(await accounts[1].getWallet()); + const tokenContractBob = tokenContractAlice.withWallet(accounts[1]); let aliceBalance = await tokenContractAlice.methods.balance_of_private(alice).view(); logger(`Alice's balance ${aliceBalance}`); @@ -168,4 +134,60 @@ describe('e2e_sandbox_example', () => { expect(aliceBalance).toBe(initialSupply - transferQuantity); expect(bobBalance).toBe(transferQuantity + mintQuantity); }, 120_000); + + it('can create accounts on the sandbox', async () => { + const logger = createDebugLogger('token'); + // We create AztecRPC client connected to the sandbox URL + const aztecRpc = createAztecRpcClient(SANDBOX_URL); + // Wait for sandbox to be ready + await waitForSandbox(aztecRpc); + + // docs:start:create_accounts + ////////////// CREATE SOME ACCOUNTS WITH SCHNORR SIGNERS ////////////// + // Creates new accounts using an account contract that verifies schnorr signatures + // Returns once the deployment transactions have settled + const createSchnorrAccounts = async (numAccounts: number, aztecRpc: AztecRPC) => { + const accountManagers = Array(numAccounts) + .fill(0) + .map(() => + getSchnorrAccount( + aztecRpc, + GrumpkinScalar.random(), // encryption private key + GrumpkinScalar.random(), // signing private key + ), + ); + return await Promise.all( + accountManagers.map(async x => { + await x.waitDeploy({}); + return x; + }), + ); + }; + + // Create 2 accounts and wallets to go with each + logger(`Creating accounts using schnorr signers...`); + const accounts = await createSchnorrAccounts(2, aztecRpc); + + ////////////// VERIFY THE ACCOUNTS WERE CREATED SUCCESSFULLY ////////////// + + const [alice, bob] = (await Promise.all(accounts.map(x => x.getCompleteAddress()))).map(x => x.address); + + // Verify that the accounts were deployed + const registeredAccounts = (await aztecRpc.getRegisteredAccounts()).map(x => x.address); + for (const [account, name] of [ + [alice, 'Alice'], + [bob, 'Bob'], + ] as const) { + if (registeredAccounts.find(acc => acc.equals(account))) { + logger(`Created ${name}'s account at ${account.toShortString()}`); + continue; + } + logger(`Failed to create account for ${name}!`); + } + // docs:end:create_accounts + + // check that alice and bob are in registeredAccounts + expect(registeredAccounts.find(acc => acc.equals(alice))).toBeTruthy(); + expect(registeredAccounts.find(acc => acc.equals(bob))).toBeTruthy(); + }); }); diff --git a/yarn-project/noir-contracts/README.md b/yarn-project/noir-contracts/README.md index 0b2fb8e44c4..2ad77cb638f 100644 --- a/yarn-project/noir-contracts/README.md +++ b/yarn-project/noir-contracts/README.md @@ -119,7 +119,7 @@ It has prebuilt binaries and is super easy to install using `noirup` 1. Go to `src/contracts` folder. 2. Create a new package whose name has to end with **\_contract**. E.g.: ``` - nargo new example_contract + nargo new --contract example_contract ``` 3. Add the aztec dependency to `nargo.toml`: