Merge branch 'next' into merge-train/fairies

Author: AztecBot

docs/docs-developers/docs/aztec-nr/standards/_category_.json

@@ -0,0 +1,6 @@
+{
+  "position": 10,
+  "collapsible": true,
+  "collapsed": true,
+  "label": "Standards"
+}

docs/docs-developers/docs/aztec-nr/standards/aip-20.md

@@ -0,0 +1,112 @@
+---
+title: "AIP-20: Fungible Token"
+sidebar_position: 1
+description: Fungible token standard with private balances, partial-note transfers, and recursive note consumption.
+---
+
+[Source](https://github.com/defi-wonderland/aztec-standards/tree/dev/src/token_contract)
+
+AIP-20 defines a fungible token with support for private balances (stored as notes in the note hash tree), public balances (stored in contract public storage), and a hybrid transfer path between the two.
+
+## Storage layout
+
+The token contract stores its name, symbol, and decimals as immutable public fields. Private balances are held in an `Owned<BalanceSet>` that restricts note access to the balance owner. Public balances use a simple `Map` keyed by address.
+
+```rust
+#[storage]
+struct Storage<Context> {
+    name: PublicImmutable<FieldCompressedString, Context>,
+    symbol: PublicImmutable<FieldCompressedString, Context>,
+    decimals: PublicImmutable<u8, Context>,
+    private_balances: Owned<BalanceSet<Context>, Context>,
+    total_supply: PublicMutable<u128, Context>,
+    public_balances: Map<AztecAddress, PublicMutable<u128, Context>, Context>,
+    minter: PublicImmutable<AztecAddress, Context>,
+    upgrade_authority: PublicImmutable<AztecAddress, Context>,
+    asset: PublicImmutable<AztecAddress, Context>,
+    vault_offset: PublicImmutable<u128, Context>,
+}
+```
+
+The `asset` and `vault_offset` fields exist to support the [AIP-4626 vault pattern](./aip-4626.md). A standalone AIP-20 token that is not used as a vault underlying asset does not need to populate these fields.
+
+## Note count constants
+
+In Aztec, every time a user receives private tokens, a new encrypted note is added to their balance. Over time, a user's balance can be spread across dozens of small notes. A transfer must consume enough of these notes to cover the amount, but each note consumed adds computational overhead (gates) to the zero-knowledge proof the user's device must generate. Without a bound, a single transfer could take minutes to prove. Two constants cap how many notes a single proof handles, keeping proving times practical:
+
+```rust
+global INITIAL_TRANSFER_CALL_MAX_NOTES: u32 = 2;
+global RECURSIVE_TRANSFER_CALL_MAX_NOTES: u32 = 8;
+```
+
+The initial call attempts to settle the transfer with at most two notes. If that is not enough to cover the amount, the contract recurses into itself and tries up to eight notes per recursive call.
+
+A **placeholder address** is used in partial-note flows to signal that a transfer destination is not yet known at the time the sender initiates the operation. This distinguishes "recipient not yet determined" from "recipient is the zero address," and allows offchain indexers to detect [partial-note transfers](#partial-note-transfers) in event logs without decrypting the note contents:
+
+```rust
+global PRIVATE_ADDRESS_MAGIC_VALUE: AztecAddress =
+    AztecAddress::from_field(0x1ea7e01501975545617c2e694d931cb576b691a4a867fed81ebd3264);
+```
+
+## Partial-note transfers
+
+AIP-20 supports partial-note (or "commitment-based") transfers. In Aztec, private functions execute on the user's device before the transaction reaches the network, so they cannot read public state (like a DEX order book or auction result). Partial notes solve this by splitting the operation: the sender privately locks funds into a commitment, and later a public function — which *can* read public state — completes the transfer to the correct recipient. This is what makes private DeFi composability possible.
+
+Concretely, the sender locks funds in a note whose destination address is not yet known. A completer — typically a contract acting as a relayer or settlement layer — later fills in the recipient and finalizes the note.
+
+The sender calls `initialize_transfer_commitment` to create the commitment:
+
+```rust
+#[external("private")]
+fn initialize_transfer_commitment(to: AztecAddress, completer: AztecAddress) -> Field {
+    let commitment = self.internal._initialize_transfer_commitment(to, completer);
+    commitment.to_field()
+}
+```
+
+The returned `Field` is an opaque commitment to the destination and completer. A separate call then subtracts the balance and completes the note:
+
+```rust
+#[external("private")]
+fn transfer_private_to_commitment(
+    from: AztecAddress,
+    commitment: Field,
+    amount: u128,
+    _nonce: Field,
+) {
+    _validate_from_private::<4>(self.context, from);
+
+    self.internal._decrease_private_balance(from, amount, INITIAL_TRANSFER_CALL_MAX_NOTES);
+
+    let completer = self.msg_sender();
+    PartialUintNote::from_field(commitment).complete_from_private(
+        self.context,
+        completer,
+        amount,
+    );
+}
+```
+
+This two-step design is useful in DeFi protocols where the recipient of funds depends on some offchain or asynchronous computation.
+
+## Recursive balance subtraction
+
+When `INITIAL_TRANSFER_CALL_MAX_NOTES` notes are insufficient to cover a transfer, the contract calls itself recursively until the full amount is consumed:
+
+```rust
+#[internal("private")]
+fn _subtract_balance(account: AztecAddress, amount: u128, max_notes: u32) -> u128 {
+    let subtracted = self.storage.private_balances.at(account).try_sub(amount, max_notes);
+    if subtracted >= amount {
+        subtracted - amount
+    } else {
+        assert(subtracted > 0, "Balance too low");
+        let remaining = amount - subtracted;
+        self.call_self.recurse_subtract_balance_internal(account, remaining)
+    }
+}
+```
+
+The recursion terminates when either the full amount has been deducted or the assertion fires.
+
+Without recursion, you would have to either size every circuit for the worst-case note count (making the common case expensive to prove) or fail transfers when the note count exceeds a fixed limit. Recursion gives the best of both worlds: the common case (2 notes) proves fast, while larger balances are handled by chaining multiple smaller proofs. Each recursive call is a separate private kernel circuit, so proving cost scales with the actual note count rather than the worst case.

docs/docs-developers/docs/aztec-nr/standards/aip-4626.md

@@ -0,0 +1,66 @@
+---
+title: "AIP-4626: Tokenized Vault"
+sidebar_position: 3
+description: Yield-bearing vault standard with share conversion across private and public contexts.
+---
+
+[Source](https://github.com/defi-wonderland/aztec-standards/tree/dev/src/token_contract) (extends the AIP-20 token contract)
+
+AIP-4626 extends [AIP-20](./aip-20.md) to describe a tokenized vault: a contract that holds an underlying asset and issues shares representing a proportional claim on that asset. It mirrors the design of ERC-4626 but adapts the share conversion arithmetic for Aztec's `u128` integer type.
+
+## Share conversion
+
+The vault tracks the total supply of shares and a `vault_offset` that prevents inflation attacks on the initial deposit. The conversion functions use integer arithmetic with configurable rounding direction:
+
+```rust
+#[internal("public")]
+fn _convert_to_shares(assets: u128, total_assets: u128, rounding: bool) -> u128 {
+    let mul_term =
+        assets * (self.storage.total_supply.read() + self.storage.vault_offset.read());
+    let denominator = (total_assets + 1);
+    let mut shares = mul_term / denominator;
+    if (rounding == ROUND_UP) & (mul_term % denominator > 0) {
+        shares = shares + 1;
+    }
+    shares
+}
+
+#[internal("public")]
+fn _convert_to_assets(shares: u128, total_assets: u128, rounding: bool) -> u128 {
+    let mul_term = shares * (total_assets + 1);
+    let denominator = (self.storage.total_supply.read() + self.storage.vault_offset.read());
+    let mut assets = mul_term / denominator;
+    if (rounding == ROUND_UP) & (mul_term % denominator > 0) {
+        assets = assets + 1;
+    }
+    assets
+}
+```
+
+The `+ 1` in the denominator and the `vault_offset` together implement the "virtual shares" technique that prevents the first depositor from manipulating the exchange rate for subsequent depositors. Without this protection, an attacker could deposit 1 wei, then donate a large amount of the underlying asset directly to the vault, inflating the share price so that the next depositor's deposit rounds down to zero shares.
+
+Deposits round shares down (in favor of the vault), while redemptions round assets down (also in favor of the vault). This is consistent with ERC-4626 rounding conventions and prevents rounding-based extraction attacks.
+
+## Deposit flow
+
+A public-to-public deposit transfers assets from the caller to the vault, computes the shares due, and mints them to the recipient:
+
+```rust
+#[external("public")]
+fn deposit_public_to_public(from: AztecAddress, to: AztecAddress, assets: u128, _nonce: Field) {
+    self.internal._validate_from_public(from);
+
+    let total_assets = self.internal._total_assets();
+    let shares = self.internal._convert_to_shares(assets, total_assets, ROUND_DOWN);
+
+    // Transfer assets from sender to vault
+    self.call(Token::at(self.storage.asset.read()).transfer_public_to_public(
+        from, self.address, assets, _nonce,
+    ));
+
+    // Mint shares to the recipient
+    self.internal._mint_to_public(to, shares);
+}
+```
+
+The vault exposes similar entry points for the other combinations of private and public contexts (`deposit_private_to_public`, `deposit_public_to_private`, `deposit_private_to_private`). Each variant transfers assets using the corresponding AIP-20 transfer function and then mints shares into the chosen output context.

docs/docs-developers/docs/aztec-nr/standards/aip-721.md

@@ -0,0 +1,71 @@
+---
+title: "AIP-721: Non-Fungible Token"
+sidebar_position: 2
+description: Non-fungible token standard with private ownership, partial-note support, and commitment-based transfers.
+---
+
+[Source](https://github.com/defi-wonderland/aztec-standards/tree/dev/src/nft_contract)
+
+AIP-721 defines a non-fungible token (NFT). Each token is identified by a unique `token_id` field. Tokens can be held privately in the note hash tree or publicly in a map from `token_id` to owner address.
+
+## Storage layout
+
+```rust
+#[storage]
+struct Storage<Context> {
+    symbol: PublicImmutable<FieldCompressedString, Context>,
+    name: PublicImmutable<FieldCompressedString, Context>,
+    private_nfts: Owned<PrivateSet<NFTNote, Context>, Context>,
+    nft_exists: Map<Field, PublicMutable<bool, Context>, Context>,
+    public_owners: Map<Field, PublicMutable<AztecAddress, Context>, Context>,
+    minter: PublicImmutable<AztecAddress, Context>,
+    upgrade_authority: PublicImmutable<AztecAddress, Context>,
+}
+```
+
+`nft_exists` tracks whether a given `token_id` has been minted, while `public_owners` records the current public owner. When an NFT is moved to a private note, the `public_owners` entry is cleared and the NFT is stored as an `NFTNote` in the holder's private set.
+
+## NFTNote and partial-note support
+
+Each private NFT is represented as an `NFTNote` containing only the `token_id`:
+
+```rust
+#[custom_note]
+pub struct NFTNote {
+    pub token_id: Field,
+}
+
+impl NFTNote {
+    pub fn partial(
+        owner: AztecAddress,
+        storage_slot: Field,
+        context: &mut PrivateContext,
+        recipient: AztecAddress,
+        completer: AztecAddress,
+    ) -> PartialNFTNote {
+        let randomness = unsafe { random() };
+        let commitment = compute_partial_commitment(owner, storage_slot, randomness);
+        // ... creates encrypted log and validity commitment
+        let partial_note = PartialNFTNote { commitment };
+        let validity_commitment = partial_note.compute_validity_commitment(completer);
+        context.push_nullifier(validity_commitment);
+        partial_note
+    }
+}
+```
+
+The `partial` constructor creates a `PartialNFTNote` whose `commitment` field commits to the future owner and storage slot. Without some form of access control, any party could call the completion function and claim the NFT for themselves. The validity commitment prevents this — it is pushed as a nullifier, and only the designated completer can produce the matching preimage needed to finalize the note. This mirrors the partial-note pattern in [AIP-20](./aip-20.md) but applies it to NFT transfers.
+
+## Partial-note transfer commitment
+
+The external entry point for initiating a partial NFT transfer is:
+
+```rust
+#[external("private")]
+fn initialize_transfer_commitment(to: AztecAddress, completer: AztecAddress) -> Field {
+    let commitment = self.internal._initialize_transfer_commitment(to, completer);
+    commitment.commitment()
+}
+```
+
+This function returns `commitment.commitment()` (the raw commitment field), whereas the AIP-20 equivalent returns `commitment.to_field()`. The difference reflects the distinct internal types — `PartialNFTNote` vs `PartialUintNote` — but both return an opaque `Field` to the caller.

docs/docs-developers/docs/aztec-nr/standards/dripper.md

@@ -0,0 +1,9 @@
+---
+title: Dripper (Development Faucet)
+sidebar_position: 6
+description: Convenience faucet for minting tokens into private or public balances during development.
+---
+
+[Source](https://github.com/defi-wonderland/aztec-standards/tree/dev/src/dripper)
+
+The `aztec-standards` repository also ships a **Dripper** contract — a convenience faucet for minting tokens into private or public balances during development. It is not a formal AIP standard and should not be used in production.

docs/docs-developers/docs/aztec-nr/standards/escrow.md

@@ -0,0 +1,79 @@
+---
+title: Escrow
+sidebar_position: 4
+description: Minimal token and NFT custody contract with salt-based authorization.
+---
+
+[Source](https://github.com/defi-wonderland/aztec-standards/tree/dev/src/escrow_contract)
+
+The Escrow standard provides a minimal contract for holding tokens or NFTs on behalf of a single owner. Rather than storing the owner in mutable private state — which would require note discovery and decryption on every authorization check — the owner is encoded in the contract's own `salt` and thus baked into the contract address at deploy time. This makes authorization a simple field comparison against immutable deployment parameters: cheaper, simpler, and impossible to front-run.
+
+## Escrow contract
+
+```rust
+#[aztec]
+pub contract Escrow {
+    #[external("private")]
+    fn withdraw(token: AztecAddress, amount: u128, recipient: AztecAddress) {
+        self.internal._assert_msg_sender();
+        self.call(Token::at(token).transfer_private_to_private(
+            self.address, recipient, amount, 0,
+        ));
+    }
+
+    #[external("private")]
+    fn withdraw_nft(nft: AztecAddress, token_id: Field, recipient: AztecAddress) {
+        self.internal._assert_msg_sender();
+        self.call(NFT::at(nft).transfer_private_to_private(
+            self.address, recipient, token_id, 0,
+        ));
+    }
+
+    #[internal("private")]
+    fn _assert_msg_sender() {
+        let msg_sender = self.msg_sender();
+        let escrow_instance: ContractInstance = get_contract_instance(self.address);
+        assert(AztecAddress::from_field(escrow_instance.salt) == msg_sender, "Not Authorized");
+    }
+}
+```
+
+The authorization check in `_assert_msg_sender` reads the `salt` field of the escrow's own `ContractInstance` and compares it against `msg_sender`. Because the `ContractInstance` is fixed at deployment time, this check cannot be spoofed by manipulating storage after deployment.
+
+## Escrow logic library
+
+A DeFi protocol (like a lending market or DEX) often needs to give each user a personal escrow to hold collateral or pending settlements. The standard ships a companion library that lets the parent contract deterministically compute escrow addresses from its own address and the user's keys — no onchain deployment transaction required:
+
+```rust
+#[contract_library_method]
+pub fn _get_escrow(
+    context: &mut PrivateContext,
+    escrow_class_id: Field,
+    master_secret_keys: MasterSecretKeys,
+) -> AztecAddress {
+    let computed_public_keys: PublicKeys = _secret_keys_to_public_keys(master_secret_keys);
+    let escrow_instance = ContractInstance {
+        salt: context.this_address().to_field(),
+        deployer: AztecAddress::from_field(0),
+        contract_class_id: ContractClassId::from_field(escrow_class_id),
+        initialization_hash: 0,
+        public_keys: computed_public_keys,
+    };
+    escrow_instance.to_address()
+}
+
+#[contract_library_method]
+pub fn _share_escrow(
+    context: &mut PrivateContext,
+    account: AztecAddress,
+    escrow: AztecAddress,
+    master_secret_keys: MasterSecretKeys,
+) {
+    let event_struct = EscrowDetailsLogContent { escrow, master_secret_keys };
+    emit_event_in_private(context, event_struct).deliver_to(
+        account, MessageDelivery.ONCHAIN_CONSTRAINED,
+    );
+}
+```
+
+`_get_escrow` reconstructs the escrow address deterministically from the calling contract's address (used as the salt) and a set of master secret keys. `_share_escrow` emits an encrypted log so that the designated `account` can discover the escrow address and the keys needed to access its notes. Without this notification, the user's PXE would have no way to find the escrow or decrypt notes held there. The `ONCHAIN_CONSTRAINED` delivery mode ensures the log is validated against the note hash tree before the recipient's PXE trusts it.

docs/docs-developers/docs/aztec-nr/standards/generic-proxy.md

@@ -0,0 +1,42 @@
+---
+title: Generic Proxy
+sidebar_position: 5
+description: Forwarding layer for account abstraction that routes calls by argument count.
+---
+
+In Aztec, account contracts authorize every transaction the user sends and must be able to forward calls to any contract. However, Noir requires function signatures to be known at compile time, so an account contract cannot call an arbitrary function with an arbitrary number of arguments in a single generic entrypoint.
+
+The Generic Proxy contract solves this by providing a fixed set of forwarding functions — one per argument count — that the account contract can call. This avoids hard-coding every possible target function signature while keeping the account contract simple.
+
+```rust
+#[aztec]
+pub contract GenericProxy {
+    #[external("private")]
+    fn forward_private_0(target: AztecAddress, selector: FunctionSelector) {
+        let _ = self.context.call_private_function_no_args(target, selector);
+    }
+
+    #[external("private")]
+    fn forward_private_4(target: AztecAddress, selector: FunctionSelector, args: [Field; 4]) {
+        let _ = self.context.call_private_function(target, selector, args);
+    }
+
+    #[external("private")]
+    fn forward_private_4_and_return(
+        target: AztecAddress,
+        selector: FunctionSelector,
+        args: [Field; 4],
+    ) -> Field {
+        let returns: Field =
+            self.context.call_private_function(target, selector, args).get_preimage();
+        returns
+    }
+    // ... forward_private_1 through forward_private_8
+}
+```
+
+The proxy exposes a family of `forward_private_N` functions, each accepting a different fixed argument count. Because Noir's type system requires array lengths to be known at compile time, the contract implements one overload per arity rather than a single variadic function. The `_and_return` variant captures the return value from the callee and passes it back to the caller.
+
+:::note
+The Generic Proxy does not implement any access control by itself. Callers are responsible for ensuring that forwarding to `target` is appropriate. In most protocols, the proxy is called from within an account contract that enforces its own authorization rules before delegating to the proxy.
+:::