docs: fix aztec-nr v4.2.0 documentation issues from audit (backport #22166) (#22227)

## Summary

Backport of #22166
to v4-next.

Fixes 52 documentation issues across aztec-nr doc pages (deprecated
import paths, missing API parameters, incorrect method names, wrong
dependency URLs, etc.).

## Conflict resolution

All 20 conflicts were modify/delete in
`docs/developer_versioned_docs/version-v4.2.0-aztecnr-rc.2/` — this
versioned docs directory does not exist on v4-next, so the deletions
were accepted. The 18 `docs-developers/` source files merged cleanly.

## Commits

1. Cherry-pick with conflicts (original attempt)
2. Conflict resolution (remove versioned docs that don't exist on
v4-next)
3. No build fixes needed (docs-only change)

ClaudeBox log: https://claudebox.work/s/78234c172376f4ce?run=1

Author: critesjosh

docs/docs-developers/docs/aztec-nr/compiling_contracts.md

@@ -33,7 +33,7 @@ Use generated interfaces instead of manual function calls:
 
 ```rust
 contract MyContract {
-    use dep::token::Token;
+    use token::Token;
 
     #[external("private")]
     fn transfer_tokens(token_address: AztecAddress, recipient: AztecAddress, amount: u128) {

docs/docs-developers/docs/aztec-nr/debugging.md

@@ -5,8 +5,6 @@ tags: [debugging, errors, logging, local_network, aztec.nr]
 description: This guide shows you how to debug issues in your Aztec contracts.
 ---
 
-<!-- need to move some into aztec.js  -->
-
 This guide shows you how to debug issues in your Aztec development environment.
 
 ## Prerequisites
@@ -160,7 +158,7 @@ link.click();
 
 ## Interpret error messages
 
-### Kernel circuit errors (2xxx)
+### Circuit and protocol errors
 
 - **Private kernel errors (2xxx)**: Issues with private function execution
 - **Public kernel errors (3xxx)**: Issues with public function execution
@@ -218,7 +216,7 @@ await wallet.getContractMetadata(myContractInstance.address);
 
 ### Decode L1 errors
 
-Check hex errors against [Errors.sol](https://github.com/AztecProtocol/aztec-packages/blob/master/l1-contracts/src/core/libraries/Errors.sol)
+Check hex errors against [Errors.sol](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/l1-contracts/src/core/libraries/Errors.sol)
 
 ## Tips
 

docs/docs-developers/docs/aztec-nr/framework-description/advanced/how_to_use_capsules.md

@@ -12,22 +12,26 @@ Capsules provide per-contract non-volatile storage in the PXE. Data is stored lo
 ```rust
 use aztec::oracle::capsules;
 
-// Inside a contract function, use self.address for contract_address
-let contract_address: AztecAddress = self.address;
+// Capsule operations are unconstrained, so these values are typically
+// passed in as parameters from the calling context.
+let contract_address: AztecAddress = /* self.address */;
 let slot: Field = 1;
+// scope is an AztecAddress used for capsule isolation, allowing multiple
+// independent namespaces within the same contract.
+let scope: AztecAddress = /* e.g. the account address */;
 
 // Store data at a slot (overwrites existing data)
-capsules::store(contract_address, slot, value);
+capsules::store(contract_address, slot, value, scope);
 
 // Load data (returns Option<T>)
-let result: Option<MyStruct> = capsules::load(contract_address, slot);
+let result: Option<MyStruct> = capsules::load(contract_address, slot, scope);
 
 // Delete data at a slot
-capsules::delete(contract_address, slot);
+capsules::delete(contract_address, slot, scope);
 
 // Copy contiguous slots (supports overlapping regions)
-// copy(contract_address, src_slot, dst_slot, num_entries: u32)
-capsules::copy(contract_address, src_slot, dst_slot, 3);
+// copy(contract_address, src_slot, dst_slot, num_entries: u32, scope)
+capsules::copy(contract_address, src_slot, dst_slot, 3, scope);
 ```
 
 Types must implement `Serialize` and `Deserialize` traits.
@@ -42,12 +46,12 @@ All capsule operations are `unconstrained`. Data loaded from capsules should be
 
 ```rust
 use aztec::capsules::CapsuleArray;
-use protocol::hash::sha256_to_field;
+use aztec::protocol::hash::sha256_to_field;
 
 // Use a hash for base_slot to avoid collisions with other storage
 global BASE_SLOT: Field = sha256_to_field("MY_CONTRACT::MY_ARRAY".as_bytes());
 
-let array: CapsuleArray<Field> = CapsuleArray::at(contract_address, BASE_SLOT);
+let array: CapsuleArray<Field> = CapsuleArray::at(contract_address, BASE_SLOT, scope);
 
 array.push(value);             // Append to end
 let value = array.get(index);  // Read at index (throws if out of bounds)

docs/docs-developers/docs/aztec-nr/framework-description/advanced/partial_notes.md

@@ -18,7 +18,7 @@ Let's say, for example, we have a `UintNote`:
 
 The `UintNote` struct itself only contains the `value` field. Additional fields including `owner`, `randomness`, and `storage_slot` are passed as parameters during note hash computation.
 
-When creating the note locally during private execution, the `owner` and `storage_slot` are known, but the `value` potentially is not (e.g., it depends on some onchain dynamic variable). First, a **partial note** can be created during private execution that commits to the `owner`, `randomness`, and `storage_slot`, and then the note is *"completed"* to create a full note by later adding the `value` field, usually during public execution.
+When creating the note locally during private execution, the `owner` and `storage_slot` are known, but the `value` potentially is not (e.g., it depends on some onchain dynamic variable). First, a **partial note** can be created during private execution that commits to the `owner` and `randomness`, and then the note is *"completed"* to create a full note by later adding the `storage_slot` and `value` fields, usually during public execution.
 
 <Image img={require("@site/static/img/partial-notes.png")} />
 
@@ -44,14 +44,14 @@ The `UintNote` struct contains only the `value` field:
 
 **Phase 1: Partial Commitment (Private Execution)**
 
-The private fields (`owner`, `randomness`, and `storage_slot`) are committed during local, private execution:
+The private fields (`owner` and `randomness`) are committed during local, private execution:
 
 #include_code compute_partial_commitment /noir-projects/aztec-nr/uint-note/src/uint_note.nr rust
 
 This creates a partial note commitment:
 
 ```
-partial_commitment = H(owner, storage_slot, randomness)
+partial_commitment = H(owner, randomness)
 ```
 
 **Phase 2: Note Completion (Public Execution)**
@@ -63,8 +63,8 @@ The note is completed by hashing the partial commitment with the public value:
 The resulting structure is a nested commitment:
 
 ```
-note_hash = H(H(owner, storage_slot, randomness), value)
-          = H(partial_commitment, value)
+note_hash = H(H(owner, randomness), storage_slot, value)
+          = H(partial_commitment, storage_slot, value)
 ```
 
 ## Universal Note Format
@@ -73,14 +73,13 @@ All notes in Aztec use the partial note format internally, even when all data is
 
 When a note is created with all fields known (including `owner`, `storage_slot`, `randomness`, and `value`):
 
-1. A partial commitment is computed from the private fields (`owner`, `storage_slot`, `randomness`)
-2. The partial commitment is immediately completed with the `value` field
+1. A partial commitment is computed from the private fields (`owner`, `randomness`)
+2. The partial commitment is immediately completed with the `storage_slot` and `value` fields
 
 #include_code compute_note_hash /noir-projects/aztec-nr/uint-note/src/uint_note.nr rust
 
 This two-step process ensures that notes with identical field values produce identical note hashes, regardless of whether they were created as partial notes or complete notes.
 
-<Image img={require("@site/static/img/shrek.jpeg")} />
 
 ## Partial Notes in Practice
 

docs/docs-developers/docs/aztec-nr/framework-description/advanced/writing_efficient_contracts.md

@@ -95,9 +95,9 @@ To get a sense of things, here is a table of gate counts for common operations:
 | ~75   | Hashing 3 fields with Poseidon2                                                |
 | 3500  | Reading a value from a tree (public data tree, note hash tree, nullifier tree) |
 | 4000  | Reading a delayed public mutable read                                          |
-| X000  | Calculating sha256                                                             |
-| X000  | Constrained encryption of a log of Y fields                                    |
-| X000  | Constrained encryption and tag a log of Y fields                               |
+| ~5,000 | Calculating sha256 (varies by input size) |
+| Varies | Constrained encryption of a private log (depends on field count) |
+| Varies | Constrained encryption and tagging of a private log (depends on field count) |
 
 ### Optimization: use arithmetic instead of non-arithmetic operations
 
@@ -106,7 +106,7 @@ Because the underlying equation in the proving backend makes use of multiplicati
 For example:
 
 ```rust
-comptime global TWO_POW_32: Field = 2.pow_32(16);
+comptime global TWO_POW_16: Field = 2.pow_32(16);
 // ...
 {
     #[external("private")]
@@ -116,7 +116,7 @@ comptime global TWO_POW_32: Field = 2.pow_32(16);
 
     #[external("private")]
     fn mul_efficient(number: Field) -> u128 {
-        (number * TWO_POW_32) as u128
+        (number * TWO_POW_16) as u128
     } // 5184 gates (60 gates less)
 }
 ```
@@ -153,7 +153,7 @@ For example, use boolean equality effectively instead of `>=`:
             }
         }
         sum
