Version: v4.0.0-nightly.20260121

Private Token Contract

The Privacy Challenge: Mental Health Benefits at Giggle

Giggle (a fictional tech company) wants to support their employees' mental health by providing BOB tokens that can be spent at Bob's Psychology Clinic. However, employees have a crucial requirement: complete privacy. They don't want Giggle to know:

How many BOB tokens they've actually used
When they're using mental health services
Their therapy patterns or frequency

In this tutorial, we'll build a token contract that allows Giggle to mint BOB tokens for employees while ensuring complete privacy in how those tokens are spent.

Prerequisites

This is an intermediate tutorial that assumes you have:

Completed the Counter Contract tutorial
A Running Aztec local network (see the Counter tutorial for setup)
Basic understanding of Aztec.nr syntax and structure
Aztec toolchain installed (bash -i <(curl -s https://install.aztec.network/4.0.0-nightly.20260121/))

If you haven't completed the Counter Contract tutorial, please do so first as we'll skip the basic setup steps covered there.

What We're Building

We'll create BOB tokens with:

Public and Private minting: Giggle can mint tokens in private or public
Public and Private transfers: Employees can spend tokens at Bob's clinic with full privacy

Project Setup

Let's create a simple yarn + aztec.nr project:

mkdir bob_token_contract
cd bob_token_contract
yarn init
# This is to ensure yarn uses node_modules instead of pnp for dependency installation
yarn config set nodeLinker node-modules
yarn add @aztec/aztec.js@v4.0.0-nightly.20260121 @aztec/accounts@v4.0.0-nightly.20260121 @aztec/test-wallet@v4.0.0-nightly.20260121 @aztec/kv-store@v4.0.0-nightly.20260121
aztec init

Contract structure

We have a messy, but working structure. In src/main.nr we even have a proto-contract. Let's replace it with a simple starting point:

use aztec::macros::aztec;

#[aztec]
pub contract BobToken {
    // We'll build the mental health token here
}

The #[aztec] macro transforms our contract code to work with Aztec's privacy protocol.

Let's import the Aztec.nr library by adding it to our dependencies in Nargo.toml:

[package]
name = "bob_token_contract"
type = "contract"

[dependencies]
aztec = { git = "https://github.com/AztecProtocol/aztec-nr/", tag = "v4.0.0-nightly.20260121", directory = "aztec" }

Since we're here, let's import more specific stuff from this library:

#[aztec]
pub contract BobToken {
    use aztec::{
        macros::{functions::{external, initializer, only_self}, storage::storage},
        messages::message_delivery::MessageDelivery,
        protocol_types::address::AztecAddress,
        state_vars::{Map, Owned},
        state_vars::public_mutable::PublicMutable,
    };
}

These are the different macros we need to define the visibility of functions, and some handy types and functions.

Building the Mental Health Token System

The Privacy Architecture

Before we start coding, let's understand how privacy works in our mental health token system:

Public Layer: Giggle mints tokens publicly - transparent and auditable
Private Layer: Employees transfer and spend tokens privately - completely confidential
Cross-layer Transfer: Employees can move tokens between public and private domains as needed

This architecture ensures that while the initial allocation is transparent (important for corporate governance), the actual usage remains completely private.

Privacy Note

In Aztec, private state uses a UTXO model with "notes" - think of them as encrypted receipts that only the owner can decrypt and spend. When an employee receives BOB tokens privately, they get encrypted notes that only they can see and use.

Let's start building! Remember to import types as needed - your IDE's Noir extension can help with auto-imports.

Part 1: Public Minting for Transparency

Let's start with the public components that Giggle will use to mint and track initial token allocations.

Setting Up Storage

First, define the storage for our BOB tokens:

#[storage]
struct Storage<Context> {
    // Giggle's admin address
    owner: PublicMutable<AztecAddress, Context>,
    // Public balances - visible for transparency
    public_balances: Map<AztecAddress, PublicMutable<u64, Context>, Context>,
}

This storage structure allows:

owner: Stores Giggle's admin address (who can mint tokens)
public_balances: Tracks public token balances (employees can verify their allocations)

Why Public Balances?

While employees want privacy when spending, having public balances during minting allows:

Employees to verify they received their mental health benefits
Auditors to confirm fair distribution
Transparency in the allocation process

Initializing Giggle as Owner

When deploying the contract, we need to set Giggle as the owner:

setup
#[initializer]
#[external("public")]
fn setup() {
    // Giggle becomes the owner who can mint mental health tokens
    self.storage.owner.write(self.msg_sender());
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L33-L40}}

The #[initializer] decorator ensures this runs once during deployment. Only Giggle's address will have the power to mint new BOB tokens for employees.

Minting BOB Tokens for Employees

Giggle needs a way to allocate mental health tokens to employees:

mint_public
#[external("public")]
fn mint_public(employee: AztecAddress, amount: u64) {
    // Only Giggle can mint tokens
    assert_eq(self.msg_sender(), self.storage.owner.read(), "Only Giggle can mint BOB tokens");

    // Add tokens to employee's public balance
    let current_balance = self.storage.public_balances.at(employee).read();
    self.storage.public_balances.at(employee).write(current_balance + amount);
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L42-L52}}

