chore: Accumulated backports to v4-next

.claude/skills/release-network-docs/SKILL.md

@@ -21,12 +21,15 @@ self-identify its release type, ask the user to confirm.
 
 **This skill does NOT:**
 
-- Generate API docs (aztec-nr or TypeScript)
+- Generate developer API docs (aztec-nr or TypeScript)
 - Generate CLI reference docs
 - Update developer version config or cut developer versioned docs
 - Update migration notes
 - Require aztec CLI, nargo, or yarn-project build
 
+**This skill DOES** regenerate the Node JSON-RPC API reference for the
+versioned docs (see Step 5a).
+
 ## Usage
 
 ```
@@ -165,7 +168,29 @@ Ask the user if any content changes are needed in `docs/docs-operate/`:
 - Operator changelog updates (if not handled by `/updating-changelog`)
 
 If the user has content changes, apply them to the source files in
-`docs/docs-operate/`. If no content changes are needed, skip to Step 6.
+`docs/docs-operate/`. If no content changes are needed, skip to Step 5a.
+
+### Step 5a: Regenerate Node API Reference
+
+The Node JSON-RPC API reference is auto-generated from TypeScript source. It
+must be regenerated from the release tag's source files to ensure the versioned
+docs reflect the actual API at that release.
+
+```bash
+cd docs
+yarn generate:node-api-reference
+```
+
+This writes to `docs/docs-operate/operators/reference/node-api-reference.md`
+using the source files from the currently checked-out tag. The generator parses
+`yarn-project/stdlib/src/interfaces/aztec-node.ts` and
+`yarn-project/stdlib/src/interfaces/aztec-node-admin.ts` directly (no
+yarn-project build needed, but `yarn-project/node_modules/` must be installed
+so `npx tsx` can resolve `typescript` — run `yarn install` from `yarn-project`
+if needed).
+
+Verify the output lists the expected number of methods and has no ungrouped
+methods warnings.
 
 ### Step 6: Build and Validate
 
@@ -284,6 +309,10 @@ Check for stash conflicts. Then report to the user:
 - **No heavy prerequisites**: This skill does not require aztec CLI, nargo, or
   a yarn-project build. Only `yarn` (for the docs build), `curl`/`jq` (for
   the RPC query), and `cast` (for on-chain address queries) are needed.
+- **Node API reference is auto-generated**: Run `yarn generate:node-api-reference`
+  (Step 5a) before building. The generator parses TypeScript source directly, so
+  no yarn-project build is required — but `yarn-project/node_modules/` must exist
+  (run `yarn install` from `yarn-project` if missing).
 - **Build must pass**: Do not cut versioned docs until `yarn build` succeeds.
 - **COMMIT_TAG needs `v` prefix**: The preprocessor uses COMMIT_TAG for GitHub
   URLs and git tag references. Omitting the `v` will break links in versioned

Makefile

@@ -262,7 +262,6 @@ aztec-nr: noir bb-cpp-native
 noir-projects-txe-tests:
 	$(call test,$@,noir-projects/aztec-nr)
 	$(call test,$@,noir-projects/noir-contracts)
-	$(call test,$@,noir-projects/noir-contracts-comp-failures)
 
 # Noir Projects - Aggregate target (builds all sub-projects)
 noir-projects: noir-protocol-circuits mock-protocol-circuits noir-contracts aztec-nr

aztec-up/README.md

@@ -9,9 +9,14 @@ That is all.
 This will install into `~/.aztec/bin` a collection of scripts to help with running aztec containers, and will update
 the user's `PATH` variable in their shell startup script so they can be found.
 
-- `aztec` - a collection of tools to compile and test contracts, to launch subsystems and interact with the aztec network."
-- `aztec-up` - a tool to install and manage aztec toolchain versions."
-- `aztec-wallet` - our minimalistic CLI wallet"
+- `aztec` - compiles and tests contracts, launches infrastructure subsystems, interacts with the network.
+- `aztec-up` - a version manager for the Aztec toolchain.
+- `aztec-wallet` - a tool for interacting with the Aztec network.
+- `aztec-bb` - the Barretenberg proving backend.
+- `aztec-nargo` - the Noir compiler and simulator.
+- `aztec-forge`, `aztec-cast`, `aztec-anvil`, `aztec-chisel` - the bundled Foundry tools.
+
+Foundry, Noir, and Barretenberg are bundled at the versions `aztec` needs. Your own `forge` / `nargo` / `bb` installs still work under their bare names.
 
 After installed, you can use `aztec-up` to install specific versions.
 

aztec-up/bin/0.0.1/aztec-install

@@ -94,12 +94,14 @@ function title {
   echo -e "Installing version: ${bold}${o}$VERSION${r}"
   echo
   echo -e "This script installs the following and updates your PATH if necessary:"
-  echo -e "  ${bold}${g}nargo${r}          - the noir programming language compiler and simulator."
-  echo -e "  ${bold}${g}noir-profiler${r}  - a profiler for analyzing and visualizing noir programs."
-  echo -e "  ${bold}${g}bb${r}             - the barretenberg proving backend."
   echo -e "  ${bold}${g}aztec${r}          - compiles and tests contracts, interacts with the network."
   echo -e "  ${bold}${g}aztec-up${r}       - installs and manages aztec toolchain versions."
   echo -e "  ${bold}${g}aztec-wallet${r}   - a minimalistic wallet cli."
+  echo -e "  ${bold}${g}aztec-bb${r}       - the barretenberg proving backend."
+  echo -e "  ${bold}${g}aztec-nargo${r}    - the noir compiler and simulator."
+  echo -e "  ${bold}${g}aztec-forge${r}, ${bold}${g}aztec-cast${r}, ${bold}${g}aztec-anvil${r}, ${bold}${g}aztec-chisel${r} - the bundled foundry tools."
+  echo
+  echo -e "Foundry, Noir, and Barretenberg are bundled at the versions ${bold}${g}aztec${r} needs. Your own ${bold}${g}forge${r} / ${bold}${g}nargo${r} / ${bold}${g}bb${r} installs still work under their bare names."
   echo
   read -p "Do you wish to continue? (Y/n) " -n 1 -r
   echo

aztec-up/bin/0.0.1/install

@@ -37,6 +37,12 @@ export FORCE_COLOR=1
 # Version-specific paths
 version_path="$AZTEC_HOME/versions/$VERSION"
 version_bin_path="$version_path/bin"
+# Native binaries (forge/nargo/anvil/...) live here and are NOT on the user's PATH.
+# The aztec wrapper prepends this directory to its child PATH so subprocesses
+# spawned from the aztec workflow (which call sibling tools by basename) resolve
+# to the bundled binaries. User-facing access is only via the aztec-* symlinks
+# in version_bin_path.
+version_internal_bin_path="$version_path/internal-bin"
 
 os="$(uname -s)"
 
@@ -137,7 +143,15 @@ function install_noir {
   set -euo pipefail
 
   if [[ -n ${NARGO:-} ]]; then
-    cp "$NARGO" "$version_bin_path/nargo"
+    cp "$NARGO" "$version_internal_bin_path/nargo"
+    # noir's release build co-locates `noir-profiler` next to `nargo`
+    # (see noir/bootstrap.sh::build_native). Copy it too so the
+    # `aztec-noir-profiler` symlink in install_native_symlinks resolves.
+    local nargo_dir
+    nargo_dir=$(dirname "$NARGO")
+    if [ -f "$nargo_dir/noir-profiler" ]; then
+      cp "$nargo_dir/noir-profiler" "$version_internal_bin_path/noir-profiler"
+    fi
   else
     local noir_version
     noir_version=$(get_version "noir")
@@ -150,13 +164,12 @@ function install_noir {
     # Always install/update noirup
     curl -Ls https://raw.githubusercontent.com/noir-lang/noirup/refs/heads/main/install | bash
 
-    # Install noir to temp location and move to version directory
+    # Install noir to temp location and move into internal-bin (off PATH).
     NARGO_HOME="$temp_nargo_home" "$HOME/.nargo/bin/noirup" -v "$noir_version"
 
-    # Move the nargo binary to our version bin directory
-    mv "$temp_nargo_home/bin/nargo" "$version_bin_path/nargo"
+    mv "$temp_nargo_home/bin/nargo" "$version_internal_bin_path/nargo"
     # Also move noir-profiler, needed by `aztec profile flamegraph`
-    mv "$temp_nargo_home/bin/noir-profiler" "$version_bin_path/noir-profiler"
+    mv "$temp_nargo_home/bin/noir-profiler" "$version_internal_bin_path/noir-profiler"
 
     # Cleanup temp directory
     rm -rf "$temp_nargo_home"
@@ -182,10 +195,11 @@ function install_foundry {
   # Install foundry to temp location and move to version directory
   FOUNDRY_DIR="$temp_foundry_dir" timeout 30 "$foundry_home/bin/foundryup" -i "$foundry_version"
 
-  # Move the foundry binaries to our version bin directory
+  # Move the foundry binaries into internal-bin (off PATH); aztec-forge etc.
+  # symlinks in version_bin_path expose them under aztec-prefixed names.
   for binary in forge cast anvil chisel; do
     if [ -f "$temp_foundry_dir/bin/$binary" ]; then
-      mv "$temp_foundry_dir/bin/$binary" "$version_bin_path/$binary"
+      mv "$temp_foundry_dir/bin/$binary" "$version_internal_bin_path/$binary"
     fi
   done
 
@@ -200,32 +214,88 @@ function install_aztec_packages {
   npm install @aztec/aztec@$VERSION @aztec/cli-wallet@$VERSION @aztec/bb.js@$VERSION --prefix "$version_path"
 }
 
-function symlink_aztec_bins {
+# Expose every native tool in internal-bin under an aztec-<tool> symlink in bin.
+# Bare `forge`/`nargo`/etc. are intentionally NOT on PATH so they cannot shadow
+# user-installed tools.
+function install_native_symlinks {
+  set -euo pipefail
+  local tool
+  for tool in forge cast anvil chisel nargo noir-profiler; do
+    if [ ! -e "$version_internal_bin_path/$tool" ]; then
+      echo "Error: expected bundled binary '$tool' missing from $version_internal_bin_path" >&2
+      exit 1
+    fi
+    ln -sfn "../internal-bin/$tool" "$version_bin_path/aztec-$tool"
+  done
+}
+
+# Npm bins are NOT mirrored into internal-bin. The contract for any TS tool
+# that needs to spawn a sibling binary is to resolve an absolute bundled
+# path itself (e.g. via @aztec/bb.js findBbBinary(), or a BB-style env
+# var) -- never by basename + PATH lookup. If you find yourself wanting to
+# add an npm bin to internal-bin so a child process can find it on PATH,
+# fix the caller instead of broadening this list.
+function install_npm_bin_symlinks {
   set -euo pipefail
-  # Populate version_bin_path with symlinks to @aztec-owned bins only. Adding
-  # node_modules/.bin wholesale to PATH would shadow user-installed tools
-  # (jest, tsc, semver, ...) with Aztec's transitive dependencies.
   local npm_bin_dir="$version_path/node_modules/.bin"
   [ -d "$npm_bin_dir" ] || return 0
 
-  local bin_link bin_name target
+  local bin_link bin_name target link_name
   for bin_link in "$npm_bin_dir"/*; do
     [ -L "$bin_link" ] || continue
     target=$(readlink "$bin_link")
     # npm writes relative symlinks like ../@aztec/aztec/... for scoped packages.
     [[ "$target" == ../@aztec/* ]] || continue
     bin_name=$(basename "$bin_link")
-    if [ -e "$version_bin_path/$bin_name" ] && [ ! -L "$version_bin_path/$bin_name" ]; then
-      echo_yellow "refusing to overwrite non-symlink $bin_name; @aztec package bin collides with a hand-installed toolchain binary" >&2
+
+    # `aztec` is a wrapper, written by install_aztec_wrapper.
+    [[ "$bin_name" == "aztec" ]] && continue
+
+    # Already prefixed (e.g. aztec-wallet) keeps its name; everything else gets
+    # renamed to aztec-<orig> so it cannot shadow a user-installed binary.
+    if [[ "$bin_name" == aztec-* ]]; then
+      link_name="$bin_name"
+    else
+      link_name="aztec-$bin_name"
+    fi
+
+    if [ -e "$version_bin_path/$link_name" ] && [ ! -L "$version_bin_path/$link_name" ]; then
+      echo_yellow "refusing to overwrite non-symlink $link_name; @aztec package bin collides with a hand-installed toolchain binary" >&2
       exit 1
     fi
-    ln -sfn "../node_modules/.bin/$bin_name" "$version_bin_path/$bin_name"
+    ln -sfn "../node_modules/.bin/$bin_name" "$version_bin_path/$link_name"
   done
 }
 
+# Wrapper for `aztec`: prepends internal-bin to PATH so the aztec workflow
+# resolves bundled native tools by basename. yarn-project/aztec/scripts/aztec.sh
+# (the npm bin entry of @aztec/aztec) calls bare `nargo` (line 36, in `aztec
+# test`) and bare `anvil` (line 55-56, in `aztec start --local-network`); the
+# TS commands it spawns also fall back to bare `forge` / `nargo` /
+# `noir-profiler` when their respective env vars are unset. The wrapper is
+# kept minimal -- it is the only place we maintain a PATH-based execution
+# context, by design (see install_npm_bin_symlinks for the rationale).
+# BASH_SOURCE[0] (not $0) so PATH-name invocation still resolves internal-bin
+# from the wrapper's actual location.
+function install_aztec_wrapper {
+  set -euo pipefail
+  local wrapper="$version_bin_path/aztec"
+  cat > "$wrapper" <<'EOF'
+#!/usr/bin/env bash
+# Auto-generated by aztec-up. Do not edit.
+set -euo pipefail
+self_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+internal_bin="$self_dir/../internal-bin"
+export PATH="$internal_bin:$PATH"
+exec "$self_dir/../node_modules/.bin/aztec" "$@"
+EOF
+  chmod +x "$wrapper"
+}
+
 function main {
-  # Create version directory
+  # Create version directories. bin/ is exposed on PATH; internal-bin/ is not.
   mkdir -p "$version_bin_path"
+  mkdir -p "$version_internal_bin_path"
 
   # Download versions manifest
   echo -n "Installing version manifest... "
@@ -250,14 +320,23 @@ function main {
   dump_fail retry install_foundry
   echo_green "done."
 
+  # Expose native tools as aztec-forge / aztec-nargo / etc.
+  echo -n "Linking aztec native tools... "
+  dump_fail install_native_symlinks
+  echo_green "done."
+
   # Install aztec npm packages
-  echo -n "Installing aztec packages... "
+  echo -n "Installing aztec npm packages... "
   dump_fail retry install_aztec_packages
   echo_green "done."
 
-  # Expose only @aztec-owned bins on PATH (drops transitive npm deps).
+  # Expose @aztec-owned npm bins under aztec-prefixed symlinks. Bare names
+  # (bb, pxe, txe, ...) are intentionally NOT exposed as they would shadow
+  # user-installed tools.
   echo -n "Making aztec commands available... "
-  dump_fail retry symlink_aztec_bins
+  dump_fail install_npm_bin_symlinks
+  # Wrap `aztec` so its subprocesses see internal-bin on PATH.
+  dump_fail install_aztec_wrapper
   echo_green "done."
 }
 

aztec-up/bootstrap.sh

@@ -104,7 +104,7 @@ EOF
 }
 
 function test_cmds {
-  for test in amm_flow bridge_and_claim basic_install counter_contract default_scaffold; do
+  for test in amm_flow bridge_and_claim basic_install counter_contract default_scaffold no_shadow_user_bins; do
     echo "$hash:TIMEOUT=15m aztec-up/scripts/run_test.sh $test"
   done
 }
@@ -234,8 +234,8 @@ function install_on_mac_vm {
     . "\$HOME/.nvm/nvm.sh"
 
     # Verify installation.
-    nargo --version
-    bb --version
+    aztec-nargo --version
+    aztec-bb --version
     aztec --version
 REMOTE_EOF
 }

aztec-up/scripts/run_isolated_test.sh

@@ -98,9 +98,9 @@ EOF
   echo "Version information:"
 
   bash -i -c -e '
-    forge --version
+    aztec-forge --version
     echo
-    nargo --version
+    aztec-nargo --version
     echo
     echo -n "aztec version: "
     aztec --version