Skip to main content
Version: v3.0.0-nightly.20251231

Migration notes

Aztec is in full-speed development. Literally every version breaks compatibility with the previous ones. This page attempts to target errors and difficulties you might encounter when upgrading, and how to resolve them.

TBD​

[AVM] Gas cost multipliers for public execution to reach simulation/proving parity​

Gas costs for several AVM opcodes have been adjusted with multipliers to better align public simulation costs with actual proving costs.

OpcodeMultiplierPrevious CostNew Cost
FDIV25x9225
SLOAD10x1291,290
SSTORE20x1,65733,140
NOTEHASHEXISTS4x126504
EMITNOTEHASH15x1,28519,275
NULLIFIEREXISTS7x132924
EMITNULLIFIER20x1,54030,800
L1TOL2MSGEXISTS5x108540
SENDL2TOL1MSG2x209418
CALL3x3,3129,936
STATICCALL3x3,3129,936
GETCONTRACTINSTANCE4x1,5276,108
POSEIDON215x24360
ECADD10x27270

Impact: Contracts with public bytecode performing any of these operations will see increased gas consumption.

[PXE] deprecated getNotes​

This function serves only for debugging purposes so we are taking it out of the main PXE API. If you still need to consume it, you can do so through the new debug sub-module.

- this.pxe.getNotes(filter);
+ this.pxe.debug.getNotes(filter);

[Aztec node, archiver] Deprecated getPrivateLogs​

Aztec node no longer offers a getPrivateLogs method. If you need to process the logs of a block, you can instead use getBlock and call getPrivateLogs on an L2BlockNew instance. See the diff below for before/after equivalent code samples.

-  const logs = await aztecNode.getPrivateLogs(blockNumber, 1);
+  const logs = (await aztecNode.getBlock(blockNumber))?.toL2Block().getPrivateLogs();

[Aztec.nr] Private event emission API changes​

Private events are still emitted via the emit function, but this now returns an EventMessage type that must have deliver_to called on it in order to deliver the event message to the intended recipients. This allows for multiple recipients to receive the same event.

- self.emit(event, recipient, delivery_method)
+ self.emit(event).delivery(recipient, delivery_method)

[Aztec.nr] History proof functions no longer require storage_slot parameter​

The RetrievedNote struct now includes a storage_slot field, making it self-contained for proving note inclusion and validity. As a result, the history proof functions in the aztec::history module no longer require a separate storage_slot parameter.

Affected functions:

  • BlockHeader::prove_note_inclusion - removed storage_slot: Field parameter
  • BlockHeader::prove_note_validity - removed storage_slot: Field parameter
  • BlockHeader::prove_note_is_nullified - removed storage_slot: Field parameter
  • BlockHeader::prove_note_not_nullified - removed storage_slot: Field parameter

Migration:

The storage_slot is now read from retrieved_note.storage_slot internally. Simply remove the storage_slot argument from all calls to these functions:

  let header = context.get_anchor_block_header();
- header.prove_note_inclusion(retrieved_note, storage_slot);
+ header.prove_note_inclusion(retrieved_note);

  let header = context.get_anchor_block_header();
- header.prove_note_validity(retrieved_note, storage_slot, context);
+ header.prove_note_validity(retrieved_note, context);

  let header = context.get_anchor_block_header();
- header.prove_note_is_nullified(retrieved_note, storage_slot, context);
+ header.prove_note_is_nullified(retrieved_note, context);

  let header = context.get_anchor_block_header();
- header.prove_note_not_nullified(retrieved_note, storage_slot, context);
+ header.prove_note_not_nullified(retrieved_note, context);

[Aztec.nr] Note fields are now public​

All note struct fields are now public, and the new() constructor methods and getter methods have been removed. Notes should be instantiated using struct literal syntax, and fields should be accessed directly.

The motivation for this change has been enshrining of randomness which lead to the new method being unnecessary boilerplate.

Affected notes:

  • UintNote - value is now public, new() and get_value() removed
  • AddressNote - address is now public, new() and get_address() removed
  • FieldNote - value is now public, new() and value() removed

Migration:

- let note = UintNote::new(100);
+ let note = UintNote { value: 100 };

- let value = note.get_value();
+ let value = note.value;

- let address_note = AddressNote::new(owner);
+ let address_note = AddressNote { address: owner };

- let address = address_note.get_address();
+ let address = address_note.address;

- let field_note = FieldNote::new(42);
+ let field_note = FieldNote { value: 42 };

- let value = field_note.value();
+ let value = field_note.value;

[Aztec.nr] emit renamed to deliver​

Private state variable functions that created notes and returned their messages no longer return a NoteEmission but instead a NoteMessage. These messages are delivered to their owner via deliver instead of emit. The verb 'emit' remains for things like emitting events.

- self.storage.balances.at(owner).add(5).emit(owner);
+ self.storage.balances.at(owner).add(5).deliver();

To deliver a message to a different recipient, use deliver_to:

- self.storage.balances.at(owner).add(5).emit(other);
+ self.storage.balances.at(owner).add(5).deliver_to(other);

[Aztec.nr] ValueNote renamed to FieldNote and value-note crate renamed to field-note​

The ValueNote struct has been renamed to FieldNote to better reflect that it stores a Field value. The crate has also been renamed from value-note to field-note.

Migration:

  • Update your Nargo.toml dependencies: value_note = { path = "..." } → field_note = { path = "..." }
  • Update imports: use value_note::value_note::ValueNote → use field_note::field_note::FieldNote
  • Update type references: ValueNote → FieldNote
  • Update generic parameters: PrivateSet<ValueNote, ...> → PrivateSet<FieldNote, ...>

[Aztec.nr] New balance-set library for managing token balances​

A new balance-set library has been created that provides BalanceSet<Context> for managing u128 token balances with UintNote. This consolidates balance management functionality that was previously duplicated across contracts.

Features:

  • add(amount: u128) - Add to balance
  • sub(amount: u128) - Subtract from balance (with change note)
  • try_sub(amount: u128, max_notes: u32) - Attempt to subtract with configurable note limit
  • balance_of() - Get total balance (unconstrained)

Usage:

use balance_set::BalanceSet;

#[storage]
struct Storage<Context> {
    balances: Owned<BalanceSet<Context>, Context>,
}

// In a private function:
self.storage.balances.at(owner).add(amount).deliver(owner, MessageDelivery.CONSTRAINED_ONCHAIN);
self.storage.balances.at(owner).sub(amount).deliver(owner, MessageDelivery.CONSTRAINED_ONCHAIN);

// In an unconstrained function:
let balance = self.storage.balances.at(owner).balance_of();

[Aztec.nr] EasyPrivateUint deprecated and removed​

The EasyPrivateUint type and easy-private-state crate have been deprecated and removed. Use BalanceSet from the balance-set crate instead.

Migration:

  • Remove easy_private_state dependency from Nargo.toml
  • Add balance_set = { path = "../../../../aztec-nr/balance-set" } to Nargo.toml
  • Update storage: EasyPrivateUint<Context> → Owned<BalanceSet<Context>, Context>
  • Update method calls:
    • add(amount, owner) → at(owner).add(amount).deliver(owner, MessageDelivery.CONSTRAINED_ONCHAIN)
    • sub(amount, owner) → at(owner).sub(amount).deliver(owner, MessageDelivery.CONSTRAINED_ONCHAIN)
    • get_value(owner) → at(owner).balance_of() (returns u128 instead of Field)

[Aztec.nr] balance_utils removed from value-note (now field-note)​

The balance_utils module has been removed from the field-note crate (formerly value-note). If you need similar functionality, implement it locally in your contract or use BalanceSet for u128 balances.

[Aztec.nr] filter_notes_min_sum removed from value-note (now field-note)​

The filter_notes_min_sum function has been removed from the field-note crate (formerly in value-note). If you need this functionality, copy it to your contract locally. This function was only used in specific test contracts and doesn't belong in the general-purpose note library.

[Aztec.nr] derive_ecdh_shared_secret_using_aztec_address removed​

This function made it annoying to deal with invalid addresses in circuits. If you were using it, replace it with derive_ecdh_shared_secret instead:

-let shared_secret = derive_ecdh_shared_secret_using_aztec_address(secret, address).unwrap();
+let shared_secret = derive_ecdh_shared_secret(secret, address.to_address_point().unwrap().inner);

[Aztec.nr] Note owner is now enshrined​

It turns out that in all the cases a note always have a logical owner. For this reason we have decided to enshrine the concept of a note owner and you should drop the field from your note:

#[derive(Deserialize, Eq, Packable, Serialize)]
#[note]
pub struct ValueNote {
    value: Field,
-    owner: AztecAddress,
}

The owner being enshrined means that our API explicitly expects it on the input. The NoteHash trait got modified as follows:

pub trait NoteHash {
    fn compute_note_hash(
        self,
+        owner: AztecAddress,
        storage_slot: Field,
        randomness: Field,
    ) -> Field;

    fn compute_nullifier(
        self,
        context: &mut PrivateContext,
+        owner: AztecAddress,
        note_hash_for_nullification: Field,
    ) -> Field;

    unconstrained fn compute_nullifier_unconstrained(
        self,
+        owner: AztecAddress,
        note_hash_for_nullification: Field,
    ) -> Field;
}

Our low-level note utilities now also accept owner as a parameter:

pub fn create_note<Note>(
    context: &mut PrivateContext,
+    owner: AztecAddress,
    storage_slot: Field,
    note: Note,
) -> NoteEmission<Note>
where
    Note: NoteType + NoteHash + Packable,
{
...
}

Signature of some functions like destroy_note_unsafe is unchanged:

pub fn destroy_note_unsafe<Note>(
    context: &mut PrivateContext,
    retrieved_note: RetrievedNote<Note>,
    note_hash_read: NoteHashRead,
)
where
    Note: NoteHash,
{
...
}

because RetrievedNote now contains owner.

PrivateImmutable, PrivateMutable and PrivateSet got modified to directly contain the owner instead of implicitly "containing it" by including it in the storage slot via a Map. These state variables now implement a newly introduced OwnedStateVariable trait (see docs of OwnedStateVariable for explanation of what it is). These changes make the state variables incompatible with Map and now instead these should be wrapped in new Owned state variable:

#[storage]
struct Storage<Context> {
-    private_nfts: Map<AztecAddress, PrivateSet<NFTNote, Context>, Context>,
+    private_nfts: Owned<PrivateSet<NFTNote, Context>, Context>,
}

Note that even though the types of your state variables are changing from Map<AztecAddress, T, Context> to Owned<T, Context>, usage remains unchanged:

let nft_notes = self.storage.private_nfts.at(from).pop_notes(NoteGetterOptions::new().select(NFTNote::properties().token_id, Comparator.EQ, token_id).set_limit(1));

With this change the underlying notes will inherit the storage slot of the Owned state variable. This is unlike Map where the nested state variable got the storage slot computed as hash([map_storage_slot, key]).

if you had PrivateImmutable or PrivateMutable defined out of a Map, e.g.:

#[storage]
struct Storage<Context> {
    signing_public_key: PrivateImmutable<PublicKeyNote, Context>,
}

you were most likely dealing with some kind of admin flow where only the admin can modify the state variable. Now, unfortunately, there is a bit of a regression and you will need to wrap the state variable in Owned and call at on the state var:

+ use aztec::state_vars::Owned;

#[storage]
struct Storage<Context> {
-   signing_public_key: PrivateImmutable<PublicKeyNote, Context>,
+   signing_public_key: Owned<PrivateImmutable<PublicKeyNote, Context>, Context>,
}

#[external("private")]
fn my_external_function() {
-   self.storage.signing_public_key.initialize(pub_key_note)
+   self.storage.signing_public_key.at(self.address).initialize(pub_key_note)
        .emit(self.address, MessageDelivery.CONSTRAINED_ONCHAIN);
}

We are likely to come up with a concept of admin state variables in the future.

None of the reference notes now contain the owner so if you manually construct AddressNote, UintNote or ValueNote you need to update the call to new method:

- let note = UintNote::new(156, owner);
+ let note = UintNote::new(156);

[Aztec.nr] Note randomness is now handled internally​

In order to prevent pre-image attacks, it is necessary to inject randomness to notes. Aztec.nr users were previously expected to add said randomness to their custom note types. From now on, Aztec.nr takes care of handling randomness as built-in note metadata, making it impossible to miss for library users. This change breaks backwards compatibility as we'll discuss below.

Changes to Aztec.nr note types​

If you're using any of the following note types, please be aware that randomness no longer is an explicit attribute in them.

  • ValueNote
  • UintNote
  • NFTNote
  • AddressNote

Migrating your custom note types: refer to UintNote as an example of how to migrate​

We show the changes to UintNote below since it serves as a good example of the adjustments you will need to make to your own custom note types, including those that need to support partial notes.

Remove randomness from note struct​
pub struct UintNote {
    /// The owner of the note, i.e. the account whose nullifier secret key is required to compute the nullifier.
    owner: AztecAddress,
-   /// Random value, protects against note hash preimage attacks.
-   randomness: Field,
    /// The number stored in the note.
    value: u128,
}