This public minting function:

Verifies that only Giggle (the owner) is calling
Transparently adds tokens to the employee's public balance
Creates an auditable record of the allocation

Real-World Scenario

Imagine Giggle allocating 100 BOB tokens to each employee at the start of the year. This public minting ensures employees can verify they received their benefits, while their actual usage remains private.

Public Transfers (Optional Transparency)

While most transfers will be private, we'll add public transfers for cases where transparency is desired:

transfer_public
#[external("public")]
fn transfer_public(to: AztecAddress, amount: u64) {
    let sender = self.msg_sender();
    let sender_balance = self.storage.public_balances.at(sender).read();
    assert(sender_balance >= amount, "Insufficient BOB tokens");

    // Deduct from sender
    self.storage.public_balances.at(sender).write(sender_balance - amount);

    // Add to recipient
    let recipient_balance = self.storage.public_balances.at(to).read();
    self.storage.public_balances.at(to).write(recipient_balance + amount);
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L54-L68}}

This might be used when:

An employee transfers tokens to a colleague who's comfortable with transparency
Bob's clinic makes a public refund
Any scenario where privacy isn't required

Admin Transfer (Future-Proofing)

In case Giggle's mental health program administration changes:

transfer_ownership
#[external("public")]
fn transfer_ownership(new_owner: AztecAddress) {
    assert_eq(self.msg_sender(), self.storage.owner.read(), "Only current admin can transfer ownership");
    self.storage.owner.write(new_owner);
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L70-L76}}

Your First Deployment - Let's See It Work

Compile Your Contract

You've written enough code to have a working token! Let's compile and test it:

aztec compile

Generate TypeScript Interface

aztec codegen target --outdir artifacts

You should now have a nice typescript interface in a new artifacts folder. Pretty useful!

Deploy and Test

Create index.ts. We will connect to our running local network and its wallet, then deploy the test accounts and get three wallets out of it. Ensure that your local network is running:

aztec start --local-network

Then we will use the giggleWallet to deploy our contract, mint 100 BOB to Alice, then transfer 10 of those to Bob's Clinic publicly... for now. Let's go:

import { BobTokenContract } from './artifacts/BobToken.js';
import { AztecAddress } from '@aztec/aztec.js/addresses';
import { createAztecNodeClient } from '@aztec/aztec.js/node';
import { getInitialTestAccountsData } from '@aztec/accounts/testing';
import { TestWallet } from '@aztec/test-wallet/server';
import { openTmpStore } from '@aztec/kv-store/lmdb';

async function main() {
    // Connect to local network
    const node = createAztecNodeClient('http://localhost:8080');

    const wallet = await TestWallet.create(node);

    const [giggleWalletData, aliceWalletData, bobClinicWalletData] = await getInitialTestAccountsData();
    const giggleAccount = await wallet.createSchnorrAccount(giggleWalletData.secret, giggleWalletData.salt);
    const aliceAccount = await wallet.createSchnorrAccount(aliceWalletData.secret, aliceWalletData.salt);
    const bobClinicAccount = await wallet.createSchnorrAccount(bobClinicWalletData.secret, bobClinicWalletData.salt);

    const giggleAddress = (await giggleAccount.getAccount()).getAddress();
    const aliceAddress = (await aliceAccount.getAccount()).getAddress();
    const bobClinicAddress = (await bobClinicAccount.getAccount()).getAddress();

    const bobToken = await BobTokenContract
        .deploy(
            wallet,
        )
        .send({ from: giggleAddress })
        .deployed();

    await bobToken.methods
        .mint_public(aliceAddress, 100n)
        .send({ from: giggleAddress })
        .wait();

    await bobToken.methods
        .transfer_public(bobClinicAddress, 10n)
        .send({ from: aliceAddress })
        .wait();
}

