> For the complete documentation index, see [llms.txt](/llms.txt)

# Overview

Aztec.nr is a Noir framework used to develop and test Aztec smart contracts. It contains both high-level abstractions (state variables, messages) and low-level protocol primitives, providing granular control to developers if they want custom contracts.

tip

If you are already familiar with writing Aztec smart contracts and Aztec.nr, visit the [API reference](/aztec-nr-api/mainnet/index.md).

## Motivation

Noir *can* be used to write circuits, but Aztec contracts are more complex than this. They include multiple external functions, each of a different type: circuits for private functions, AVM bytecode for public functions, and brillig bytecode for utility functions. The circuits for private functions also need to interact with the protocol's kernel circuits in specific ways, so manually writing them, and then combining everything into a contract artifact is involved work. Aztec.nr takes care of all of this heavy lifting and makes writing contracts as simple as marking functions with the corresponding attributes e.g. `#[external("private")]`.

It allows safe and easy implementation of well understood design patterns, such as the multiple kinds of private state variables, meaning developers don't need to understand the low-levels of how the protocol works. These features are optional, however, advanced developers are not prevented from building their own custom solutions.

## Design principles

* Make it hard to shoot yourself in the foot by making it clear when something is unsafe.
* Dangerous actions should be easy to spot. e.g. ignoring return values or calling functions with the `_unsafe` prefix.
* This is achieved by having rails that intentionally trigger a developer's "WTF?" response, to ensure they understand what they're doing.

A good example of this is writing to private state variables. These functions return a `NoteMessage` struct, which results in a compiler error unless used. This is because writing to private state also requires sending an encrypted message with the new state to the people that need to access it - otherwise, because it is private, they will not even know the state changed.

```rust
storage.votes.insert(new_vote); // compiler error - unused NoteMessage return value
storage.votes.insert(new_vote).deliver(MessageDelivery::onchain_constrained()); // deliver the note message onchain
```

## Contract Development

### Prerequisites

* Install [Aztec Local Network and Tooling](/developers/getting_started_on_local_network.md)
* Install the [Noir VSCode Extension](/developers/docs/aztec-nr/installation.md) for syntax highlighting and error detection.

### Flow

1. Write your contract and specify your contract dependencies. Create a new project with `aztec new my_project`, which scaffolds a workspace with two crates: a `my_project_contract` crate for your contract and a `my_project_test` crate for tests, with the `aztec` dependency already configured. If you need additional dependencies, add them to `my_project_contract/Nargo.toml`:

```toml
# my_project_contract/Nargo.toml
[dependencies]
aztec = { git="https://github.com/aztec-labs-eng/aztec-nr/", tag="v6.0.0", directory="aztec" }
```

Update your `my_project_contract/src/main.nr` contract file to use the Aztec.nr macros for writing contracts.

```rust
use aztec::macros::aztec;

#[aztec]
pub contract Counter {
```

> [Source code: docs/examples/contracts/counter\_contract/src/main.nr#L1-L6](https://github.com/aztec-labs-eng/aztec-node/blob/v6.0.0/docs/examples/contracts/counter_contract/src/main.nr#L1-L6)

and import dependencies from the Aztec.nr library.

```rust
use aztec::{
    macros::{functions::{external, initializer}, storage::storage},
    messages::delivery::MessageDelivery,
    oracle::logging::debug_log_format,
    protocol::{address::AztecAddress, traits::ToField},
    state_vars::Owned,
};
use balance_set::BalanceSet;
```

> [Source code: docs/examples/contracts/counter\_contract/src/main.nr#L7-L16](https://github.com/aztec-labs-eng/aztec-node/blob/v6.0.0/docs/examples/contracts/counter_contract/src/main.nr#L7-L16)

info

You can see a complete example of a simple counter contract written with Aztec.nr [here](https://github.com/aztec-labs-eng/aztec-node/blob/v6.0.0/docs/examples/contracts/counter_contract/src/main.nr).

2. [Profile](/developers/docs/aztec-nr/framework-description/advanced/how_to_profile_transactions.md) the private functions in your contract to get a sense of how long generating client side proofs will take
3. Write unit tests [directly in Noir](/developers/docs/aztec-nr/testing_contracts.md) and end-to-end tests [with TypeScript](/developers/docs/aztec-js/how_to_test.md)
4. [Compile](/developers/docs/aztec-nr/compiling_contracts.md) your contract
5. [Deploy](/developers/docs/aztec-js/how_to_deploy_contract.md) your contract with Aztec.js

## Section Contents

## [📄️Noir VSCode Extension](/developers/docs/aztec-nr/installation.md)

[Learn how to install and configure the Noir Language Server for a better development experience.](/developers/docs/aztec-nr/installation.md)

## [📄️Compiling Contracts](/developers/docs/aztec-nr/compiling_contracts.md)

[Compile your Aztec smart contracts into deployable artifacts using aztec command.](/developers/docs/aztec-nr/compiling_contracts.md)

## [📄️Contract Deployment Reference](/developers/docs/aztec-nr/contract_readiness_states.md)

[A practical guide to determine which deployment steps your Aztec contract needs and when functions become callable.](/developers/docs/aztec-nr/contract_readiness_states.md)

## [🗃Framework Description](/developers/docs/aztec-nr/framework-description/functions.md)

[18 items](/developers/docs/aztec-nr/framework-description/functions.md)

## [📄️Logging from Contracts](/developers/docs/aztec-nr/logging.md)

[Add log statements to your Aztec contracts and control log verbosity in tests and local networks.](/developers/docs/aztec-nr/logging.md)

## [📄️Debugging Aztec Code](/developers/docs/aztec-nr/debugging.md)

[This guide shows you how to debug issues in your Aztec contracts.](/developers/docs/aztec-nr/debugging.md)

## [📄️Testing Contracts](/developers/docs/aztec-nr/testing_contracts.md)

[Write and run tests for your Aztec smart contracts using Noir's TestEnvironment.](/developers/docs/aztec-nr/testing_contracts.md)

## [🗃Standards](/developers/docs/aztec-nr/standards.md)

[6 items](/developers/docs/aztec-nr/standards.md)

## [📄️Aztec.nr API Reference](/developers/docs/aztec-nr/api.md)

[Auto-generated API reference documentation for the Aztec.nr smart contract framework.](/developers/docs/aztec-nr/api.md)