feat(docs): New getting started flow (#2957)

Closes #2960 This PR - [x] Restructures getting started / aztec.js / sandbox / cli content so it's in an order that makes sense nothing is reused - [x] Implements Diataxis philosophy in CLI, sandbox, aztecjs, and getting started sections - [x] Creates reference pages for CLI and Sandbox (any new stuff we dump into there!) - [x] Creates a basic getting-started guide for Aztec.nr (I know the counter contract is very simple, but one thing I've learned from our feedback partners & people in discord is that it helps a tonnn with understanding syntax and has unblocked people. so i defo want it in our docs. and it's fast to go through) - [x] Creates new top level Updating page # Checklist: Remove the checklist to signal you've completed it. Enable auto-merge if the PR is ready to merge. - [x] If the pull request requires a cryptography review (e.g. cryptographic algorithm implementations) I have added the 'crypto' tag. - [ ] 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). --------- Co-authored-by: Josh Crites <jc@joshcrites.com> Co-authored-by: josh crites <critesjosh@gmail.com>
AztecProtocol · Nov 2, 2023 · f23f868 · f23f868
1 parent 8c41664
commit f23f868
Show file tree

Hide file tree

Showing 25 changed files with 834 additions and 359 deletions.
diff --git a/circuits/cpp/src/aztec3/circuits/rollup/base/.test.cpp b/circuits/cpp/src/aztec3/circuits/rollup/base/.test.cpp
@@ -258,7 +258,7 @@ TEST_F(base_rollup_tests, native_new_commitments_tree)
     // Then get sibling path so we can verify insert them into the tree.
 
     std::array<PreviousKernelData<NT>, 2> kernel_data = { get_empty_kernel(), get_empty_kernel() };
-    std::array<NT::fr, MAX_NEW_COMMITMENTS_PER_TX* 2> new_commitments = { 0, 1, 2, 3, 4, 5, 6, 7 };
+    std::array<NT::fr, MAX_NEW_COMMITMENTS_PER_TX * 2> new_commitments = { 0, 1, 2, 3, 4, 5, 6, 7 };
     for (uint8_t i = 0; i < 2; i++) {
         std::array<fr, MAX_NEW_COMMITMENTS_PER_TX> kernel_commitments;
         for (uint8_t j = 0; j < MAX_NEW_COMMITMENTS_PER_TX; j++) {
@@ -481,7 +481,7 @@ TEST_F(base_rollup_tests, native_nullifier_tree_regression)
     initial_values[7] = uint256_t("2bb9aa4a22a6ae7204f2c67abaab59cead6558cde4ee25ce3464704cb2e38136");
     initial_values[8] = uint256_t("16a732095298ccca828c4d747813f8bd46e188079ed17904e2c9de50760833c8");
 
-    std::array<fr, MAX_NEW_NULLIFIERS_PER_TX* 2> new_nullifiers = { 0 };
+    std::array<fr, MAX_NEW_NULLIFIERS_PER_TX * 2> new_nullifiers = { 0 };
     new_nullifiers[0] = uint256_t("16da4f27fb78de7e0db4c5a04b569bc46382c5f471da2f7d670beff1614e0118"),
     new_nullifiers[1] = uint256_t("26ab07ce103a55e29f11478eaa36cebd10c4834b143a7debcc7ef53bfdb547dd");
 
@@ -519,7 +519,7 @@ TEST_F(base_rollup_tests, native_nullifier_tree_regression)
 TEST_F(base_rollup_tests, nullifier_tree_regression_2)
 {
     // Regression test caught when testing the typescript nullifier tree implementation
-    std::array<fr, MAX_NEW_NULLIFIERS_PER_TX* 2> new_nullifiers = { 0 };
+    std::array<fr, MAX_NEW_NULLIFIERS_PER_TX * 2> new_nullifiers = { 0 };
     new_nullifiers[0] = uint256_t("2a7d956c1365d259646d2d85babe1abb793bb8789e98df7e2336a29a0c91fd01");
     new_nullifiers[1] = uint256_t("236bf2d113f9ffee89df1a7a04890c9ad3583c6773eb9cdec484184f66abd4c6");
     new_nullifiers[4] = uint256_t("2f5c8a1ee33c7104b244e22a3e481637cd501c9eae868cfab6b16e3b4ef3d635");
@@ -530,7 +530,7 @@ TEST_F(base_rollup_tests, nullifier_tree_regression_2)
 
 TEST_F(base_rollup_tests, nullifier_tree_regression_3)
 {
-    std::array<fr, MAX_NEW_NULLIFIERS_PER_TX* 2> new_nullifiers = { 0 };
+    std::array<fr, MAX_NEW_NULLIFIERS_PER_TX * 2> new_nullifiers = { 0 };
     new_nullifiers[0] = uint256_t("0740a17aa6437e71836d2adcdcb3f52879bb869cdd9c8fb8dc39a12846cd17f2");
     new_nullifiers[1] = uint256_t("282e0e2f38310a7c7c98b636830b66f3276294560e26ef2499da10892f00af8f");
     new_nullifiers[4] = uint256_t("0f117936e888bd3befb4435f4d65300d25609e95a3d1563f62ef7e58c294f578");

diff --git a/docs/docs/dev_docs/aztecjs/main.md b/docs/docs/dev_docs/aztecjs/main.md
@@ -0,0 +1,65 @@
+---
+title: Aztec.js
+---
+
+If you are looking for the API reference, go [here](../../apis/aztec-js/index.md).
+
+## Introduction
+
+Aztec.js is a library that provides APIs for managing accounts and interacting with contracts on the Aztec network. It communicates with the [Private eXecution Environment (PXE)](https://docs.aztec.network/apis/pxe/interfaces/PXE) through a `PXE` implementation, allowing developers to easily register new accounts, deploy contracts, view functions, and send transactions.
+
+## Usage
+
+### Create a new account
+
+```typescript
+import { getSchnorrAccount } from "@aztec/aztec.js";
+import { GrumpkinPrivateKey } from "@aztec/types";
+
+const encryptionPrivateKey = GrumpkinPrivateKey.random();
+const signingPrivateKey = GrumpkinPrivateKey.random();
+const wallet = getSchnorrAccount(
+  pxe,
+  encryptionPrivateKey,
+  signingPrivateKey
+).waitDeploy();
+console.log(`New account deployed at ${wallet.getAddress()}`);
+```
+
+### Deploy a contract
+
+```typescript
+import { Contract } from "@aztec/aztec.js";
+
+const contract = await Contract.deploy(wallet, MyContractArtifact, [
+  ...constructorArgs,
+])
+  .send()
+  .deployed();
+console.log(`Contract deployed at ${contract.address}`);
+```
+
+### Send a transaction
+
+```typescript
+import { Contract } from "@aztec/aztec.js";
+
+const contract = await Contract.at(contractAddress, MyContractArtifact, wallet);
+const tx = await contract.methods
+  .transfer(amount, recipientAddress)
+  .send()
+  .wait();
+console.log(
+  `Transferred ${amount} to ${recipientAddress} on block ${tx.blockNumber}`
+);
+```
+
+### Call a view function
+
+```typescript
+import { Contract } from "@aztec/aztec.js";
+
+const contract = await Contract.at(contractAddress, MyContractArtifact, wallet);
+const balance = await contract.methods.getBalance(wallet.getAddress()).view();
+console.log(`Account balance is ${balance}`);
+```
diff --git a/...ocs/dev_docs/getting_started/blank_box.md → docs/docs/dev_docs/cli/blank_box.md b/...ocs/dev_docs/getting_started/blank_box.md → docs/docs/dev_docs/cli/blank_box.md
@@ -16,7 +16,7 @@ There are also boxes that include a basic React interface (`blank-react`) and an
 
 ## Setup
 
-See the Quickstart page for [requirements](./quickstart.md#requirements), starting the local [Sandbox environment](./quickstart.md#sandbox-installation) and [installing the CLI](./quickstart#cli-installation).
+See the Quickstart page for [requirements](../getting_started/quickstart.md#requirements), starting the local [Sandbox environment](../getting_started/quickstart.md#sandbox-installation) and [installing the CLI](../getting_started/quickstart#cli-installation).
 
 Aztec Boxes use [yarn](https://classic.yarnpkg.com/) for package management, so if you want to follow along exactly, make sure you have it [installed](https://classic.yarnpkg.com/en/docs/install).
 
@@ -68,7 +68,7 @@ yarn
 
 ### Start the Sandbox
 
-See the Quickstart for [installing and starting the Sandbox](./quickstart.md#sandbox-installation).
+See the Quickstart for [installing and starting the Sandbox](../getting_started/quickstart.md#sandbox-installation).
 
 ### Start the frontend
 

diff --git a/docs/docs/dev_docs/cli/cli-commands.md b/docs/docs/dev_docs/cli/cli-commands.md
@@ -0,0 +1,96 @@
+---
+title: CLI Commands
+---
+
+Here you will find a reference to the commands available in the Aztec CLI.
+
+## Installation
+
+This command will install the Aztec CLI.
+
+```bash
+npm install -g @aztec/cli
+```
+
+## Creating Accounts
+
+The first thing we want to do is create a couple of accounts. We will use the `create-account` command which will generate a new private key for us, register the account on the sandbox, and deploy a simple account contract which [uses a single key for privacy and authentication](../../concepts/foundation/accounts/keys.md):
+
+#include_code create-account yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+Once the account is set up, the CLI returns the resulting address, its privacy key, and partial address. You can read more about these [here](../../concepts/foundation/accounts/keys.md#addresses-partial-addresses-and-public-keys).
+
+Save the Address and Private key as environment variables. We will be using them later.
+
+```bash
+export ADDRESS=<Address printed when you run the command>
+export PRIVATE_KEY=<Private key printed when you run the command>
+```
+
+Alternatively, we can also manually generate a private key and use it for creating the account, either via a `-k` option or by setting the `PRIVATE_KEY` environment variable.
+
+#include_code create-account-from-private-key yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+For all commands that require a user's private key, the CLI will look for the `PRIVATE_KEY` environment variable in absence of an optional argument.
+
+Let's double check that the accounts have been registered with the sandbox using the `get-accounts` command:
+
+#include_code get-accounts yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+You will see a that a number of accounts exist that we did not create. The Sandbox initializes itself with 3 default accounts. Save one of the printed accounts (not the one that you generated above) in an environment variable. We will use it later.
+
+```bash
+export ADDRESS2=<Account address printed by the above command>
+```
+
+## Deploying a Token Contract
+
+We will now deploy a token contract using the `deploy` command, and set an address of the admin via a constructor argument. You can find the contract we are deploying [here](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr) (or write it for yourself in [this tutorial!](../tutorials/writing_token_contract.md))
+Make sure to replace this address with one of the two you created earlier.
+
+#include_code deploy yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+Save the contract address as an environment variable. We will use it later.
+
+```bash
+export CONTRACT_ADDRESS=<Your new contract address>
+```
+
+- `--args` - Arguments to the constructor of the contract. In this case we have set an address as admin.
+
+The CLI tells us that the contract was successfully deployed. We can use the `check-deploy` command to verify that a contract has been successfully deployed to that address:
+
+#include_code check-deploy yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+## Sending a Transaction
+
+We can now send a transaction to the network. We will mint funds in the public domain.
+To form and submit the transaction we will use the `send` command of `aztec-cli`.
+The `send` command expect the function name as the first unnamed argument and the following named arguments:
+
+- `--args` - The list of arguments to the function call.
+- `--contract-artifact` - The artifact of the contract to call.
+- `--contract-address` - The deployed address of the contract to call.
+- `--private-key` - The private key of the sender.
+
+#include_code send yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+We called the [`mint_public`](https://github.com/AztecProtocol/aztec-packages/blob/87fa621347e55f82e36c70515c1824161eee5282/yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr#L157C10-L157C10) function and provided it with the 2 arguments it expects: the recipient's address and the amount to be minted. Make sure to replace all addresses in this command with yours.
+
+The command output tells us the details of the transaction such as its hash and status. We can use this hash to query the receipt of the transaction at a later time:
+
+#include_code get-tx-receipt yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+## Calling an Unconstrained (View) Function
+
+Now that the `mint_public` tx has been settled we can call the `balance_of_public` unconstrained function:
+
+#include_code call yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+
+The `call` command calls a read-only method on a contract, one that will not generate a transaction to be sent to the network. The arguments here are:
+
+- `--args` - The address for which we want to retrieve the balance.
+- `--contract-artifact` - The artifact of the contract we are calling.
+- `--contract-address` - The address of the deployed contract
+
+As you can see from the result, this address has a public balance of 543, as expected.
diff --git a/docs/docs/dev_docs/cli/main.md b/docs/docs/dev_docs/cli/main.md
@@ -1,144 +1,39 @@
 ---
-title: Aztec CLI
+title: Sandbox and CLI
 ---
 
-## Introduction
+The Aztec Sandbox is an environment for local development on the Aztec Network. It's easy to get setup with just a single, simple command, and contains all the components needed to develop and test Aztec contracts and applications. The Aztec CLI will allow you to interact with the sandbox.
 
-The Aztec CLI is a command-line tool allowing the user to interact directly with the Aztec Network.
+## Components of the Aztec network
 
-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.
-
-## Requirements
-
-You should have [node.js](https://nodejs.org/en/download) installed with version >= 18.
-
-To install the Aztec CLI run:
-
-```bash
-npm install -g @aztec/cli
-```
-
-Or if you use yarn:
-
-```bash
-yarn global add @aztec/cli
-```
-
-Then verify that it is installed with:
-
-```bash
-aztec-cli -h
-```
-
-Once installed it is invoked via:
-
-`aztec-cli [options] [command]`
-
-## I have the Sandbox running, now what?
-
-Lets first establish that we are able to communicate with the Sandbox. Most commands will require the url to the Sandbox, which defaults in the CLI to `http://localhost:8080`. You can override this as an option with each command or by setting `PXE_URL` environment variable.
-
-To test communication with the Sandbox, let's run the command:
-
-#include_code block-number yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
-
-You should see the current block number (1) printed to the screen!
-
-## Contracts
-
-We have shipped a number of example contracts in the `@aztec/noir-contracts` npm package. This is included with the cli by default so you are able to use these contracts to test with. To get a list of the names of the contracts run:
-
-#include_code example-contracts yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
-
-You can see all of our example contracts in the monorepo [here](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/noir-contracts/src/contracts).
-
-In the following sections there will be commands that require contracts as options. You can either specify the full directory path to the contract artifact, or you can use the name of one of these examples as the option value. This will become clearer later on.
-
-## Creating Accounts
-
-The first thing we want to do is create a couple of accounts. We will use the `create-account` command which will generate a new private key for us, register the account on the sandbox, and deploy a simple account contract which [uses a single key for privacy and authentication](../../concepts/foundation/accounts/keys.md):
-
-#include_code create-account yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+Aztec's Layer 2 network is a fully programmable combined private/public ZK rollup. To achieve this, the network contains the following primary components:
 
-Once the account is set up, the CLI returns the resulting address, its privacy key, and partial address. You can read more about these [here](../../concepts/foundation/accounts/keys.md#addresses-partial-addresses-and-public-keys).
+- Aztec Node - Aggregates all of the 'backend' services necessary for the building and publishing of rollups. This packages is currently in development and much of the functionality is mocked.
+- [Private Execution Environment (PXE)](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/pxe) - Normally residing with the end client, this decrypts and stores a client's private state, executes simulations and submits transactions to the Aztec Node.
+- [Aztec.js](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/aztec.js) - Aztec's client library for interacting with the PXE (think Ethers.js). See the getting started guide [here](../getting_started/aztecjs-getting-started.md).
 
-Save the Address and Private key as environment variables. We will be using them later.
+All of this is included in the Sandbox, with the exception of Aztec.js which you can use to interact with it.
 
-```bash
-export ADDRESS=<Address printed when you run the command>
-export PRIVATE_KEY=<Private key printed when you run the command>
-```
+With the help of Aztec.js you will be able to:
 
-Alternatively, we can also manually generate a private key and use it for creating the account, either via a `-k` option or by setting the `PRIVATE_KEY` environment variable.
+- Create an account
+- Deploy a contract
+- Call view methods on contracts
+- Simulate the calling of contract functions
+- Send transactions to the network
+- Be notified when transactions settle
+- Query chain state such as chain id, block number etc.
 
-#include_code create-account-from-private-key yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+## What's in the Sandbox?
 
-For all commands that require a user's private key, the CLI will look for the `PRIVATE_KEY` environment variable in absence of an optional argument.
+The sandbox contains a local Ethereum instance running [Anvil](https://book.getfoundry.sh/anvil/), a local instance of the Aztec rollup, an aztec private execution client for handling user transactions and state, and, if using Docker, an [Otterscan](https://github.com/otterscan/otterscan) block explorer for the local Ethereum network.
 
-Let's double check that the accounts have been registered with the sandbox using the `get-accounts` command:
+These provide a self contained environment which deploys Aztec on a local (empty) Ethereum network, creates 3 smart contract wallet accounts on the rollup, and allows transactions to be processed on the local Aztec sequencer.
 
-#include_code get-accounts yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
+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.
 
-You will see a that a number of accounts exist that we did not create. The Sandbox initializes itself with 3 default accounts. Save one of the printed accounts (not the one that you generated above) in an environment variable. We will use it later.
+## Aztec CLI
 
-```bash
-export ADDRESS2=<Account address printed by the above command>
-```
+The Aztec CLI is a command-line tool allowing the user to interact directly with the Aztec network and sandbox.
 
-## Deploying a Token Contract
-
-We will now deploy a token contract using the `deploy` command, and set an address of the admin via a constructor argument.
-Make sure to replace this address with one of the two you created earlier.
-
-#include_code deploy yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
-
-Save the contract address as an environment variable. We will use it later.
-
-```bash
-export CONTRACT_ADDRESS=<Your new contract address>
-```
-
-- `--args` - Arguments to the constructor of the contract. In this case we have set an address as admin.
-
-The CLI tells us that the contract was successfully deployed. We can use the `check-deploy` command to verify that a contract has been successfully deployed to that address:
-
-#include_code check-deploy yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
-
-## Sending a Transaction
-
-We can now send a transaction to the network. We will mint funds in the public domain.
-To form and submit the transaction we will use the `send` command of `aztec-cli`.
-The `send` command expect the function name as the first unnamed argument and the following named arguments:
-
-- `--args` - The list of arguments to the function call.
-- `--contract-artifact` - The artifact of the contract to call.
-- `--contract-address` - The deployed address of the contract to call.
-- `--private-key` - The private key of the sender.
-
-#include_code send yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
-
-We called the `mint_public` function and provided it with the 2 arguments it expects: the recipient's address and the amount to be minted. Make sure to replace all addresses in this command with yours.
-
-The command output tells us the details of the transaction such as its hash and status. We can use this hash to query the receipt of the transaction at a later time:
-
-#include_code get-tx-receipt yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
-
-## Calling an Unconstrained (View) Function
-
-Now that the `mint_public` tx has been settled we can call the `balance_of_public` unconstrained function:
-
-#include_code call yarn-project/end-to-end/src/cli_docs_sandbox.test.ts bash
-
-The `call` command calls a read-only method on a contract, one that will not generate a transaction to be sent to the network. The arguments here are:
-
-- `--args` - The address for which we want to retrieve the balance.
-- `--contract-artifact` - The artifact of the contract we are calling.
-- `--contract-address` - The address of the deployed contract
-
-As you can see from the result, this address has a public balance of 543, as expected.
-
-## Compute Function Selector
-`aztec-cli --compute-selector <signature e.g. foo(Field,Field)>` gives the function selector.  
-
-## Inspect Contract
-`aztec-cli --compute-selector <json artifact file e.g. artifacts/token_contract.json>` gives the list of all callable functions along with their function signature and selector.
+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.