main().catch(console.error);

Run your test:

npx tsx index.ts

tip

What's this tsx dark magic? Well, it just compiles and runs typescript using reasonable defaults. Pretty cool for small snippets like this!

🎉 Celebrate

Congratulations! You've just deployed a working token contract on Aztec! You can:

✅ Mint BOB tokens as Giggle
✅ Transfer tokens between employees
✅ Track balances publicly

But there's a problem... Giggle can see everything! They know:

Who's transferring tokens
How much is being spent
When mental health services are being used

This defeats the whole purpose of our mental health privacy initiative. Let's fix this by adding private functionality!

Part 2: Adding Privacy - The Real Magic Begins

Now let's add the privacy features that make our mental health benefits truly confidential.

Understanding Private Notes

Here's where Aztec's privacy magic happens. Unlike public balances (a single number), private balances are collections of encrypted "notes". Think of it this way:

Public balance: "Alice has 100 BOB tokens" (visible to everyone)
Private balance: Alice has encrypted notes [Note1: 30 BOB, Note2: 50 BOB, Note3: 20 BOB] that only she can decrypt

When Alice spends 40 BOB tokens at Bob's clinic:

She consumes Note1 (30 BOB) and Note2 (50 BOB) = 80 BOB total
She creates a new note for Bob's clinic (40 BOB)
She creates a "change" note for herself (40 BOB)
The consumed notes are nullified (marked as spent)

In this case, all that the network sees (including Giggle) is just "something happening to some state in some contract". How cool is that?

Updating Storage for Privacy

For something like balances, you can use a simple library called easy_private_state which abstracts away a custom private Note. A Note is at the core of how private state works in Aztec and you can read about it here. For now, let's just import the library in Nargo.toml:

[dependencies]
aztec = { git="https://github.com/AztecProtocol/aztec-nr", tag="v4.0.0-nightly.20260121", directory="aztec" }
balance_set = { git = "https://github.com/AztecProtocol/aztec-nr/", tag = "v4.0.0-nightly.20260121", directory = "balance-set" }

Then import BalanceSet in our contract:

use aztec::macros::aztec;

#[aztec]
pub contract BobToken {
    // ... other imports
    use balance_set::BalanceSet;
    // ...
}

We need to update the contract storage to have private balances as well:

storage
#[storage]
struct Storage<Context> {
    // Giggle's admin address
    owner: PublicMutable<AztecAddress, Context>,
    // Public balances - visible for transparency
    public_balances: Map<AztecAddress, PublicMutable<u64, Context>, Context>,
    // Private balances - only the owner can see these
    private_balances: Owned<BalanceSet<Context>, Context>,
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L20-L31}}

The private_balances use BalanceSet which manages encrypted notes automatically.

Moving Tokens to Privateland

Great, now our contract knows about private balances. Let's implement a method to allow users to move their publicly minted tokens there:

public_to_private
#[external("private")]
fn public_to_private(amount: u64) {
    let sender = self.msg_sender();
    // This will enqueue a public function to deduct from public balance
    self.enqueue_self._deduct_public_balance(sender, amount);
    // Add to private balance
    self.storage.private_balances.at(sender).add(amount as u128).deliver(
        MessageDelivery.ONCHAIN_CONSTRAINED,
    );
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L78-L89}}

And the helper function:

_deduct_public_balance
#[external("public")]
#[only_self]
fn _deduct_public_balance(owner: AztecAddress, amount: u64) {
    let balance = self.storage.public_balances.at(owner).read();
    assert(balance >= amount, "Insufficient public BOB tokens");
    self.storage.public_balances.at(owner).write(balance - amount);
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L91-L99}}

By calling public_to_private we're telling the network "deduct this amount from my balance" while simultaneously creating a Note with that balance in privateland.

Private Transfers

Now for the crucial privacy feature - transferring BOB tokens in privacy. This is actually pretty simple:

