---
# System prepended metadata

title: Aztec Handbook

---

# Aztec Handbook

This handbook is focused on the aspects of building on Aztec.network--no high level explainers of how to do things. 

High level explanations should link back to docs pages. Much of this content is already written. For content that is already exists, link to it--for content that does not exist yet, create an issue and maybe write it.

**The goal is to reduce the on-boarding time to Aztec to <1 week.**

Before wave 3 we need to create a handbook of existing repos and research on the design space
- Includes Forum posts, github repos, and relevant public info aggregate info from previous notes/ discord discussions
- Dont want new partners to reinvent anything
- Complete this by the end of Q1
- Can be a list of references
- Can be a single page document that lives in docs.aztec.network

> :warning: The Aztec protocol is under rapid development. We typically do releases of updated software at least once a week. Releases are often not backwards compatible. Libraries, compiler and sandbox must all be the same version to work.
> 
> As a result design patterns and suggestions linked here may change, but this is a great place to start.

## Installation

### Prerequisites

- Node.js >= 18. Recommended to use [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating)
- Docker

### Sandbox

```bash
bash -i <(curl -s install.aztec.network)
```

Once this is installed, update by running `aztec-up`.

[Doc](https://docs.aztec.network/developers/getting_started/quickstart#install-the-sandbox)

## Write your first contract

- [Writing a private counter contract](https://docs.aztec.network/developers/getting_started/aztecnr-getting-started)
- [Example contracts](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/noir-contracts/contracts)

### Aztec.nr

- [Installing Aztec.nr](https://github.com/AztecProtocol/aztec-nr?tab=readme-ov-file#installing-aztec-nr-libraries)
- Contents: 
    - [Address Note](https://docs.aztec.network/developers/contracts/references/aztec-nr/address-note/address_note), [Github](https://github.com/AztecProtocol/aztec-nr/tree/master/address-note/src)
    - [Authorization Witnesses](https://docs.aztec.network/developers/contracts/references/aztec-nr/authwit/account), [Github](https://github.com/AztecProtocol/aztec-nr/tree/master/authwit/src)
    - [Easy private state](https://docs.aztec.network/developers/contracts/references/aztec-nr/easy-private-state/easy_private_uint), [Github](https://github.com/AztecProtocol/aztec-nr/tree/master/easy-private-state/src)
    - [FieldNote](https://docs.aztec.network/developers/contracts/references/aztec-nr/field-note/field_note), [Github](https://github.com/AztecProtocol/aztec-nr/tree/master/field-note/src)
    - [Slow updates tree](https://docs.aztec.network/developers/contracts/references/aztec-nr/slow-updates-tree/leaf), [Github](https://github.com/AztecProtocol/aztec-nr/tree/master/slow-updates-tree/src)
    - [ValueNote](https://docs.aztec.network/developers/contracts/references/aztec-nr/value-note/balance_utils), [Github](https://github.com/AztecProtocol/aztec-nr/tree/master/value-note)
    - [Aztec helpers Github](https://github.com/AztecProtocol/aztec-nr/tree/master/aztec/src)
    
## Compile

- Compiling contracts with `aztec-nargo` [doc](https://docs.aztec.network/developers/contracts/compiling_contracts/how_to_compile_contract#compile-using-aztec-nargo)
- [Generating contract interfaces](https://docs.aztec.network/developers/contracts/compiling_contracts/how_to_compile_contract#aztecnr-interfaces)
- [Generating Typescript interfaces](https://docs.aztec.network/developers/contracts/compiling_contracts/how_to_compile_contract#typescript-interfaces)

## Deploy

- [Deploying with the CLI/ aztec.js](https://docs.aztec.network/developers/contracts/deploying_contracts/how_to_deploy_contract)

## Testing

- [Testing docs page](https://docs.aztec.network/developers/contracts/testing_contracts/main)
- [Protocol end-to-end test (in typescript)](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/end-to-end/src)
- [Cheat codes](https://docs.aztec.network/developers/sandbox/references/cheat_codes)
- [Example test in the aztec-starter](https://github.com/AztecProtocol/aztec-starter/blob/main/src/test/index.test.ts)
- [Examples in Aztec Boxes](https://github.com/AztecProtocol/aztec-packages/tree/master/boxes)

## Starter boxes

- [Vanilla box with front-end](https://github.com/AztecProtocol/aztec-packages/tree/master/boxes/boxes/vanilla)
- [React front end with contract](https://github.com/AztecProtocol/aztec-packages/tree/master/boxes/boxes/react)

## Debugging

- [Debugging docs page](https://docs.aztec.network/developers/debugging/main)

## Understanding the PXE

- [Overview](https://docs.aztec.network/learn/concepts/pxe/main)
- [Running an indpendent PXE (not connected to a run)](https://docs.aztec.network/developers/sandbox/references/sandbox-reference#running-aztec-pxe--node--p2p-bootstrap-node)
- [Running multiple PXEs](https://docs.aztec.network/developers/sandbox/guides/run_more_than_one_pxe_sandbox)
- [Reference docs](https://docs.aztec.network/apis/pxe/interfaces/PXE)
- [Setting up the PXE in tests (aztec-starter)](https://github.com/AztecProtocol/aztec-starter/blob/main/src/test/index.test.ts#L5)

## Oracles

- [Overview](https://docs.aztec.network/developers/contracts/writing_contracts/oracles/main)
- [Using the `popCapsule` oracle](https://docs.aztec.network/developers/contracts/writing_contracts/oracles/pop_capsule) to pass arbitrary information into a contract from the PXE
- Adding capsules to the PXE (TODO: [issue](https://github.com/AztecProtocol/dev-rel/issues/194))

## Common Patterns

- [Moving data from public state to private state](https://docs.aztec.network/developers/contracts/resources/common_patterns/main#moving-public-data-into-the-private-domain)
- [Approve others to act on your behalf](https://docs.aztec.network/developers/contracts/resources/common_patterns/main#moving-public-data-into-the-private-domain)
- [Prevent duplicate actions with nullifiers](https://docs.aztec.network/developers/contracts/resources/common_patterns/main#prevent-the-same-user-flow-from-happening-twice-using-nullifiers)
- [Read public state in private functions](https://docs.aztec.network/developers/contracts/resources/common_patterns/main#reading-public-storage-in-private)
- [Writing public state from private functions](https://docs.aztec.network/developers/contracts/resources/common_patterns/main#writing-public-storage-from-private)
- [L1 - L2 interactions](https://docs.aztec.network/developers/contracts/resources/common_patterns/main#l1----l2-interactions)
- [Defi Wonderland common patterns](https://github.com/defi-wonderland/aztec-patterns/tree/dev) includes:
    - private-public state mirroring
    - shared nullifier keys
    - note sharing
    - contracts as note owners
    - immediate note nullification
    - function callbacks
    - multi-party note sharing
    - additive homomorphic encryption

## Authorization Witnesses (Authwit)

- [Aztec.nr Authwit References](https://docs.aztec.network/developers/contracts/references/aztec-nr/authwit/account)
- [Authorizing actions (Accounts doc)](https://docs.aztec.network/learn/concepts/accounts/main#authorizing-actions)
- [AuthWitnessProvider reference doc](https://docs.aztec.network/apis/aztec-js/interfaces/account.AuthWitnessProvider)
- Examples in e2e tests:
    - [Authwit tests](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/end-to-end/src/e2e_authwit.test.ts)

## Portal contracts

- []()

## Note lifecycle info

## Transaction lifecycle

## Accounts

Intro to account abstraction
writing account contracts

