From 1a1b477d9885fd75a833f7b4c888bf94e02ad872 Mon Sep 17 00:00:00 2001 From: josh crites Date: Tue, 9 Jan 2024 04:33:17 -0500 Subject: [PATCH] chore(docs): Update install script (#3847) Updates the docker install script to get the sandbox, cli and nargo. ~~just verify that the LSP works with aztec-nargo. suggestions to install nargo have been removed.~~ EDIT: I added the recommendation to install nargo back in for the LSP. Closes: #3846 # Checklist: Remove the checklist to signal you've completed it. Enable auto-merge if the PR is ready to merge. - [ ] If the pull request requires a cryptography review (e.g. cryptographic algorithm implementations) I have added the 'crypto' tag. - [x] I have reviewed my diff in github, line by line and removed unexpected formatting changes, testing logs, or commented-out code. - [x] Every change is related to the PR description. - [x] I have [linked](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) this pull request to relevant issues (if any exist). --- .../concepts/advanced/contract_creation.md | 2 +- docs/docs/dev_docs/cli/blank_box.md | 2 +- docs/docs/dev_docs/cli/cli-commands.md | 1 + docs/docs/dev_docs/cli/main.md | 8 ++- docs/docs/dev_docs/cli/sandbox-reference.md | 42 ++++++++--- docs/docs/dev_docs/contracts/deploying.md | 14 +++- docs/docs/dev_docs/contracts/main.md | 12 ++-- .../contracts/resources/dependencies.md | 14 ++-- docs/docs/dev_docs/contracts/setup.md | 15 ++-- .../aztecnr-getting-started.md | 19 +++-- .../dev_docs/getting_started/quickstart.md | 16 ++++- .../token_portal/withdrawing_to_l1.md | 10 ++- docs/docs/dev_docs/tutorials/uniswap/setup.md | 21 +++--- .../tutorials/uniswap/typescript_glue_code.md | 11 ++- .../writing_dapp/contract_deployment.md | 25 ++++--- .../writing_dapp/contract_interaction.md | 6 +- .../writing_private_voting_contract.md | 69 +++++++++++-------- .../tutorials/writing_token_contract.md | 16 +++-- docs/docs/dev_docs/updating.md | 28 ++++---- docs/docusaurus.config.js | 8 +++ docs/netlify.toml | 19 +++-- 21 files changed, 230 insertions(+), 128 deletions(-) diff --git a/docs/docs/concepts/advanced/contract_creation.md b/docs/docs/concepts/advanced/contract_creation.md index 15156b961b8..3eb3380b6c9 100644 --- a/docs/docs/concepts/advanced/contract_creation.md +++ b/docs/docs/concepts/advanced/contract_creation.md @@ -206,7 +206,7 @@ The `deployedContracts` array has a maximum size `MAX_NUM_DEPLOYED_CONTRACTS`. I Excluding these steps, constructor function call is executed identically to a regular private function. -> Under this design, if a public constructor is desired, one must create a private constructor function that then calls a public function. This could be abstracted away by the Noir++ compiler. +> Under this design, if a public constructor is desired, one must create a private constructor function that then calls a public function. This could be abstracted away by the aztec-nargo compiler. **Q: why can't deployments be part of the public fn callstack?** diff --git a/docs/docs/dev_docs/cli/blank_box.md b/docs/docs/dev_docs/cli/blank_box.md index bbd4258fa78..2f1b586d832 100644 --- a/docs/docs/dev_docs/cli/blank_box.md +++ b/docs/docs/dev_docs/cli/blank_box.md @@ -20,7 +20,7 @@ See the Quickstart page for [requirements](../getting_started/quickstart.md#requ 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 Noir to compile contracts. You can find instructions for installing the latest version of Noir that is compatible with the Sandbox on the [Aztec.nr Contracts](../contracts/main.md#install-noir) page. +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). ## Getting the Box diff --git a/docs/docs/dev_docs/cli/cli-commands.md b/docs/docs/dev_docs/cli/cli-commands.md index 7a7c9e38761..922cc512447 100644 --- a/docs/docs/dev_docs/cli/cli-commands.md +++ b/docs/docs/dev_docs/cli/cli-commands.md @@ -49,6 +49,7 @@ This command does a few things to manage updates: - It looks for `Nargo.toml` at the `--contract` paths specified and updates all `aztec.nr` dependencies to the versions the sandbox expects. - It outputs the changes. +You can specify a version to update to with the `--aztec-version` flag, but it defaults to `latest` so this is typically not necessary. :::info diff --git a/docs/docs/dev_docs/cli/main.md b/docs/docs/dev_docs/cli/main.md index d811c2adb74..a10ff03e281 100644 --- a/docs/docs/dev_docs/cli/main.md +++ b/docs/docs/dev_docs/cli/main.md @@ -32,8 +32,10 @@ These provide a self contained environment which deploys Aztec on a local (empty The current sandbox does not generate or verify proofs, but provides a working end to end developer flow for writing and interacting with Aztec.nr smart contracts. -## Aztec CLI +## Aztec CLI and aztec-nargo -The Aztec CLI is a command-line tool allowing the user to interact directly with the Aztec network and sandbox. +The Aztec CLI is a command-line tool allowing you to interact directly with the Aztec network and sandbox. -It aims to provide all of the functionality required to deploy, compile, and invoke contracts and query system state such as contract data, transactions and emitted logs. +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. diff --git a/docs/docs/dev_docs/cli/sandbox-reference.md b/docs/docs/dev_docs/cli/sandbox-reference.md index bd22da35e4f..97dfc98998a 100644 --- a/docs/docs/dev_docs/cli/sandbox-reference.md +++ b/docs/docs/dev_docs/cli/sandbox-reference.md @@ -11,22 +11,44 @@ You can run the Sandbox using Docker. See the [Quickstart](../getting_started/qu ### With Docker ```bash -/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" +bash -i <(curl -s install.aztec.network) ``` -This will attempt to run the Sandbox on ` localhost:8080`. You can change the port defined in `./.aztec/docker-compose.yml`. Running the command again will overwrite any changes made to the `docker-compose.yml`. +This will install the following: -This command also installs or updates the CLI. If you have previously installed the CLI via a node package manager, you will need to uninstall it and remove it from your project dependencies and install it via Docker. +- **aztec** - launches various infrastructure subsystems (sequencer, prover, pxe, etc). +- **aztec-cli** - a command line tool for interfacing and experimenting with infrastructure. +- **aztec-nargo** - aztec's build of nargo, the noir compiler toolchain. +- **aztec-sandbox** - a wrapper around docker-compose that launches services needed for sandbox testing. +- **aztec-up** - a tool to upgrade the aztec toolchain to the latest, or specific versions. + +Once these have been installed, to start the sandbox, run: + +```bash +aztec-sandbox +``` + +This will attempt to run the Sandbox with the PXE listening on ` localhost:8080`. You can change the port defined in `./.aztec/docker-compose.yml` or by setting the `PXE_PORT` environment variable. Running the install command again will overwrite any changes made to the `docker-compose.yml`. + +See the full list of configurable environment variables [here](#environment-variables). + +If you have previously installed the CLI via a node package manager, you will need to uninstall it and remove it from your project dependencies and install it via Docker. To install a specific version of the sandbox, you can set the environment variable `SANDBOX_VERSION` ```bash -SANDBOX_VERSION= /bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" +VERSION= bash -i <(curl -s install.aztec.network) ``` ## Running -The installation command will run the sandbox, and once installed you can run like so: +Once the installed, you can run the sandbox with: + +```bash +aztec-sandbox +``` + +Alternatively, you can run like so: ```bash cd ~/.aztec && docker-compose up @@ -37,12 +59,10 @@ cd ~/.aztec && docker-compose up If you wish to run components of the Aztec network stack separately, you can still use the Sandbox by including a `MODE` variable. The values for `MODE` can be: -``` - sandbox (default) - node - pxe - p2p-bootstrap -``` ## Environment Variables @@ -152,21 +172,25 @@ We have shipped a number of example contracts in the `@aztec/noir-contracts` [np BenchmarkingContractArtifact CardGameContractArtifact ChildContractArtifact +CounterContractArtifact DocsExampleContractArtifact EasyPrivateTokenContractArtifact +EasyPrivateVotingContractArtifact EcdsaAccountContractArtifact EscrowContractArtifact ImportTestContractArtifact +InclusionProofsContractArtifact LendingContractArtifact ParentContractArtifact PendingCommitmentsContractArtifact -PokeableTokenContractArtifact PriceFeedContractArtifact SchnorrAccountContractArtifact SchnorrHardcodedAccountContractArtifact SchnorrSingleKeyAccountContractArtifact +SlowTreeContractArtifact StatefulTestContractArtifact TestContractArtifact +TokenBlacklistContractArtifact TokenBridgeContractArtifact TokenContractArtifact UniswapContractArtifact @@ -180,4 +204,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](./blank_box.md). diff --git a/docs/docs/dev_docs/contracts/deploying.md b/docs/docs/dev_docs/contracts/deploying.md index b3b25d27773..7e1f9a6d012 100644 --- a/docs/docs/dev_docs/contracts/deploying.md +++ b/docs/docs/dev_docs/contracts/deploying.md @@ -4,7 +4,7 @@ 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) +- `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) @@ -27,11 +27,19 @@ aztec-cli deploy /path/to/contract/artifact.json Pre-requisite - Compile the contract and generate a type-safe typescript class for it. +Compile the contract: + +```bash +aztec-nargo compile +``` + +Generate the ABI and typescript class: + ```bash -aztec-cli compile /path/to/contract -o target/ -ts target/ +aztec-cli codegen ./aztec-nargo/output/target/path -o src/artifacts --ts ``` -This would create a typescript file like `Example.ts` in the path specified. More details in the [compiling page](./compiling.md) +This would create a typescript file like `Example.ts` in `./src/artifacts`. Read more on the [compiling page](./compiling.md). Now you can import it to easily deploy and interact with the contract. diff --git a/docs/docs/dev_docs/contracts/main.md b/docs/docs/dev_docs/contracts/main.md index 0fa6e8f5029..00b11485ce8 100644 --- a/docs/docs/dev_docs/contracts/main.md +++ b/docs/docs/dev_docs/contracts/main.md @@ -18,19 +18,17 @@ An **Aztec smart contract** is a smart contract with **private** state variables # Getting started -## Install Noir +## Install aztec-nargo -To write an Aztec.nr contract, you need to write Noir, [aztec-cli](../cli/cli-commands) comes with a built-in compiler for Noir contracts. +To write an Aztec.nr contract, you need to write Noir, `aztec-nargo` comes with a built-in compiler for Aztec contracts written in Noir. See install instructions [here](../cli/sandbox-reference.md). :::info -For those coming from vanilla Noir, the version used for aztec.nr is tracked separately to nargo for vanilla noir, so be sure to use the nargo version shown above +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. ::: ## Install `nargo` (recommended) -The CLI comes with the Noir compiler, so installing `nargo` is not required, however it is recommended as it provides a better developer experience for writing contracts. You will need nargo installed to take advantage of the [Noir Language Server](https://noir-lang.org/nargo/language_server), which provides syntax highlighting and formatting for your Aztec contracts. - -You will also need `nargo` if you want to run unit tests in Noir. +`aztec-nargo` comes with the Noir compiler, so installing `nargo` is not required, however it is recommended as it provides a better developer experience for writing contracts. You will need nargo installed to take advantage of the [Noir Language Server](https://noir-lang.org/nargo/language_server), which provides syntax highlighting and formatting for your Aztec contracts. You can install `nargo` with the following commands: @@ -38,7 +36,7 @@ You can install `nargo` with the following commands: ## 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). +There are a number of tools to make writing Aztec.nr contracts in Noir more pleasant. See [here](https://github.com/noir-lang/awesome-noir#get-coding). ## Tutorials diff --git a/docs/docs/dev_docs/contracts/resources/dependencies.md b/docs/docs/dev_docs/contracts/resources/dependencies.md index 35f60ee3c67..36ed74a3bf0 100644 --- a/docs/docs/dev_docs/contracts/resources/dependencies.md +++ b/docs/docs/dev_docs/contracts/resources/dependencies.md @@ -26,12 +26,6 @@ This allows you to use authentication witnesses in your contract. Find more abou address_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/address-note" } ``` -## Assets - -```toml -assets = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/assets" } -``` - This is a library for utilizing notes that hold addresses. Find it on [GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/aztec-nr/address-note/src). ## Easy private state @@ -42,6 +36,14 @@ easy_private_state = { git="https://github.com/AztecProtocol/aztec-packages/", t This is an abstraction library for using private variables like [`EasyPrivateUint`](https://github.com/AztecProtocol/aztec-packages/blob/6c20b45993ee9cbd319ab8351e2722e0c912f427/yarn-project/aztec-nr/easy-private-state/src/easy_private_state.nr#L17). +## Protocol Types + +```toml +protocol_types = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/noir-protocol-circuits/src/crates/types"} +``` + +This library contains types that are used in the Aztec protocol. Find it on [GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-protocol-circuits/src/crates/types/src). + ## Safe math ```toml diff --git a/docs/docs/dev_docs/contracts/setup.md b/docs/docs/dev_docs/contracts/setup.md index 8d6e561aa0f..ed97c3ae705 100644 --- a/docs/docs/dev_docs/contracts/setup.md +++ b/docs/docs/dev_docs/contracts/setup.md @@ -14,19 +14,13 @@ 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/quickstart.md). -## Set up for aztec.nr contracts +## Setup for Aztec.nr contracts 1. Inside the yarn project you created from the [Sandbox page](../getting_started/quickstart.md), create a sub-folder where the contracts will reside. @@ -36,14 +30,14 @@ 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 +1. Next, create an Aztec contract project using aztec-nargo by running the following in the terminal from the `contracts` folder ```bash cd contracts -nargo new --contract example_contract +aztec-nargo new --contract example_contract ``` -This creates `example_contract` directory within contracts which is a noir project with: +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`. @@ -77,6 +71,7 @@ type = "contract" [dependencies] # Framework import aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" } +protocol_types = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/noir-protocol-circuits/src/crates/types"} # Utility dependencies value_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/value-note"} diff --git a/docs/docs/dev_docs/getting_started/aztecnr-getting-started.md b/docs/docs/dev_docs/getting_started/aztecnr-getting-started.md index 21fa6175cfb..abc144a5f62 100644 --- a/docs/docs/dev_docs/getting_started/aztecnr-getting-started.md +++ b/docs/docs/dev_docs/getting_started/aztecnr-getting-started.md @@ -50,9 +50,10 @@ authors = [""] compiler_version = ">=0.18.0" [dependencies] -aztec = { git="https://github.com/AztecProtocol/aztec-packages", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" } -value_note = { git="https://github.com/AztecProtocol/aztec-packages", tag="#include_aztec_version", directory="yarn-project/aztec-nr/value-note"} -easy_private_state = { git="https://github.com/AztecProtocol/aztec-packages", tag="#include_aztec_version", directory="yarn-project/aztec-nr/easy-private-state"} +aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" } +value_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/value-note"} +easy_private_state = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/easy-private-state"} +protocol_types = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/noir-protocol-circuits/src/crates/types"} ``` ## Define the functions @@ -148,14 +149,20 @@ Now we've written a simple Aztec.nr smart contract, it's time to ensure everythi ### Compile the smart contract -In the root of the `nargo` project, run this: +In `./contracts/counter/` directory, run this: ```bash -aztec-cli compile . +aztec-nargo compile ``` This will compile the smart contract and create a `target` folder with a `.json` artifact inside. +After compiling, you need to generate the ABI and typescript class. In the same directory, run this: + +```bash +aztec-cli codegen target -o src/artifacts --ts +``` + ### Deploy You can use the previously generated artifact to deploy the smart contract. Our constructor takes two arguments - `initial_counter` and `owner` so let's make sure to pass those in. @@ -192,7 +199,7 @@ 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: ```bash -aztec-cli deploy target/Counter.json --args 100 0x25048e8c1b7dea68053d597ac2d920637c99523651edfb123d0632da785970d0 +aztec-cli deploy contracts/counter/src/artifacts/Counter.json --args 100 0x2a0f32c34c5b948a7f9766f0c1aad70a86c0ee649f56208e936be4324d49b0b9 ``` You can also test the functions by applying what you learned in the [quickstart](./quickstart.md). diff --git a/docs/docs/dev_docs/getting_started/quickstart.md b/docs/docs/dev_docs/getting_started/quickstart.md index 8f210f21de8..b5120e84489 100644 --- a/docs/docs/dev_docs/getting_started/quickstart.md +++ b/docs/docs/dev_docs/getting_started/quickstart.md @@ -36,7 +36,21 @@ You can run the Sandbox using Docker. To install the latest Sandbox version, run: ```bash -/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" +bash -i <(curl -s install.aztec.network) +``` + +This will install the following: + +- **aztec** - launches various infrastructure subsystems (sequencer, prover, pxe, etc). +- **aztec-cli** - a command line tool for interfacing and experimenting with infrastructure. +- **aztec-nargo** - aztec's build of nargo, the noir compiler toolchain. +- **aztec-sandbox** - a wrapper around docker-compose that launches services needed for sandbox testing. +- **aztec-up** - a tool to upgrade the aztec toolchain to the latest, or specific versions. + +Once these have been installed, to start the sandbox, run: + +```bash +aztec-sandbox ``` This will attempt to run the Sandbox on ` localhost:8080`, so you will have to make sure nothing else is running on that port or change the port defined in `./.aztec/docker-compose.yml`. Running the command again will overwrite any changes made to the `docker-compose.yml`. diff --git a/docs/docs/dev_docs/tutorials/token_portal/withdrawing_to_l1.md b/docs/docs/dev_docs/tutorials/token_portal/withdrawing_to_l1.md index d176e99a919..fd2a2ea1721 100644 --- a/docs/docs/dev_docs/tutorials/token_portal/withdrawing_to_l1.md +++ b/docs/docs/dev_docs/tutorials/token_portal/withdrawing_to_l1.md @@ -75,8 +75,14 @@ npx hardhat compile And compile your Aztec.nr contracts like this: ```bash -cd aztec-contracts -aztec-cli compile --typescript ../../src/test/fixtures token_bridge +cd aztec-contracts/token-bridge +aztec-nargo compile +``` + +And generate the TypeScript interface for the contract and add it to the test dir: + +```bash +aztec-cli codegen target -o ../../../src/test/fixtures --ts ``` This will create a TS interface in our `src/test` folder! diff --git a/docs/docs/dev_docs/tutorials/uniswap/setup.md b/docs/docs/dev_docs/tutorials/uniswap/setup.md index 6083c9bf9fa..13e7a1fae66 100644 --- a/docs/docs/dev_docs/tutorials/uniswap/setup.md +++ b/docs/docs/dev_docs/tutorials/uniswap/setup.md @@ -22,12 +22,12 @@ Inside `ISwapRouter.sol` paste this: This is an interface for the Uniswap V3 Router, providing token swapping functionality. The contract defines methods for token swaps, both between two tokens or via a multi-hop path. Our portal will interact with the Uniswap V3 Router via this interface to perform token swaps on L1. We’ll see more about this in the next step. -# Create another Noir project +## Create another Aztec project -In `aztec-contracts` create a new Noir project. +In `aztec-contracts` create a new Aztec contract project. ```bash -cd aztec-contracts && nargo new --contract uniswap +cd aztec-contracts && aztec-nargo new --contract uniswap ``` Now your `aztec-contracts` will look like this: @@ -49,12 +49,11 @@ Inside `uniswap/Nargo.toml` paste this in `[dependencies]`: ```json [dependencies] aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" } -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"} authwit = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/authwit"} +protocol_types = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/noir-protocol-circuits/src/crates/types"} ``` -# L2 contracts +## L2 contracts The `main.nr` will utilize a few helper functions that are outside the scope of this tutorial. Inside `uniswap/src` create two new files: @@ -71,12 +70,18 @@ This creates interfaces for the `Token` contract and `TokenBridge` contract - `Token` is a reference implementation for a token on Aztec. Here we just need two methods - [`transfer_public`](../writing_token_contract.md#transfer_public) and [`unshield()`](../writing_token_contract.md#unshield). - The `TokenBridge` facilitates interactions with our [bridge contract](../token_portal/main.md). Here we just need its [`exit_to_l1_public`](../token_portal/withdrawing_to_l1.md) -# Run Aztec sandbox +## Run Aztec sandbox You will need a running sandbox. ```bash -/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" +bash -i <(curl -s install.aztec.network) +``` + +Then + +```bash +aztec-sandbox ``` In the next step, we will write the L1 Uniswap Portal. diff --git a/docs/docs/dev_docs/tutorials/uniswap/typescript_glue_code.md b/docs/docs/dev_docs/tutorials/uniswap/typescript_glue_code.md index 6260a26a6d8..67b46b1b952 100644 --- a/docs/docs/dev_docs/tutorials/uniswap/typescript_glue_code.md +++ b/docs/docs/dev_docs/tutorials/uniswap/typescript_glue_code.md @@ -27,11 +27,16 @@ cd l1-contracts npx hardhat compile ``` -and the Aztec.nr contracts: +and the each of the Aztec.nr contracts by going into each folder and running: ```bash -cd aztec-contracts -aztec-cli compile --typescript ../../src/test/fixtures uniswap +aztec-nargo compile +``` + +And then generate the ABIs and typescript interface: + +```bash +aztec-cli codegen ./target/ -o ../../../src/test/fixtures uniswap --ts ``` This will create a TS interface in our `src/test` folder that will help us write our test. diff --git a/docs/docs/dev_docs/tutorials/writing_dapp/contract_deployment.md b/docs/docs/dev_docs/tutorials/writing_dapp/contract_deployment.md index ae8edd0e575..94ebf5ad032 100644 --- a/docs/docs/dev_docs/tutorials/writing_dapp/contract_deployment.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/contract_deployment.md @@ -1,18 +1,18 @@ # Contract Deployment -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. +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](../../contracts/setup.md) to install `nargo` if you haven't done so already. ::: -## Initialize Noir project +## Initialize Aztec project Create a new `contracts` folder, and from there, initialize a new project called `token`: ```sh mkdir contracts && cd contracts -nargo new --contract token +aztec-nargo new --contract token ``` Then, open the `contracts/token/Nargo.toml` configuration file, and add the `aztec.nr` and `value_note` libraries as dependencies: @@ -22,6 +22,7 @@ Then, open the `contracts/token/Nargo.toml` configuration file, and add the `azt aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" } authwit = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/authwit"} safe_math = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/aztec-nr/safe-math"} +protocol_types = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/noir-protocol-circuits/src/crates/types"} ``` Last, copy-paste the code from the `Token` contract into `contracts/token/main.nr`: @@ -34,19 +35,21 @@ The `Token` contract also requires some helper files. You can view the files [he ## Compile your contract -We'll now use the [Aztec CLI](../../cli/main.md) to [compile](../../contracts/compiling.md) our project. If you haven't installed the 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.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). -Now run the following from your project root: +Now run the following from your contract folder (containing Nargo.toml): ```sh -aztec-cli compile contracts/token +aztec-nargo compile ``` -:::info -If you are using Typescript, consider including the `--typescript` option to [generate type-safe wrappers](../../contracts/compiling.md#typescript-interfaces) for your contracts. -::: +Once you have compiled your contracts, you need to generate the ABIs: + +```sh +aztec-cli codegen ./target/path -o src/artifacts --ts +``` -This should have created an artifact `contracts/token/target/Token.json` with the interface and bytecode for your contract. +This should have created an artifact `contracts/token/src/artifacts/Token.json` with the interface and bytecode for your contract. ## Deploy your contracts @@ -59,7 +62,7 @@ Create a new file `src/deploy.mjs`: import { writeFileSync } from 'fs'; import { Contract, ContractDeployer, createPXEClient, getSandboxAccountsWallets } from '@aztec/aztec.js'; import { getSandboxAccountsWallets } from '@aztec/accounts/testing'; -import TokenContractArtifact from "../contracts/token/target/Token.json" assert { type: "json" }; +import TokenContractArtifact from "../contracts/token/src/artifacts/Token.json" assert { type: "json" }; #include_code dapp-deploy yarn-project/end-to-end/src/sample-dapp/deploy.mjs raw diff --git a/docs/docs/dev_docs/tutorials/writing_dapp/contract_interaction.md b/docs/docs/dev_docs/tutorials/writing_dapp/contract_interaction.md index e2f9ea026ca..05510f43778 100644 --- a/docs/docs/dev_docs/tutorials/writing_dapp/contract_interaction.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/contract_interaction.md @@ -18,7 +18,7 @@ To do this, let's first initialize a new `Contract` instance using `aztec.js` th // src/contracts.mjs import { Contract } from "@aztec/aztec.js"; import { readFileSync } from "fs"; -import TokenContractArtifact from "../contracts/token/target/Token.json" assert { type: "json" }; +import TokenContractArtifact from "../contracts/token/src/artifacts/Token.json" assert { type: "json" }; ``` And then add the following code for initializing the `Contract` instances: @@ -56,10 +56,10 @@ const wallet = await getSchnorrAccount( ).getWallet(); ``` -For ease of use, `accounts` also ships with a helper `getSandboxAccountsWallets` method that returns a wallet for each of the pre-initialized accounts in the Sandbox, so you can send transactions as any of them. +For ease of use, `accounts` also ships with a helper `getSandboxAccountsWallets` method that returns a wallet for each of the pre-initialized accounts in the Sandbox, so you can send transactions as any of them. ```js -import { getSandboxAccountsWallets } from '@aztec/accounts/testing'; +import { getSandboxAccountsWallets } from "@aztec/accounts/testing"; ``` We'll use one of these wallets to initialize the `Contract` instance that represents our private token contract, so every transaction sent through it will be sent through that wallet. diff --git a/docs/docs/dev_docs/tutorials/writing_private_voting_contract.md b/docs/docs/dev_docs/tutorials/writing_private_voting_contract.md index 8468927e715..e28815fc6bd 100644 --- a/docs/docs/dev_docs/tutorials/writing_private_voting_contract.md +++ b/docs/docs/dev_docs/tutorials/writing_private_voting_contract.md @@ -8,23 +8,23 @@ We will build this: -* The contract will be initialized with an admin, stored publicly -* A voter can vote privately, which will call a public function and update the votes publically -* The admin can end the voting period, which is a public boolean +- The contract will be initialized with an admin, stored publicly +- A voter can vote privately, which will call a public function and update the votes publicly +- The admin can end the voting period, which is a public boolean -To keep things simple, we won't create ballots or allow for delegate voting. +To keep things simple, we won't create ballots or allow for delegate voting. ## Prerequisites -- You have followed the [quickstart](../getting_started/quickstart.md) +- You have followed the [quickstart](../getting_started/quickstart.md) to install `aztec-nargo`, `aztec-cli` and `aztec-sandbox`. - Running Aztec Sandbox ## Set up a project -First, [create a new contract project with `nargo`](../getting_started/aztecnr-getting-started.md). +First, create a new contract project with `aztec-nargo`. ```bash -nargo new --contract private_voting +aztec-nargo new --contract private_voting ``` Your file structure should look something like this: @@ -50,6 +50,7 @@ compiler_version = ">=0.18.0" [dependencies] aztec = { git="https://github.com/AztecProtocol/aztec-packages", tag="#include_aztec_version", directory="yarn-project/aztec-nr/aztec" } +protocol_types = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="yarn-project/noir-protocol-circuits/src/crates/types"} ``` ## Initiate the contract and define imports @@ -61,6 +62,7 @@ contract Voting { } ``` + This defines a contract called `Voter`. Everything will sit inside this block. Inside this, paste these imports: @@ -69,13 +71,13 @@ Inside this, paste these imports: We are using various utils within the Aztec library: -* `context` - exposes things such as the contract address, msg_sender, etc -* `oracle::get_secret_key` - get your secret key to help us create a randomized nullifier -* `FunctionSelector::from_signature` - compute a function selector from signature so we can call functions from other functions -* `state_vars::{ map::Map, public_state::PublicState, }` - we will use a Map to store the votes (key = voteId, value = number of votes), and PublicState to hold our public values that we mentioned earlier -* `types::type_serialization::{..}` - various serialization methods for defining how to use these types -* `types::address::{AztecAddress},` - our admin will be held as an address -* `constants::EMPTY_NULLIFIED_COMMITMENT,` - this will come in useful when creating our nullifier +- `context` - exposes things such as the contract address, msg_sender, etc +- `oracle::get_secret_key` - get your secret key to help us create a randomized nullifier +- `FunctionSelector::from_signature` - compute a function selector from signature so we can call functions from other functions +- `state_vars::{ map::Map, public_state::PublicState, }` - we will use a Map to store the votes (key = voteId, value = number of votes), and PublicState to hold our public values that we mentioned earlier +- `types::type_serialization::{..}` - various serialization methods for defining how to use these types +- `types::address::{AztecAddress},` - our admin will be held as an address +- `constants::EMPTY_NULLIFIED_COMMITMENT,` - this will come in useful when creating our nullifier ## Set up storage @@ -89,6 +91,7 @@ Define the storage struct like so: #include_code storage_struct yarn-project/noir-contracts/contracts/easy_private_voting_contract/src/main.nr rust In this contract, we will store three vars: + 1. admin, as an Aztec address held in public state 2. tally, as a map with key as the persona and value as the number (in Field) held in public state 3. voteEnded, as a boolean held in public state @@ -97,7 +100,7 @@ Under the struct, define the impl block like this: #include_code storage_impl yarn-project/noir-contracts/contracts/easy_private_voting_contract/src/main.nr rust -The `impl` block must define one function `init` that explains how to access and manipulate our variables. We pass context, a storage slot, and serialization methods we imported earlier. +The `impl` block must define one function `init` that explains how to access and manipulate our variables. We pass context, a storage slot, and serialization methods we imported earlier. This `init` function will be called every time we access `storage` in our functions. @@ -112,6 +115,7 @@ Therefore our constructor must call a public function by using `context.call_pub #include_code constructor yarn-project/noir-contracts/contracts/easy_private_voting_contract/src/main.nr rust `context.call_public_function()` takes three arguments: + 1. The contract address whose method we want to call 2. The selector of the function to call (we can use `FunctionSelector::from_signature(...)` for this) 3. The arguments of the function (we pass the `admin`) @@ -127,6 +131,7 @@ This function is set as `internal` so that it can only be called from within the ## Casting a vote privately For the sake of simplicity, we will have three requirements: + 1. Everyone with an Aztec account gets a vote 2. They can only vote once in this contract 3. Who they are is private, but their actual vote is not @@ -151,7 +156,7 @@ The first thing we do here is assert that the vote has not ended. `assert()` takes two arguments: the assertion, in this case that `storage.voteEnded` is not false, and the error thrown if the assertion fails. -The code after the assertion will only run if the assertion is true. In this snippet, we read the current vote tally at the voteId, add 1 to it, and write this new number to the voteId. The `Field` element allows us to use `+` to add to an integer. +The code after the assertion will only run if the assertion is true. In this snippet, we read the current vote tally at the voteId, add 1 to it, and write this new number to the voteId. The `Field` element allows us to use `+` to add to an integer. ## Getting the number of votes @@ -163,7 +168,7 @@ We set it as `unconstrained` and do not annotate it because it is only reading f ## Allowing an admin to end a voting period -To ensure that only an admin can end a voting period, we can use another `assert()` statement. +To ensure that only an admin can end a voting period, we can use another `assert()` statement. Paste this function in your contract: @@ -183,20 +188,24 @@ We can simply return `[0,0,0,0]` because we are not creating any notes in our co ## Compiling and deploying -The easiest way to compile and deploy a contract is by using the [Aztec CLI](../cli/cli-commands.md). +The easiest way to compile the contract is with `aztec-nargo`. Run the following command in the directory with your Nargo.toml file: + +```bash +aztec-nargo compile +``` -In the `private_voting` directory, run this: +This will create a new directory called `target` and a JSON artifact inside it. To create the Aztec contract ABI and typescript interface, run: ```bash -aztec-cli compile . +aztec-cli codegen target -o src/artifacts --ts ``` -This should create a new directory called `target` and a JSON artifact inside it called `Voting.json`. If you are getting some errors here you might want to check out the [debugging page](../debugging/main.md). +This will create the ABI called `Voting.json` in `src/artifacts`. If you are getting some errors here you might want to check out the [debugging page](../debugging/main.md). -Once it is compiled you can deploy 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.md) it to the sandbox. Ensure your [sandbox is running](../cli/sandbox-reference.md) and run this in the same dir as before: ```bash -aztec-cli deploy ./target/Voting.json --args $ADMIN_ADDRESS +aztec-cli deploy ./src/artifacts/Voting.json --args $ADMIN_ADDRESS ``` The constructor takes an address as an argument to set the admin, so you can use an address that is deployed with the sandbox - check the sandbox terminal or run `aztec-cli get-accounts`. @@ -206,22 +215,22 @@ You should see a success message with the contract address. Now we can start cal Cast a vote like this: ```bash -aztec-cli send cast_vote --contract-artifact ./target/Voting.json --contract-address $CONTRACT_ADDRESS --args 1 --private-key $PRIVATE_KEY +aztec-cli send cast_vote --contract-artifact ./src/artifacts/Voting.json --contract-address $CONTRACT_ADDRESS --args 1 --private-key $PRIVATE_KEY ``` You can get the contract address from the sandbox terminal or the message printed when you deployed the contract. You can also get a private key from the sandbox terminal, or generate one with `aztec-cli generate-private-key`. -This should return a `mined` success message. +This should return a `mined` success message. You can now try running this command again to ensure our nullifier works. Get the number of votes like this: ```bash -aztec-cli call get_vote --contract-artifact ./target/Voting.json --contract-address $CONTRACT_ADDRESS --args 1 +aztec-cli call get_vote --contract-artifact ./src/artifacts/Voting.json --contract-address $CONTRACT_ADDRESS --args 1 ``` -This should return `1n`. +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). @@ -229,6 +238,6 @@ You can follow this pattern to test `end_vote()` and access control of other fun Now you have learned the foundations of Aztec smart contracts, you can start to play around with some more advanced features. Some ideas: -* Add some more features into this contract, like the admin can distribute votes, people can delegate their votes, or voteIds can have more data like names, descriptions, etc -* Create a frontend for this contract using [Aztec.js](../aztecjs/main.md). -* Go to the [next tutorial](writing_token_contract.md) and learn how to write a token contract \ No newline at end of file +- Add some more features into this contract, like the admin can distribute votes, people can delegate their votes, or voteIds can have more data like names, descriptions, etc +- Create a frontend for this contract using [Aztec.js](../aztecjs/main.md). +- Go to the [next tutorial](writing_token_contract.md) and learn how to write a token contract diff --git a/docs/docs/dev_docs/tutorials/writing_token_contract.md b/docs/docs/dev_docs/tutorials/writing_token_contract.md index 925d4fa3f34..345ed20a799 100644 --- a/docs/docs/dev_docs/tutorials/writing_token_contract.md +++ b/docs/docs/dev_docs/tutorials/writing_token_contract.md @@ -18,9 +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-cli` installed in order to compile Aztec.nr contracts. See the [quickstart guide](../getting_started/quickstart.md#cli) for installation instructions. - -When you are running the Sandbox, `aztec-cli`, and compiling contracts with Noir, make sure you are using matching versions--we will be shipping breaking changes so mis-matched versions may not work. +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 should also install the [Noir Language Support extension](https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir) for VS Code. @@ -462,10 +460,18 @@ If you don't yet have any private state variables defined put there a placeholde ## Compiling -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. +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. + +Run the following command in the directory where your `Nargo.toml` file is located: + +```bash +aztec-nargo compile +``` + +Once your contract is compiled, generate the Aztec contract ABI with typescript interface with the following command: ```bash -aztec-cli compile /path/to/token_contracts_folder +aztec-cli codegen target -o src/artifacts --ts ``` ## Next Steps diff --git a/docs/docs/dev_docs/updating.md b/docs/docs/dev_docs/updating.md index 7d21478163c..690f3fe27e2 100644 --- a/docs/docs/dev_docs/updating.md +++ b/docs/docs/dev_docs/updating.md @@ -29,7 +29,7 @@ npm -g uninstall @aztec/aztec-sandbox @aztec/cli 1. Updating the sandbox and CLI: ```shell -/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" +aztec-up latest ``` 2. Updating aztec-nr and individual @aztec dependencies: @@ -41,16 +41,17 @@ cd your/aztec/project aztec-cli update . --contract src/contract1 --contract src/contract2 ``` -The sandbox must be running for the update command to work. +The sandbox must be running for the update command to work. Make sure it is [installed and running](../dev_docs/cli/sandbox-reference.md). 3. Refer [Migration Notes](../misc/migration_notes.md) on any breaking changes that might affect your dapp + --- There are three components whose versions need to be kept compatible: 1. Aztec Sandbox 2. Aztec CLI -3. Noir framework for Aztec contracts `aztec.nr` +3. `Aztec.nr`, the Noir framework for writing Aztec contracts All three are using the same versioning scheme and their versions must match. Docker ensures that the sandbox and CLI are always compatible, but you need to update Aztec.nr manually or using `aztec-cli update`. @@ -66,12 +67,7 @@ aztec-cli update . --contract src/contract1 --contract src/contract2 ### Manual update -Finally we need to update the Noir framework for Aztec contracts. -We need to install a version compatible with our `nargo` and Sandbox. - -To update the framework we will update a tag of the `aztec.nr` dependency in the `Nargo.toml` file to the `SANDBOX_VERSION` from above. -Find all the dependencies pointing to the directory within `aztec.nr` framework and update the corresponding tag. -E.g.: +To update the aztec.nr packages manually, update the tags of the `aztec.nr` dependencies in the `Nargo.toml` file. ```diff [dependencies] @@ -81,17 +77,19 @@ E.g.: +value_note = { git="https://github.com/AztecProtocol/aztec-packages", tag="#include_aztec_version", directory="yarn-project/aztec-nr/value-note" } ``` -Go to the project directory and try compiling it with `aztec-cli` to verify that the update was successful: +Go to the contract directory and try compiling it with `aztec-nargo compile` to verify that the update was successful: ```shell -cd /your/project/root -aztec-cli compile ./ +cd /your/contract/directory +aztec-nargo compile ``` If the dependencies fail to resolve ensure that the tag matches a tag in the [aztec-packages repository](https://github.com/AztecProtocol/aztec-packages/tags). -## Updating `nargo` +## Updating `aztec-nargo` -Nargo is not strictly required, but you may want to use it for the LSP or testing. More info [here](./getting_started/aztecnr-getting-started.md#install-nargo-recommended). +`aztec-nargo` is updated by running: - +```bash +aztec-up latest +``` diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index ed6e068ddb4..3bb61948edd 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -223,6 +223,10 @@ const config = { label: "Developer Quickstart", to: "/dev_docs/getting_started/quickstart", }, + { + label: "Aztec.nr", + to: "https://github.com/AztecProtocol/aztec-nr", + }, ], }, { @@ -253,6 +257,10 @@ const config = { label: "GitHub", href: "https://github.com/AztecProtocol", }, + { + label: "Awesome Aztec", + to: "https://github.com/AztecProtocol/awesome-aztec", + }, { label: "Grants", href: "https://aztec.network/grants", diff --git a/docs/netlify.toml b/docs/netlify.toml index 1a022d8a71b..a26ea50351b 100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@ -140,11 +140,19 @@ [[redirects]] from = "/aztec/how-it-works/private-state" - to = "/concepts/foundation/state_model" + to = "/concepts/foundation/state_model/main" + +[[redirects]] + from = "/concepts/foundation/state_model" + to = "/concepts/foundation/state_model/main" [[redirects]] from = "/aztec/how-it-works/private-public-execution" - to = "/concepts/foundation/communication/public_private_calls" + to = "/concepts/foundation/communication/public_private_calls/main" + +[[redirects]] + from="/concepts/foundation/communication/public_private_calls" + to="/concepts/foundation/communication/public_private_calls/main" [[redirects]] from = "/aztec/how-it-works/l1-l2-messaging" @@ -194,7 +202,10 @@ from = "/dev_docs/contracts/common_errors" to = "dev_docs/debugging/aztecnr-errors" - [[redirects]] from = "/misc/aztec-connect-sunset" - to = "/misc/aztec_connect_sunset" \ No newline at end of file + to = "/misc/aztec_connect_sunset" + +[[redirects]] + from= "zk-money/userguide" + to= "/misc/aztec_connect_sunset" \ No newline at end of file