transfer_private
#[external("private")]
fn transfer_private(to: AztecAddress, amount: u64) {
    let sender = self.msg_sender();
    // Spend sender's notes (consumes existing notes)
    self.storage.private_balances.at(sender).sub(amount as u128).deliver(
        MessageDelivery.ONCHAIN_CONSTRAINED,
    );
    // Create new notes for recipient
    self.storage.private_balances.at(to).add(amount as u128).deliver(
        MessageDelivery.ONCHAIN_CONSTRAINED,
    );
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L102-L115}}

This function simply nullifies the sender's notes, while adding them to the recipient.

Real-World Impact

When an employee uses 50 BOB tokens at Bob's clinic, this private transfer ensures Giggle has no visibility into:

The fact that the employee is seeking mental health services
The frequency of visits
The amount spent on treatment

Checking Balances

Employees can check their BOB token balances without hitting the network by using utility unconstrained functions:

check_balances
#[external("utility")]
unconstrained fn private_balance_of(owner: AztecAddress) -> pub u128 {
    self.storage.private_balances.at(owner).balance_of()
}

#[external("utility")]
unconstrained fn public_balance_of(owner: AztecAddress) -> pub u64 {
    self.storage.public_balances.at(owner).read()
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L117-L127}}

Part 3: Securing Private Minting

Let's make this a little bit harder, and more interesting. Let's say Giggle doesn't want to mint the tokens in public. Can we have private minting on Aztec?

Sure we can. Let's see.

Understanding Execution Domains

Our BOB token system operates in two domains:

Public Domain: Where Giggle mints tokens transparently
Private Domain: Where employees spend tokens confidentially

The key challenge: How do we ensure only Giggle can mint tokens when the minting happens in a private function?

Privacy Trade-off

Private functions can't directly read current public state (like who the owner is). They can only read historical public state or enqueue public function calls for validation.

The Access Control Challenge

We want Giggle to mint BOB tokens directly to employees' private balances (for maximum privacy), but we need to ensure only Giggle can do this. The challenge: ownership is stored publicly, but private functions can't read current public state.

Let's use a clever pattern where private functions enqueue public validation checks. First we make a little helper function in public. Remember, public functions always run after private functions, since private functions run client-side.

_assert_is_owner
#[external("public")]
#[only_self]
fn _assert_is_owner(address: AztecAddress) {
    assert_eq(address, self.storage.owner.read(), "Only Giggle can mint BOB tokens");
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L129-L135}}

Now we can add a secure private minting function. It looks pretty easy, and it is, since the whole thing will revert if the public function fails:

mint_private
#[external("private")]
fn mint_private(employee: AztecAddress, amount: u64) {
    // Enqueue ownership check (will revert if not Giggle)
    self.enqueue_self._assert_is_owner(self.msg_sender());

    // If check passes, mint tokens privately
    self.storage.private_balances.at(employee).add(amount as u128).deliver(
        MessageDelivery.ONCHAIN_CONSTRAINED,
    );
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L137-L148}}

This pattern ensures:

The private minting executes first (creating the proof)
The public ownership check executes after
If the check fails, the entire transaction (including the private part) reverts
Only Giggle can successfully mint BOB tokens

Part 4: Converting Back to Public

For the sake of completeness, let's also have a function that brings the tokens back to publicland:

private_to_public
#[external("private")]
fn private_to_public(amount: u64) {
    let sender = self.msg_sender();
    // Remove from private balance
    self.storage.private_balances.at(sender).sub(amount as u128).deliver(
        MessageDelivery.ONCHAIN_CONSTRAINED,
    );
    // Enqueue public credit
    self.enqueue_self._credit_public_balance(sender, amount);
}

#[external("public")]
#[only_self]
fn _credit_public_balance(owner: AztecAddress, amount: u64) {
    let balance = self.storage.public_balances.at(owner).read();
    self.storage.public_balances.at(owner).write(balance + amount);
}

