Framework (Aztec.nr, Aztec.js, etc) Release Notes: v4.1.3 → v4.2.0

Date: 2026-04-14
Range: v4.1.3..v4.2.0 (2026-04-02 → 2026-04-14)
Commits: 135 framework-relevant commits

Full migration instructions for every breaking change below live in docs/docs-developers/docs/resources/migration_notes.md.

Breaking Changes

Aztec.nr

• [Aztec.nr] Capsule operations are now scoped by AztecAddress. CapsuleArray::at and all capsules::{store,load,delete,copy} functions require a new scope argument, and the PXE enforces scope access at runtime. (#21533, #22113, #22136)
• [Aztec.nr] Domain-separated tags on every emitted log. Low-level emit_private_log / emit_raw_note_log / emit_public_log have been renamed _unsafe and now take tag as an explicit first parameter. Prefer the higher-level emit / MessageDelivery APIs. (#21910, #22027)
• [Aztec.nr] Public events no longer append the event type selector; a domain-separated tag is prepended at fields[0] instead. Direct consumers of node.getPublicLogs must update their parsing. (#21910)
• [Aztec.nr] Private initialization nullifier now includes init_hash (Poseidon2 of [address, init_hash]). assert_contract_was_initialized_by / _not_initialized_by require an additional init_hash parameter. Contracts with external public functions can no longer be deployed with skipClassPublication: true. (#21427)
• [Aztec.nr] Two separate init nullifiers (private + public) are now emitted. only_self functions skip init checks; external functions called during private init must be #[only_self]. (#20775)
• [Aztec.nr] attempt_note_discovery (and related discovery helpers) now take separate compute_note_hash and compute_note_nullifier functions instead of a combined compute_note_hash_and_nullifier. The combined helper is deprecated. (#21639)
• [Aztec.nr] compute_note_hash_for_nullification is now unconstrained; constrained nullification should use compute_confirmed_note_hash_for_nullification. Note-hash preimage order also changed (storage slot is now first for consistent domain separation). (#21639)
• [Aztec.nr] Ephemeral arrays — internal framework refactor that changes how short-lived arrays are represented in generated circuits. (#22162)
• [Aztec.nr] app-silo getSharedSecret oracle — shared-secret derivation is now app-siloed. Bumps ORACLE_VERSION to 21. (#22020)
• [Aztec.nr] AES128 decrypt oracle now returns Option so callers can handle decryption failure without aborting. (#21696)
• [Aztec.nr] Unused message discovery functions made private; only the supported discovery entry points remain public. (#20831)
• [Aztec.nr] process_message auto-generated utility removed — use offchain_receive + sync_state instead. CustomMessageHandler gains a new scope: AztecAddress parameter. (#20379, #20893)
• [Aztec.nr] Offchain messages now emit the anchor block timestamp. (#21414)
• [Aztec.nr] Event size is now validated at private emission rather than at declaration, enabling dynamic-sized events to compile. (#22168)
• [Aztec.nr] get_random_bytes removed from aztec::utils::random; call the random oracle directly. (#21639)
• [Aztec.nr] storage_slot moved from partial commitment into the note completion hash, enabling cleaner partial-note flows. (#21351)

aztec.js / PXE / Wallet SDK

• [PXE] ALL_SCOPES removed. simulateTx, executeUtility, profileTx, and proveTx now require an explicit AztecAddress[] for scopes. (#22136)
• [aztec.js] GasSettings.default() → GasSettings.fallback(). DEFAULT_GAS_LIMIT and DEFAULT_TEARDOWN_GAS_LIMIT constants removed; limits now derive from protocol maxima. New GasSettings.forEstimation() for simulation with skipTxValidation: true.
• [aztec.js] NO_FROM sentinel replaces AztecAddress.ZERO for bypassing account-contract entrypoints. Multi-call flows must wrap payloads via DefaultMultiCallEntrypoint manually. (#21716)
• [aztec.js] ContractMetadata.isContractInitialized → initializationStatus (tri-state enum: INITIALIZED / UNINITIALIZED / UNKNOWN). (#21754)
• [aztec.js] DeployMethod.send() always returns { contract, receipt, instance }; DeployTxReceipt and DeployWaitOptions removed along with the returnReceipt flag.
• [aztec.js] ExecuteUtilityOptions.scope renamed to scopes: AztecAddress[] to align with PXE / sendTx.
• [aztec.js] getPublicEvents now returns { events, maxLogsHit }; use afterLog for pagination.
• [aztec.js] computeL2ToL1MembershipWitness signature changed — epoch is resolved internally from txHash and returned on the witness. New optional messageIndexInTx disambiguates duplicate messages.
• [aztec.js] TxReceipt now includes epochNumber.
• [aztec.js] EmbeddedWalletOptions consolidated pxeConfig + pxeOptions into a single pxe field (old fields deprecated). (#22348)
• [aztec.js / CLI] Custom-token FPCs removed from the default public setup allowlist. PublicFeePaymentMethod / PrivateFeePaymentMethod and fpc-public / fpc-private CLI payment methods no longer work on public networks; switch to FeeJuicePaymentMethodWithClaim.
• [PXE] PXE rejects registering invalid addresses (e.g., infinity points) as senders, preventing a class of silent tag-computation failures. (#22489, #22026)
• [PXE] Log retrieval requests for contracts not in the current execution context are now rejected. (#22047)
• [Accounts] Insecure SchnorrSingleKeyAccount contract removed. (#21548)

New Features

Aztec.nr

• [Aztec.nr] Custom message handlers — contracts can register handlers for arbitrary offchain message types. (#20379)
• [Aztec.nr] Offchain reception + offchain_receive — standard inbox for offchain messages, processed during sync_state. Utility functions can also emit messages. (#20893, #21422)
• [Aztec.nr] Initialization check added to utility functions. (#21751)
• [Aztec.nr] Runtime-length arrays of sorts and selects. (#22250)
• [Aztec.nr] Compile-time size check for events. (#21024)
• [Aztec.nr] Note hash and nullifier helper functions. (#21189)
• [Aztec.nr] Manual Packable implementations for structs with sub-Field members. (#21576)
• [Aztec.nr] BoundedVec oracle returns are guarded against dirty trailing storage. (#21589)
• [Aztec.nr] env.deploy accepts salt and secret parameters in tests. (#21183)
• [Aztec.nr] All aztec-nr contract logs are prefixed with [aztec-nr] for easier debugging. (#21080)

aztec.js / PXE / Wallet SDK

• [Wallet SDK] Iframe wallets SDK — new SDK for embedding wallet flows in an iframe. (#21978)
• [CLI] cli-wallet ships as a first-class package for scripting wallet operations from the terminal. (#21757)
• [aztec.js] Gas estimation on .send() — callers no longer have to estimate separately. (#21646)
• [aztec.js] Entrypoint replay protection. (#21649)
• [aztec.js] Additional scopes supported on the wallet transaction API and ContractFunctionPattern. (#20487, #20660)
• [aztec.js] Auto-inject contract address into scopes for account deploys. (#20665)
• [PXE] Kernelless simulations by default — dramatically faster simulation for dApp UIs. (#21575)
• [PXE] Minor/major oracle version tracking — incompatible oracle versions now produce actionable error pages. (#22254, #21943)
• [PXE] Sync cache invalidation oracle. (#21459)
• [PXE] syncImmediate verifies blockHash before applying state. (#21556)
• [PXE] warn_log_format used for discarded messages for clearer debugging. (#21053)

Bug Fixes

Aztec.nr / Reference Contracts

• [Aztec.nr] check_notes_order now performs a correct lexicographic multi-key sort. (#21973)
• [Aztec.nr] Subfield note selectors resolve correctly. (#22211)
• [Aztec.nr] #[authorize_once] generates the correct args length. (#22209)
• [Aztec.nr] Out-of-bounds index fixed when using a nonzero offset. (#21613)
• [Aztec.nr] Correct inverted constrained encryption check in message delivery. (#21399)
• [Aztec.nr] Search all note nonces instead of only the note-index nonce. (#21438)
• [Aztec.nr] Warn on unknown note type id. (#21525)

aztec.js / PXE

• [PXE] Prepopulated scopes in simulateViaEntrypoint. (#22464)
• [PXE] executeUtility now respects additionalScopes. (#22411)
• [PXE] Pass user call info from the wallet. (#21937)
• [PXE] Tag computation no longer fails for invalid recipients. (#22163)
• [PXE] Robust error handling in message processing; handle empty/malformed logs. (#21093, #21192)
• [PXE] getSyncedBlockHeader is a concurrency-1 job to prevent IndexedDB tx liveness issues. (#21944)
• [PXE] Reject queries made ahead of the anchor block; use anchor block for getL1ToL2MsgWitness. (#21874, #21872)
• [PXE] Do not reuse tags of partially reverted txs. (#20817)
• [PXE] Include validation reason in simulate error. (#20768)
• [PXE] Warn and return first log instead of throwing on ambiguous log retrieval. (#22044)
• [aztec.js] All account overrides and gas-limit flows work together. (#22173)
• [aztec.js] DeployAccountMethod preserves type through with() chaining. (#22322)
• [aztec.js] AbiDecoder decodes EthAddress, FunctionSelector, and wrapped Field structs. (#21926)
• [Wallet SDK] Custom PrivateKernelProver supported; EmbeddedWalletOptions unified. (#22348)
• [CLI] cli-wallet claim params parse decimal values via Fr.fromString. (#22197)
• [CLI] Peek the claim stack for estimate-gas-only instead of popping it. (#22196)

Improvements

• [Aztec.nr] Use registered accounts as capsule test scopes. (#22171)
• [Aztec.nr] Remove aztec dependency from aztec_sublib. (#22033)
• [PXE] Oracle implementations renamed for consistency; legacy oracle mappings typed and audited. (#22044, #21569, #22018)
• [PXE] Load all accounts before LogService.#getSecretsForSenders (A-779). (#21923)
• [Aztec.nr] Dead globals, to_be_bytes, and old field comparison fns removed in favor of lt. (#22244, #22243, #22249)
• [Aztec.nr] Consistent usage of contract-class-hash function. (#22248)
• [Aztec.nr] Noir upgraded to nightly 2026-04-10 compatibility. (#22393)

Internal / Infrastructure

• Noir toolchain compatibility: removed comptime mutable methods, mut cleanups, nightly-02-27 and nightly-04-10 alignment. (#21801, #20798, #22393)
• aztec compile uses the bundled bb binary rather than relying on $PATH.
• Indefinite retry for prover-node / agent-broker communication. (#22202)
• RPC endpoints for manipulating time in local networks. (#22084)
• Date provider sync from Anvil stdout on every mined block. (#21829)