-    } // 45068 gates (751 gates less)
+    } // 45068 gates (751 gates more due to the boolean operations, but the pattern demonstrates how to avoid range checks)
 }
 ```
 
@@ -279,9 +279,12 @@ Like with sqrt, we have the inefficient function that does the sort with constra
         // Safety: calculate in unconstrained function, then constrain the result
         let sorted_array = unsafe { super::sort_array(array) };
         // constrain that sorted_array elements are sorted
-        for i in 0..super::ARRAY_SIZE as u32 {
+        for i in 0..super::ARRAY_SIZE as u32 - 1 {
             assert(sorted_array[i] <= sorted_array[i + 1], "array should be sorted");
         }
+        // Note: A production implementation should also verify that sorted_array is a
+        // permutation of the input array to prevent a malicious prover from returning
+        // arbitrary sorted values.
         sorted_array
     } // 5870 gates (953 gates less) for 10 elements, 12582 gates for 100 elements (115198 gates less)
 }
@@ -309,7 +312,7 @@ Note: The stdlib provides a highly optimized version of sort on arrays, `array.s
 ```rust
     #[external("private")]
     fn sort_stdlib(array: [u32; super::ARRAY_SIZE]) -> [u32; super::ARRAY_SIZE] {
-        array.sort();
+        array.sort()
     } // 5943 gates (880 gates less) for 10 elements, 13308 gates for 100 elements (114472 gates less)
 ```
 