^{_{Source code: docs/examples/contracts/bob_token_contract/src/main.nr#L151-L169}}

Now you've made changes to your contract, you need to recompile your contract.

Here are the steps from above, for reference:

aztec compile
aztec codegen target --outdir artifacts

Testing the Complete Privacy System

Now that you've implemented all the privacy features, let's update our test script to showcase the full privacy flow:

Update Your Test Script

Let's stop being lazy and add a nice little "log" function that just spits out everyone's balances to the console, for example:

// at the top of your file
async function getBalances(contract: BobTokenContract, aliceAddress: AztecAddress, bobAddress: AztecAddress) {
    await Promise.all([
        contract.methods
            .public_balance_of(aliceAddress)
            .simulate({ from: aliceAddress }),
        contract.methods
            .private_balance_of(aliceAddress)
            .simulate({ from: aliceAddress }),
        contract.methods
            .public_balance_of(bobAddress)
            .simulate({ from: bobAddress }),
        contract.methods
            .private_balance_of(bobAddress)
            .simulate({ from: bobAddress })
    ]).then(([alicePublicBalance, alicePrivateBalance, bobPublicBalance, bobPrivateBalance]) => {
        console.log(`📊 Alice has ${alicePublicBalance} public BOB tokens and ${alicePrivateBalance} private BOB tokens`);
        console.log(`📊 Bob's Clinic has ${bobPublicBalance} public BOB tokens and ${bobPrivateBalance} private BOB tokens`);
    });
}

Looks ugly but it does what it says: prints Alice's and Bob's balances. This will make it easier to see our contract working.

Now let's add some more stuff to our index.ts:

async function main() {
    // ...etc
    await bobToken.methods
        .mint_public(aliceAddress, 100n)
        .send({ from: giggleAddress })
        .wait();
    await getBalances(bobToken, aliceAddress, bobClinicAddress);

    await bobToken.methods
        .transfer_public(bobClinicAddress, 10n)
        .send({ from: aliceAddress })
        .wait();
    await getBalances(bobToken, aliceAddress, bobClinicAddress);

    await bobToken.methods
        .public_to_private(90n)
        .send({ from: aliceAddress })
        .wait();
    await getBalances(bobToken, aliceAddress, bobClinicAddress);

    await bobToken.methods
        .transfer_private(bobClinicAddress, 50n)
        .send({ from: aliceAddress })
        .wait();
    await getBalances(bobToken, aliceAddress, bobClinicAddress);

    await bobToken.methods
        .private_to_public(10n)
        .send({ from: aliceAddress })
        .wait();
    await getBalances(bobToken, aliceAddress, bobClinicAddress);

    await bobToken.methods
        .mint_private(aliceAddress, 100n)
        .send({ from: giggleAddress })
        .wait();
    await getBalances(bobToken, aliceAddress, bobClinicAddress);
}

main().catch(console.error);

The flow is something like:

Giggle mints Alice 100 BOB in public
Alice transfers 10 BOB to Bob in public
Alice makes the remaining 90 BOB private
Alice transfers 50 of those to Bob, in private
Of the remaining 40 BOB, she makes 10 public again
Giggle mints 100 BOB tokens for Alice, in private

Let's give it a try:

npx tsx index.ts

You should see the complete privacy journey from transparent allocation to confidential usage!

Summary

You've built a privacy-preserving token system that solves a real-world problem: enabling corporate mental health benefits while protecting employee privacy. This demonstrates Aztec's unique ability to provide both transparency and privacy where each is most needed.

The BOB token shows how blockchain can enable new models of corporate benefits that weren't possible before - where verification and privacy coexist, empowering employees to seek help without fear of judgment or career impact.

What You Learned

How to create tokens with both public and private states
How to bridge between public and private domains
How to implement access control across execution contexts
How to build real-world privacy solutions on Aztec

Continue Your Journey

Explore cross-chain communication to integrate with existing health systems
Learn about account abstraction for recovery mechanisms

The Privacy Challenge: Mental Health Benefits at Giggle​

Prerequisites​

What We're Building​

Project Setup​

Contract structure​

Building the Mental Health Token System​

The Privacy Architecture​

Part 1: Public Minting for Transparency​

Setting Up Storage​

Initializing Giggle as Owner​

Minting BOB Tokens for Employees​

Public Transfers (Optional Transparency)​

Admin Transfer (Future-Proofing)​

Your First Deployment - Let's See It Work​

Compile Your Contract​

Generate TypeScript Interface​

Deploy and Test​

🎉 Celebrate​

Part 2: Adding Privacy - The Real Magic Begins​

Understanding Private Notes​

Updating Storage for Privacy​

Moving Tokens to Privateland​

Private Transfers​

Checking Balances​

Part 3: Securing Private Minting​

Understanding Execution Domains​

The Access Control Challenge​

Part 4: Converting Back to Public​

Testing the Complete Privacy System​

Update Your Test Script​

Summary​

What You Learned​

Continue Your Journey​