impl UintNote {
    pub fn new(value: u128, owner: AztecAddress) -> Self {
-       let randomness = unsafe { random() };
-       Self { value, owner, randomness }
+       Self { value, owner }
    }
Add randomness to compute_note_hash implementation​

The NoteHash trait now requires compute_note_hash to receive a randomness field. This impacts

pub trait NoteHash {
    /// ...
-   fn compute_note_hash(self, storage_slot: Field) -> Field;
+   fn compute_note_hash(self, storage_slot: Field, randomness: Field) -> Field;

Then in trait implementations:

impl NoteHash for UintNote {
-   fn compute_note_hash(self, storage_slot: Field) -> Field {
+   fn compute_note_hash(self, storage_slot: Field, randomness: Field) -> Field {
    /// ...
-   let private_content =
-       UintPartialNotePrivateContent { owner: self.owner, randomness: self.randomness };
-   let partial_note = PartialUintNote {
-        commitment: private_content.compute_partial_commitment(storage_slot),
-   };

+   let private_content =
+       UintPartialNotePrivateContent { owner: self.owner };
+   let partial_note = PartialUintNote {
+        commitment: private_content.compute_partial_commitment(storage_slot, randomness),
+   };

It's worth noting that this change also affects how partial notes are structured and handled.

pub fn partial(
        owner: AztecAddress,
        storage_slot: Field,
        randomness: Field,
        context: &mut PrivateContext,
        recipient: AztecAddress,
        completer: AztecAddress,
    ) -> PartialUintNote {
-   let commitment = UintPartialNotePrivateContent { owner, randomness }
-       .compute_partial_commitment(storage_slot);
+   let commitment = UintPartialNotePrivateContent { owner }
+       .compute_partial_commitment(storage_slot, randomness);

    let private_log_content =
-       UintPartialNotePrivateLogContent { owner, randomness, public_log_tag: commitment };
+       UintPartialNotePrivateLogContent { owner, public_log_tag: commitment };
        let encrypted_log = note::compute_partial_note_private_content_log(
            private_log_content,
            storage_slot,
+           randomness,
            recipient,
        );
    /// ...
}

struct UintPartialNotePrivateContent {
    owner: AztecAddress,
-   randomness: Field,
}

impl UintPartialNotePrivateContent {
-   fn compute_partial_commitment(self, storage_slot: Field) -> Field {
+   fn compute_partial_commitment(self, storage_slot: Field, randomness: Field) -> Field {
        poseidon2_hash_with_separator(
-           self.pack().concat([storage_slot]),
+           self.pack().concat([storage_slot, randomness]),
            DOM_SEP__NOTE_HASH,
        )
    }
}

struct UintPartialNotePrivateLogContent {
    public_log_tag: Field,
    owner: AztecAddress,
-   randomness: Field,
}
Note size​

As a result of this change, the maximum packed length of the content of a note is 11 fields, down from 12. This is a direct consequence of moving the randomness field from the note content structure to the note's metadata.

RetrievedNote now includes randomness field​

pub struct RetrievedNote<Note> {
    pub note: Note,
    pub contract_address: AztecAddress,
+   pub randomness: Field,
    pub metadata: NoteMetadata,
}

[L1 Contracts] Block is now Checkpoint​

A checkpoint is now the primary unit handled by the L1 contracts.

A checkpoint may contain one or more L2 blocks. The protocol circuits already support producing multiple blocks per checkpoint. Updating the L1 contracts to operate on checkpoints allow L2 blockchain to advance faster.

Below are the API and event renames reflecting this change:

- event L2BlockProposed
+ event CheckpointProposed
- event BlockInvalidated
+ event CheckpointInvalidated
- function getEpochForBlock(uint256 _blockNumber) external view returns (Epoch);
+ function getEpochForCheckpoint(uint256 _checkpointNumber) external view returns (Epoch);
- function getProvenBlockNumber() external view returns (uint256);
+ function getProvenCheckpointNumber() external view returns (uint256);
- function getPendingBlockNumber() external view returns (uint256);
+ function getPendingCheckpointNumber() external view returns (uint256);
- function getBlock(uint256 _blockNumber) external view returns (BlockLog memory);
+ function getCheckpoint(uint256 _checkpointNumber) external view returns (CheckpointLog memory);
- function getBlockReward() external view returns (uint256);
+ function getCheckpointReward() external view returns (uint256);

Additionally, any function or struct that previously referenced an L2 block number now uses a checkpoint number instead:

- function status(uint256 _blockNumber) external view returns (
+ function status(uint256 _checkpointNumber) external view returns (
-    uint256 provenBlockNumber,
+    uint256 provenCheckpointNumber,
     bytes32 provenArchive,
-    uint256 pendingBlockNumber,
+    uint256 pendingCheckpointNumber,
     bytes32 pendingArchive,
     bytes32 archiveOfMyBlock,
     Epoch provenEpochNumber
);

Note: current node softwares still produce exactly one L2 block per checkpoint, so for now checkpoint numbers and L2 block numbers remain equal. This may change once multi-block checkpoints are enabled.

[Aztec.js] Wallet interface changes​

simulateTx is now batchable​

The simulateTx method on the Wallet interface is now batchable, meaning it can be called as part of a batch operation using wallet.batch(). This allows you to batch simulations together with other wallet operations like registerContract, sendTx, and registerSender.

- // Could not batch simulations
- const simulationResult = await wallet.simulateTx(executionPayload, options);
+ // Can now batch simulations with other operations
+ const results = await wallet.batch([
+   { name: 'registerContract', args: [instance, artifact] },
+   { name: 'simulateTx', args: [executionPayload, options] },
+   { name: 'sendTx', args: [anotherPayload, sendOptions] },
+ ]);

ExecutionPayload moved to @aztec/stdlib/tx​

The ExecutionPayload type has been moved from @aztec/aztec.js to @aztec/stdlib/tx. Update your imports accordingly.

- import { ExecutionPayload } from '@aztec/aztec.js';
+ import { ExecutionPayload } from '@aztec/stdlib/tx';
+ // Or import from the re-export in aztec.js/tx:
+ import { ExecutionPayload } from '@aztec/aztec.js/tx';

ExecutionPayload now includes feePayer property​

The ExecutionPayload class now includes an optional feePayer property that specifies which address is paying for the fee in the execution payload (if any)

  const payload = new ExecutionPayload(
    calls,
    authWitnesses,
    capsules,
    extraHashedArgs,
+   feePayer // optional AztecAddress
  );

This was previously provided as part of the SendOptions (and others) in the wallet interface, which could cause problems if a payload was assembled with a payment method and the parameter was later omitted. This means SendOptions now loses embeddedPaymentMethodFeePayer

-wallet.simulateTx(executionPayload, { from: address, embeddedFeePaymentMethodFeePayer: feePayer });
+wallet.simulateTx(executionPayload, { from: address });

simulateUtility signature and return type changed​

The simulateUtility method signature has changed to accept a FunctionCall object instead of separate functionName, args, and to parameters. Additionally, the return type has changed from AbiDecoded to Fr[].

- const result: AbiDecoded = await wallet.simulateUtility(functionName, args, to, authWitnesses);
+ const result: UtilitySimulationResult = await wallet.simulateUtility(functionCall, authWitnesses?);
+ // result.result is now Fr[] instead of AbiDecoded

The new signature takes:

  • functionCall: A FunctionCall object containing name, args, to, selector, type, isStatic, hideMsgSender, and returnTypes
  • authWitnesses (optional): An array of AuthWitness objects

The first argument is exactly the same as what goes into ExecutionPayload.calls. As such, the data is already encoded. The return value is now UtilitySimulationResult with result: Fr[] instead of returning an AbiDecoded value directly. You'll need to decode the Fr[] array yourself if you need typed results.

Contract.at() is now synchronous and no longer calls registerContract​

The Contract.at() method (and generated contract .at() methods) is now synchronous and no longer automatically registers the contract with the wallet. This reduces unnecessary artifact storage and RPC calls.

- const contract = await TokenContract.at(address, wallet);
+ const contract = TokenContract.at(address, wallet);

Important: You now need to explicitly call registerContract if you want the wallet to store the contract instance and artifact. This is only necessary when:

  • An app first registers a contract
  • An app tries to update a contract's artifact

If you need to register the contract, do so explicitly:

// Get the instance from deployment
const { contract, instance } = await TokenContract.deploy(wallet, ...args)
  .send({ from: address })
  .wait();

// wallet already has it registered, since the deploy method does it by default
// to avoid it, set skipContractRegistration: true in the send options.

// Register it with another wallet
await otherWallet.registerContract(instance, TokenContract.artifact);

// Now you can use the contract
const otherContract = TokenContract.at(instance.address, otherWallet);

Publicly deployed contract instances can be retrieved via node.getContract(address). Otherwise and if deployment parameters are known, an instance can be computed via the getContractInstanceFromInstantiationParams from @aztec/aztec.js/contracts

registerContract signature simplified​

The registerContract method now takes a ContractInstanceWithAddress instead of a Contract object, and the artifact parameter is now optional. If the artifact is not provided, the wallet will attempt to look it up from its contract class storage.

- await wallet.registerContract(contract);
+ await wallet.registerContract(instance, artifact?);

The method now only accepts:

  • instance: A ContractInstanceWithAddress object
  • artifact (optional): A ContractArtifact object
  • secretKey (optional): A secret key for privacy keys registration

Return value of getNotes no longer contains a recipient and it contains some other additional info​

Return value of getNotes used to be defined as Promise<UniqueNote[]> and now it's defined as Promise<UniqueNote[]>. NoteDao is mostly a super-set of UniqueNote but it doesn't contain a recipient. Having the recipient in the return value has been redundant as the same outcome can be achieved by populating the scopes array in NoteFilter with the recipient value.

Changes to getPrivateEvents​

The signature of getPrivateEvents has changed for two reasons:

  1. To align it with how other query methods that include filtering by block range work (for example, AztecNode#getPublicLogs)
  2. To enrich the returned private events with metadata.
getPrivateEvents<T>(
-    contractAddress: AztecAddress,
-    eventMetadata: EventMetadataDefinition,
-    from: number,
-    numBlocks: number,
-    recipients: AztecAddress[],
-  ): Promise<T[]>;
+    eventFilter: PrivateEventFilter,
+  ): Promise<PrivateEvent<T>[]>;

PrivateEvent<T> bundles together an ABI decoded event of type T, with metadata of type InTx:

export type InBlock = {
  l2BlockNumber: BlockNumber;
  l2BlockHash: L2BlockHash;
};

export type InTx = InBlock & {
  txHash: TxHash;
};

export type PrivateEvent<T> = {
  event: T;
  metadata: InTx;
};

You will need to update any calls to Wallet#getPrivateEvents accordingly. See below for before/after comparison which conserves semantics.

Pay special attention to the fact that the old method expects a numBlocks parameter that instructs it to return numBlocks blocks after fromBlock, whereas the new version expects an (exclusive) toBlock block number.

Also note we're replacing recipient terminology with scope. While underlying data types are equivalent (they are Aztec addresses), they have different semantics. Messages have a recipient who will be able to receive and process them. As a result of processing messages for a given recipient address, PXE might discover events. Those events are then said to be in scope for that address.

- const events = await context.client.getPrivateEvents(contractAddress, eventMetadata, 42, 10, [recipient]);
- doSomethingWithAnEvent(events[0]);

+ const events = await context.client.getPrivateEvents(eventMetadata, {
+   contractAddress,
+   fromBlock: BlockNumber(42),
+   toBlock: BlockNumber(42 + 10),
+   scopes: [scope],
+ });
+ doSomethingWithAnEvent(events[0].event);

Please refer to the wallet interface js-docs for further details.

[CLI] Command refactor​

The sandbox command has been renamed and remapped to "local network". We believe this conveys better what is actually being spun up when running it.

REMOVED/RENAMED:

  • aztec start --sandbox: now aztec start --local-network

[Aztec.nr] - Contract API redesign​

In this release we decided to largely redesign our contract API. Most of the changes here are not a breaking change (only renaming of original #[internal] to #[only_self] and storage now being available on the newly introduced self struct are a breaking change).

1. Renaming of original #[internal] as #[only_self]​

We want for internal to mean the same as in Solidity where internal function can be called only from the same contract and is also inlined (EVM JUMP opcode and not EVM CALL). The original implementation of our #[internal] macro also results in the function being callable only from the same contract but it results in a different call (hence it doesn't map to EVM JUMP). This is very confusing for people that know Solidity hence we are doing the rename. A true #[internal] will be introduced in the future.

To migrate your contracts simply rename all the occurrences of #[internal] with #[only_self] and update the imports:

- use aztec::macros::functions::internal;
+ use aztec::macros::functions::only_self;
#[external("public")]
- #[internal]
+ #[only_self]
fn _deduct_public_balance(owner: AztecAddress, amount: u64) {
    ...
}

2. Introducing of new #[internal]​

Same as in Solidity internal functions are functions that are callable from inside the contract. Unlike #[only_self] functions, internal functions are inlined (e.g. akin to EVM's JUMP and not EVM's CALL).

Internal function can be called using the following API which leverages the new self struct (see change 3 below for details):

self.internal.my_internal_function(...)

Private internal functions can only be called from other private external or internal functions. Public internal functions can only be called from other public external or internal functions.

3. Introducing self in contracts and a new call interface​

Aztec contracts now automatically inject a self parameter into every contract function, providing a unified interface for accessing the contract's address, storage, calling of function and an execution context.

What is self?​

self is an instance of ContractSelf<Context, Storage> that provides:

  • self.address - The contract's own address
  • self.storage - Access to your contract's storage
  • self.context - The execution context (private, public, or utility)
  • self.msg_sender() - Get the address of the caller
  • self.emit(...) - Emit events
  • self.call(...) - Call an external function
  • self.view(...) - Call an external function statically
  • self.enqueue(...) - Enqueue a call to an external function
  • self.enqueue_view(...) - Enqueue a call to an external function
  • self.enqueue_incognito(...) - Enqueue a call to an external function but hides the msg_sender
  • self.enqueue_view_incognito(...) - Enqueue a static call to an external function but hides the msg_sender
  • self.set_as_teardown(...) - Enqueue a call to an external public function and sets the call as teardown
  • self.set_as_teardown_incognito(...) - Enqueue a call to an external public function and sets the call as teardown and hides the msg_sender
  • self.internal.my_internal_fn(...) - Call an internal function

self also provides you with convenience API to call and enqueue calls to external functions from within the same contract (this is just a convenience API as self.call(MyContract::at(self.address).my_external_fn(...)) would also work):

  • self.call_self.my_external_fn(...) - Call external function from within the same contract
  • self.enqueue_self.my_public_external_fn(...)
  • self.call_self_static.my_static_external_fn(...)
  • self.enqueue_self_static.my_static_external_public_fn(...)
How it works​

The #[external(...)] macro automatically injects self into your function. When you write:

#[external("private")]
fn transfer(amount: u128, recipient: AztecAddress) {
    let sender = self.msg_sender().unwrap();
    self.storage.balances.at(sender).sub(amount);
    self.storage.balances.at(recipient).add(amount);
}

The macro transforms it to initialize self with the context and storage before your code executes.

Migration guide​

Before: Access context and storage as separate parameters

#[external("private")]
fn old_transfer(amount: u128, recipient: AztecAddress) {
    let storage = Storage::init(context);
    let sender = context.msg_sender().unwrap();
    storage.balances.at(sender).sub(amount);
}

After: Use self to access everything

#[external("private")]
fn new_transfer(amount: u128, recipient: AztecAddress) {
    let sender = self.msg_sender().unwrap();
    self.storage.balances.at(sender).sub(amount);
}
Key changes​
  1. Storage and context access:

Storage and context are no longer injected into the function as standalone variables and instead you need to access them via self:

- let balance = storage.balances.at(owner).read();
+ let balance = self.storage.balances.at(owner).read();
- context.push_nullifier(nullifier);
+ self.context.push_nullifier(nullifier);

Note that context is expected to be use only when needing to access a low-level API (like directly emitting a nullifier).

  1. Getting caller address: Use self.msg_sender() instead of context.msg_sender()

    - let caller = context.msg_sender().unwrap();
    + let caller = self.msg_sender().unwrap();

  2. Getting contract address: Use self.address instead of context.this_address()

    - let this_contract = context.this_address();
    + let this_contract = self.address;

  3. Emitting events:

    In private functions:

    - emit_event_in_private(event, context, recipient, delivery_mode);
    + self.emit(event, recipient, delivery_mode);

    In public functions:

    - emit_event_in_public(event, context);
    + self.emit(event);

  4. Calling functions:

    In private functions:

    - Token::at(stable_coin).mint_to_public(to, amount).call(&mut context);
    + self.call(Token::at(stable_coin).mint_to_public(to, amount));
Example: Full contract migration​

Before:

#[external("private")]
fn withdraw(amount: u128, recipient: AztecAddress) {
    let storage = Storage::init(context);
    let sender = context.msg_sender().unwrap();
    let token = storage.donation_token.get_note().get_address();

    // ... withdrawal logic

    emit_event_in_private(Withdraw { withdrawer, amount }, context, withdrawer, MessageDelivery.UNCONSTRAINED_ONCHAIN);
}

After:

#[external("private")]
fn withdraw(amount: u128, recipient: AztecAddress) {
    let sender = self.msg_sender().unwrap();
    let token = self.storage.donation_token.get_note().get_address();

    // ... withdrawal logic

    self.emit(Withdraw { withdrawer, amount }, withdrawer, MessageDelivery.UNCONSTRAINED_ONCHAIN);
}

No-longer allowing calling of non-view function statically via the old higher-level API​

We used to allow calling of non-view function statically as follows:

MyContract::at(address).my_non_view_function(...).view(context);
MyContract::at(address).my_non_view_function(...).enqueue_view(context);

This is no-longer allowed and if you will want to call a function statically you will need to mark the function with #[view].

Phase checks​

Now private external functions check by default that no phase change from non revertible to revertible happens during the execution of the function or any of its nested calls. If you're developing a function that handles phase change (you call context.end_setup() or call a function that you expect will change phase) you need to opt out of the phase check using the #[nophasecheck] macro. Also, now it's possible to know if you're in the revertible phase of the transaction at any point using self.context.in_revertible_phase().

[aztec command] Moving functionality of aztec-nargo to aztec command​

aztec-nargo has been deprecated and all workflows should now migrate to the aztec command that fully replaces aztec-nargo:

  • For contract initialization:

    aztec init

    (Behaves like nargo init, but defaults to a contract project.)

  • For testing:

    aztec test

    (Starts the Aztec TXE and runs your tests.)

  • For compiling contracts:

    aztec compile

    (Transpiles your contracts and generates verification keys.)

3.0.0-devnet.4​

[aztec.js] Removal of barrel export​

aztec.js is now divided into granular exports, which improves loading performance in node.js and also makes the job of web bundlers easier:

-import { AztecAddress, Fr, getContractInstanceFromInstantiationParams, type Wallet } from '@aztec/aztec.js';
+import { AztecAddress } from '@aztec/aztec.js/addresses';
+import { getContractInstanceFromInstantiationParams } from '@aztec/aztec.js/contracts';
+import { Fr } from '@aztec/aztec.js/fields';
+import type { Wallet } from '@aztec/aztec.js/wallet';

Additionally, some general utilities reexported from foundation have been removed:

-export { toBigIntBE } from '@aztec/foundation/bigint-buffer';
-export { sha256, Grumpkin, Schnorr } from '@aztec/foundation/crypto';
-export { makeFetch } from '@aztec/foundation/json-rpc/client';
-export { retry, retryUntil } from '@aztec/foundation/retry';
-export { to2Fields, toBigInt } from '@aztec/foundation/serialize';
-export { sleep } from '@aztec/foundation/sleep';
-export { elapsed } from '@aztec/foundation/timer';
-export { type FieldsOf } from '@aztec/foundation/types';
-export { fileURLToPath } from '@aztec/foundation/url';

getSenders renamed to getAddressBook in wallet interface​

An app could request "contacts" from the wallet, which don't necessarily have to be senders in the wallet's PXE. This method has been renamed to reflect that fact:

-wallet.getSenders();
+wallet.getAddressBook();

Removal of proveTx from Wallet interface​

Exposing this method on the interface opened the door for certain types of attacks, were an app could route proven transactions through malicious nodes (that stored them for later decryption, or collected user IPs for example). It also made transactions difficult to track for the wallet, since they could be sent without their knowledge at any time. This change also affects ContractFunctionInteraction and DeployMethod, which no longer expose a prove() method.

msg_sender is now an Option<AztecAddress> type.​

Because Aztec has native account abstraction, the very first function call of a tx has no msg_sender. (Recall, the first function call of an Aztec transaction is always a private function call).

Previously (before this change) we'd been silently setting this first msg_sender to be AztecAddress::from_field(-1);, and enforcing this value in the protocol's kernel circuits. Now we're passing explicitness to smart contract developers by wrapping msg_sender in an Option type. We'll explain the syntax shortly.

We've also added a new protocol feature. Previously (before this change) whenever a public function call was enqueued by a private function (a so-called private->public call), the called public function (and hence the whole world) would be able to see msg_sender. For some use cases, visibility of msg_sender is important, to ensure the caller executed certain checks in private-land. For #[only_self] public functions, visibility of msg_sender is unavoidable (the caller of an #[only_self] function must be the same contract address by definition). But for some use cases, a visible msg_sender is an unnecessary privacy leakage. We therefore have added a feature where msg_sender can be optionally set to Option<AztecAddress>::none() for enqueued public function calls (aka private->public calls). We've been colloquially referring to this as "setting msg_sender to null".

Aztec.nr diffs​

Note: we'll be doing another pass at this aztec.nr syntax in the near future.

Given the above, the syntax for accessing msg_sender in Aztec.nr is slightly different:

For most public and private functions, to adjust to this change, you can make this change to your code:

- let sender: AztecAddress = context.msg_sender();
+ let sender: AztecAddress = context.msg_sender().unwrap();

Recall that Option::unwrap() will throw if the Option is "none".

Indeed, most smart contract functions will require access to a proper contract address (instead of a "null" value), in order to do bookkeeping (allocation of state variables against user addresses), and so in such cases throwing is sensible behaviour.

If you want to output a useful error message when unwrapping fails, you can use Option::expect:

- let sender: AztecAddress = context.msg_sender();
+ let sender: AztecAddress = context.msg_sender().expect(f"Sender must not be none!");

For a minority of functions, a "null" msg_sender will be acceptable:

  • A private entrypoint function.
  • A public function which doesn't seek to do bookkeeping against msg_sender.

Some apps might even want to assert that the msg_sender is "null" to force their users into strong privacy practices:

let sender: Option<AztecAddress> = context.msg_sender();
assert(sender.is_none());
Enqueueing public function calls​
Auto-generated contract interfaces​

When you use the #[aztec] macro, it will generate a noir contract interface for your contract, behind the scenes.

This provides pretty syntax when you come to call functions of that contract. E.g.:

Token::at(context.this_address())._increase_public_balance(to, amount).enqueue(&mut context);

In keeping with this new feature of being able to enqueue public function calls with a hidden msg_sender, there are some new methods that can be chained instead of .enqueue(...):

  • enqueue_incognito -- akin to enqueue, but msg_sender is set "null".
  • enqueue_view_incognito -- akin to enqueue_view, but msg_sender is "null".
  • set_as_teardown_incognito -- akin to set_as_teardown, but msg_sender is "null".

The name "incognito" has been chosen to imply "msg_sender will not be visible to observers".

These new functions enable the calling contract to specify that it wants its address to not be visible to the called public function. This is worth re-iterating: it is the caller's choice. A smart contract developer who uses these functions must be sure that the target public function will accept a "null" msg_sender. It would not be good (for example) if the called public function did context.msg_sender().unwrap(), because then a public function that is called via enqueue_incognito would always fail! Hopefully smart contract developers will write sufficient tests to catch such problems during development!

Making lower-level public function calls from the private context​

This is discouraged vs using the auto-generated contract interfaces described directly above.

If you do use any of these low-level methods of the PrivateContext in your contract:

  • call_public_function
  • static_call_public_function
  • call_public_function_no_args
  • static_call_public_function_no_args
  • call_public_function_with_calldata_hash
  • set_public_teardown_function
  • set_public_teardown_function_with_calldata_hash

... there is a new hide_msg_sender: bool parameter that you will need to specify.

Aztec.js diffs​

Note: we'll be doing another pass at this aztec.js syntax in the near future.

When lining up a new tx, the FunctionCall struct has been extended to include a hide_msg_sender: bool field.

  • is_public & hide_msg_sender -- will make a public call with msg_sender set to "null".
  • is_public & !hide_msg_sender -- will make a public call with a visible msg_sender, as was the case before this new feature.
  • !is_public & hide_msg_sender -- Incompatible flags.
  • !is_public & !hide_msg_sender -- will make a private call with a visible msg_sender (noting that since it's a private function call, the msg_sender will only be visible to the called private function, but not to the rest of the world).

[cli-wallet]​

The deploy-account command now requires the address (or alias) of the account to deploy as an argument, not a parameter

+aztec-wallet deploy-account main
-aztec-wallet deploy-account -f main

This release includes a major architectural change to the system. The PXE JSON RPC Server has been removed, and PXE is now available only as a library to be used by wallets.

[Aztec node]​

Network config. The node now pulls default configuration from the public repository AztecProtocol/networks after it applies the configuration it takes from the running environment and the configuration values baked into the source code. See associated Design document

[Aztec.js]​

Removing Aztec cheatcodes​

The Aztec cheatcodes class has been removed. Its functionality can be replaced by using the getNotes(...) function directly available on our TestWallet, along with the relevant functions available on the Aztec Node interface (note that the cheatcodes were generally just a thin wrapper around the Aztec Node interface).

CLI Wallet commands dropped from aztec command​

The following commands used to be exposed by both the aztec and the aztec-wallet commands:

  • import-test-accounts
  • create-account
  • deploy-account
  • deploy
  • send
  • simulate
  • profile
  • bridge-fee-juice
  • create-authwit
  • authorize-action
  • get-tx
  • cancel-tx
  • register-sender
  • register-contract

These were dropped from aztec and now are exposed only by the cli-wallet command exposed by the @aztec/cli-wallet package.

PXE commands dropped from aztec command​

The following commands were dropped from the aztec command:

  • add-contract: use can be replaced with register-contract on our cli-wallet
  • get-contract-data: debug-only and not considered important enough to need a replacement
  • get-accounts: debug-only and can be replaced by loading aliases from cli-wallet
  • get-account: debug-only and can be replaced by loading aliases from cli-wallet
  • get-pxe-info: debug-only and not considered important enough to need a replacement

[Aztec.nr]​

Replacing #[private], #[public], #[utility] with #[external(...)] macro​

The original naming was not great in that it did not sufficiently communicate what the given macro did. We decided to rename #[private] as #[external("private")], #[public] as #[external("public")], and #[utility] as #[external("utility")] to better communicate that these functions are externally callable and to specify their execution context. In this sense, external now means the exact same thing as in Solidity, i.e. a function that can be called from other contracts, and that can only be invoked via a contract call (i.e. the CALL opcode in the EVM, and a kernel call/AVM CALL opcode in Aztec).

You have to do the following changes in your contracts:

Update import:

- use aztec::macros::functions::private;
- use aztec::macros::functions::public;
- use aztec::macros::functions::utility;
+ use aztec::macros::functions::external;

Update attributes of your functions:

-    #[private]
+    #[external("private")]
    fn my_private_func() {
-    #[public]
+    #[external("public")]
    fn my_public_func() {
-    #[utility]
+    #[external("utility")]
    fn my_utility_func() {

Dropping remote mutable references to public context​

PrivateContext generally needs to be passed as a mutable reference to functions because it does actually hold state we're mutating. This is not the case for PublicContext, or UtilityContext - these are just marker objects that indicate the current execution mode and make available the correct subset of the API. For this reason we have dropped the mutable reference from the API.

If you've passed the context as an argument to custom functions you will need to do the following migration (example from our token contract):

#[contract_library_method]
fn _finalize_transfer_to_private(
    from_and_completer: AztecAddress,
    amount: u128,
    partial_note: PartialUintNote,
-    context: &mut PublicContext,
-    storage: Storage<&mut PublicContext>,
+    context: PublicContext,
+    storage: Storage<PublicContext>,
) {
    ...
}

Authwit Test Helper now takes env​

The add_private_authwit_from_call_interface test helper available in test::helpers::authwit now takes a TestEnvironment parameter, mirroring add_public_authwit_from_call_interface. This adds some unfortunate verbosity, but there are bigger plans to improve authwit usage in Noir tests in the near future.

add_private_authwit_from_call_interface(
+   env,
    on_behalf_of,
    caller,
    call_interface,
);

Historical block renamed as anchor block​

A historical block term has been used as a term that denotes the block against which a private part of a tx has been executed. This name is ambiguous and for this reason we've introduce "anchor block". This naming change resulted in quite a few changes and if you've access private context's or utility context's block header you will need to update your code:

- let header = context.get_block_header();
+ let header = context.get_anchor_block_header();

Removed ValueNote utils​

The value_note::utils module has been removed because it was incorrect to have those in the value note package.

For the increment function you can easily just insert the note:

- use value_note::utils;
- utils::increment(storage.notes.at(owner), value, owner, sender);
+ let note = ValueNote::new(value, owner);
+ storage.notes.at(owner).insert(note).emit(&mut context, owner, MessageDelivery.CONSTRAINED_ONCHAIN);

PrivateMutable: replace / initialize_or_replace behaviour change​

Motivation: Updating a note used to require reading it first (via get_note, which nullifies and recreates it) and then calling replace — effectively proving a note twice. Now, replace accepts a callback that transforms the current note directly, and initialize_or_replace simply uses this updated replace internally. This reduces circuit cost while maintaining exactly one current note.

Key points:

  1. replace(self, new_note) (old) → replace(self, f) (new), where f takes the current note and returns a transformed note.
  2. initialize_or_replace(self, note) (old) → initialize_or_replace(self, f) (new), where f takes an Option with the current none, or none if uninitialized.
  3. Previous note is automatically nullified before the new note is inserted.
  4. NoteEmission<Note> still requires .emit() or .discard().

Example Migration:

- let current_note = storage.my_var.get_note();
- let new_note = f(current_note);
- storage.my_var.replace(new_note);
+ storage.my_var.replace(|current_note| f(current_note));
- storage.my_var.initialize_or_replace(new_note);
+ storage.my_var.initialize_or_replace(|_| new_note);

This makes it easy and efficient to handle both initialization and current value mutation via initialize_or_replace, e.g. if implementing a note that simply counts how many times it has been read:

+ storage.my_var.initialize_or_replace(|opt_current: Option<Note>| opt_current.unwrap_or(0 /* initial value */) + 1);
  • The callback can be a closure (inline) or a named function.
  • Any previous assumptions that replace simply inserts a new_note directly must be updated.

Unified oracles into single get_utility_context oracle​

The following oracles:

  1. get_contract_address,
  2. get_block_number,
  3. get_timestamp,
  4. get_chain_id,
  5. get_version

were replaced with a single get_utility_context oracle whose return value contains all the values returned from the removed oracles.

If you have used one of these removed oracles before, update the import, e.g.:

- aztec::oracle::execution::get_chain_id;
+ aztec::oracle::execution::get_utility_context

and get the value out of the returned utility context:

- let chain_id = get_chain_id();
+ let chain_id = get_utility_context().chain_id();

Note emission API changes​

The note emission API has been significantly reworked to provide clearer semantics around message delivery guarantees. The key changes are:

  1. encode_and_encrypt_note has been removed in favor of calling emit directly with MessageDelivery.CONSTRAINED_ONCHAIN
  2. encode_and_encrypt_note_unconstrained has been removed in favor of calling emit directly with MessageDelivery.UNCONSTRAINED_ONCHAIN
  3. encode_and_encrypt_note_and_emit_as_offchain_message has been removed in favor of using emit with MessageDelivery.UNCONSTRAINED_OFFCHAIN
  4. Note emission now takes a delivery_mode parameter with the following values:
    • CONSTRAINED_ONCHAIN: For onchain delivery with cryptographic guarantees that recipients can discover and decrypt messages. Uses constrained encryption but is slower to prove. Best for critical messages that contracts need to verify.
    • UNCONSTRAINED_ONCHAIN: For onchain delivery without encryption constraints. Faster proving but trusts the sender. Good when the sender is incentivized to perform encryption correctly (e.g. they are buying something and will only get it if the recipient sees the note). No guarantees that recipients will be able to find or decrypt messages.
    • UNCONSTRAINED_OFFCHAIN: For offchain delivery (e.g. cloud storage) without constraints. Lowest cost since no onchain storage needed. Requires custom infrastructure for delivery. No guarantees that messages will be delivered or that recipients will ever find them.
  5. The context object no longer needs to be passed to these functions

Example migration:

First you need to update imports in your contract:

- aztec::messages::logs::note::encode_and_encrypt_note;
- aztec::messages::logs::note::encode_and_encrypt_note_unconstrained;
- aztec::messages::logs::note::encode_and_encrypt_note_and_emit_as_offchain_message;
+ aztec::messages::message_delivery::MessageDelivery;

Then update the emissions:

- storage.balances.at(from).sub(from, amount).emit(encode_and_encrypt_note(&mut context, from));
+ storage.balances.at(from).sub(from, amount).emit(&mut context, from, MessageDelivery.CONSTRAINED_ONCHAIN);
- storage.balances.at(from).add(from, change).emit(encode_and_encrypt_note_unconstrained(&mut context, from));
+ storage.balances.at(from).add(from, change).emit(&mut context, from, MessageDelivery.UNCONSTRAINED_ONCHAIN);
- storage.balances.at(owner).insert(note).emit(encode_and_encrypt_note_and_emit_as_offchain_message(&mut context, context.msg_sender());
+ storage.balances.at(owner).insert(note).emit(&mut context, context.msg_sender(), MessageDelivery.UNCONSTRAINED_OFFCHAIN);

2.0.2​

[Public functions]​

The L2 gas cost of the different AVM opcodes have been updated to reflect more realistic proving costs. Developers should review the L2 gas costs of executing public functions and reevaluate any hardcoded L2 gas limits.

[Aztec Tools]​

Contract compilation now requires two steps​

The aztec-nargo command is now a direct pass-through to vanilla nargo, without any special compilation flags or postprocessing. Contract compilation for Aztec now requires two explicit steps:

  1. Compile your contracts with aztec-nargo compile
  2. Run postprocessing with the new aztec-postprocess-contract command

The postprocessing step includes:

  • Transpiling functions for the Aztec VM
  • Generating verification keys for private functions
  • Caching verification keys for faster subsequent compilations

Update your build scripts accordingly:

- aztec-nargo compile
+ aztec-nargo compile
+ aztec-postprocess-contract

If you're using the aztec-up installer, the aztec-postprocess-contract command will be automatically installed alongside aztec-nargo.

[Aztec.js] Mandatory from​

As we prepare for a bigger Wallet interface refactor and the upcoming WalletSDK, a new parameter has been added to contract interactions, which now should indicate explicitly the address of the entrypoint (usually the account contract) that will be used to authenticate the request. This will be checked in runtime against the current this.wallet.getAddress() value, to ensure consistent behavior while the rest of the API is reworked.

- await contract.methods.my_func(arg).send().wait();
+ await contract.methods.my_func(arg).send({ from: account1Address }).wait();

[Aztec.nr]​

emit_event_in_public_log function renamed as emit_event_in_public​

This change was done to make the naming consistent with the private counterpart (emit_event_in_private).

Private event emission API changes​

The private event emission API has been significantly reworked to provide clearer semantics around message delivery guarantees. The key changes are:

  1. emit_event_in_private_log has been renamed to emit_event_in_private and now takes a delivery_mode parameter instead of constraints
  2. emit_event_as_offchain_message has been removed in favor of using emit_event_in_private with MessageDelivery.UNCONSTRAINED_OFFCHAIN
  3. PrivateLogContent enum has been replaced with MessageDelivery enum with the following values:
    • CONSTRAINED_ONCHAIN: For onchain delivery with cryptographic guarantees that recipients can discover and decrypt messages. Uses constrained encryption but is slower to prove. Best for critical messages that contracts need to verify.
    • UNCONSTRAINED_ONCHAIN: For onchain delivery without encryption constraints. Faster proving but trusts the sender. Good when the sender is incentivized to perform encryption correctly (e.g. they are buying something and will only get it if the recipient sees the note). No guarantees that recipients will be able to find or decrypt messages.
    • UNCONSTRAINED_OFFCHAIN: For offchain delivery (e.g. cloud storage) without constraints. Lowest cost since no onchain storage needed. Requires custom infrastructure for delivery. No guarantees that messages will be delivered or that recipients will ever find them.

Contract functions can no longer be pub or pub(crate)​

With the latest changes to TestEnvironment, making contract functions have public visibility is no longer required given the new call_public and simulate_utility functions. To avoid accidental direct invocation, and to reduce confusion with the autogenerated interfaces, we're forbidding them being public.

- pub(crate) fn balance_of_private(account: AztecAddress) -> 128 {
+ fn balance_of_private(account: AztecAddress) -> 128 {

Notes require you to manually implement or derive Packable​

We have decided to drop auto-derivation of Packable from the #[note] macro because we want to make the macros less magical. With this change you will be forced to either apply #[derive(Packable) on your notes:

+use aztec::protocol_types::traits::Packable;

+#[derive(Packable)]
#[note]
pub struct UintNote {
    owner: AztecAddress,
    randomness: Field,
    value: u128,
}

or to implement it manually yourself:

impl Packable for UintNote {
    let N: u32 = 3;

    fn pack(self) -> [Field; Self::N] {
        [self.owner.to_field(), randomness, value as Field]
    }

    fn unpack(fields: [Field; Self::N]) -> Self {
        let owner = AztecAddress::from_field(fields[0]);
        let randomness = fields[1];
        let value = fields[2] as u128;
        UintNote { owner, randomness, value }
    }
}

Tagging sender now managed via oracle functions​

Now, instead of manually needing to pass a tagging sender as an argument to log emission functions (e.g. encode_and_encrypt_note, encode_and_encrypt_note_unconstrained, emit_event_in_private_log, ...) we automatically load the sender via the get_sender_for_tags() oracle. This value is expected to be populated by account contracts that should call set_sender_for_tags() in their entry point functions.

The changes you need to do in your contracts are quite straightforward. You simply need to drop the sender arg from the callsites of the log emission functions. E.g. note emission:

storage.balances.at(from).sub(from, amount).emit(encode_and_encrypt_note(
    &mut context,
    from,
-    tagging_sender,
));

E.g. private event emission:

emit_event_in_private_log(
    Transfer { from, to, amount },
    &mut context,
-    tagging_sender,
    to,
    PrivateLogContent.NO_CONSTRAINTS,
);

This change affected arguments prepare_private_balance_increase and mint_to_private functions on the Token contract. Drop the from argument when calling these.

Example n TypeScript test:

- await token.methods.mint_to_private(fundedWallet.getAddress(), alice, mintAmount).send().wait();
+ await token.methods.mint_to_private(alice, mintAmount).send().wait();

Example when

let token_out_partial_note = Token::at(token_out).prepare_private_balance_increase(
    sender,
-    tagging_sender
).call(&mut context);

SharedMutable -> DelayedPublicMutable​

The SharedMutable state variable has been renamed to DelayedPublicMutable. It is a public mutable with a delay before state changes take effect. It can be read in private during the delay period. The name "shared" confuses developers who actually wish to work with so-called "shared private state". Also, we're working on a DelayedPrivateMutable which will have similar properties, except writes will be scheduled from private instead. With this new state variable in mind, the new name works nicely.

[TXE] - Testing Aztec Contracts using Noir​

Full TestEnvironment API overhaul​

As part of a broader effort to make Noir tests that leverage TXE easier to use and reason about, large parts of it were changed or adapted, resulting in the API now being quite different. No functionality was lost, so it should be possible to migrate any older Noir test to use the new API.

Network State Manipulation​

  • committed_timestamp removed: this function did not work correctly
  • private_at_timestamp: this function was not really meaningful: private contexts are built from block numbers, not timestamps
  • pending_block_number was renamed to next_block_number. pending_timestamp was removed since it was confusing and not useful
  • committed_block_number was renamed to last_block_number
  • advance_timestamp_to and advance_timestamp_by were renamed to set_next_block_timestamp and advance_next_block_timestamp_by respectively
  • advance_block_to was renamed to mine_block_at, which takes a timestamp instead of a target block number
  • advance_block_by was renamed to mine_block, which now mines a single block

Account Management​

  • create_account was renamed to create_light_account
  • create_account_contract was renamed to create_contract_account

Contract Deployment​

  • deploy_self removed: merged into deploy
  • deploy now accepts both local and external contracts

Contract Interactions​

The old way of calling contract functions is gone. Contract functions are now invoked via the call_private, view_private, call_public, view_public and simulate_utility TestEnvironment methods. These take a CallInterface, like their old counterparts, but now also take an explicit from parameter (for the call variants - this is left out of the view and simulate methods for simplicity).

Raw Context Access​

The private and public methods are gone. Private, public and utility contexts can now be crated with the private_context, public_context and utility_context functions, all of which takes a callback function that is called with the corresponding context. This functions are expected to be defined in-line as lambdas, and contain the user-defined test logic. This helps delineate where contexts begin and end. Contexts automatically mine blocks on closing, when appropriate.

Error-expecting Functions​

assert_public_call_revert and variants have been removed. Use #[test(should_fail_with = "message")] instead.

Example Migration​

The following are two tests using the older version of TestEnvironment:

#[test]
unconstrained fn initial_empty_value() {
    let mut env = TestEnvironment::new();

    // Setup without account contracts. We are not using authwits here, so dummy accounts are enough
    let admin = env.create_account(1);

    let initializer_call_interface = Auth::interface().constructor(admin);

    let auth_contract =
        env.deploy_self("Auth").with_public_void_initializer(admin, initializer_call_interface);
    let auth_contract_address = auth_contract.to_address();

    env.impersonate(admin);
    let authorized = Auth::at(auth_contract_address).get_authorized().view(&mut env.public());
    assert_eq(authorized, AztecAddress::from_field(0));
}

#[test]
unconstrained fn non_admin_cannot_set_authorized() {
    let mut env = TestEnvironment::new();

    // Setup without account contracts. We are not using authwits here, so dummy accounts are enough
    let admin = env.create_account(1);
    let other = env.create_account(2);

    let initializer_call_interface = Auth::interface().constructor(admin);

    let auth_contract =
        env.deploy_self("Auth").with_public_void_initializer(admin, initializer_call_interface);
    let auth_contract_address = auth_contract.to_address();

    env.impersonate(other);
    env.assert_public_call_fails(Auth::at(auth_contract_address).set_authorized(to_authorize));
}

These now look like this:

#[test]
unconstrained fn authorized_initially_unset() {
    let mut env = TestEnvironment::new();

    let admin = env.create_light_account(); // Manual secret management gone

    let auth_contract_address =
        env.deploy("Auth").with_public_initializer(admin, Auth::interface().constructor(admin)); // deploy_self replaced
    let auth = Auth::at(auth_contract_address);

    assert_eq(env.view_public(auth.get_authorized()), AztecAddress::zero()); // .view_public() instead of .public()
}

#[test(should_fail_with = "caller is not admin")]
unconstrained fn non_admin_cannot_set_unauthorized() {
    let mut env = TestEnvironment::new();

    let admin = env.create_light_account();
    let other = env.create_light_account();

    let auth_contract_address =
        env.deploy("Auth").with_public_initializer(admin, Auth::interface().constructor(admin)); // deploy_self replaced
    let auth = Auth::at(auth_contract_address);

    env.call_public(other, auth.set_authorized(other)); // .call_public(), should_fail_with
}

[Aztec.js]​

Cheatcodes​

Cheatcodes where moved out of the @aztec/aztec.js package to @aztec/ethereum and @aztec/aztec packages. While all of the cheatcodes can be imported from the @aztec/aztec package EthCheatCodes and RollupCheatCodes reside in @aztec/ethereum package and if you need only those importing only that package should result in a lighter build.

Note exports dropped from artifact​

Notes are no longer exported in the contract artifact. Exporting notes was technical debt from when we needed to interpret notes in TypeScript.

The following code will no longer work since notes is no longer available on the artifact:

const valueNoteTypeId = StatefulTestContractArtifact.notes['ValueNote'].id;

[core protocol, Aztec.nr, Aztec.js] Max block number property changed to be seconds based​

max_block_number -> include_by_timestamp​

The transaction expiration mechanism has been updated to use seconds rather than number of blocks. As part of this change, the transaction property max_block_number has been renamed to include_by_timestamp.

This change significantly impacts the SharedMutable state variable in Aztec.nr, which now operates on a seconds instead of number of blocks. If your contract uses SharedMutable, you'll need to:

  1. Update the INITIAL_DELAY numeric generic to use seconds instead of blocks
  2. Modify any related logic to account for timestamp-based timing
  3. Note that timestamps use u64 values while block numbers use u32

Removed prelude, so your dep::aztec::prelude::... imports will need to be amended.​

Instead of importing common types from dep::aztec::prelude..., you'll now need to import them from their lower-level locations. The Noir Language Server vscode extension is now capable of autocompleting imports: just type some of the import and press 'tab' when it pops up with the correct item, and the import will be inserted at the top of the file.

As a quick reference, here are the paths to the types that were previously in the prelude. So, for example, if you were previously using dep::aztec::prelude::AztecAddress, you'll need to replace it with dep::aztec::protocol_types::address::AztecAddress. Apologies for any pain this brings. The reasoning is that these types were somewhat arbitrary, and it was unclear which types were worthy enough to be included here.

use dep::aztec::{
    context::{PrivateCallInterface, PrivateContext, PublicContext, UtilityContext, ReturnsHash},
    note::{
        note_getter_options::NoteGetterOptions,
        note_interface::{NoteHash, NoteType},
        note_viewer_options::NoteViewerOptions,
        retrieved_note::RetrievedNote,
    },
    state_vars::{
        map::Map, private_immutable::PrivateImmutable, private_mutable::PrivateMutable,
        private_set::PrivateSet, public_immutable::PublicImmutable, public_mutable::PublicMutable,
        shared_mutable::SharedMutable,
    },
};

use dep::aztec::protocol_types::{
    abis::function_selector::FunctionSelector,
    address::{AztecAddress, EthAddress},
    point::Point,
    traits::{Deserialize, Serialize},
};

include_by_timestamp is now mandatory​

Each transaction must now include a valid include_by_timestamp that satisfies the following conditions:

  • It must be greater than the historical block’s timestamp.
  • The duration between the include_by_timestamp and the historical block’s timestamp must not exceed the maximum allowed (currently 24 hours).
  • It must be greater than or equal to the timestamp of the block in which the transaction is included.

The protocol circuits compute the include_by_timestamp for contract updates during each private function iteration. If a contract does not explicitly specify a value, the default will be the maximum allowed duration. This ensures that include_by_timestamp is never left unset.

No client-side changes are required. However, please note that transactions now have a maximum lifespan of 24 hours and will be removed from the transaction pool once expired.

0.88.0​

[Aztec.nr] Deprecation of the authwit library​

It is now included in aztec-nr, so imports must be updated:

-dep::authwit::...
+dep::aztec::authwit...

and stale dependencies removed from Nargo.toml

-authwit = { path = "../../../../aztec-nr/authwit" }

0.87.0​

[Aztec.js/TS libraries]​

We've bumped our minimum supported node version to v20, as v18 is now EOL. As a consequence, the deprecated type assertion syntax has been replaced with modern import attributes whenever contract artifact JSONs are loaded:

-import ArtifactJson from '../artifacts/contract-Contract.json' assert { type: 'json' };
+import ArtifactJson from '../artifacts/contract-Contract.json' with { type: 'json' };

[Aztec.js/PXE] simulateUtility return type​

pxe.simulateUtility() now returns a complex object (much like .simulateTx()) so extra information can be provided such as simulation timings.

This information can be accessed setting the includeMetadata flag in SimulateMethodOptions to true, but not providing it (which is the default) will NOT change the behavior of the current code.

-const result = await pxe.simulateUtility(...);
+const { meta, result } = await pxe.simulateUtility(...);

const result = await Contract.methods.myFunction(...).simulate();
const { result, meta} = await Contract.methods.myFunction(...).simulate({ includeMetadata: true });

[Aztec.js] Removed mandatory simulation before proving in contract interfaces​

Previously, our autogenerated contract classes would perform a simulation when calling .prove or .send on them. This could potentially catch errors earlier, but took away control from the app/wallets on how to handle network interactions. Now this process has to be triggered manually, which means just proving an interaction (or proving and sending it to the network in one go via .send) is much faster.

WARNING: This means users can incurr in network fees if a transaction that would otherwise be invalid is sent without sanity checks. To ensure this, it is recommended to do:

+await Contract.method.simulate();
await Contract.method.send().wait();

0.86.0​

[PXE] Removed PXE_L2_STARTING_BLOCK environment variable​

PXE now fast-syncs by skipping finalized blocks and never downloads all blocks, so there is no longer a need to specify a starting block.

[Aztec.nr] Logs and messages renaming​

The following renamings have taken place:

  • encrypted_logs to messages: this module now handles much more than just encrypted logs (including unconstrained message delivery, message encoding, etc.)
  • log_assembly_strategies to logs
  • discovery moved to messages: given that what is discovered are messages
  • default_aes128 removed

Most contracts barely used these modules, the only frequent imports are the encode_and_encrypt functions:

- use dep::aztec::messages::logs::note::encode_and_encrypt_note;
+ use dep::aztec::messages::logs::note::encode_and_encrypt_note;

[noir-contracts] Reference Noir contracts directory structure change​

noir-projects/noir-contracts/contracts directory became too cluttered so we grouped contracts into account, app, docs, fees, libs, protocol and test dirs. If you import contract from the directory make sure to update the paths accordingly. E.g. for a token contract:

#[dependencies]
-token = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "v0.83.0", directory = "noir-projects/noir-contracts/contracts/src/token_contract" }
+token = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "v0.83.0", directory = "noir-projects/noir-contracts/contracts/app/src/token_contract" }

[Aztec.nr] #[utility] contract functions​

Aztec contracts have three kinds of functions: #[private], #[public] and what was sometimes called 'top-level unconstrained': an unmarked unconstrained function in the contract module. These are now called [#utility] functions, and must be explicitly marked as such:

+    #[utility]
    unconstrained fn balance_of_private(owner: AztecAddress) -> u128 {
        storage.balances.at(owner).balance_of()
    }

Utility functions are standalone unconstrained functions that cannot be called from private or public functions: they are meant to be called by applications to perform auxiliary tasks: query contract state (e.g. a token balance), process messages received offchain, etc.

All functions in a contract block must now be marked as one of either #[private], #[public], #[utility], #[contract_library_method], or #[test].

Additionally, the UnconstrainedContext type has been renamed to UtilityContext. This led us to rename the unkonstrained method on TestEnvironment to utility, so any tests using it also need updating:

-     SharedMutable::new(env.unkonstrained(), storage_slot)
+     SharedMutable::new(env.utility(), storage_slot)

[AuthRegistry] function name change​

As part of the broader transition from "top-level unconstrained" to "utility" name (detailed in the note above), the unconstrained_is_consumable function in AuthRegistry has been renamed to utility_is_consumable. The function's signature and behavior remain unchanged - only the name has been updated to align with the new convention. If you're currently using this function, a simple rename in your code will suffice.

0.83.0​

[aztec.js] AztecNode.getPrivateEvents API change​

The getPrivateEvents method signature has changed to require an address of a contract that emitted the event and use recipient addresses instead of viewing public keys:

- const events = await wallet.getPrivateEvents<Transfer>(TokenContract.events.Transfer, 1, 1, [recipient.getCompleteAddress().publicKeys.masterIncomingViewingPublicKey()]);
+ const events = await wallet.getPrivateEvents<Transfer>(token.address, TokenContract.events.Transfer, 1, 1, [recipient.getAddress()]);

[portal contracts] Versions and Non-following message boxes​

The version number is no longer hard-coded to be 1 across all deployments (it not depends on where it is deployed to and with what genesis and logic). This means that if your portal were hard-coding 1 it will now fail when inserting into the inbox or consuming from the outbox because of a version mismatch. Instead you can get the real version (which don't change for a deployment) by reading the VERSION on inbox and outbox, or using getVersion() on the rollup.

New Deployments of the protocol do not preserve former state/across each other. This means that after a new deployment, any "portal" following the registry would try to send messages into this empty rollup to non-existant contracts. To solve, the portal should be linked to a specific deployment, e.g., a specific inbox. This can be done by storing the inbox/outbox/version at the time of deployment or initialize and not update them.

Both of these issues were in the token portal and the uniswap portal, so if you used them as a template it is very likely that you will also have it.

0.82.0​

[aztec.js] AztecNode.findLeavesIndexes returns indexes with block metadata​

It's common that we need block metadata of a block in which leaves where inserted when querying indexes of these tree leaves. For this reason we now return that information along with the indexes. This allows us to reduce the number of individual AztecNode queries.

Along this change findNullifiersIndexesWithBlock and findBlockNumbersForIndexes functions wer removed as all its uses can now be replaced with the newly modified findLeavesIndexes function.

[aztec.js] AztecNode.getPublicDataTreeWitness renamed as AztecNode.getPublicDataWitness​

This change was done to have consistent naming across codebase.

[aztec.js] Wallet interface and Authwit management​

The Wallet interface in aztec.js is undergoing transformations, trying to be friendlier to wallet builders and reducing the surface of its API. This means Wallet no longer extends PXE, and instead just implements a subset of the methods of the former. This is NOT going to be its final form, but paves the way towards better interfaces and starts to clarify what the responsibilities of the wallet are:

/**
 * The wallet interface.
 */
export type Wallet = AccountInterface &
  Pick<
    PXE,
    // Simulation
    | "simulateTx"
    | "simulateUnconstrained"
    | "profileTx"
    // Sending
    | "sendTx"
    // Contract management (will probably be collapsed in the future to avoid instance and class versions)
    | "getContractClassMetadata"
    | "getContractMetadata"
    | "registerContract"
    | "registerContractClass"
    // Likely to be removed
    | "proveTx"
    // Will probably be collapsed
    | "getNodeInfo"
    | "getPXEInfo"
    // Fee info
    | "getCurrentBaseFees"
    // Still undecided, kept for the time being
    | "updateContract"
    // Sender management
    | "registerSender"
    | "getSenders"
    | "removeSender"
    // Tx status
    | "getTxReceipt"
    // Events. Kept since events are going to be reworked and changes will come when that's done
    | "getPrivateEvents"
    | "getPublicEvents"
  > & {
    createAuthWit(intent: IntentInnerHash | IntentAction): Promise<AuthWitness>;
  };

As a side effect, a few debug only features have been removed

// Obtain tx effects
const { txHash, debugInfo } = await contract.methods
      .set_constant(value)
      .send()
--      .wait({ interval: 0.1, debug: true });
++      .wait({ interval: 0.1 })

--    // check that 1 note hash was created
--    expect(debugInfo!.noteHashes.length).toBe(1);
++    const txEffect = await aztecNode.getTxEffect(txHash);
++    const noteHashes = txEffect?.data.noteHashes;
++    // check that 1 note hash was created
++    expect(noteHashes?.length).toBe(1);

// Wait for a tx to be proven
--      tx.wait({ timeout: 300, interval: 10, proven: true, provenTimeout: 3000 })));
++      const receipt = await tx.wait({ timeout: 300, interval: 10 });
++      await waitForProven(aztecNode, receipt, { provenTimeout: 3000 });

Authwit management has changed, and PXE no longer stores them. This is unnecessary because now they can be externally provided to simulations and transactions, making sure no stale authorizations are kept inside PXE's db.

const witness = await wallet.createAuthWit({ caller, action });
--await callerWallet.addAuthWitness(witness);
--await action.send().wait();
++await action.send({ authWitnesses: [witness] }).wait();

Another side effect of this is that the interface of the lookupValidity method has changed, and now the authwitness has to be provided:

const witness = await wallet.createAuthWit({ caller, action });
--await callerWallet.addAuthWitness(witness);
--await wallet.lookupValidity(wallet.getAddress(), { caller, action });
++await wallet.lookupValidity(wallet.getAddress(), { caller, action }, witness);

0.80.0​

[PXE] Concurrent contract function simulation disabled​

PXE is no longer be able to execute contract functions concurrently (e.g. by collecting calls to simulateTx and then using await Promise.all). They will instead be put in a job queue and executed sequentially in order of arrival.

0.79.0​

[aztec.js] Changes to BatchCall and BaseContractInteraction​

The constructor arguments of BatchCall have been updated to improve usability. Previously, it accepted an array of FunctionCall, requiring users to manually set additional data such as authwit and capsules. Now, BatchCall takes an array of BaseContractInteraction, which encapsulates all necessary information.

class BatchCall extends BaseContractInteraction {
-    constructor(wallet: Wallet, protected calls: FunctionCall[]) {
+    constructor(wallet: Wallet, protected calls: BaseContractInteraction[]) {
        ...
    }

The request method of BaseContractInteraction now returns ExecutionPayload. This object includes all the necessary data to execute one or more functions. BatchCall invokes this method on all interactions to aggregate the required information. It is also used internally in simulations for fee estimation.

Declaring a BatchCall:

new BatchCall(wallet, [
-    await token.methods.transfer(alice, amount).request(),
-    await token.methods.transfer_to_private(bob, amount).request(),
+    token.methods.transfer(alice, amount),
+    token.methods.transfer_to_private(bob, amount),
])

0.77.0​

[aztec-nr] TestEnvironment::block_number() refactored​

The block_number function from TestEnvironment has been expanded upon with two extra functions, the first being pending_block_number, and the second being committed_block_number. pending_block_number now returns what block_number does. In other words, it returns the block number of the block we are currently building. committed_block_number returns the block number of the last committed block, i.e. the block number that gets used to execute the private part of transactions when your PXE is successfully synced to the tip of the chain.

+    `TestEnvironment::pending_block_number()`
+    `TestEnvironment::committed_block_number()`

[aztec-nr] compute_nullifier_without_context renamed​

The compute_nullifier_without_context function from NoteHash (ex NoteInterface) is now called compute_nullifier_unconstrained, and instead of taking storage slot, contract address and nonce it takes a note hash for nullification (same as compute_note_hash). This makes writing this function simpler:

-    unconstrained fn compute_nullifier_without_context(self, storage_slot: Field, contract_address: AztecAddress, nonce: Field) -> Field {
-       let note_hash_for_nullify = ...;
+    unconstrained fn compute_nullifier_unconstrained(self, note_hash_for_nullify: Field) -> Field {
        ...
    }

U128 type replaced with native u128​

The U128 type has been replaced with the native u128 type. This means that you can no longer use the U128 type in your code. Instead, you should use the u128 type. Doing the changes is as straightforward as:

    #[public]
    #[view]
-    fn balance_of_public(owner: AztecAddress) -> U128 {
+    fn balance_of_public(owner: AztecAddress) -> u128 {
        storage.public_balances.at(owner).read()
    }

UintNote has also been updated to use the native u128 type.

[aztec-nr] Removed compute_note_hash_and_optionally_a_nullifer​

This function is no longer mandatory for contracts, and the #[aztec] macro no longer injects it.

[PXE] Removed addNote and addNullifiedNote​

These functions have been removed from PXE and the base Wallet interface. If you need to deliver a note manually because its creation is not being broadcast in an encrypted log, then create an unconstrained contract function to process it and simulate execution of it. The aztec::discovery::private_logs::do_process_log function can be used to perform note discovery and add to it to PXE.

See an example of how to handle a TransparentNote:

    unconstrained fn deliver_transparent_note(
        contract_address: AztecAddress,
        amount: Field,
        secret_hash: Field,
        tx_hash: Field,
        unique_note_hashes_in_tx: BoundedVec<Field, MAX_NOTE_HASHES_PER_TX>,
        first_nullifier_in_tx: Field,
        recipient: AztecAddress,
    ) {
        // do_process_log expects a standard aztec-nr encoded note, which has the following shape:
        // [ storage_slot, note_type_id, ...packed_note ]
        let note = TransparentNote::new(amount, secret_hash);
        let log_plaintext = BoundedVec::from_array(array_concat(
            [
                MyContract::storage_layout().my_state_variable.slot,
                TransparentNote::get_note_type_id(),
            ],
            note.pack(),
        ));

        do_process_log(
            contract_address,
            log_plaintext,
            tx_hash,
            unique_note_hashes_in_tx,
            first_nullifier_in_tx,
            recipient,
            _compute_note_hash_and_nullifier,
        );
    }

The note is then processed by calling this function:

const txEffects = await wallet.getTxEffect(txHash);
await contract.methods
  .deliver_transparent_note(
    contract.address,
    new Fr(amount),
    secretHash,
    txHash.hash,
    toBoundedVec(txEffects!.data.noteHashes, MAX_NOTE_HASHES_PER_TX),
    txEffects!.data.nullifiers[0],
    wallet.getAddress()
  )
  .simulate();

Fee is mandatory​

All transactions must now pay fees. Previously, the default payment method was NoFeePaymentMethod; It has been changed to FeeJuicePaymentMethod, with the wallet owner as the fee payer.

For example, the following code will still work:

await TokenContract.at(address, wallet).methods.transfer(recipient, 100n).send().wait();

However, the wallet owner must have enough fee juice to cover the transaction fee. Otherwise, the transaction will be rejected.

The 3 test accounts deployed in the sandbox are pre-funded with 10 ^ 22 fee juice, allowing them to send transactions right away.

In addition to the native fee juice, users can pay the transaction fees using tokens that have a corresponding FPC contract. The sandbox now includes BananaCoin and BananaFPC. Users can use a funded test account to mint banana coin for a new account. The new account can then start sending transactions and pay fees with banana coin.

import { getDeployedTestAccountsWallets } from "@aztec/accounts/testing";
import {
  getDeployedBananaCoinAddress,
  getDeployedBananaFPCAddress,
} from "@aztec/aztec";

// Fetch the funded test accounts.
const [fundedWallet] = await getDeployedTestAccountsWallets(pxe);

// Create a new account.
const secret = Fr.random();
const signingKey = GrumpkinScalar.random();
const alice = await getSchnorrAccount(pxe, secret, signingKey);
const aliceWallet = await alice.getWallet();
const aliceAddress = alice.getAddress();

// Deploy the new account using the pre-funded test account.
await alice.deploy({ deployWallet: fundedWallet }).wait();

// Mint banana coin for the new account.
const bananaCoinAddress = await getDeployedBananaCoinAddress(pxe);
const bananaCoin = await TokenContract.at(bananaCoinAddress, fundedWallet);
const mintAmount = 10n ** 20n;
await bananaCoin.methods
  .mint_to_private(fundedWallet.getAddress(), aliceAddress, mintAmount)
  .send()
  .wait();

// Use the new account to send a tx and pay with banana coin.
const transferAmount = 100n;
const bananaFPCAddress = await getDeployedBananaFPCAddress(pxe);
const paymentMethod = new PrivateFeePaymentMethod(
  bananaFPCAddress,
  aliceWallet
);
const receipt = await bananaCoin
  .withWallet(aliceWallet)
  .methods.transfer(recipient, transferAmount)
  .send({ fee: { paymentMethod } })
  .wait();
const transactionFee = receipt.transactionFee!;

// Check the new account's balance.
const aliceBalance = await bananaCoin.methods
  .balance_of_private(aliceAddress)
  .simulate();
expect(aliceBalance).toEqual(mintAmount - transferAmount - transactionFee);

The tree of protocol contract addresses is now an indexed tree​

This is to allow for non-membership proofs for non-protocol contract addresses. As before, the canonical protocol contract addresses point to the index of the leaf of the 'real' computed protocol address.

For example, the canonical DEPLOYER_CONTRACT_ADDRESS is a constant = 2. This is used in the kernels as the contract_address. We calculate the computed_address (currently 0x1665c5fbc1e58ba19c82f64c0402d29e8bbf94b1fde1a056280d081c15b0dac1) and check that this value exists in the indexed tree at index 2. This check already existed and ensures that the call cannot do 'special' protocol contract things unless it is a real protocol contract.

The new check an indexed tree allows is non-membership of addresses of non protocol contracts. This ensures that if a call is from a protocol contract, it must use the canonical address. For example, before this check a call could be from the deployer contract and use 0x1665c5fbc1e58ba19c82f64c0402d29e8bbf94b1fde1a056280d081c15b0dac1 as the contract_address, but be incorrectly treated as a 'normal' call.

- let computed_protocol_contract_tree_root = if is_protocol_contract {
-     0
- } else {
-     root_from_sibling_path(
-         computed_address.to_field(),
-         protocol_contract_index,
-         private_call_data.protocol_contract_sibling_path,
-     )
- };

+ conditionally_assert_check_membership(
+     computed_address.to_field(),
+     is_protocol_contract,
+     private_call_data.protocol_contract_leaf,
+     private_call_data.protocol_contract_membership_witness,
+     protocol_contract_tree_root,
+ );

[Aztec.nr] Changes to note interfaces and note macros​

In this releases we decided to do a large refactor of notes which resulted in the following changes:

  1. We removed NoteHeader and we've introduced a RetrievedNote struct that contains a note and the information originally stored in the NoteHeader.
  2. We removed the pack_content and unpack_content functions from the NoteInterfaceand made notes implement the standard Packable trait.
  3. We renamed the NullifiableNote trait to NoteHash and we've moved the compute_note_hash function to this trait from the NoteInterface trait.
  4. We renamed NoteInterface trait as NoteType and get_note_type_id function as get_id.
  5. The #[note] and #[partial_note] macros now generate both the NoteType and NoteHash traits.
  6. #[custom_note_interface] macro has been renamed to #[custom_note] and it now implements the NoteInterface trait.

This led us to do the following changes to the interfaces:

-pub trait NoteInterface<let N: u32> {
+pub trait NoteType {
    fn get_id() -> Field;
-    fn pack_content(self) -> [Field; N];
-    fn unpack_content(fields: [Field; N]) -> Self;
-    fn get_header(self) -> NoteHeader;
-    fn set_header(&mut self, header: NoteHeader) -> ();
-    fn compute_note_hash(self) -> Field;
}

pub trait NoteHash {
+    fn compute_note_hash(self, storage_slot: Field) -> Field;

    fn compute_nullifier(self, context: &mut PrivateContext, note_hash_for_nullify: Field) -> Field;

-    unconstrained fn compute_nullifier_without_context(self) -> Field;
+    unconstrained fn fn compute_nullifier_without_context(self, storage_slot: Field, contract_address: AztecAddress, note_nonce: Field) -> Field;
}

If you are using #[note] or #[partial_note(...)] macros you will need to delete the implementations of the NullifiableNote (now NoteHash) trait as it now gets auto-generated. Your note will also need to have an owner (a note struct field called owner) as its used in the auto-generated nullifier functions.

If you need a custom implementation of the NoteHash interface use the #[custom_note] macro.

If you used #[note_custom_interface] macro before you will need to update your notes by using the #[custom_note] macro and implementing the compute_note_hash function. If you have no need for a custom implementation of the compute_note_hash function copy the default one:

fn compute_note_hash(self, storage_slot: Field) -> Field {
    let inputs = aztec::protocol_types::utils::arrays::array_concat(self.pack(), [storage_slot]);
    aztec::protocol_types::hash::poseidon2_hash_with_separator(inputs, aztec::protocol_types::constants::DOM_SEP__NOTE_HASH)
}

If you need to keep the custom implementation of the packing functionality, manually implement the Packable trait:

+ use dep::aztec::protocol_types::traits::Packable;

+impl Packable<N> for YourNote {
+    fn pack(self) -> [Field; N] {
+        ...
+    }
+
+    fn unpack(fields: [Field; N]) -> Self {
+        ...
+    }
+}

If you don't provide a custom implementation of the Packable trait, a default one will be generated.

[Aztec.nr] Changes to state variables​

Since we've removed NoteHeader from notes we no longer need to modify the header in the notes when working with state variables. This means that we no longer need to be passing a mutable note reference which led to the following changes in the API.

PrivateImmutable​

For PrivateImmutable the changes are fairly straightforward. Instead of passing in a mutable reference &mut note just pass in note.

impl<Note> PrivateImmutable<Note, &mut PrivateContext> {
-    pub fn initialize<let N: u32>(self, note: &mut Note) -> NoteEmission<Note>
+    pub fn initialize<let N: u32>(self, note: Note) -> NoteEmission<Note>
    where
        Note: NoteInterface<N> + NullifiableNote,
    {
        ...
    }
}

PrivateSet​

For PrivateSet the changes are a bit more involved than the changes in PrivateImmutable. Instead of passing in a mutable reference &mut note to the insert function just pass in note. The remove function now takes in a RetrievedNote<Note> instead of a Note and the get_notes function now returns a vector RetrievedNotes instead of a vector Notes. Note getters now generally return RetrievedNotes so getting a hold of the RetrievedNote for removal should be straightforward.

impl<Note, let N: u32> PrivateSet<Note, &mut PrivateContext>
where
    Note: NoteInterface<N> + NullifiableNote + Eq,
{
-    pub fn insert(self, note: &mut Note) -> NoteEmission<Note> {
+    pub fn insert(self, note: Note) -> NoteEmission<Note> {
        ...
    }

-    pub fn remove(self, note: Note) {
+    pub fn remove(self, retrieved_note: RetrievedNote<Note>) {
        ...
    }

    pub fn get_notes<PREPROCESSOR_ARGS, FILTER_ARGS>(
        self,
        options: NoteGetterOptions<Note, N, PREPROCESSOR_ARGS, FILTER_ARGS>,
-    ) -> BoundedVec<Note, MAX_NOTE_HASH_READ_REQUESTS_PER_CALL> {
+    ) -> BoundedVec<RetrievedNote<Note>, MAX_NOTE_HASH_READ_REQUESTS_PER_CALL> {
        ...
    }
}

- impl<Note, let N: u32> PrivateSet<Note, &mut PublicContext>
- where
-    Note: NoteInterface<N> + NullifiableNote,
- {
-    pub fn insert_from_public(self, note: &mut Note) {
-        create_note_hash_from_public(self.context, self.storage_slot, note);
-    }
- }

PrivateMutable​

For PrivateMutable the changes are similar to the changes in PrivateImmutable.

impl<Note, let N: u32> PrivateMutable<Note, &mut PrivateContext>
where
    Note: NoteInterface<N> + NullifiableNote,
{
-    pub fn initialize(self, note: &mut Note) -> NoteEmission<Note> {
+    pub fn initialize(self, note: Note) -> NoteEmission<Note> {
        ...
    }

-    pub fn replace(self, new_note: &mut Note) -> NoteEmission<Note> {
+    pub fn replace(self, new_note: Note) -> NoteEmission<Note> {
        ...
    }

-    pub fn initialize_or_replace(self, note: &mut Note) -> NoteEmission<Note> {
+    pub fn initialize_or_replace(self, note: Note) -> NoteEmission<Note> {
        ...
    }
}

0.75.0​

Changes to TokenBridge interface​

get_token and get_portal_address functions got merged into a single get_config function that returns a struct containing both the token and portal addresses.

[Aztec.nr] SharedMutable can store size of packed length larger than 1​

SharedMutable has been modified such that now it can store type T which packs to a length larger than 1. This is a breaking change because now SharedMutable requires T to implement Packable trait instead of ToField and FromField traits.

To implement the Packable trait for your type you can use the derive macro:

+ use std::meta::derive;

+ #[derive(Packable)]
pub struct YourType {
    ...
}

[Aztec.nr] Introduction of WithHash<T>​

WithHash<T> is a struct that allows for efficient reading of value T from public storage in private. This is achieved by storing the value with its hash, then obtaining the values via an oracle and verifying them against the hash. This results in in a fewer tree inclusion proofs for values T that are packed into more than a single field.

WithHash<T> is leveraged by state variables like PublicImmutable. This is a breaking change because now we require values stored in PublicImmutable and SharedMutable to implement the Eq trait.

To implement the Eq trait you can use the #[derive(Eq)] macro:

+ use std::meta::derive;

+ #[derive(Eq)]
pub struct YourType {
    ...
}

0.73.0​

There was a complexity leak of fee-related functionality in the token contract. We've came up with a way how to achieve the same objective with the general functionality of the Token contract. This lead to the removal of setup_refund and complete_refund functions from the Token contract and addition of complete_refund function to the FPC.

[Aztec.nr] Improved storage slot allocation​

State variables are no longer assumed to be generic over a type that implements the Serialize trait: instead, they must implement the Storage trait with an N value equal to the number of slots they need to reserve.

For the vast majority of state variables, this simply means binding the serialization length to this trait:

+ impl<T, let N: u32> Storage<N> for MyStateVar<T> where T: Serialize<N> { };

[Aztec.nr] Introduction of Packable trait​

We have introduced a Packable trait that allows types to be serialized and deserialized with a focus on minimizing the size of the resulting Field array. This is in contrast to the Serialize and Deserialize traits, which follows Noir's intrinsic serialization format. This is a breaking change because we now require Packable trait implementation for any type that is to be stored in contract storage.

Example implementation of Packable trait for U128 type from noir::std:

use crate::traits::{Packable, ToField};

let U128_PACKED_LEN: u32 = 1;

impl Packable<U128_PACKED_LEN> for U128 {
    fn pack(self) -> [Field; U128_PACKED_LEN] {
        [self.to_field()]
    }

    fn unpack(fields: [Field; U128_PACKED_LEN]) -> Self {
        U128::from_integer(fields[0])
    }
}

Logs for notes, partial notes, and events have been refactored.​

We're preparing to make log assembly more customisable. These paths have changed.

- use dep::aztec::encrypted_logs::encrypted_note_emission::encode_and_encrypt_note,
+ use dep::aztec::messages::logs::note::encode_and_encrypt_note,

And similar paths for encode_and_encrypt_note_unconstrained, and for events and partial notes.

The way in which logs are assembled in this "default_aes128" strategy is has also changed. I repeat: Encrypted log layouts have changed. The corresponding typescript for note discovery has also been changed, but if you've rolled your own functions for parsing and decrypting logs, those will be broken by this change.

NoteInferface and EventInterface no-longer have a to_be_bytes method.​

You can remove this method from any custom notes or events that you've implemented.

[Aztec.nr] Packing notes resulting in changes in NoteInterface​

Note interface implementation generated by our macros now packs note content instead of serializing it With this change notes are being less costly DA-wise to emit when some of the note struct members implements the Packable trait (this is typically the UintNote which represents value as U128 that gets serialized as 2 fields but packed as 1). This results in the following changes in the NoteInterface:

pub trait NoteInterface<let N: u32> {
-    fn serialize_content(self) -> [Field; N];
+    fn pack_content(self) -> [Field; N];

-    fn deserialize_content(fields: [Field; N]) -> Self;
+    fn unpack_content(fields: [Field; N]) -> Self;

    fn get_header(self) -> NoteHeader;
    fn set_header(&mut self, header: NoteHeader) -> ();
    fn get_note_type_id() -> Field;
    fn compute_note_hash(self) -> Field;
}

[PXE] Cleanup of Contract and ContractClass information getters​

- pxe.isContractInitialized
- pxe.getContractInstance
- pxe.isContractPubliclyDeployed
+ pxe.getContractMetadata

have been merged into getContractMetadata

- pxe.getContractClass
- pxe.isContractClassPubliclyRegistered
- pxe.getContractArtifact
+ pxe.getContractClassMetadata

These functions have been merged into pxe.getContractMetadata and pxe.getContractClassMetadata.

0.72.0​

Some functions in aztec.js and @aztec/accounts are now async​

In our efforts to make libraries more browser-friendly and providing with more bundling options for bb.js (like a non top-level-await version), some functions are being made async, in particular those that access our cryptographic functions.

- AztecAddress.random();
+ await AztecAddress.random();

- getSchnorrAccount();
+ await getSchnorrAccount();

Public logs replace unencrypted logs​

Any log emitted from public is now known as a public log, rather than an unencrypted log. This means methods relating to these logs have been renamed e.g. in the pxe, archiver, txe:

- getUnencryptedLogs(filter: LogFilter): Promise<GetUnencryptedLogsResponse>
- getUnencryptedEvents<T>(eventMetadata: EventMetadataDefinition, from: number, limit: number): Promise<T[]>
+ getPublicLogs(filter: LogFilter): Promise<GetPublicLogsResponse>
+ getPublicEvents<T>(eventMetadata: EventMetadataDefinition, from: number, limit: number): Promise<T[]>

The context method in aztec.nr is now:

- context.emit_unencrypted_log(log)
+ context.emit_public_log(log)

These logs were treated as bytes in the node and as hashes in the protocol circuits. Now, public logs are treated as fields everywhere:

- unencryptedLogs: UnencryptedTxL2Logs
- unencrypted_logs_hashes: [ScopedLogHash; MAX_UNENCRYPTED_LOGS_PER_TX]
+ publicLogs: PublicLog[]
+ public_logs: [PublicLog; MAX_PUBLIC_LOGS_PER_TX]

A PublicLog contains the log (as an array of fields) and the app address.

This PR also renamed encrypted events to private events:

- getEncryptedEvents<T>(eventMetadata: EventMetadataDefinition, from: number, limit: number, vpks: Point[]): Promise<T[]>
+ getPrivateEvents<T>(eventMetadata: EventMetadataDefinition, from: number, limit: number, vpks: Point[]): Promise<T[]>

0.70.0​

[Aztec.nr] Removal of getSiblingPath oracle​

Use getMembershipWitness oracle instead that returns both the sibling path and index.

0.68.0​

[archiver, node, pxe] Remove contract artifacts in node and archiver and store function names instead​

Contract artifacts were only in the archiver for debugging purposes. Instead function names are now (optionally) emitted when registering contract classes

Function changes in the Node interface and Contract Data source interface:

- addContractArtifact(address: AztecAddress, artifact: ContractArtifact): Promise<void>;
+ registerContractFunctionNames(address: AztecAddress, names: Record<string, string>): Promise<void>;

So now the PXE registers this when calling registerContract()

await this.node.registerContractFunctionNames(instance.address, functionNames);

Function changes in the Archiver

- addContractArtifact(address: AztecAddress, artifact: ContractArtifact)
-  getContractArtifact(address: AztecAddress)
+  registerContractFunctionNames(address: AztecAddress, names: Record<string, string>): Promise<void>

[fees, fpc] Changes in setting up FPC as fee payer on AztecJS and method names in FPC​

On AztecJS, setting up PrivateFeePaymentMethod and PublicFeePaymentMethod are now the same. The don't need to specify a sequencer address or which coin to pay in. The coins are set up in the FPC contract!

- paymentMethod: new PrivateFeePaymentMethod(bananaCoin.address,bananaFPC.address,aliceWallet,sequencerAddress),
+ paymentMethod: new PrivateFeePaymentMethod(bananaFPC.address, aliceWallet),

- paymentMethod: new PublicFeePaymentMethod(bananaCoin.address, bananaFPC.address, aliceWallet),
+ paymentMethod: new PublicFeePaymentMethod(bananaFPC.address, aliceWallet),

Changes in FeePaymentMethod class in AztecJS

- getAsset(): AztecAddress;
+ getAsset(): Promise<AztecAddress>;

Changes in the token contract: FPC specific methods, setup_refund() and complete_refund() have minor args rename.

Changes in FPC contract: Rename of args in all of FPC functions as FPC now stores the accepted token address and admin and making it clearer the amounts are corresponding to the accepted token and not fee juice. Also created a public function pull_funds() for admin to clawback any money in the FPC

Expect more changes in FPC in the coming releases!

Name change from contact to sender in PXE API​

contact has been deemed confusing because the name is too similar to contract. For this reason we've decided to rename it:

- await pxe.registerContact(address);
+ await pxe.registerSender(address);
- await pxe.getContacts();
+ await pxe.getSenders();
- await pxe.removeContact(address);
+ await pxe.removeSender(address);

0.67.1​

Noir contracts package no longer exposes artifacts as default export​

To reduce loading times, the package @aztec/noir-contracts.js no longer exposes all artifacts as its default export. Instead, it exposes a ContractNames variable with the list of all contract names available. To import a given artifact, use the corresponding export, such as @aztec/noir-contracts.js/FPC.

Blobs​

We now publish the majority of DA in L1 blobs rather than calldata, with only contract class logs remaining as calldata. This replaces all code that touched the txsEffectsHash. In the rollup circuits, instead of hashing each child circuit's txsEffectsHash to form a tree, we track tx effects by absorbing them into a sponge for blob data (hence the name: spongeBlob). This sponge is treated like the state trees in that we check each rollup circuit 'follows' the next:

- let txs_effects_hash = sha256_to_field(left.txs_effects_hash, right.txs_effects_hash);
+ assert(left.end_sponge_blob.eq(right.start_sponge_blob));
+ let start_sponge_blob = left.start_sponge_blob;
+ let end_sponge_blob = right.end_sponge_blob;

This sponge is used in the block root circuit to confirm that an injected array of all txEffects does match those rolled up so far in the spongeBlob. Then, the txEffects array is used to construct and prove opening of the polynomial representing the blob commitment on L1 (this is done efficiently thanks to the Barycentric formula). On L1, we publish the array as a blob and verify the above proof of opening. This confirms that the tx effects in the rollup circuit match the data in the blob:

- bytes32 txsEffectsHash = TxsDecoder.decode(_body);
+ bytes32 blobHash = _validateBlob(blobInput);

Where blobInput contains the proof of opening and evaluation calculated in the block root rollup circuit. It is then stored and used as a public input to verifying the epoch proof.

0.67.0​

L2 Gas limit of 6M enforced for public portion of TX​

A 12M limit was previously enforced per-enqueued-public-call. The protocol now enforces a stricter limit that the entire public portion of a transaction consumes at most 6,000,000 L2 gas.

[aztec.nr] Renamed Header and associated helpers​

The Header struct has been renamed to BlockHeader, and the get_header() family of functions have been similarly renamed to get_block_header().

- let header = context.get_header_at(block_number);
+ let header = context.get_block_header_at(block_number);

Outgoing Events removed​

Previously, every event which was emitted included:

  • Incoming Header (to convey the app contract address to the recipient)
  • Incoming Ciphertext (to convey the note contents to the recipient)
  • Outgoing Header (served as a backup, to convey the app contract address to the "outgoing viewer" - most likely the sender)
  • Outgoing Ciphertext (served as a backup, encrypting the symmetric key of the incoming ciphertext to the "outgoing viewer" - most likely the sender)

The latter two have been removed from the .emit() functions, so now only an Incoming Header and Incoming Ciphertext will be emitted.

The interface for emitting a note has therefore changed, slightly. No more ovpk's need to be derived and passed into .emit() functions.

- nfts.at(to).insert(&mut new_note).emit(encode_and_encrypt_note(&mut context, from_ovpk_m, to, from));
+ nfts.at(to).insert(&mut new_note).emit(encode_and_encrypt_note(&mut context, to, from));

The getOutgoingNotes function is removed from the PXE interface.

Some aztec.nr library methods' arguments are simplified to remove an outgoing_viewer parameter. E.g. ValueNote::increment, ValueNote::decrement, ValueNote::decrement_by_at_most, EasyPrivateUint::add, EasyPrivateUint::sub.

Further changes are planned, so that:

  • Outgoing ciphertexts (or any kind of abstract ciphertext) can be emitted by a contract, and on the other side discovered and then processed by the contract.
  • Headers will be removed, due to the new tagging scheme.

0.66​

DEBUG env var is removed​

The DEBUG variable is no longer used. Use LOG_LEVEL with one of silent, fatal, error, warn, info, verbose, debug, or trace. To tweak log levels per module, add a list of module prefixes with their overridden level. For example, LOG_LEVEL="info; verbose: aztec:sequencer, aztec:archiver; debug: aztec:kv-store" sets info as the default log level, verbose for the sequencer and archiver, and debug for the kv-store. Module name match is done by prefix.

tty resolve fallback required for browser bundling​

When bundling aztec.js for web, the tty package now needs to be specified as an empty fallback:

resolve: {
  plugins: [new ResolveTypeScriptPlugin()],
  alias: { './node/index.js': false },
  fallback: {
    crypto: false,
    os: false,
    fs: false,
    path: false,
    url: false,
+   tty: false,
    worker_threads: false,
    buffer: require.resolve('buffer/'),
    util: require.resolve('util/'),
    stream: require.resolve('stream-browserify'),
  },
},

0.65​

[aztec.nr] Removed SharedImmutable​

The SharedImmutable state variable has been removed, since it was essentially the exact same as PublicImmutable, which now contains functions for reading from private:

-   foo: SharedImmutable<T, Context>.
+   foo: PublicImmutable<T, Context>.

[aztec.nr] SharedImmutable renamings​

SharedImmutable::read_private and SharedImmutable::read_public were renamed to simply read, since only one of these versions is ever available depending on the current context.

// In private
- let value = storage.my_var.read_private();
+ let value = storage.my_var.read();

// In public
- let value = storage.my_var.read_public();
+ let value = storage.my_var.read();

[aztec.nr] SharedMutable renamings​

SharedMutable getters (get_current_value_in_public, etc.) were renamed by dropping the _in<public|private|unconstrained> suffix, since only one of these versions is ever available depending on the current context.

// In private
- let value = storage.my_var.get_current_value_in_private();
+ let value = storage.my_var.get_current_value();

// In public
- let value = storage.my_var.get_current_value_in_public();
+ let value = storage.my_var.get_current_value();

[aztec.js] Random addresses are now valid​

The AztecAddress.random() function now returns valid addresses, i.e. addresses that can receive encrypted messages and therefore have notes be sent to them. AztecAddress.isValid() was also added to check for validity of an address.

0.63.0​

[PXE] Note tagging and discovery​

PXE's trial decryption of notes has been replaced in favor of a tagging and discovery approach. It is much more efficient and should scale a lot better as the network size increases, since notes can now be discovered on-demand. For the time being, this means that accounts residing on different PXE instances should add senders to their contact list, so notes can be discovered (accounts created on the same PXE instance will be added as senders for each other by default)

+pxe.registerContact(senderAddress)

The note discovery process is triggered automatically whenever a contract invokes the get_notes oracle, meaning no contract changes are expected. Just in case, every contract has now a utility method sync_notes that can trigger the process manually if necessary. This can be useful since now the DebugInfo object that can be obtained when sending a tx with the debug flag set to true no longer contains the notes that were generated in the transaction:

const receipt = await inclusionsProofsContract.methods.create_note(owner, 5n).send().wait({ debug: true });
-const { visibleIncomingNotes } = receipt.debugInfo!;
-expect(visibleIncomingNotes.length).toEqual(1);
+await inclusionsProofsContract.methods.sync_notes().simulate();
+const incomingNotes = await wallet.getIncomingNotes({ txHash: receipt.txHash });
+expect(incomingNotes.length).toEqual(1);

We've decided to replace the old "shield" flow with one leveraging partial notes. This led to a removal of shield and redeem_shield functions and an introduction of transfer_to_private. An advantage of the new approach is that only 1 tx is required and the API of partial notes is generally nicer. For more information on partial notes refer to docs.

[Token contract] Function naming changes​

There have been a few naming changes done for improved consistency. These are the renamings: transfer_public --> transfer_in_public transfer_from --> transfer_in_private mint_public --> mint_to_public burn --> burn_private

0.62.0​

[TXE] Single execution environment​

Thanks to recent advancements in Brillig TXE performs every single call as if it was a nested call, spawning a new ACVM or AVM simulator without performance loss. This ensures every single test runs in a consistent environment and allows for clearer test syntax:

-let my_call_interface = MyContract::at(address).my_function(args);
-env.call_private(my_contract_interface)
+MyContract::at(address).my_function(args).call(&mut env.private());

This implies every contract has to be deployed before it can be tested (via env.deploy or env.deploy_self) and of course it has to be recompiled if its code was changed before TXE can use the modified bytecode.

Uniqueness of L1 to L2 messages​

L1 to L2 messages have been updated to guarantee their uniqueness. This means that the hash of an L1 to L2 message cannot be precomputed, and must be obtained from the MessageSent event emitted by the Inbox contract, found in the L1 transaction receipt that inserted the message:

event MessageSent(uint256 indexed l2BlockNumber, uint256 index, bytes32 indexed hash);

This event now also includes an index. This index was previously required to consume an L1 to L2 message in a public function, and now it is also required for doing so in a private function, since it is part of the message hash preimage. The PrivateContext in aztec-nr has been updated to reflect this:

pub fn consume_l1_to_l2_message(
    &mut self,
    content: Field,
    secret: Field,
    sender: EthAddress,
+   leaf_index: Field,
) {

This change has also modified the internal structure of the archiver database, making it incompatible with previous ones. Last, the API for obtaining an L1 to L2 message membership witness has been simplified to leverage message uniqueness:

getL1ToL2MessageMembershipWitness(
  blockNumber: L2BlockNumber,
  l1ToL2Message: Fr,
- startIndex: bigint,
): Promise<[bigint, SiblingPath<typeof L1_TO_L2_MSG_TREE_HEIGHT>] | undefined>;

Address is now a point​

The address now serves as someone's public key to encrypt incoming notes. An address point has a corresponding address secret, which is used to decrypt the notes encrypted with the address point.

Notes no longer store a hash of the nullifier public keys, and now store addresses​

Because of removing key rotation, we can now store addresses as the owner of a note. Because of this and the above change, we can and have removed the process of registering a recipient, because now we do not need any keys of the recipient.

example_note.nr

-npk_m_hash: Field
+owner: AztecAddress

PXE Interface

-registerRecipient(completeAddress: CompleteAddress)

0.58.0​

[l1-contracts] Inbox's MessageSent event emits global tree index​

Earlier MessageSent event in Inbox emitted a subtree index (index of the message in the subtree of the l2Block). But the nodes and Aztec.nr expects the index in the global L1_TO_L2_MESSAGES_TREE. So to make it easier to parse this, Inbox now emits this global index.

0.57.0​

Changes to PXE API and `ContractFunctionInteraction``​

PXE APIs have been refactored to better reflect the lifecycle of a Tx (execute private -> simulate kernels -> simulate public (estimate gas) -> prove -> send)

  • .simulateTx: Now returns a TxSimulationResult, containing the output of private execution, kernel simulation and public simulation (optional).
  • .proveTx: Now accepts the result of executing the private part of a transaction, so simulation doesn't have to happen again.

Thanks to this refactor, ContractFunctionInteraction has been updated to remove its internal cache and avoid bugs due to its mutable nature. As a result our type-safe interfaces now have to be used as follows:

-const action = MyContract.at(address).method(args);
-await action.prove();
-await action.send().wait();
+const action = MyContract.at(address).method(args);
+const provenTx = await action.prove();
+await provenTx.send().wait();

It's still possible to use .send() as before, which will perform proving under the hood.

More changes are coming to these APIs to better support gas estimation mechanisms and advanced features.

Changes to public calling convention​

Contracts that include public functions (that is, marked with #[public]), are required to have a function public_dispatch(selector: Field) which acts as an entry point. This will be soon the only public function registered/deployed in contracts. The calling convention is updated so that external calls are made to this function.

If you are writing your contracts using Aztec-nr, there is nothing you need to change. The public_dispatch function is automatically generated by the #[aztec] macro.

[Aztec.nr] Renamed unsafe_rand to random​

Since this is an unconstrained function, callers are already supposed to include an unsafe block, so this function has been renamed for reduced verbosity.

-use aztec::oracle::unsafe_rand::unsafe_rand;
+use aztec::oracle::random::random;

-let random_value = unsafe { unsafe_rand() };
+let random_value = unsafe { random() };

[Aztec.js] Removed L2Block.fromFields​

L2Block.fromFields was a syntactic sugar which is causing issues so we've removed it.

-const l2Block = L2Block.fromFields({ header, archive, body });
+const l2Block = new L2Block(archive, header, body);

[Aztec.nr] Removed SharedMutablePrivateGetter​

This state variable was deleted due to it being difficult to use safely.

[Aztec.nr] Changes to NullifiableNote​

The compute_nullifier_without_context function is now unconstrained. It had always been meant to be called in unconstrained contexts (which is why it did not receive the context object), but now that Noir supports trait functions being unconstrained this can be implemented properly. Users must add the unconstrained keyword to their implementations of the trait:

impl NullifiableNote for MyCustomNote {
-    fn compute_nullifier_without_context(self) -> Field {
+    unconstrained fn compute_nullifier_without_context(self) -> Field {

[Aztec.nr] Make TestEnvironment unconstrained​

All of TestEnvironment's functions are now unconstrained, preventing accidentally calling them in a constrained circuit, among other kinds of user error. Becuase they work with mutable references, and these are not allowed to cross the constrained/unconstrained barrier, tests that use TestEnvironment must also become unconstrained. The recommended practice is to make all Noir tests and test helper functions be `unconstrained:

#[test]
-fn test_my_function() {
+unconstrained fn test_my_function() {
    let env = TestEnvironment::new();

[Aztec.nr] removed encode_and_encrypt_note and renamed encode_and_encrypt_note_with_keys to encode_and_encrypt_note​

contract XYZ {
-   use dep::aztec::encrypted_logs::encrypted_note_emission::encode_and_encrypt_note_with_keys;
+   use dep::aztec::encrypted_logs::encrypted_note_emission::encode_and_encrypt_note;
...

-    numbers.at(owner).initialize(&mut new_number).emit(encode_and_encrypt_note_with_keys(&mut context, owner_ovpk_m, owner_ivpk_m, owner));
+    numbers.at(owner).initialize(&mut new_number).emit(encode_and_encrypt_note(&mut context, owner_ovpk_m, owner_ivpk_m, owner));
}

0.56.0​

[Aztec.nr] Changes to contract definition​

We've migrated the Aztec macros to use the newly introduce meta programming Noir feature. Due to being Noir-based, the new macros are less obscure and can be more easily modified.

As part of this transition, some changes need to be applied to Aztec contracts:

  • The top level contract block needs to have the #[aztec] macro applied to it.
  • All #[aztec(name)] macros are renamed to #[name].
  • The storage struct (the one that gets the #[storage] macro applied) but be generic over a Context type, and all state variables receive this type as their last generic type parameter.
+ use dep::aztec::macros::aztec;

#[aztec]
contract Token {
+    use dep::aztec::macros::{storage::storage, events::event, functions::{initializer, private, view, public}};

-    #[aztec(storage)]
-    struct Storage {
+    #[storage]
+    struct Storage<Context> {
-        admin: PublicMutable<AztecAddress>,
+        admin: PublicMutable<AztecAddress, Context>,
-        minters: Map<AztecAddress, PublicMutable<bool>>,
+        minters: Map<AztecAddress, PublicMutable<bool, Context>, Context>,
    }

-    #[aztec(public)]
-    #[aztec(initializer)]
+    #[public]
+    #[initializer]
    fn constructor(admin: AztecAddress, name: str<31>, symbol: str<31>, decimals: u8) {
        ...
    }

-    #[aztec(public)]
-    #[aztec(view)]
-    fn public_get_name() -> FieldCompressedString {
+    #[public]
+    #[view]
    fn public_get_name() -> FieldCompressedString {
        ...
    }

[Aztec.nr] Changes to NoteInterface​

The new macro model prevents partial trait auto-implementation: they either implement the entire trait or none of it. This means users can no longer implement part of NoteInterface and have the rest be auto-implemented.

For this reason we've separated the methods which are auto-implemented and those which needs to be implemented manually into two separate traits: the auto-implemented ones stay in the NoteInterface trace and the manually implemented ones were moved to NullifiableNote (name likely to change):

-#[aztec(note)]
+#[note]
struct AddressNote {
    ...
}

-impl NoteInterface<ADDRESS_NOTE_LEN, ADDRESS_NOTE_BYTES_LEN> for AddressNote {
+impl NullifiableNote for AddressNote {
    fn compute_nullifier(self, context: &mut PrivateContext, note_hash_for_nullify: Field) -> Field {
        ...
    }

    fn compute_nullifier_without_context(self) -> Field {
        ...
    }
}

[Aztec.nr] Changes to contract interface​

The Contract::storage() static method has been renamed to Contract::storage_layout().

-    let fee_payer_balances_slot = derive_storage_slot_in_map(Token::storage().balances.slot, fee_payer);
-    let user_balances_slot = derive_storage_slot_in_map(Token::storage().balances.slot, user);
+    let fee_payer_balances_slot = derive_storage_slot_in_map(Token::storage_layout().balances.slot, fee_payer);
+    let user_balances_slot = derive_storage_slot_in_map(Token::storage_layout().balances.slot, user);

Key rotation removed​

The ability to rotate incoming, outgoing, nullifying and tagging keys has been removed - this feature was easy to misuse and not worth the complexity and gate count cost. As part of this, the Key Registry contract has also been deleted. The API for fetching public keys has been adjusted accordingly:

- let keys = get_current_public_keys(&mut context, account);
+ let keys = get_public_keys(account);

[Aztec.nr] Rework NoteGetterOptions::select​

The select function in both NoteGetterOptions and NoteViewerOptions no longer takes an Option of a comparator, but instead requires an explicit comparator to be passed. Additionally, the order of the parameters has been changed so that they are (lhs, operator, rhs). These two changes should make invocations of the function easier to read:

- options.select(ValueNote::properties().value, amount, Option::none())
+ options.select(ValueNote::properties().value, Comparator.EQ, amount)

0.53.0​

[Aztec.nr] Remove OwnedNote and create UintNote​

OwnedNote allowed having a U128 value in the custom note while ValueNote restricted to just a Field.

We have removed OwnedNote but are introducing a more genric UintNote within aztec.nr

#[aztec(note)]
struct UintNote {
    // The integer stored by the note
    value: U128,
    // The nullifying public key hash is used with the nsk_app to ensure that the note can be privately spent.
    npk_m_hash: Field,
    // Randomness of the note to hide its contents
    randomness: Field,
}

[TXE] logging​

You can now use debug_log() within your contract to print logs when using the TXE

Remember to set the following environment variables to activate debug logging:

export DEBUG="aztec:*"
export LOG_LEVEL="debug"

[Account] no assert in is_valid_impl​

is_valid_impl method in account contract asserted if signature was true. Instead now we will return the verification to give flexibility to developers to handle it as they please.

- let verification = std::ecdsa_secp256k1::verify_signature(public_key.x, public_key.y, signature, hashed_message);
- assert(verification == true);
- true
+ std::ecdsa_secp256k1::verify_signature(public_key.x, public_key.y, signature, hashed_message)

0.49.0​

Key Rotation API overhaul​

Public keys (ivpk, ovpk, npk, tpk) should no longer be fetched using the old get_[x]pk_m methods on the Header struct, but rather by calling get_current_public_keys, which returns a PublicKeys struct with all four keys at once:

+use dep::aztec::keys::getters::get_current_public_keys;

-let header = context.header();
-let owner_ivpk_m = header.get_ivpk_m(&mut context, owner);
-let owner_ovpk_m = header.get_ovpk_m(&mut context, owner);
+let owner_keys = get_current_public_keys(&mut context, owner);
+let owner_ivpk_m = owner_keys.ivpk_m;
+let owner_ovpk_m = owner_keys.ovpk_m;

If using more than one key per account, this will result in very large circuit gate count reductions.

Additionally, get_historical_public_keys was added to support reading historical keys using a historical header:

+use dep::aztec::keys::getters::get_historical_public_keys;

let historical_header = context.header_at(some_block_number);
-let owner_ivpk_m = header.get_ivpk_m(&mut context, owner);
-let owner_ovpk_m = header.get_ovpk_m(&mut context, owner);
+let owner_keys = get_historical_public_keys(historical_header, owner);
+let owner_ivpk_m = owner_keys.ivpk_m;
+let owner_ovpk_m = owner_keys.ovpk_m;

0.48.0​

NoteInterface changes​

compute_note_hash_and_nullifier* functions were renamed as compute_nullifier* and the compute_nullifier function now takes note_hash_for_nullify as an argument (this allowed us to reduce gate counts and the hash was typically computed before). Also compute_note_hash_for_consumption function was renamed as compute_note_hash_for_nullification.

impl NoteInterface<VALUE_NOTE_LEN, VALUE_NOTE_BYTES_LEN> for ValueNote {
-    fn compute_note_hash_and_nullifier(self, context: &mut PrivateContext) -> (Field, Field) {
-        let note_hash_for_nullify = compute_note_hash_for_consumption(self);
-        let secret = context.request_nsk_app(self.npk_m_hash);
-        let nullifier = poseidon2_hash_with_separator([
-            note_hash_for_nullify,
-            secret,
-        ],
-            DOM_SEP__NOTE_NULLIFIER as Field,
-        );
-        (note_hash_for_nullify, nullifier)
-    }
-    fn compute_note_hash_and_nullifier_without_context(self) -> (Field, Field) {
-        let note_hash_for_nullify = compute_note_hash_for_consumption(self);
-        let secret = get_nsk_app(self.npk_m_hash);
-        let nullifier = poseidon2_hash_with_separator([
-            note_hash_for_nullify,
-            secret,
-        ],
-            DOM_SEP__NOTE_NULLIFIER as Field,
-        );
-        (note_hash_for_nullify, nullifier)
-    }

+    fn compute_nullifier(self, context: &mut PrivateContext, note_hash_for_nullify: Field) -> Field {
+        let secret = context.request_nsk_app(self.npk_m_hash);
+        poseidon2_hash_with_separator([
+            note_hash_for_nullify,
+            secret
+        ],
+            DOM_SEP__NOTE_NULLIFIER as Field,
+        )
+    }
+    fn compute_nullifier_without_context(self) -> Field {
+        let note_hash_for_nullify = compute_note_hash_for_nullification(self);
+        let secret = get_nsk_app(self.npk_m_hash);
+        poseidon2_hash_with_separator([
+            note_hash_for_nullify,
+            secret,
+        ],
+            DOM_SEP__NOTE_NULLIFIER as Field,
+        )
+    }
}

Fee Juice rename​

The name of the canonical Gas contract has changed to Fee Juice. Update noir code:

-GasToken::at(contract_address)
+FeeJuice::at(contract_address)

Additionally, NativePaymentMethod and NativePaymentMethodWithClaim have been renamed to FeeJuicePaymentMethod and FeeJuicePaymentMethodWithClaim.

PrivateSet::pop_notes(...)​

The most common flow when working with notes is obtaining them from a PrivateSet via get_notes(...) and then removing them via PrivateSet::remove(...). This is cumbersome and it results in unnecessary constraints due to a redundant note read request checks in the remove function.

For this reason we've implemented pop_notes(...) which gets the notes, removes them from the set and returns them. This tight coupling of getting notes and removing them allowed us to safely remove the redundant read request check.

Token contract diff:

-let options = NoteGetterOptions::with_filter(filter_notes_min_sum, target_amount).set_limit(max_notes);
-let notes = self.map.at(owner).get_notes(options);
-let mut subtracted = U128::from_integer(0);
-for i in 0..options.limit {
-    if i < notes.len() {
-        let note = notes.get_unchecked(i);
-        self.map.at(owner).remove(note);
-        subtracted = subtracted + note.get_amount();
-    }
-}
-assert(minuend >= subtrahend, "Balance too low");
+let options = NoteGetterOptions::with_filter(filter_notes_min_sum, target_amount).set_limit(max_notes);
+let notes = self.map.at(owner).pop_notes(options);
+let mut subtracted = U128::from_integer(0);
+for i in 0..options.limit {
+    if i < notes.len() {
+        let note = notes.get_unchecked(i);
+        subtracted = subtracted + note.get_amount();
+    }
+}
+assert(minuend >= subtrahend, "Balance too low");

Note that pop_notes may not have obtained and removed any notes! The caller must place checks on the returned notes, e.g. in the example above by checking a sum of balances, or by checking the number of returned notes (assert_eq(notes.len(), expected_num_notes)).

0.47.0​

[Aztec sandbox] TXE deployment changes

The way simulated deployments are done in TXE tests has changed to avoid relying on TS interfaces. It is now possible to do it by directly pointing to a Noir standalone contract or workspace:

-let deployer = env.deploy("path_to_contract_ts_interface");
+let deployer = env.deploy("path_to_contract_root_folder_where_nargo_toml_is", "ContractName");

Extended syntax for more use cases:

// The contract we're testing
env.deploy_self("ContractName"); // We have to provide ContractName since nargo it's ready to support multi-contract files

// A contract in a workspace
env.deploy("../path/to/workspace@package_name", "ContractName"); // This format allows locating the artifact in the root workspace target folder, regardless of internal code organization

The deploy function returns a Deployer, which requires performing a subsequent call to without_initializer(), with_private_initializer() or with_public_initializer() just like before in order to actually deploy the contract.

[CLI] Command refactor and unification + aztec test​

Sandbox commands have been cleaned up and simplified. Doing aztec-up now gets you the following top-level commands:

aztec: All the previous commands + all the CLI ones without having to prefix them with cli. Run aztec for help! aztec-nargo: No changes

REMOVED/RENAMED:

  • aztec-sandbox and aztec sandbox: now aztec start --sandbox
  • aztec-builder: now aztec codegen and aztec update

ADDED:

  • aztec test [options]: runs aztec start --txe && aztec-nargo test --oracle-resolver http://aztec:8081 --silence-warnings [options] via docker-compose allowing users to easily run contract tests using TXE

0.45.0​

[Aztec.nr] Remove unencrypted logs from private​

They leak privacy so is a footgun!

0.44.0​

[Aztec.nr] Autogenerate Serialize methods for events​

#[aztec(event)]
struct WithdrawalProcessed {
    who: Field,
    amount: Field,
}

-impl Serialize<2> for WithdrawalProcessed {
-    fn serialize(self: Self) -> [Field; 2] {
-        [self.who.to_field(), self.amount as Field]
-    }
}

[Aztec.nr] rename encode_and_encrypt_with_keys to encode_and_encrypt_note_with_keys​

contract XYZ {
-   use dep::aztec::encrypted_logs::encrypted_note_emission::encode_and_encrypt_with_keys;
+   use dep::aztec::encrypted_logs::encrypted_note_emission::encode_and_encrypt_note_with_keys;
....

-    numbers.at(owner).initialize(&mut new_number).emit(encode_and_encrypt_with_keys(&mut context, owner_ovpk_m, owner_ivpk_m));
+    numbers.at(owner).initialize(&mut new_number).emit(encode_and_encrypt_note_with_keys(&mut context, owner_ovpk_m, owner_ivpk_m));
}

[Aztec.nr] changes to NoteInterface​

compute_nullifier function was renamed to compute_note_hash_and_nullifier and now the function has to return not only the nullifier but also the note hash used to compute the nullifier. The same change was done to compute_nullifier_without_context function. These changes were done because having the note hash exposed allowed us to not having to re-compute it again in destroy_note function of Aztec.nr which led to significant decrease in gate counts (see the optimization PR for more details).

- impl NoteInterface<VALUE_NOTE_LEN, VALUE_NOTE_BYTES_LEN> for ValueNote {
-    fn compute_nullifier(self, context: &mut PrivateContext) -> Field {
-        let note_hash_for_nullify = compute_note_hash_for_consumption(self);
-        let secret = context.request_nsk_app(self.npk_m_hash);
-        poseidon2_hash([
-            note_hash_for_nullify,
-            secret,
-            DOM_SEP__NOTE_NULLIFIER as Field,
-        ])
-    }
-
-    fn compute_nullifier_without_context(self) -> Field {
-        let note_hash_for_nullify = compute_note_hash_for_consumption(self);
-        let secret = get_nsk_app(self.npk_m_hash);
-        poseidon2_hash([
-            note_hash_for_nullify,
-            secret,
-            DOM_SEP__NOTE_NULLIFIER as Field,
-        ])
-    }
- }
+ impl NoteInterface<VALUE_NOTE_LEN, VALUE_NOTE_BYTES_LEN> for ValueNote {
+    fn compute_note_hash_and_nullifier(self, context: &mut PrivateContext) -> (Field, Field) {
+        let note_hash_for_nullify = compute_note_hash_for_consumption(self);
+        let secret = context.request_nsk_app(self.npk_m_hash);
+        let nullifier = poseidon2_hash([
+            note_hash_for_nullify,
+            secret,
+            DOM_SEP__NOTE_NULLIFIER as Field,
+        ]);
+        (note_hash_for_nullify, nullifier)
+    }
+
+    fn compute_note_hash_and_nullifier_without_context(self) -> (Field, Field) {
+        let note_hash_for_nullify = compute_note_hash_for_consumption(self);
+        let secret = get_nsk_app(self.npk_m_hash);
+        let nullifier = poseidon2_hash([
+            note_hash_for_nullify,
+            secret,
+            DOM_SEP__NOTE_NULLIFIER as Field,
+        ]);
+        (note_hash_for_nullify, nullifier)
+    }
+ }

[Aztec.nr] note_getter returns BoundedVec​

The get_notes and view_notes function no longer return an array of options (i.e. [Option<Note>, N_NOTES]) but instead a BoundedVec<Note, N_NOTES>. This better conveys the useful property the old array had of having all notes collapsed at the beginning of the array, which allows for powerful optimizations and gate count reduction when setting the options.limit value.

A BoundedVec has a max_len(), which equals the number of elements it can hold, and a len(), which equals the number of elements it currently holds. Since len() is typically not knwon at compile time, iterating over a BoundedVec looks slightly different than iterating over an array of options:

- let option_notes = get_notes(options);
- for i in 0..option_notes.len() {
-     if option_notes[i].is_some() {
-         let note = option_notes[i].unwrap_unchecked();
-     }
- }
+ let notes = get_notes(options);
+ for i in 0..notes.max_len() {
+     if i < notes.len() {
+         let note = notes.get_unchecked(i);
+     }
+ }

To further reduce gate count, you can iterate over options.limit instead of max_len(), since options.limit is guaranteed to be larger or equal to len(), and smaller or equal to max_len():

- for i in 0..notes.max_len() {
+ for i in 0..options.limit {

[Aztec.nr] static private authwit​

The private authwit validation is now making a static call to the account contract instead of passing over control flow. This is to ensure that it cannot be used for re-entry.

To make this change however, we cannot allow emitting a nullifier from the account contract, since that would break the static call. Instead, we will be changing the spend_private_authwit to a verify_private_authwit and in the auth library emit the nullifier. This means that the "calling" contract will now be emitting the nullifier, and not the account. For example, for a token contract, the nullifier is now emitted by the token contract. However, as this is done inside the auth library, the token contract doesn't need to change much.

The biggest difference is related to "cancelling" an authwit. Since it is no longer in the account contract, you cannot just emit a nullifier from it anymore. Instead it must rely on the token contract providing functionality for cancelling.

There are also a few general changes to how authwits are generated, namely to more easily support the data required for a validity lookup now. Previously we could lookup the message_hash directly at the account contract, now we instead need to use the inner_hash and the contract of the consumer to figure out if it have already been emitted.

A minor extension have been made to the authwit creations to make it easier to sign a specific a hash with a specific caller, e.g., the inner_hash can be provided as {consumer, inner_hash} to the createAuthWit where it previously needed to do a couple of manual steps to compute the outer hash. The computeOuterAuthWitHash have been made internal and the computeAuthWitMessageHash can instead be used to compute the values similarly to other authwit computations.

const innerHash = computeInnerAuthWitHash([Fr.ZERO, functionSelector.toField(), entrypointPackedArgs.hash]);
-const outerHash = computeOuterAuthWitHash(
-    this.dappEntrypointAddress,
-    new Fr(this.chainId),
-    new Fr(this.version),
-    innerHash,
-);
+const messageHash = computeAuthWitMessageHash(
+    { consumer: this.dappEntrypointAddress, innerHash },
+    { chainId: new Fr(this.chainId), version: new Fr(this.version) },
+);

If the wallet is used to compute the authwit, it will populate the chain id and version instead of requiring it to be provided by tha actor.

const innerHash = computeInnerAuthWitHash([Fr.fromString('0xdead')]);
-const outerHash = computeOuterAuthWitHash(wallets[1].getAddress(), chainId, version, innerHash);
-const witness = await wallets[0].createAuthWit(outerHash);
+ const witness = await wallets[0].createAuthWit({ comsumer: accounts[1].address, inner_hash });

0.43.0​

[Aztec.nr] break token.transfer() into transfer and transferFrom​

Earlier we had just one function - transfer() which used authwits to handle the case where a contract/user wants to transfer funds on behalf of another user. To reduce circuit sizes and proof times, we are breaking up transfer and introducing a dedicated transferFrom() function like in the ERC20 standard.

[Aztec.nr] options.limit has to be constant​

The limit parameter in NoteGetterOptions and NoteViewerOptions is now required to be a compile-time constant. This allows performing loops over this value, which leads to reduced circuit gate counts when setting a limit value.

[Aztec.nr] canonical public authwit registry​

The public authwits are moved into a shared registry (auth registry) to make it easier for sequencers to approve for their non-revertible (setup phase) whitelist. Previously, it was possible to DOS a sequencer by having a very expensive authwit validation that fails at the end, now the whitelist simply need the registry.

Notable, this means that consuming a public authwit will no longer emit a nullifier in the account contract but instead update STORAGE in the public domain. This means that there is a larger difference between private and public again. However, it also means that if contracts need to approve, and use the approval in the same tx, it is transient and don't need to go to DA (saving 96 bytes).

For the typescript wallets this is handled so the APIs don't change, but account contracts should get rid of their current setup with approved_actions.

- let actions = AccountActions::init(&mut context, ACCOUNT_ACTIONS_STORAGE_SLOT, is_valid_impl);
+ let actions = AccountActions::init(&mut context, is_valid_impl);

For contracts we have added a set_authorized function in the auth library that can be used to set values in the registry.

- storage.approved_action.at(message_hash).write(true);
+ set_authorized(&mut context, message_hash, true);

[Aztec.nr] emit encrypted logs​

Emitting or broadcasting encrypted notes are no longer done as part of the note creation, but must explicitly be either emitted or discarded instead.

+ use dep::aztec::encrypted_logs::encrypted_note_emission::{encode_and_encrypt, encode_and_encrypt_with_keys};

- storage.balances.sub(from, amount);
+ storage.balances.sub(from, amount).emit(encode_and_encrypt_with_keys(&mut context, from, from));
+ storage.balances.sub(from, amount).emit(encode_and_encrypt_with_keys(&mut context, from_ovpk, from_ivpk));
+ storage.balances.sub(from, amount).discard();

0.42.0​

[Aztec.nr] Unconstrained Context​

Top-level unconstrained execution is now marked by the new UnconstrainedContext, which provides access to the block number and contract address being used in the simulation. Any custom state variables that provided unconstrained functions should update their specialization parameter:

+ use dep::aztec::context::UnconstrainedContext;

- impl MyStateVariable<()> {
+ impl MyStateVariable<UnconstrainedContext> {

[Aztec.nr] Filtering is now constrained​

The filter argument of NoteGetterOptions (typically passed via the with_filter() function) is now applied in a constraining environment, meaning any assertions made during the filtering are guaranteed to hold. This mirrors the behavior of the select() function.

[Aztec.nr] Emitting encrypted notes and logs​

The emit_encrypted_log context function is now encrypt_and_emit_log or encrypt_and_emit_note.

- context.emit_encrypted_log(log1);
+ context.encrypt_and_emit_log(log1);
+ context.encrypt_and_emit_note(note1);

Broadcasting a note will call encrypt_and_emit_note in the background. To broadcast a generic event, use encrypt_and_emit_log with the same encryption parameters as notes require. Currently, only fields and arrays of fields are supported as events.

By default, logs emitted via encrypt_and_emit_log will be siloed with a masked contract address. To force the contract address to be revealed, so everyone can check it rather than just the log recipient, provide randomness = 0.

Public execution migrated to the Aztec Virtual Machine​

What does this mean for me?

It should be mostly transparent, with a few caveats:

  • Not all Noir blackbox functions are supported by the AVM. Only Sha256, PedersenHash, Poseidon2Permutation, Keccak256, and ToRadix are supported.
  • For public functions, context.nullifier_exists(...) will now also consider pending nullifiers.
  • The following methods of PublicContext are not supported anymore: fee_recipient, fee_per_da_gas, fee_per_l2_gas, call_public_function_no_args, static_call_public_function_no_args, delegate_call_public_function_no_args, call_public_function_with_packed_args, set_return_hash, finish. However, in terms of functionality, the new context's interface should be equivalent (unless otherwise specified in this list).
  • Delegate calls are not yet supported in the AVM.
  • If you have types with custom serialization that you use across external contracts calls, you might need to modify its serialization to match how Noir would serialize it. This is a known problem unrelated to the AVM, but triggered more often when using it.
  • A few error messages might change format, so you might need to change your test assertions.

Internal details

Before this change, public bytecode was executed using the same simulator as in private: the ACIR simulator (and internally, the Brillig VM). On the Aztec.nr side, public functions accessed the context through PublicContext.

After this change, public bytecode will be run using the AVM simulator (the simulator for our upcoming zkVM). This bytecode is generated from Noir contracts in two steps: First, nargo compile produces an artifact which has Brillig bytecode for public functions, just as it did before. Second: the avm-transpiler takes that artifact, and it transpiles Brillig bytecode to AVM bytecode. This final artifact can now be deployed and used with the new public runtime.

On the Aztec.nr side, public functions keep accessing the context using PublicContext but the underlying implementation is switch with what formerly was the AvmContext.

0.41.0​

[Aztec.nr] State variable rework​

Aztec.nr state variables have been reworked so that calling private functions in public and vice versa is detected as an error during compilation instead of at runtime. This affects users in a number of ways:

New compile time errors​

It used to be that calling a state variable method only available in public from a private function resulted in obscure runtime errors in the form of a failed _is_some assertion.

Incorrect usage of the state variable methods now results in compile time errors. For example, given the following function:

#[aztec(public)]
fn get_decimals() -> pub u8 {
    storage.decimals.read_private()
}

The compiler will now error out with

Expected type SharedImmutable<_, &mut PrivateContext>, found type SharedImmutable<u8, &mut PublicContext>

The key component is the second generic parameter: the compiler expects a PrivateContext (becuse read_private is only available during private execution), but a PublicContext is being used instead (because of the #[aztec(public)] attribute).

Generic parameters in Storage​

The Storage struct (the one marked with #[aztec(storage)]) should now be generic over a Context type, which matches the new generic parameter of all Aztec.nr libraries. This parameter is always the last generic parameter.

This means that, without any additional features, we'd end up with some extra boilerplate when declaring this struct:

#[aztec(storage)]
- struct Storage {
+ struct Storage<Context> {
-   nonce_for_burn_approval: PublicMutable<Field>,
+   nonce_for_burn_approval: PublicMutable<Field, Context>,
-   portal_address: SharedImmutable<EthAddress>,
+   portal_address: SharedImmutable<EthAddress, Context>,
-   approved_action: Map<Field, PublicMutable<bool>>,
+   approved_action: Map<Field, PublicMutable<bool, Context>, Context>,
}

Because of this, the #[aztec(storage)] macro has been updated to automatically inject this Context generic parameter. The storage declaration does not require any changes.

Removal of Context​

The Context type no longer exists. End users typically didn't use it, but if imported it needs to be deleted.

[Aztec.nr] View functions and interface navigation​

It is now possible to explicitly state a function doesn't perform any state alterations (including storage, logs, nullifiers and/or messages from L2 to L1) with the #[aztec(view)] attribute, similarly to solidity's view function modifier.

    #[aztec(public)]
+   #[aztec(view)]
    fn get_price(asset_id: Field) -> Asset {
        storage.assets.at(asset_id).read()
    }

View functions only generate a StaticCallInterface that doesn't include .call or .enqueue methods. Also, the denomination static has been completely removed from the interfaces, in favor of the more familiar view

- let price = PriceFeed::at(asset.oracle).get_price(0).static_call(&mut context).price;
+ let price = PriceFeed::at(asset.oracle).get_price(0).view(&mut context).price;
#[aztec(private)]
fn enqueue_public_get_value_from_child(target_contract: AztecAddress, value: Field) {
-   StaticChild::at(target_contract).pub_get_value(value).static_enqueue(&mut context);
+   StaticChild::at(target_contract).pub_get_value(value).enqueue_view(&mut context);
}

Additionally, the Noir LSP will now honor "go to definitions" requests for contract interfaces (Ctrl+click), taking the user to the original function implementation.

[Aztec.js] Simulate changes​

  • .simulate() now tracks closer the process performed by .send().wait(), specifically going through the account contract entrypoint instead of directly calling the intended function.
  • wallet.viewTx(...) has been renamed to wallet.simulateUnconstrained(...) to better clarify what it does.

[Aztec.nr] Keys: Token note now stores an owner master nullifying public key hash instead of an owner address​

i.e.

struct TokenNote {
    amount: U128,
-   owner: AztecAddress,
+   npk_m_hash: Field,
    randomness: Field,
}

Creating a token note and adding it to storage now looks like this:

- let mut note = ValueNote::new(new_value, owner);
- storage.a_private_value.insert(&mut note, true);
+ let owner_npk_m_hash = get_npk_m_hash(&mut context, owner);
+ let owner_ivpk_m = get_ivpk_m(&mut context, owner);
+ let mut note = ValueNote::new(new_value, owner_npk_m_hash);
+ storage.a_private_value.insert(&mut note, true, owner_ivpk_m);

Computing the nullifier similarly changes to use this master nullifying public key hash.

0.40.0​

[Aztec.nr] Debug logging​

The function debug_log_array_with_prefix has been removed. Use debug_log_format with {} instead. The special sequence {} will be replaced with the whole array. You can also use {0}, {1}, ... as usual with debug_log_format.

- debug_log_array_with_prefix("Prefix", my_array);
+ debug_log_format("Prefix {}", my_array);

0.39.0​

[Aztec.nr] Mutable delays in SharedMutable​

The type signature for SharedMutable changed from SharedMutable<T, DELAY> to SharedMutable<T, INITIAL_DELAY>. The behavior is the same as before, except the delay can now be changed after deployment by calling schedule_delay_change.

[Aztec.nr] get_public_key oracle replaced with get_ivpk_m​

When implementing changes according to a new key scheme we had to change oracles. What used to be called encryption public key is now master incoming viewing public key.

- use dep::aztec::oracles::get_public_key::get_public_key;
+ use dep::aztec::keys::getters::get_ivpk_m;

- let encryption_pub_key = get_public_key(self.owner);
+ let ivpk_m = get_ivpk_m(context, self.owner);

0.38.0​

[Aztec.nr] Emitting encrypted logs​

The emit_encrypted_log function is now a context method.

- use dep::aztec::log::emit_encrypted_log;
- use dep::aztec::logs::emit_encrypted_log;

- emit_encrypted_log(context, log1);
+ context.emit_encrypted_log(log1);

0.36.0​

FieldNote removed​

FieldNote only existed for testing purposes, and was not a note type that should be used in any real application. Its name unfortunately led users to think that it was a note type suitable to store a Field value, which it wasn't.

If using FieldNote, you most likely want to use ValueNote instead, which has both randomness for privacy and an owner for proper nullification.

SlowUpdatesTree replaced for SharedMutable​

The old SlowUpdatesTree contract and libraries have been removed from the codebase, use the new SharedMutable library instead. This will require that you add a global variable specifying a delay in blocks for updates, and replace the slow updates tree state variable with SharedMutable variables.

+ global CHANGE_ROLES_DELAY_BLOCKS = 5;

struct Storage {
-  slow_update: SharedImmutable<AztecAddress>,
+  roles: Map<AztecAddress, SharedMutable<UserFlags, CHANGE_ROLES_DELAY_BLOCKS>>,
}

Reading from SharedMutable is much simpler, all that's required is to call get_current_value_in_public or get_current_value_in_private, depending on the domain.

- let caller_roles = UserFlags::new(U128::from_integer(slow.read_at_pub(context.msg_sender().to_field()).call(&mut context)));
+ let caller_roles = storage.roles.at(context.msg_sender()).get_current_value_in_public();

Finally, you can remove all capsule usage on the client code or tests, since those are no longer required when working with SharedMutable.

[Aztec.nr & js] Portal addresses​

Deployments have been modified. No longer are portal addresses treated as a special class, being immutably set on creation of a contract. They are no longer passed in differently compared to the other variables and instead should be implemented using usual storage by those who require it. One should use the storage that matches the usecase - likely shared storage to support private and public.

This means that you will likely add the portal as a constructor argument

- fn constructor(token: AztecAddress) {
-    storage.token.write(token);
- }
+ struct Storage {
    ...
+   portal_address: SharedImmutable<AztecAddress>,
+ }
+ fn constructor(token: AztecAddress, portal_address: EthAddress) {
+    storage.token.write(token);
+    storage.portal_address.initialize(portal_address);
+ }

And read it from storage whenever needed instead of from the context.

- context.this_portal_address(),
+ storage.portal_address.read_public(),

[Aztec.nr] Oracles​

Oracle get_nullifier_secret_key was renamed to get_app_nullifier_secret_key and request_nullifier_secret_key function on PrivateContext was renamed as request_app_nullifier_secret_key.

- let secret = get_nullifier_secret_key(self.owner);
+ let secret = get_app_nullifier_secret_key(self.owner);
- let secret = context.request_nullifier_secret_key(self.owner);
+ let secret = context.request_app_nullifier_secret_key(self.owner);

[Aztec.nr] Contract interfaces​

It is now possible to import contracts on another contracts and use their automatic interfaces to perform calls. The interfaces have the same name as the contract, and are automatically exported. Parameters are automatically serialized (using the Serialize<N> trait) and return values are automatically deserialized (using the Deserialize<N> trait). Serialize and Deserialize methods have to conform to the standard ACVM serialization schema for the interface to work!

  1. Only fixed length types are supported
  2. All numeric types become Fields
  3. Strings become arrays of Fields, one per char
  4. Arrays become arrays of Fields following rules 2 and 3
  5. Structs become arrays of Fields, with every item defined in the same order as they are in Noir code, following rules 2, 3, 4 and 5 (recursive)
- context.call_public_function(
-   storage.gas_token_address.read_private(),
-   FunctionSelector::from_signature("pay_fee(Field)"),
-   [42]
- );
-
- context.call_public_function(
-   storage.gas_token_address.read_private(),
-   FunctionSelector::from_signature("pay_fee(Field)"),
-   [42]
- );
-
- let _ = context.call_private_function(
-           storage.subscription_token_address.read_private(),
-           FunctionSelector::from_signature("transfer((Field),(Field),Field,Field)"),
-           [
-            context.msg_sender().to_field(),
-            storage.subscription_recipient_address.read_private().to_field(),
-            storage.subscription_price.read_private(),
-            nonce
-           ]
-  );
+ use dep::gas_token::GasToken;
+ use dep::token::Token;
+
+ ...
+ // Public call from public land
+ GasToken::at(storage.gas_token_address.read_private()).pay_fee(42).call(&mut context);
+ // Public call from private land
+ GasToken::at(storage.gas_token_address.read_private()).pay_fee(42).enqueue(&mut context);
+ // Private call from private land
+ Token::at(asset).transfer(context.msg_sender(), storage.subscription_recipient_address.read_private(), amount, nonce).call(&mut context);

It is also possible to use these automatic interfaces from the local contract, and thus enqueue public calls from private without having to rely on low level context calls.

[Aztec.nr] Rename max block number setter​

The request_max_block_number function has been renamed to set_tx_max_block_number to better reflect that it is not a getter, and that the setting is transaction-wide.

- context.request_max_block_number(value);
+ context.set_tx_max_block_number(value);

[Aztec.nr] Get portal address​

The get_portal_address oracle was removed. If you need to get the portal address of SomeContract, add the following methods to it

#[aztec(private)]
fn get_portal_address() -> EthAddress {
    context.this_portal_address()
}

#[aztec(public)]
fn get_portal_address_public() -> EthAddress {
    context.this_portal_address()
}

and change the call to get_portal_address

- let portal_address = get_portal_address(contract_address);
+ let portal_address = SomeContract::at(contract_address).get_portal_address().call(&mut context);

[Aztec.nr] Required gas limits for public-to-public calls​

When calling a public function from another public function using the call_public_function method, you must now specify how much gas you're allocating to the nested call. This will later allow you to limit the amount of gas consumed by the nested call, and handle any out of gas errors.

Note that gas limits are not yet enforced. For now, it is suggested you use dep::aztec::context::gas::GasOpts::default() which will forward all available gas.

+ use dep::aztec::context::gas::GasOpts;

- context.call_public_function(target_contract, target_selector, args);
+ context.call_public_function(target_contract, target_selector, args, GasOpts::default());

Note that this is not required when enqueuing a public function from a private one, since top-level enqueued public functions will always consume all gas available for the transaction, as it is not possible to handle any out-of-gas errors.

[Aztec.nr] Emitting unencrypted logs​

The emit_unencrypted_logs function is now a context method.

- use dep::aztec::log::emit_unencrypted_log;
- use dep::aztec::log::emit_unencrypted_log_from_private;

- emit_unencrypted_log(context, log1);
- emit_unencrypted_log_from_private(context, log2);
+ context.emit_unencrypted_log(log1);
+ context.emit_unencrypted_log(log2);

0.33​

[Aztec.nr] Storage struct annotation​

The storage struct now identified by the annotation #[aztec(storage)], instead of having to rely on it being called Storage.

- struct Storage {
-    ...
- }
+ #[aztec(storage)]
+ struct MyStorageStruct {
+    ...
+ }

[Aztec.js] Storage layout and note info​

Storage layout and note information are now exposed in the TS contract artifact

- const note = new Note([new Fr(mintAmount), secretHash]);
- const pendingShieldStorageSlot = new Fr(5n); // storage slot for pending_shields
- const noteTypeId = new Fr(84114971101151129711410111011678111116101n); // note type id for TransparentNote
- const extendedNote = new ExtendedNote(
-   note,
-   admin.address,
-   token.address,
-   pendingShieldStorageSlot,
-   noteTypeId,
-   receipt.txHash,
- );
- await pxe.addNote(extendedNote);
+ const note = new Note([new Fr(mintAmount), secretHash]);
+ const extendedNote = new ExtendedNote(
+   note,
+   admin.address,
+   token.address,
+   TokenContract.storage.pending_shields.slot,
+   TokenContract.notes.TransparentNote.id,
+   receipt.txHash,
+ );
+ await pxe.addNote(extendedNote);

[Aztec.nr] rand oracle is now called unsafe_rand​

oracle::rand::rand has been renamed to oracle::unsafe_rand::unsafe_rand. This change was made to communicate that we do not constrain the value in circuit and instead we just trust our PXE.

- let random_value = rand();
+ let random_value = unsafe_rand();

[AztecJS] Simulate and get return values for ANY call and introducing prove()​

Historically it have been possible to "view" unconstrained functions to simulate them and get the return values, but not for public nor private functions. This has lead to a lot of bad code where we have the same function implemented thrice, once in private, once in public and once in unconstrained. It is not possible to call simulate on any call to get the return values! However, beware that it currently always returns a Field array of size 4 for private and public. This will change to become similar to the return values of the unconstrained functions with proper return types.

-    #[aztec(private)]
-    fn get_shared_immutable_constrained_private() -> pub Leader {
-        storage.shared_immutable.read_private()
-    }
-
-    unconstrained fn get_shared_immutable() -> pub Leader {
-        storage.shared_immutable.read_public()
-    }

+    #[aztec(private)]
+    fn get_shared_immutable_private() -> pub Leader {
+        storage.shared_immutable.read_private()
+    }

- const returnValues = await contract.methods.get_shared_immutable().view();
+ const returnValues = await contract.methods.get_shared_immutable_private().simulate();
await expect(
-   asset.withWallet(wallets[1]).methods.update_admin(newAdminAddress).simulate()).rejects.toThrow(
+   asset.withWallet(wallets[1]).methods.update_admin(newAdminAddress).prove()).rejects.toThrow(
        "Assertion failed: caller is not admin 'caller_roles.is_admin'",
);

0.31.0​

[Aztec.nr] Public storage historical read API improvement​

history::public_value_inclusion::prove_public_value_inclusion has been renamed to history::public_storage::public_storage_historical_read, and its API changed slightly. Instead of receiving a value parameter it now returns the historical value stored at that slot.

If you were using an oracle to get the value to pass to prove_public_value_inclusion, drop the oracle and use the return value from public_storage_historical_read instead:

- let value = read_storage();
- prove_public_value_inclusion(value, storage_slot, contract_address, context);
+ let value = public_storage_historical_read(storage_slot, contract_address, context);

If you were proving historical existence of a value you got via some other constrained means, perform an assertion against the return value of public_storage_historical_read instead:

- prove_public_value_inclusion(value, storage_slot, contract_address, context);
+ assert(public_storage_historical_read(storage_slot, contract_address, context) == value);

0.30.0​

[AztecJS] Simplify authwit syntax​

- const messageHash = computeAuthWitMessageHash(accounts[1].address, action.request());
- await wallets[0].setPublicAuth(messageHash, true).send().wait();
+ await wallets[0].setPublicAuthWit({ caller: accounts[1].address, action }, true).send().wait();
const action = asset
    .withWallet(wallets[1])
    .methods.unshield(accounts[0].address, accounts[1].address, amount, nonce);
-const messageHash = computeAuthWitMessageHash(accounts[1].address, action.request());
-const witness = await wallets[0].createAuthWitness(messageHash);
+const witness = await wallets[0].createAuthWit({ caller: accounts[1].address, action });
await wallets[1].addAuthWitness(witness);

Also note some of the naming changes: setPublicAuth -> setPublicAuthWit createAuthWitness -> createAuthWit

[Aztec.nr] Automatic NoteInterface implementation and selector changes​

Implementing a note required a fair amount of boilerplate code, which has been substituted by the #[aztec(note)] attribute.

+ #[aztec(note)]
struct AddressNote {
    address: AztecAddress,
    owner: AztecAddress,
    randomness: Field,
    header: NoteHeader
}

impl NoteInterface<ADDRESS_NOTE_LEN>  for AddressNote {
-    fn serialize_content(self) -> [Field; ADDRESS_NOTE_LEN]{
-        [self.address.to_field(), self.owner.to_field(), self.randomness]
-    }
-
-    fn deserialize_content(serialized_note: [Field; ADDRESS_NOTE_LEN]) -> Self {
-        AddressNote {
-            address: AztecAddress::from_field(serialized_note[0]),
-            owner: AztecAddress::from_field(serialized_note[1]),
-            randomness: serialized_note[2],
-            header: NoteHeader::empty(),
-        }
-    }
-
-    fn compute_note_content_hash(self) -> Field {
-        pedersen_hash(self.serialize_content(), 0)
-    }
-
    fn compute_nullifier(self, context: &mut PrivateContext) -> Field {
        let note_hash_for_nullify = compute_note_hash_for_consumption(self);
        let secret = context.request_nullifier_secret_key(self.owner);
        pedersen_hash([
            note_hash_for_nullify,
            secret.low,
            secret.high,
        ],0)
    }

    fn compute_nullifier_without_context(self) -> Field {
        let note_hash_for_nullify = compute_note_hash_for_consumption(self);
        let secret = get_nullifier_secret_key(self.owner);
        pedersen_hash([
            note_hash_for_nullify,
            secret.low,
            secret.high,
        ],0)
    }

-    fn set_header(&mut self, header: NoteHeader) {
-        self.header = header;
-    }
-
-    fn get_header(note: Self) -> NoteHeader {
-        note.header
-    }

    fn broadcast(self, context: &mut PrivateContext, slot: Field) {
        let encryption_pub_key = get_public_key(self.owner);
        emit_encrypted_log(
            context,
            (*context).this_address(),
            slot,
            Self::get_note_type_id(),
            encryption_pub_key,
            self.serialize_content(),
        );
    }

-    fn get_note_type_id() -> Field {
-        6510010011410111511578111116101
-    }
}

Automatic note (de)serialization implementation also means it is now easier to filter notes using NoteGetterOptions.select via the ::properties() helper:

Before:

let options = NoteGetterOptions::new().select(0, amount, Option::none()).select(1, owner.to_field(), Option::none()).set_limit(1);

After:

let options = NoteGetterOptions::new().select(ValueNote::properties().value, amount, Option::none()).select(ValueNote::properties().owner, owner.to_field(), Option::none()).set_limit(1);

The helper returns a metadata struct that looks like this (if autogenerated)

ValueNoteProperties {
    value: PropertySelector { index: 0, offset: 0, length: 32 },
    owner: PropertySelector { index: 1, offset: 0, length: 32 },
    randomness: PropertySelector { index: 2, offset: 0, length: 32 },
}

It can also be used for the .sort method.

0.27.0​

initializer macro replaces constructor​

Before this version, every contract was required to have exactly one constructor private function, that was used for deployment. We have now removed this requirement, and made constructor a function like any other.

To signal that a function can be used to initialize a contract, you must now decorate it with the #[aztec(initializer)] attribute. Initializers are regular functions that set an "initialized" flag (a nullifier) for the contract. A contract can only be initialized once, and contract functions can only be called after the contract has been initialized, much like a constructor. However, if a contract defines no initializers, it can be called at any time. Additionally, you can define as many initializer functions in a contract as you want, both private and public.

To migrate from current code, simply add an initializer attribute to your constructor functions.

+ #[aztec(initializer)]
#[aztec(private)]
fn constructor() { ... }

If your private constructor was used to just call a public internal initializer, then remove the private constructor and flag the public function as initializer. And if your private constructor was an empty one, just remove it.

0.25.0​

[Aztec.nr] Static calls​

It is now possible to perform static calls from both public and private functions. Static calls forbid any modification to the state, including L2->L1 messages or log generation. Once a static context is set through a static all, every subsequent call will also be treated as static via context propagation.

context.static_call_private_function(targetContractAddress, targetSelector, args);

context.static_call_public_function(targetContractAddress, targetSelector, args);

[Aztec.nr] Introduction to prelude​

A new prelude module to include common Aztec modules and types. This simplifies dependency syntax. For example:

use dep::aztec::protocol_types::address::AztecAddress;
use dep::aztec::{
    context::{PrivateContext, Context}, note::{note_header::NoteHeader, utils as note_utils},
    state_vars::Map
};

Becomes:

use dep::aztec::prelude::{AztecAddress, NoteHeader, PrivateContext, Map};
use dep::aztec::context::Context;
use dep::aztec::notes::utils as note_utils;

This will be further simplified in future versions (See 4496 for further details).

The prelude consists of

[Edit: removed because the prelude no-longer exists]

internal is now a macro​

The internal keyword is now removed from Noir, and is replaced by an aztec(internal) attribute in the function. The resulting behavior is exactly the same: these functions will only be callable from within the same contract.

Before:

#[aztec(private)]
internal fn double(input: Field) -> Field {
    input * 2
}

After:

#[aztec(private)]
#[aztec(internal)]
fn double(input: Field) -> Field {
    input * 2
}

[Aztec.nr] No SafeU120 anymore!​

Noir now have overflow checks by default. So we don't need SafeU120 like libraries anymore.

You can replace it with U128 instead

Before:

SafeU120::new(0)

Now:

U128::from_integer(0)

[Aztec.nr] compute_note_hash_and_nullifier is now autogenerated​

Historically developers have been required to include a compute_note_hash_and_nullifier function in each of their contracts. This function is now automatically generated, and all instances of it in contract code can be safely removed.

It is possible to provide a user-defined implementation, in which case auto-generation will be skipped (though there are no known use cases for this).

[Aztec.nr] Updated naming of state variable wrappers​

We have decided to change the naming of our state variable wrappers because the naming was not clear. The changes are as follows:

  1. Singleton -> PrivateMutable
  2. ImmutableSingleton -> PrivateImmutable
  3. StablePublicState -> SharedImmutable
  4. PublicState -> PublicMutable

This is the meaning of "private", "public" and "shared": Private: read (R) and write (W) from private, not accessible from public Public: not accessible from private, R/W from public Shared: R from private, R/W from public

Note: SlowUpdates will be renamed to SharedMutable once the implementation is ready.

[Aztec.nr] Authwit updates​

Authentication Witnesses have been updates such that they are now cancellable and scoped to a specific consumer. This means that the authwit nullifier must be emitted from the account contract, which require changes to the interface. Namely, the assert_current_call_valid_authwit_public and assert_current_call_valid_authwit in auth.nr will NO LONGER emit a nullifier. Instead it will call a spend_*_authwit function in the account contract - which will emit the nullifier and perform a few checks. This means that the is_valid functions have been removed to not confuse it for a non-mutating function (static). Furthermore, the caller parameter of the "authwits" have been moved "further out" such that the account contract can use it in validation, allowing scoped approvals from the account POV. For most contracts, this won't be changing much, but for the account contract, it will require a few changes.

Before:

#[aztec(public)]
fn is_valid_public(message_hash: Field) -> Field {
    let actions = AccountActions::public(&mut context, ACCOUNT_ACTIONS_STORAGE_SLOT, is_valid_impl);
    actions.is_valid_public(message_hash)
}

#[aztec(private)]
fn is_valid(message_hash: Field) -> Field {
    let actions = AccountActions::private(&mut context, ACCOUNT_ACTIONS_STORAGE_SLOT, is_valid_impl);
    actions.is_valid(message_hash)
}

After:

#[aztec(private)]
fn verify_private_authwit(inner_hash: Field) -> Field {
    let actions = AccountActions::private(&mut context, ACCOUNT_ACTIONS_STORAGE_SLOT, is_valid_impl);
    actions.verify_private_authwit(inner_hash)
}

#[aztec(public)]
fn spend_public_authwit(inner_hash: Field) -> Field {
    let actions = AccountActions::public(&mut context, ACCOUNT_ACTIONS_STORAGE_SLOT, is_valid_impl);
    actions.spend_public_authwit(inner_hash)
}

0.24.0​

Introduce Note Type IDs​

Note Type IDs are a new feature which enable contracts to have multiple Maps with different underlying note types, something that was not possible before. This is done almost without any user intervention, though some minor changes are required.

The mandatory compute_note_hash_and_nullifier now has a fifth parameter note_type_id. Use this instead of storage_slot to determine which deserialization function to use.

Before:

unconstrained fn compute_note_hash_and_nullifier(
    contract_address: AztecAddress,
    nonce: Field,
    storage_slot: Field,
    preimage: [Field; TOKEN_NOTE_LEN]
) -> pub [Field; 4] {
    let note_header = NoteHeader::new(contract_address, nonce, storage_slot);

    if (storage_slot == storage.pending_shields.get_storage_slot()) {
        note_utils::compute_note_hash_and_nullifier(TransparentNote::deserialize_content, note_header, preimage)
    } else if (note_type_id == storage.slow_update.get_storage_slot()) {
        note_utils::compute_note_hash_and_nullifier(FieldNote::deserialize_content, note_header, preimage)
    } else {
        note_utils::compute_note_hash_and_nullifier(TokenNote::deserialize_content, note_header, preimage)
    }

Now:

unconstrained fn compute_note_hash_and_nullifier(
    contract_address: AztecAddress,
    nonce: Field,
    storage_slot: Field,
    note_type_id: Field,
    preimage: [Field; TOKEN_NOTE_LEN]
) -> pub [Field; 4] {
    let note_header = NoteHeader::new(contract_address, nonce, storage_slot);

    if (note_type_id == TransparentNote::get_note_type_id()) {
        note_utils::compute_note_hash_and_nullifier(TransparentNote::deserialize_content, note_header, preimage)
    } else if (note_type_id == FieldNote::get_note_type_id()) {
        note_utils::compute_note_hash_and_nullifier(FieldNote::deserialize_content, note_header, preimage)
    } else {
        note_utils::compute_note_hash_and_nullifier(TokenNote::deserialize_content, note_header, preimage)
    }

The NoteInterface trait now has an additional get_note_type_id() function. This implementation will be autogenerated in the future, but for now providing any unique ID will suffice. The suggested way to do it is by running the Python command shown in the comment below:

impl NoteInterface<N> for MyCustomNote {
    fn get_note_type_id() -> Field {
        // python -c "print(int(''.join(str(ord(c)) for c in 'MyCustomNote')))"
       771216711711511611110978111116101
    }
}

[js] Importing contracts in JS​

@aztec/noir-contracts is now @aztec/noir-contracts.js. You'll need to update your package.json & imports.

Before:

import { TokenContract } from "@aztec/noir-contracts/Token";

Now:

import { TokenContract } from "@aztec/noir-contracts.js/Token";

[Aztec.nr] Aztec.nr contracts location change in Nargo.toml​

Aztec contracts are now moved outside of the yarn-project folder and into noir-projects, so you need to update your imports.

Before:

easy_private_token_contract = {git = "https://github.com/AztecProtocol/aztec-packages/", tag ="v0.23.0", directory = "yarn-project/noir-contracts/contracts/easy_private_token_contract"}

Now, update the yarn-project folder for noir-projects:

easy_private_token_contract = {git = "https://github.com/AztecProtocol/aztec-packages/", tag ="v0.24.0", directory = "noir-projects/noir-contracts/contracts/easy_private_token_contract"}

0.22.0​

Note::compute_note_hash renamed to Note::compute_note_content_hash​

The compute_note_hash function in of the Note trait has been renamed to compute_note_content_hash to avoid being confused with the actual note hash.

Before:

impl NoteInterface for CardNote {
    fn compute_note_hash(self) -> Field {
        pedersen_hash([
            self.owner.to_field(),
        ], 0)
    }

Now:

impl NoteInterface for CardNote {
    fn compute_note_content_hash(self) -> Field {
        pedersen_hash([
            self.owner.to_field(),
        ], 0)
    }

Introduce compute_note_hash_for_consumption and compute_note_hash_for_insertion​

Makes a split in logic for note hash computation for consumption and insertion. This is to avoid confusion between the two, and to make it clear that the note hash for consumption is different from the note hash for insertion (sometimes).

compute_note_hash_for_consumption replaces compute_note_hash_for_read_or_nullify. compute_note_hash_for_insertion is new, and mainly used in `lifecycle.nr``

Note::serialize_content and Note::deserialize_content added to `NoteInterface​

The NoteInterface have been extended to include serialize_content and deserialize_content functions. This is to convey the difference between serializing the full note, and just the content. This change allows you to also add a serialize function to support passing in a complete note to a function.

Before:

impl Serialize<ADDRESS_NOTE_LEN> for AddressNote {
    fn serialize(self) -> [Field; ADDRESS_NOTE_LEN]{
        [self.address.to_field(), self.owner.to_field(), self.randomness]
    }
}
impl Deserialize<ADDRESS_NOTE_LEN> for AddressNote {
    fn deserialize(serialized_note: [Field; ADDRESS_NOTE_LEN]) -> Self {
        AddressNote {
            address: AztecAddress::from_field(serialized_note[0]),
            owner: AztecAddress::from_field(serialized_note[1]),
            randomness: serialized_note[2],
            header: NoteHeader::empty(),
        }
    }

Now

impl NoteInterface<ADDRESS_NOTE_LEN>  for AddressNote {
    fn serialize_content(self) -> [Field; ADDRESS_NOTE_LEN]{
        [self.address.to_field(), self.owner.to_field(), self.randomness]
    }

    fn deserialize_content(serialized_note: [Field; ADDRESS_NOTE_LEN]) -> Self {
        AddressNote {
            address: AztecAddress::from_field(serialized_note[0]),
            owner: AztecAddress::from_field(serialized_note[1]),
            randomness: serialized_note[2],
            header: NoteHeader::empty(),
        }
    }
    ...
}

[Aztec.nr] No storage.init() and Serialize, Deserialize, NoteInterface as Traits, removal of SerializationMethods and SERIALIZED_LEN​

Storage definition and initialization has been simplified. Previously:

struct Storage {
    leader: PublicState<Leader, LEADER_SERIALIZED_LEN>,
    legendary_card: Singleton<CardNote, CARD_NOTE_LEN>,
    profiles: Map<AztecAddress, Singleton<CardNote, CARD_NOTE_LEN>>,
    test: Set<CardNote, CARD_NOTE_LEN>,
    imm_singleton: PrivateImmutable<CardNote, CARD_NOTE_LEN>,
}

impl Storage {
        fn init(context: Context) -> Self {
            Storage {
                leader: PublicMutable::new(
                    context,
                    1,
                    LeaderSerializationMethods,
                ),
                legendary_card: PrivateMutable::new(context, 2, CardNoteMethods),
                profiles: Map::new(
                    context,
                    3,
                    |context, slot| {
                        PrivateMutable::new(context, slot, CardNoteMethods)
                    },
                ),
                test: Set::new(context, 4, CardNoteMethods),
                imm_singleton: PrivateImmutable::new(context, 4, CardNoteMethods),
            }
        }
    }

Now:

struct Storage {
    leader: PublicMutable<Leader>,
    legendary_card: Singleton<CardNote>,
    profiles: Map<AztecAddress, Singleton<CardNote>>,
    test: Set<CardNote>,
    imm_singleton: PrivateImmutable<CardNote>,
}

For this to work, Notes must implement Serialize, Deserialize and NoteInterface Traits. Previously:

use dep::aztec::protocol_types::address::AztecAddress;
use dep::aztec::{
    note::{
        note_header::NoteHeader,
        note_interface::NoteInterface,
        utils::compute_note_hash_for_read_or_nullify,
    },
    oracle::{
        nullifier_key::get_nullifier_secret_key,
        get_public_key::get_public_key,
    },
    log::emit_encrypted_log,
    hash::pedersen_hash,
    context::PrivateContext,
};

// Shows how to create a custom note

global CARD_NOTE_LEN: Field = 1;

impl CardNote {
    pub fn new(owner: AztecAddress) -> Self {
        CardNote {
            owner,
        }
    }

    pub fn serialize(self) -> [Field; CARD_NOTE_LEN] {
        [self.owner.to_field()]
    }

    pub fn deserialize(serialized_note: [Field; CARD_NOTE_LEN]) -> Self {
        CardNote {
            owner: AztecAddress::from_field(serialized_note[1]),
        }
    }

    pub fn compute_note_hash(self) -> Field {
        pedersen_hash([
            self.owner.to_field(),
        ],0)
    }

    pub fn compute_nullifier(self, context: &mut PrivateContext) -> Field {
        let note_hash_for_nullify = compute_note_hash_for_read_or_nullify(CardNoteMethods, self);
        let secret = context.request_nullifier_secret_key(self.owner);
        pedersen_hash([
            note_hash_for_nullify,
            secret.high,
            secret.low,
        ],0)
    }

    pub fn compute_nullifier_without_context(self) -> Field {
        let note_hash_for_nullify = compute_note_hash_for_read_or_nullify(CardNoteMethods, self);
        let secret = get_nullifier_secret_key(self.owner);
        pedersen_hash([
            note_hash_for_nullify,
            secret.high,
            secret.low,
        ],0)
    }

    pub fn set_header(&mut self, header: NoteHeader) {
        self.header = header;
    }

    // Broadcasts the note as an encrypted log on L1.
    pub fn broadcast(self, context: &mut PrivateContext, slot: Field) {
        let encryption_pub_key = get_public_key(self.owner);
        emit_encrypted_log(
            context,
            (*context).this_address(),
            slot,
            encryption_pub_key,
            self.serialize(),
        );
    }
}

fn deserialize(serialized_note: [Field; CARD_NOTE_LEN]) -> CardNote {
    CardNote::deserialize(serialized_note)
}

fn serialize(note: CardNote) -> [Field; CARD_NOTE_LEN] {
    note.serialize()
}

fn compute_note_hash(note: CardNote) -> Field {
    note.compute_note_hash()
}

fn compute_nullifier(note: CardNote, context: &mut PrivateContext) -> Field {
    note.compute_nullifier(context)
}

fn compute_nullifier_without_context(note: CardNote) -> Field {
    note.compute_nullifier_without_context()
}

fn get_header(note: CardNote) -> NoteHeader {
    note.header
}

fn set_header(note: &mut CardNote, header: NoteHeader) {
    note.set_header(header)
}

// Broadcasts the note as an encrypted log on L1.
fn broadcast(context: &mut PrivateContext, slot: Field, note: CardNote) {
    note.broadcast(context, slot);
}

global CardNoteMethods = NoteInterface {
    deserialize,
    serialize,
    compute_note_hash,
    compute_nullifier,
    compute_nullifier_without_context,
    get_header,
    set_header,
    broadcast,
};

Now:

use dep::aztec::{
    note::{
        note_header::NoteHeader,
        note_interface::NoteInterface,
        utils::compute_note_hash_for_read_or_nullify,
    },
    oracle::{
        nullifier_key::get_nullifier_secret_key,
        get_public_key::get_public_key,
    },
    log::emit_encrypted_log,
    hash::pedersen_hash,
    context::PrivateContext,
    protocol_types::{
        address::AztecAddress,
        traits::{Serialize, Deserialize, Empty}
    }
};

// Shows how to create a custom note

global CARD_NOTE_LEN: Field = 1;

impl CardNote {
    pub fn new(owner: AztecAddress) -> Self {
        CardNote {
            owner,
        }
    }
}

impl NoteInterface for CardNote {
    fn compute_note_content_hash(self) -> Field {
        pedersen_hash([
            self.owner.to_field(),
        ],0)
    }

    fn compute_nullifier(self, context: &mut PrivateContext) -> Field {
        let note_hash_for_nullify = compute_note_hash_for_read_or_nullify(self);
        let secret = context.request_nullifier_secret_key(self.owner);
        pedersen_hash([
            note_hash_for_nullify,
            secret.high,
            secret.low,
        ],0)
    }

    fn compute_nullifier_without_context(self) -> Field {
        let note_hash_for_nullify = compute_note_hash_for_read_or_nullify(self);
        let secret = get_nullifier_secret_key(self.owner);
        pedersen_hash([
            note_hash_for_nullify,
            secret.high,
            secret.low,
        ],0)
    }

    fn set_header(&mut self, header: NoteHeader) {
        self.header = header;
    }

    fn get_header(note: CardNote) -> NoteHeader {
        note.header
    }

    fn serialize_content(self) -> [Field; CARD_NOTE_LEN]{
        [self.owner.to_field()]
    }

    fn deserialize_content(serialized_note: [Field; CARD_NOTE_LEN]) -> Self {
        AddressNote {
            owner: AztecAddress::from_field(serialized_note[0]),
            header: NoteHeader::empty(),
        }
    }

    // Broadcasts the note as an encrypted log on L1.
    fn broadcast(self, context: &mut PrivateContext, slot: Field) {
        let encryption_pub_key = get_public_key(self.owner);
        emit_encrypted_log(
            context,
            (*context).this_address(),
            slot,
            encryption_pub_key,
            self.serialize(),
        );
    }
}

Public state must implement Serialize and Deserialize traits.

It is still possible to manually implement the storage initialization (for custom storage wrappers or internal types that don't implement the required traits). For the above example, the impl Storage section would look like this:

impl Storage {
    fn init(context: Context) -> Self {
        Storage {
            leader: PublicMutable::new(
                context,
                1
            ),
            legendary_card: PrivateMutable::new(context, 2),
            profiles: Map::new(
                context,
                3,
                |context, slot| {
                    PrivateMutable::new(context, slot)
                },
            ),
            test: Set::new(context, 4),
            imm_singleton: PrivateImmutable::new(context, 4),
        }
    }
}

0.20.0​

[Aztec.nr] Changes to NoteInterface​

  1. Changing compute_nullifier() to compute_nullifier(private_context: PrivateContext)

    This API is invoked for nullifier generation within private functions. When using a secret key for nullifier creation, retrieve it through:

    private_context.request_nullifier_secret_key(account_address)

    The private context will generate a request for the kernel circuit to validate that the secret key does belong to the account.

    Before:

     pub fn compute_nullifier(self) -> Field {
         let secret = oracle.get_secret_key(self.owner);
         pedersen_hash([
             self.value,
             secret.low,
             secret.high,
         ])
     }

    Now:

     pub fn compute_nullifier(self, context: &mut PrivateContext) -> Field {
         let secret = context.request_nullifier_secret_key(self.owner);
         pedersen_hash([
             self.value,
             secret.low,
             secret.high,
         ])
     }

  2. New API compute_nullifier_without_context().

    This API is used within unconstrained functions where the private context is not available, and using an unverified nullifier key won't affect the network or other users. For example, it's used in compute_note_hash_and_nullifier() to compute values for the user's own notes.

    pub fn compute_nullifier_without_context(self) -> Field {
         let secret = oracle.get_nullifier_secret_key(self.owner);
         pedersen_hash([
             self.value,
             secret.low,
             secret.high,
         ])
     }

    Note that the get_secret_key oracle API has been renamed to get_nullifier_secret_key.

0.18.0​

[Aztec.nr] Remove protocol_types from Nargo.toml​

The protocol_types package is now being reexported from aztec. It can be accessed through dep::aztec::protocol_types.

aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="v3.0.0-nightly.20251231", directory="yarn-project/aztec-nr/aztec" }

[Aztec.nr] key type definition in Map​

The Map class now requires defining the key type in its declaration which must implement the ToField trait.

Before:

struct Storage {
    balances: Map<PublicMutable<Field, FIELD_SERIALIZED_LEN>>
}

let user_balance = balances.at(owner.to_field())

Now:

struct Storage {
    balances: Map<AztecAddress, PublicState<Field, FIELD_SERIALIZED_LEN>>
}

let user_balance = balances.at(owner)

[js] Updated function names​

  • waitForSandbox renamed to waitForPXE in @aztec/aztec.js
  • getSandboxAccountsWallets renamed to getInitialTestAccountsWallets in @aztec/accounts/testing

0.17.0​

[js] New @aztec/accounts package​

Before:

import { getSchnorrAccount } from "@aztec/aztec.js"; // previously you would get the default accounts from the `aztec.js` package:

Now, import them from the new package @aztec/accounts

import { getSchnorrAccount } from "@aztec/accounts";

Typed Addresses​

Address fields in Aztec.nr now is of type AztecAddress as opposed to Field

Before:

unconstrained fn compute_note_hash_and_nullifier(contract_address: Field, nonce: Field, storage_slot: Field, serialized_note: [Field; VALUE_NOTE_LEN]) -> [Field; 4] {
        let note_header = NoteHeader::new(_address, nonce, storage_slot);
        ...

Now:

unconstrained fn compute_note_hash_and_nullifier(
        contract_address: AztecAddress,
        nonce: Field,
        storage_slot: Field,
        serialized_note: [Field; VALUE_NOTE_LEN]
    ) -> pub [Field; 4] {
        let note_header = NoteHeader::new(contract_address, nonce, storage_slot);

Similarly, there are changes when using aztec.js to call functions.

To parse a AztecAddress to BigInt, use .inner Before:

const tokenBigInt = await bridge.methods.token().simulate();

Now:

const tokenBigInt = (await bridge.methods.token().simulate()).inner;

[Aztec.nr] Add protocol_types to Nargo.toml​

aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="v3.0.0-nightly.20251231", directory="yarn-project/aztec-nr/aztec" }
protocol_types = { git="https://github.com/AztecProtocol/aztec-packages/", tag="v3.0.0-nightly.20251231", directory="yarn-project/noir-protocol-circuits/crates/types"}

[Aztec.nr] moving compute_address func to AztecAddress​

Before:

let calculated_address = compute_address(pub_key_x, pub_key_y, partial_address);

Now:

let calculated_address = AztecAddress::compute(pub_key_x, pub_key_y, partial_address);

[Aztec.nr] moving compute_selector to FunctionSelector​

Before:

let selector = compute_selector("_initialize((Field))");

Now:

let selector = FunctionSelector::from_signature("_initialize((Field))");

[js] Importing contracts in JS​

Contracts are now imported from a file with the type's name.

Before:

import { TokenContract } from "@aztec/noir-contracts/types";

Now:

import { TokenContract } from "@aztec/noir-contracts/Token";

[Aztec.nr] Aztec example contracts location change in Nargo.toml​

Aztec contracts are now moved outside of the src folder, so you need to update your imports.

Before:

easy_private_token_contract = {git = "https://github.com/AztecProtocol/aztec-packages/", tag ="v0.16.9", directory = "noir-projects/noir-contracts/contracts/easy_private_token_contract"}

Now, just remove the src folder,:

easy_private_token_contract = {git = "https://github.com/AztecProtocol/aztec-packages/", tag ="v0.17.0", directory = "noir-projects/noir-contracts/contracts/easy_private_token_contract"}