diff --git a/docs/docs/dev_docs/cli/cli-commands.md b/docs/docs/dev_docs/cli/cli-commands.md index cbf8afff54b..7efa13eef1f 100644 --- a/docs/docs/dev_docs/cli/cli-commands.md +++ b/docs/docs/dev_docs/cli/cli-commands.md @@ -2,48 +2,57 @@ title: CLI Commands --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + Here you will find a reference to the commands available in the Aztec CLI. ## Installation -### NPM - -This command will install the Aztec CLI as a dev dependency in your npm project. +### Docker -```bash -npm install --save-dev @aztec/cli -``` +The CLI will be installed automatically via Docker by running the command to install and start the sandbox, [instructions here](./sandbox-reference.md#with-docker). :::info -You can install the CLI globally, but it is recommended that you install the CLI as a local dependency in your project. This will make it easier to keep the CLI version in sync with the sandbox version. +The `@aztec/aztec-sandbox` and `@aztec/cli` packages published to npm **should not be used**, in favor of Docker. If you've installed the sandbox or the CLI via NPM, **uninstall** them and remove them from your project dependencies and [install via Docker](./sandbox-reference.md#with-docker). -::: + + + + +yarn global remove @aztec/aztec-sandbox @aztec/cli + -### Docker + + -The CLI will be installed automatically via Docker if it is not already found locally, by running the command to install and start the sandbox, [instructions here](./sandbox-reference.md#with-docker). + +npm -g uninstall @aztec/aztec-sandbox @aztec/cli + + + + +::: ## Update The CLI comes with an update command. ```bash -npx @aztec/cli@latest update . --contract src/contract1 --contract src/contract2 +aztec-cli update . --contract src/contract1 --contract src/contract2 ``` This command does a few things to manage updates: -- If you installed the CLI globally via a node package manager, it updates to the specified version. Defaults to latest. - It looks for a `package.json` and updates all `@aztec/` dependencies to the versions the sandbox expects. - 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. -The sandbox must be running for the update command to work unless there the project defines `@aztec/aztec-sandbox` as a dependency, in which case the command will compare against the version listed in `package.json`. :::info -If you installed the CLI via Docker (with the sandbox install Docker command), the `aztec-cli update` command won't work. You can update the CLI it by [running the command again](./sandbox-reference.md#installation-with-docker). +The update command won't update the CLI itself. To update these follow the [updating instructions which point to our curl command](./sandbox-reference.md#with-docker). ::: diff --git a/docs/docs/dev_docs/cli/sandbox-reference.md b/docs/docs/dev_docs/cli/sandbox-reference.md index 171ee587295..71b5c427c55 100644 --- a/docs/docs/dev_docs/cli/sandbox-reference.md +++ b/docs/docs/dev_docs/cli/sandbox-reference.md @@ -6,7 +6,7 @@ Here you will find a reference to everything available within the Sandbox. ## Installation -You can run the Sandbox using either Docker or npm. +You can run the Sandbox using Docker. See the [Quickstart](../getting_started/quickstart.md#install-docker) for instructions on installing Docker. ### With Docker @@ -16,7 +16,7 @@ You can run the Sandbox using either Docker or npm. 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`. -If you don't have the CLI installed via a node package manager, this command will also install or update the CLI. +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. To install a specific version of the sandbox, you can set the environment variable `SANDBOX_VERSION` @@ -24,20 +24,6 @@ To install a specific version of the sandbox, you can set the environment variab SANDBOX_VERSION= /bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" ``` -NOTE: The sandbox version should be the same as your `@aztec/cli` package to ensure compatibility. - -### With npm - -You can download and run the Sandbox package directly if you have nodejs 18 or higher installed. - -You will also need an Ethereum node like Anvil or Hardhat running locally on port 8545. - -```bash -npx @aztec/aztec-sandbox @aztec/cli -``` - -You can read [this tutorial on how to use the npm package](../tutorials/testing.md#running-sandbox-in-the-nodejs-process) - ## Running The installation command will run the sandbox, and once installed you can run like so: diff --git a/docs/docs/dev_docs/contracts/deploying.md b/docs/docs/dev_docs/contracts/deploying.md index 09859bbd66e..2d947914a3d 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` 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) diff --git a/docs/docs/dev_docs/debugging/main.md b/docs/docs/dev_docs/debugging/main.md index 3b343efec0d..b2a0e0de46f 100644 --- a/docs/docs/dev_docs/debugging/main.md +++ b/docs/docs/dev_docs/debugging/main.md @@ -52,9 +52,6 @@ Prepend the command to start the sandbox with `DEBUG=aztec:*` to log everything ```bash # Using the docker-compose.yml setup cd ~./aztec && DEBUG=aztec:* docker-compose up - -# or if you're using the npm package -DEBUG=aztec:* aztec-sandbox ``` Alternatively you can update the `DEBUG` environment variable in docker-compose.yml and start the sandbox normally. diff --git a/docs/docs/dev_docs/getting_started/quickstart.md b/docs/docs/dev_docs/getting_started/quickstart.md index fe8630cfa55..8f210f21de8 100644 --- a/docs/docs/dev_docs/getting_started/quickstart.md +++ b/docs/docs/dev_docs/getting_started/quickstart.md @@ -14,11 +14,24 @@ In this guide, you will ## Prerequisites - Node.js >= v18 (recommend installing with [nvm](https://github.com/nvm-sh/nvm)) -- Docker and Docker Compose (Docker Desktop under WSL2 on windows) + +## Install Docker + +See this page of the Docker docs for instructions on how to install Docker Desktop for your operating system: [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/) + +Once you have Docker installed, make sure it is running by opening the Docker Desktop application. + +### Note on Linux + +If you are running Linux, you will need to set the context (because Docker Desktop runs in a VM by default). See [this page](https://docs.docker.com/desktop/faqs/linuxfaqs/#what-is-the-difference-between-docker-desktop-for-linux-and-docker-engine) for more information. You can do this by running: + +```bash +docker context use default +``` ## Install the Sandbox -You can run the Sandbox using either Docker or npm. In this guide we will use Docker, but you can learn more about alternative installation methods [here](../cli/sandbox-reference.md). +You can run the Sandbox using Docker. To install the latest Sandbox version, run: @@ -30,8 +43,6 @@ This will attempt to run the Sandbox on ` localhost:8080`, so you will have to m This command will also install the CLI if a node package version of the CLI isn't found locally. -Alternatively, you can [run the sandbox as an npm package](../cli/sandbox-reference.md#with-npm). - ## Deploy a contract using the CLI The sandbox is preloaded with multiple accounts. Let's assign them to shell variables. Run the following in your terminal, so we can refer to the accounts as $ALICE and $BOB from now on: diff --git a/docs/docs/dev_docs/tutorials/token_portal/setup.md b/docs/docs/dev_docs/tutorials/token_portal/setup.md index f2a0e01dae1..490bd8802e6 100644 --- a/docs/docs/dev_docs/tutorials/token_portal/setup.md +++ b/docs/docs/dev_docs/tutorials/token_portal/setup.md @@ -43,7 +43,7 @@ Now inside `packages` create a new directory called `aztec-contracts` Inside `aztec-contracts`, create the following file structure: -``` +```tree aztec-contracts └── token_bridge ├── Nargo.toml @@ -68,7 +68,7 @@ safe_math = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#incl We will also be writing some helper functions that should exist elsewhere so we don't overcomplicated our contract. In `src` create two more files - one called `util.nr` and one called `token_interface` - so your dir structure should now look like this: -``` +```tree aztec-contracts └── token_bridge ├── Nargo.toml 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 207af323c97..4bc580b5ffe 100644 --- a/docs/docs/dev_docs/tutorials/writing_dapp/contract_deployment.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/contract_deployment.md @@ -20,7 +20,7 @@ Then, open the `contracts/token/Nargo.toml` configuration file, and add the `azt ```toml [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"} +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"} ``` @@ -28,24 +28,18 @@ Last, copy-paste the code from the `Token` contract into `contracts/token/main.n #include_code token_all yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr rust -The `Token` contract also requires a helper file. Copy it too: +### Helper files -Create `contracts/token/types.nr` and copy-paste the following: - -#include_code token_types_all yarn-project/noir-contracts/src/contracts/token_contract/src/types/transparent_note.nr rust +The `Token` contract also requires some helper files. You can view the files [here](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/yarn-project/noir-contracts/src/contracts/token_contract/src). Copy the `types.nr` and the `types` folder into `contracts/token/src`. ## 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, you can install it locally to your project running: - -```sh -yarn add -D @aztec/cli -``` +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). Now run the following from your project root: ```sh -yarn aztec-cli compile contracts/token +aztec-cli compile contracts/token ``` :::info diff --git a/docs/docs/dev_docs/tutorials/writing_dapp/testing.md b/docs/docs/dev_docs/tutorials/writing_dapp/testing.md index 4c1a5e947b6..594bb81e5d9 100644 --- a/docs/docs/dev_docs/tutorials/writing_dapp/testing.md +++ b/docs/docs/dev_docs/tutorials/writing_dapp/testing.md @@ -14,18 +14,13 @@ Start by installing our test runner, in this case jest: yarn add -D jest ``` -We'll also be running our Sandbox within the test suite, to avoid polluting a global instance, so we'll need to install the Sandbox itself as a dependency as well: - -```sh -yarn add -D @aztec/aztec-sandbox -``` +We'll need to [install and run the Sandbox](../../cli/sandbox-reference.md#installation). ## Test setup Create a new file `src/index.test.mjs` with the imports we'll be using and an empty test suite to begin with: ```js -import { createSandbox } from "@aztec/aztec-sandbox"; import { Contract, createAccount } from "@aztec/aztec.js"; import TokenContractArtifact from "../contracts/token/target/Token.json" assert { type: "json" }; diff --git a/docs/docs/dev_docs/tutorials/writing_token_contract.md b/docs/docs/dev_docs/tutorials/writing_token_contract.md index 27cb44bd8f1..43f6f1e4b3d 100644 --- a/docs/docs/dev_docs/tutorials/writing_token_contract.md +++ b/docs/docs/dev_docs/tutorials/writing_token_contract.md @@ -210,13 +210,17 @@ Just below the contract definition, add the following imports: #include_code imports /yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr rust -We are importing the Option type, note utilities, context (for managing private and public execution contexts), `state_vars` for helping manage state, `compute_selector` for helping with calling public functions from private functions, and `types` for data manipulation. We also import the `authwit` [library](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/aztec-nr/aztec/src/auth.nr) to handle token authorizations from [Account Contracts](../../concepts/foundation/accounts/main). Check out the Account Contract with AuthWitness [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/noir-contracts/src/contracts/schnorr_single_key_account_contract/src/main.nr). +We are importing the Option type, items from the `value_note` library to help manage private value storage, note utilities, context (for managing private and public execution contexts), `state_vars` for helping manage state, `types` for data manipulation and `oracle` for help passing data from the private to public execution context. We also import the `auth` [library](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/aztec-nr/aztec/src/auth.nr) to handle token authorizations from [Account Contracts](../../concepts/foundation/accounts/main). Check out the Account Contract with AuthWitness [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/noir-contracts/src/contracts/schnorr_single_key_account_contract/src/main.nr). [SafeU120](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/aztec-nr/safe-math/src/safe_u120.nr) is a library to do safe math operations on unsigned integers that protects against overflows and underflows. For more detail on execution contexts, see [Contract Communication](../../concepts/foundation/communication/main). -We are also importing types from a `types.nr` file. The main thing to note from this types file is the `TransparentNote` definition. This defines how the contract moves value from the public domain into the private domain. It is similar to the `value_note` that we imported, but with some modifications namely, instead of a defined `owner`, it allows anyone that can produce the pre-image to the stored `secret_hash` to spend the note. +### Types files + +We are also importing types from a `types.nr` file, which imports types from the `types` folder. You can view them [here](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/yarn-project/noir-contracts/src/contracts/token_contract/src). + +The main thing to note from this types folder is the `TransparentNote` definition. This defines how the contract moves value from the public domain into the private domain. It is similar to the `value_note` that we imported, but with some modifications namely, instead of a defined `owner`, it allows anyone that can produce the pre-image to the stored `secret_hash` to spend the note. ### Note on private state @@ -309,7 +313,7 @@ First, storage is initialized. Then it checks whether the calling contract (`con ##### Authorizing token spends -If the `msg_sender` is **NOT** the same as the account to debit from, the function checks that the account has authorized the `msg_sender` contract to debit tokens on its behalf. This check is done by computing the function selector that needs to be authorized (in this case, the `shield` function), computing the hash of the message that the account contract has approved. This is a hash of the contract that is approved to spend (`context.msg_sender`), the token contract that can be spent from (`context.this_address()`), the `selector`, the account to spend from (`from.address`), the `amount`, the `secret_hash` and a `nonce` to prevent multiple spends. This hash is passed to `assert_current_call_valid_authwit_public` to ensure that the Account Contract has approved tokens to be spent on it's behalf. +If the `msg_sender` is **NOT** the same as the account to debit from, the function checks that the account has authorized the `msg_sender` contract to debit tokens on its behalf. This check is done by computing the function selector that needs to be authorized (in this case, the `shield` function), computing the hash of the message that the account contract has approved. This is a hash of the contract that is approved to spend (`context.msg_sender`), the token contract that can be spent from (`context.this_address()`), the `selector`, the account to spend from (`from.address`), the `amount`, the `secret_hash` and a `nonce` to prevent multiple spends. This hash is passed to `assert_valid_public_message_for` to ensure that the Account Contract has approved tokens to be spent on it's behalf. If the `msg_sender` is the same as the account to debit tokens from, the authorization check is bypassed and the function proceeds to update the account's `public_balance` and adds a new `TransparentNote` to the `pending_shields`. @@ -360,7 +364,7 @@ The function returns `1` to indicate successful execution. This private function enables un-shielding of private `ValueNote`s stored in `balances` to any Aztec account's `public_balance`. -After initializing storage, the function checks that the `msg_sender` is authorized to spend tokens. See [the Authorizing token spends section](#authorizing-token-spends) above for more detail--the only difference being that `assert_current_call_valid_authwit` is modified to work specifically in the private context. After the authorization check, the sender's private balance is decreased using the `decrement` helper function for the `value_note` library. Then it stages a public function call on this contract ([`_increase_public_balance`](#_increase_public_balance)) to be executed in the [public execution phase](#execution-contexts) of transaction execution. `_increase_public_balance` is marked as an `internal` function, so can only be called by this token contract. +After initializing storage, the function checks that the `msg_sender` is authorized to spend tokens. See [the Authorizing token spends section](#authorizing-token-spends) above for more detail--the only difference being that `assert_valid_message_for` is modified to work specifically in the private context. After the authorization check, the sender's private balance is decreased using the `decrement` helper function for the `value_note` library. Then it stages a public function call on this contract ([`_increase_public_balance`](#_increase_public_balance)) to be executed in the [public execution phase](#execution-contexts) of transaction execution. `_increase_public_balance` is marked as an `internal` function, so can only be called by this token contract. The function returns `1` to indicate successful execution. @@ -370,7 +374,7 @@ The function returns `1` to indicate successful execution. This private function enables private token transfers between Aztec accounts. -After initializing storage, the function checks that the `msg_sender` is authorized to spend tokens. See [the Authorizing token spends section](#authorizing-token-spends) above for more detail--the only difference being that `assert_current_call_valid_authwit` is modified to work specifically in the private context. After authorization, the function gets the current balances for the sender and recipient and decrements and increments them, respectively, using the `value_note` helper functions. +After initializing storage, the function checks that the `msg_sender` is authorized to spend tokens. See [the Authorizing token spends section](#authorizing-token-spends) above for more detail--the only difference being that `assert_valid_message_for` is modified to work specifically in the private context. After authorization, the function gets the current balances for the sender and recipient and decrements and increments them, respectively, using the `value_note` helper functions. #include_code transfer /yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr rust diff --git a/docs/docs/dev_docs/updating.md b/docs/docs/dev_docs/updating.md index 8ce48746b3f..05c9b76de53 100644 --- a/docs/docs/dev_docs/updating.md +++ b/docs/docs/dev_docs/updating.md @@ -2,103 +2,56 @@ title: Updating --- -## TL;DR +:::info +The `@aztec/aztec-sandbox` and `@aztec/cli` packages published to npm **should not be used**, in favor of Docker. If you've installed the sandbox or the CLI via NPM, **uninstall** them and remove them from your project dependencies and [install via Docker](./cli/sandbox-reference.md#with-docker). -1. **Updating the sandbox:** + + + + +yarn global remove @aztec/aztec-sandbox @aztec/cli + -- If you installed sandbox via docker, run: + + -```shell -/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" -``` + +npm -g uninstall @aztec/aztec-sandbox @aztec/cli + -- If you have installed via an npm package then step 3 handles the update. + + -2. **Updating Aztec-CLI:** +::: -- The above command also downloads the aztec-cli if a node package version of the CLI isn't found locally. -- If you have globally installed the CLI previously, then run: +## TL;DR + +1. Updating the sandbox and CLI: ```shell -npm install -g @aztec/cli +/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" ``` -(replace with `yarn` or your node package version manager tool). - -- If you have aztec-cli listed as a local dependency in your project's `package.json`, then step 3 handles the update. - -:::info - -You can install the CLI globally, but it is recommended that you install the CLI as a local dependency in your project. This will make it easier to keep the CLI version in sync with the sandbox version. - -::: - -1. **Updating aztec-nr and individual @aztec dependencies:** +2. Updating aztec-nr and individual @aztec dependencies: Inside your project run: ```shell cd your/aztec/project -npx @aztec/cli@latest update . --contract src/contract1 --contract src/contract2 +aztec-cli update . --contract src/contract1 --contract src/contract2 ``` -The sandbox must be running for the update command to work unless there the project defines `@aztec/aztec-sandbox` as a dependency, in which case the command will compare against the version listed in `package.json`. +The sandbox must be running for the update command to work. --- 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`. - -All three are using the same versioning scheme and their versions must match. - -## Updating Aztec Sandbox - -To update the sandbox to the latest version, simply run the curl command we used for installation again: - -```shell -/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" -``` - -This will also update the CLI if a node package version of the CLI isn't found locally. +1. Aztec Sandbox +2. Aztec CLI +3. Noir framework for Aztec contracts `aztec.nr` -## Updating Aztec CLI - -### npm - -:::info - -You can install the CLI globally, but it is recommended that you install the CLI as a local dependency in your project. This will make it easier to keep the CLI version in sync with the sandbox version. - -::: - -If the latest version was used when updating the sandbox then we can simply run the following command to update the CLI: - -```shell -npm install --save-dev @aztec/cli -``` - -If a specific version was set for the sandbox then we need to install the CLI with the same version: - -```shell -npm install --save-dev @aztec/cli@$SANDBOX_VERSION -``` - -E.g.: - -```shell -npm install --save-dev @aztec/cli@#include_aztec_short_version -``` - -### Docker - -If you don't have the CLI installed globally via package manager or locally in your npm project, then you can update it by running the sandbox installation command again: - -```shell -/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')" -``` +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`. ## Updating Aztec.nr packages diff --git a/docs/netlify.toml b/docs/netlify.toml index b43de67e36f..1a022d8a71b 100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@ -74,6 +74,10 @@ from = "/dev_docs/sandbox/main" to = "/dev_docs/getting_started/sandbox" +[[redirects]] + from = "/dev_docs/cli/updating" + to = "/dev_docs/updating" + [[redirects]] from = "/dev_docs/dapps/tutorials/main" to = "/dev_docs/tutorials/writing_dapp/main" @@ -193,4 +197,4 @@ [[redirects]] from = "/misc/aztec-connect-sunset" - to = "/misc/aztec_connect_sunset" + to = "/misc/aztec_connect_sunset" \ No newline at end of file