Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(docs): Remove references to npm from docs #3587

Merged
merged 10 commits into from
Dec 6, 2023
21 changes: 6 additions & 15 deletions docs/docs/dev_docs/cli/cli-commands.md
Original file line number Diff line number Diff line change
@@ -6,44 +6,35 @@ 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 if it is not already found locally, by running the command to install and start the sandbox, [instructions here](./sandbox-reference.md#with-docker).
critesjosh marked this conversation as resolved.
Show resolved Hide resolved

:::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 are deprecated 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).

critesjosh marked this conversation as resolved.
Show resolved Hide resolved
:::

### 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).

## 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`.
The sandbox must be running for the update command to work.

:::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. You can update the CLI itself by [running the command again](./sandbox-reference.md#installation-with-docker).
critesjosh marked this conversation as resolved.
Show resolved Hide resolved

:::

18 changes: 2 additions & 16 deletions docs/docs/dev_docs/cli/sandbox-reference.md
Original file line number Diff line number Diff line change
@@ -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,28 +16,14 @@ 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`

```bash
SANDBOX_VERSION=<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:
2 changes: 1 addition & 1 deletion docs/docs/dev_docs/contracts/deploying.md
Original file line number Diff line number Diff line change
@@ -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)

3 changes: 0 additions & 3 deletions docs/docs/dev_docs/debugging/main.md
Original file line number Diff line number Diff line change
@@ -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.
19 changes: 15 additions & 4 deletions docs/docs/dev_docs/getting_started/quickstart.md
Original file line number Diff line number Diff line change
@@ -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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice!


```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:
4 changes: 2 additions & 2 deletions docs/docs/dev_docs/tutorials/token_portal/setup.md
Original file line number Diff line number Diff line change
@@ -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
16 changes: 5 additions & 11 deletions docs/docs/dev_docs/tutorials/writing_dapp/contract_deployment.md
Original file line number Diff line number Diff line change
@@ -20,32 +20,26 @@ 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"}
```

Last, copy-paste the code from the `Token` contract into `contracts/token/main.nr`:

#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
7 changes: 1 addition & 6 deletions docs/docs/dev_docs/tutorials/writing_dapp/testing.md
Original file line number Diff line number Diff line change
@@ -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" };

6 changes: 5 additions & 1 deletion docs/docs/dev_docs/tutorials/writing_token_contract.md
Original file line number Diff line number Diff line change
@@ -216,7 +216,11 @@ We are importing the Option type, items from the `value_note` library to help ma

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

89 changes: 13 additions & 76 deletions docs/docs/dev_docs/updating.md
Original file line number Diff line number Diff line change
@@ -2,103 +2,40 @@
title: Updating
---

## TL;DR

1. **Updating the sandbox:**

- If you installed sandbox via docker, run:
:::info

```shell
/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')"
```
The `@aztec/aztec-sandbox` and `@aztec/cli` packages published to npm are deprecated 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.

- If you have installed via an npm package then step 3 handles the update.
:::

2. **Updating Aztec-CLI:**
## TL;DR

- 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:
1. Updating the sandbox and CLI:

```shell
npm install -g @aztec/cli
/bin/bash -c "$(curl -fsSL 'https://sandbox.aztec.network')"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this will eventually get changed to install.aztec.network but I'm not sure when.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool, ill leave it for now then.

```

(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

4 changes: 4 additions & 0 deletions docs/netlify.toml
Original file line number Diff line number Diff line change
@@ -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"