zkWhirl docs

This guide is intended to introduce the Aztec SDK through the lens of Aztec CLI.

What is Aztec CLI

Aztec CLI is a command line application for interacting with the Aztec Network, powered by the Aztec SDK. It is useful for both accessing the Aztec Network, as well as experimenting with the Aztec SDK.

What is Aztec SDK

Aztec SDK is a set of tools for developing user-facing means to interact with the Aztec Network.

It is designed to abstract away the complexities of zero-knowledge proofs from developers, providing them with simple APIs to develop applications that enjoy the privacy and scaling benefits the Aztec Network offers.

Workshop Video

A video demo of the Aztec CLI is available at:

Certain content of this guide is also covered in this workshop video:

Install

Prerequisites

Install Node.js
Install Yarn
Install Truffle

Install Aztec CLI

Using Yarn

Install Aztec CLI using Yarn:

yarn global add azteccli

1.1 If you are prompted to select an @aztec/bridge-clients version, select the latest one.

Check the path where yarn binaries are installed:

yarn global bin

You should see something like:

$ yarn global bin
/{HOME_DIRECTORY}/.yarn/bin

If not already, add the path to the PATH environmental variable to enable access to the yarn binaries (including azteccli) by your terminal.

You can do this by adding:

export PATH="/{HOME_DIRECTORY}/.yarn/bin:$PATH"

to your .profile / .bashrc file in your home directory.

Note: Changes on the profile file are not applied until the system restarts. To apply the changes immediately, run:

source $HOME/.profile

Check if azteccli is successfully installed:

azteccli help

Set Metamask as the wallet to be used by azteccli:

azteccli conf wallet metamask

Start the Truffle Dashboard:

truffle dashboard

You may now connect your Metamask wallet through the dashboard and start using azteccli by running e.g. azteccli history.

For more details on available commands, you can:

Run azteccli help
Check the commands directory
Check the Aztec CLI repository README

Compile from Source

Alternatively, you can also run the CLI with the latest updates directly from the Github repo.

Clone the repo.
Install dependencies. $ yarn
Edit/add new commands in ./src/.
Test your edits by running ./bin/dev [command] [args] [flags]. (ie $ ./bin/dev deposit .01)

Code Highlights

The workshop video linked at the beginning of this guide is a great walkthrough of the content in this section.

SDK Version

The version of SDK used in Aztec CLI is specified in its package.json:

"dependencies": {
    "@aztec/sdk": "2.1.0-testnet.108", // check for a newer version
    ...
  },

The SDK is rapidly developed upon. The list of version numbers can be found in the Versions tab of @aztec/sdk on the npm registry.

Network Configuration

The networks the Aztec CLI is configured to support are specified in network_config.ts:

let networkConfig: Config = {
  1: {
    rollupProvider: "https://api.aztec.network/aztec-connect-prod/falafel",
    explorerUrl: "https://aztec-connect-prod-explorer.aztec.network/",
  },
  1337: { // local devnet
    rollupProvider: "http://localhost:8081",
    explorerUrl: "",
  },
};

The network of Chain ID 1337 is the Aztec mainnet fork local developer network. It is a local network that is forked from and mimics the Ethereum Mainnet.

Account Alias

Account registering on the Aztec Network comes with an option to specify a preferred account alias. An example of utilizing so through the Aztec SDK can be seen in Aztec CLI's register.ts:

public async run(): Promise<void> {
    const { alias, ttpPubKey, time, asset } = this.flags;
    ...
    const controller = await this.sdk.createRegisterController(
      accountKeys.publicKey,
      alias,
      accountKeys.privateKey,
      ...
    );

An account alias is an arbitrary string that users could "name" their accounts with. Users transferring assets on the Aztec Network can then specify aliases instead of long public keys as their recipients, simplifying the UX.

Controllers

The Aztec SDK abstracts away the backend complexities by exposing interactions with the Aztec Network through controllers.

An example of utilizing so can be seen in Aztec CLI's register.ts, where a RegisterController is first initiated with the arguments gathered:

const controller = await this.sdk.createRegisterController(
  accountKeys.publicKey,
  alias,
  accountKeys.privateKey,
  signer.getPublicKey(),
  recoveryPublicKey, // defaults to nothing
  depositValue,
  txFee,
  depositor // defaults to the logged in Ethereum accounts
  // optional feePayer requires an Aztec Signer to pay the fee
);

Functions of the controller are then called to perform a deposit, generate a client-side proof, sign it and send it to the Aztec backend:

if ((await controller.getPendingFunds()) < tokenQuantity) {
  await controller.depositFundsToContract();
  await controller.awaitDepositFundsToContract();
}

await controller.createProof();
await controller.sign();
let txId = await controller.send();

Different controllers for different actions are available in the Aztec SDK. For example, DepositController is used for depositing assets from Ethereum and TransferController is used for asset transfers on the Aztec Network.

For more information on available controllers, check the SDK section of the Aztec Docs and the controllers directory of the SDK repository.

Aztec Connect

One of the most interesting use cases of the Aztec SDK is to enable users on the Aztec Network to interact with protocols on Ethereum Layer 1 privately and inexpensively through Aztec Connect Bridges with the DefiController.

For more information, check the Ethereum Interaction page and the separate guide on Getting Started with Aztec Connect Bridges.

Command Line Interface (CLI)