docs/docs-developers/docs/aztec-nr/framework-description/contract_structure.md

@@ -98,15 +98,16 @@ use aztec::macros::aztec;
 pub contract MyContract {
     use aztec::{
         macros::storage,
-        state_vars::{PrivateMutable, PublicMutable}
+        state_vars::{Owned, PrivateMutable, PublicMutable}
     };
+    use uint_note::UintNote;
 
     // The storage struct can have any name, but is typically called `Storage`. It must have the `#[storage]` macro applied to it.
     // This struct must also have a generic type called C or Context.
     #[storage]
     struct Storage<Context> {
         // A private numeric value which can change over time. This value will be hidden, and only those with the secret can know its current value.
-        my_private_state_variable: Owned<PrivateMutable<NoteType, Context>>,
+        my_private_state_variable: Owned<PrivateMutable<UintNote, Context>, Context>,
         // A public numeric value which can change over time. This value will be known to everyone and is equivalent to the Solidity example above.
         my_public_state_variable: PublicMutable<u128, Context>,
     }
@@ -142,6 +143,7 @@ use aztec::macros::aztec;
 #[aztec]
 contract MyContract {
     use aztec::macros::functions::external;
+    use aztec::protocol::address::AztecAddress;
 
     #[external("private")]
     fn my_private_function(parameter_a: u128, parameter_b: AztecAddress) {
@@ -154,7 +156,7 @@ contract MyContract {
     }
 
     #[external("utility")]
-    fn my_utility_function(parameter_a: u128, parameter_b: AztecAddress) {
+    unconstrained fn my_utility_function(parameter_a: u128, parameter_b: AztecAddress) {
         // ...
     }
 }

docs/docs-developers/docs/aztec-nr/framework-description/contract_upgrades.md

@@ -41,6 +41,13 @@ fn update_to(new_class_id: ContractClassId) {
 }
 ```
 
+:::info
+To use the `ContractInstanceRegistry`, add this dependency to your `Nargo.toml`:
+```toml
+contract_instance_registry = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/noir-contracts/contracts/protocol_interface/contract_instance_registry_interface" }
+```
+:::
+
 The `update` function in the registry is a public function, so you can enqueue it from a private function (as shown above) or call it directly from a public function.
 
 :::warning[Access Control]

docs/docs-developers/docs/aztec-nr/framework-description/custom_notes.md

@@ -29,21 +29,21 @@ Aztec.nr provides pre-built note types for common use cases:
 
 ```toml
 # In Nargo.toml
-uint_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/aztec-nr/uint-note" }
+uint_note = { git="https://github.com/AztecProtocol/aztec-nr", tag="#include_aztec_version", directory="uint-note" }
 ```
 
 **FieldNote** - For storing single Field values:
 
 ```toml
 # In Nargo.toml
-field_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/aztec-nr/field-note" }
+field_note = { git="https://github.com/AztecProtocol/aztec-nr", tag="#include_aztec_version", directory="field-note" }
 ```
 
 **AddressNote** - For storing Aztec addresses:
 
 ```toml
 # In Nargo.toml
-address_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="#include_aztec_version", directory="noir-projects/aztec-nr/address-note" }
+address_note = { git="https://github.com/AztecProtocol/aztec-nr", tag="#include_aztec_version", directory="address-note" }
 ```
 
 :::

docs/docs-developers/docs/aztec-nr/framework-description/events_and_logs.md

@@ -34,7 +34,7 @@ use aztec::messages::message_delivery::MessageDelivery;
 
 #[external("private")]
 fn transfer(to: AztecAddress, amount: u128) {
-    let from = self.msg_sender().unwrap();
+    let from = self.msg_sender();
 
     // ... transfer logic ...
 

docs/docs-developers/docs/aztec-nr/framework-description/functions/attributes.md

@@ -126,7 +126,7 @@ It is also useful in private functions when dealing with tasks of an unknown siz
 This macro inserts a check at the beginning of the function to ensure that the caller is the contract itself. This is done by adding the following assertion:
 
 ```rust
-assert(self.msg_sender().unwrap() == self.address, "Function can only be called internally");
+assert(self.msg_sender() == self.address, "Function can only be called internally");
 ```
 
 ## #[allow_phase_change]