Merge remote-tracking branch 'origin/next' into docs/define-atp-atv-staking-tokens

Author: critesjosh

.claude/README.md

@@ -0,0 +1,22 @@
+# `.claude/`
+
+Project-level Claude Code configuration for aztec-packages. This file documents layout decisions; the filesystem describes the contents.
+
+## Layout rules
+
+1. Universal content lives at repository root: `CLAUDE.md`, `.claude/agents/`, `.claude/scripts/`, and the root `settings.json` hooks.
+2. Subdirectory `.claude/` directories hold only component-specific skills, permission allowlists, and settings. Content is not merged upward.
+3. A subdirectory that has its own `.claude/` must symlink `agents/` to the repository root's `.claude/agents/`. Claude Code's ancestor walk stops at the nearest `.claude/` and does not merge ancestors, so subdirectories otherwise shadow the root agents. Subdirectories without their own `.claude/` inherit the root automatically. `skills/` is intentionally *not* symlinked — skills are scoped to their subdir (root skills are repo-wide workflows; `yarn-project/.claude/skills/` are TS-specific; etc.).
+4. Tracked `.codex` symlinks point at the nearest `.claude/` directory. Keep `.claude/` canonical and do not duplicate agent or skill indexes in `AGENTS.md`.
+5. Prefer XML-tagged sections inside `CLAUDE.md` for prose guidance. A `.claude/rules/` directory is only warranted when a rule needs YAML frontmatter (e.g. path-scoped `paths:` metadata) that `CLAUDE.md` cannot express. `.claude/rules/` without frontmatter does not auto-load when Claude Code is started from a subdirectory, so plain rules files are strictly worse than inlining into `CLAUDE.md`.
+
+## Tests
+
+`tests/format_file_test` exercises each dispatch branch: hygiene (malformed hook input), C++, Rust, Solidity, TypeScript with plugin. Invocation via `./.claude/bootstrap.sh test_cmds` follows the same convention as `ci3/bootstrap.sh`.
+
+## Adding new files
+
+- A new agent used repository-wide: `.claude/agents/` at root.
+- A new skill scoped to one component: `component/.claude/skills/`.
+- A new hook: add a script to `.claude/scripts/`, register it in `.claude/settings.json` via `git rev-parse --show-toplevel` so the path resolves from any cwd, and add a test in `.claude/tests/`. You need to add it to each subdirectory where you want the hook active.
+- A new `.claude/` subdirectory: symlink `agents/` back to the repository root's `.claude/agents/`.

.claude/agents/retrospective.md

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Bootstrap + test entry for the .claude/ tooling directory. Mirrors the shape
+# used by ci3/bootstrap.sh: emits test commands via `test_cmds`, runs them via
+# `test`. Keeps hook scripts and their tests as a self-contained component.
+source $(git rev-parse --show-toplevel)/ci3/source_bootstrap
+
+hash=$(cache_content_hash ^.claude)
+
+function test_cmds {
+  # source_base cd's us into .claude/, so glob relative-to-here, but emit paths
+  # relative to the git root (same convention used by ci3/bootstrap.sh).
+  for f in tests/*; do
+    [[ -x "$f" ]] || continue
+    echo "$hash ./.claude/$f"
+  done
+}
+
+function test {
+  echo_header ".claude tests"
+  test_cmds | filter_test_cmds | parallelize
+}
+
+case "$cmd" in
+  "")
+    test
+    ;;
+  *)
+    default_cmd_handler "$@"
+    ;;
+esac

.claude/bootstrap.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# PostToolUse hook: format files after Edit/Write by dispatching to the right
+# formatter based on extension. Reads Claude Code's hook JSON from stdin.
+#
+# Never fails the edit — prints hints to stderr on missing tools and exits 0.
+
+set -u
+
+input=$(cat)
+file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
+
+[[ -z "$file" ]] && exit 0
+[[ ! -f "$file" ]] && exit 0
+
+hint() { printf 'format-file.sh: %s\n' "$*" >&2; }
+
+case "$file" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.json)
+    root=""
+    if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]] && [[ -f "$CLAUDE_PROJECT_DIR/yarn-project/package.json" ]]; then
+      root="$CLAUDE_PROJECT_DIR"
+    else
+      root=$(git -C "$(dirname "$file")" rev-parse --show-toplevel 2>/dev/null || true)
+    fi
+    if [[ -n "$root" && -x "$root/yarn-project/node_modules/.bin/prettier" ]]; then
+      "$root/yarn-project/node_modules/.bin/prettier" --write --log-level=warn "$file" \
+        || hint "prettier failed on $file"
+    else
+      hint "prettier not found — run yarn-project bootstrap to enable format-on-edit"
+    fi
+    ;;
+  *.cpp|*.cxx|*.cc|*.hpp|*.hxx|*.h)
+    cf=""
+    if command -v clang-format-20 >/dev/null 2>&1; then
+      cf=clang-format-20
+    elif [[ -x /opt/homebrew/opt/llvm/bin/clang-format ]] && /opt/homebrew/opt/llvm/bin/clang-format --version 2>/dev/null | grep -q 'version 20'; then
+      cf=/opt/homebrew/opt/llvm/bin/clang-format
+    elif [[ -x /usr/local/opt/llvm/bin/clang-format ]] && /usr/local/opt/llvm/bin/clang-format --version 2>/dev/null | grep -q 'version 20'; then
+      cf=/usr/local/opt/llvm/bin/clang-format
+    fi
+    if [[ -n "$cf" ]]; then
+      "$cf" -i "$file" || hint "$cf failed on $file"
+    else
+      hint "clang-format 20 not found — install via 'apt install clang-format-20' (Linux) or 'brew install llvm' (macOS)"
+    fi
+    ;;
+  *.rs)
+    # rustfmt walks up from the file path to find .rustfmt.toml, which pins
+    # edition and style. Don't pass --edition here; it would override that.
+    if command -v rustfmt >/dev/null 2>&1; then
+      rustfmt "$file" || hint "rustfmt failed on $file"
+    else
+      hint "rustfmt not found — install via 'rustup component add rustfmt'"
+    fi
+    ;;
+  *.sol)
+    if command -v forge >/dev/null 2>&1; then
+      (cd "$(dirname "$file")" && forge fmt "$file") || hint "forge fmt failed on $file"
+    else
+      hint "forge not found — install foundry via 'curl -L https://foundry.paradigm.xyz | bash && foundryup'"
+    fi
+    ;;
+  *.nr)
+    # nargo fmt operates on whole crates, not individual files.
+    hint "nargo fmt is crate-scoped — run 'nargo fmt' from the noir project directory before committing"
+    ;;
+esac
+
+exit 0

.claude/scripts/format-file.sh

@@ -10,6 +10,17 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'GITROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; [ -n \"$GITROOT\" ] && exec \"$GITROOT/.claude/scripts/format-file.sh\"; exit 0'"
+          }
+        ]
+      }
     ]
   }
 }

.claude/settings.json

@@ -0,0 +1,62 @@
+---
+name: chonk-inputs
+description: Manage pinned Chonk IVC inputs and the Chonk/rollup UltraHonk proving checks. Use when updating, testing, benchmarking, or reviewing the CI flow for Chonk input refreshes.
+argument-hint: <action> e.g. "download", "check", "refresh-pr", "benchmark", "ultrahonk"
+---
+
+# Chonk Inputs
+
+Pinned Chonk IVC inputs live in an S3 tarball keyed by `barretenberg/cpp/scripts/chonk-inputs.hash`. The owner scripts are:
+
+- `barretenberg/cpp/scripts/pinned_chonk_inputs.sh` for shared shell helpers.
+- `barretenberg/cpp/scripts/chonk_inputs.sh` for download, check, and update.
+- `barretenberg/cpp/scripts/ci_update_chonk_inputs.sh` for the PR push-back step.
+
+Use the scripts instead of open-coding URLs, hashes, temp paths, or bucket listings.
+
+## Common Commands
+
+Download or repair the local fixture directory:
+
+```bash
+barretenberg/cpp/scripts/chonk_inputs.sh download
+```
+
+Check pinned VK compatibility without updating:
+
+```bash
+barretenberg/cpp/scripts/chonk_inputs.sh check
+```
+
+Refresh the pin locally:
+
+```bash
+barretenberg/cpp/scripts/chonk_inputs.sh update
+```
+
+In PR CI, refresh via the `ci-refresh-chonk` label or a `--ci-refresh-chonk` head-commit marker. The follow-up refresh commit includes `--ci-skip`.
+Proving is handled by the pinned-input tests; the CI push-back step runs one small pinned flow before committing a refreshed hash.
+
+## Benchmark and Proving Checks
+
+Barretenberg owns the Chonk and rollup UltraHonk benchmark commands. Use `barretenberg/cpp/bootstrap.sh bench_cmds` to inspect the CI command list, or `bench_ivc` for a focused Chonk run.
+
+The benchmark scripts restore or regenerate their inputs when missing:
+
+```bash
+barretenberg/cpp/scripts/chonk_inputs.sh download
+barretenberg/cpp/scripts/ci_benchmark_ivc_flows.sh native
+
+barretenberg/cpp/scripts/ci_benchmark_ultrahonk_circuits.sh parity_base \
+  ../../yarn-project/end-to-end/ultrahonk-bench-inputs 8
+```
+
+Keep Chonk benchmark command enumeration in barretenberg; `yarn-project/end-to-end/bootstrap.sh build_bench_capture` is only for live input capture during pin refresh.
+
+## Review Checklist
+
+- Do not use `aws s3 ls` or depend on bucket listing. Verify exact object URLs.
+- Use `.cache/` for scratch state and clean job-specific subdirectories.
+- Keep refresh commits scoped to `barretenberg/cpp/scripts/chonk-inputs.hash`.
+- Run `bash -n` on edited shell scripts and `yq e . .github/workflows/ci3.yml` after workflow edits.
+- For update-step changes, run `.cache/chonk-ux-harness/run.sh` when available.

.claude/skills/chonk-inputs/SKILL.md

@@ -13,7 +13,7 @@ The merge-train system is fully automated via GitHub Actions in `.github/workflo
 
 1. **PR Creation** (`merge-train-create-pr.yml`): Triggered on push to `merge-train/*` branches. Creates a PR targeting `next` with the `ci-no-squash` label (and `ci-full-no-test-cache` for spartan). Skips merge commits and commits already in `next`.
 
-2. **Body Updates** (`merge-train-update-pr-body.yml`): Triggered on push to `merge-train/**` and `backport-to-*-staging` branches. Updates the PR body with meaningful commits (those containing PR references like `(#1234)`). The body uses `BEGIN_COMMIT_OVERRIDE` / `END_COMMIT_OVERRIDE` markers for release-please. Backport staging PRs also call `update-pr-body.sh` inline from `scripts/backport_to_staging.sh` to handle the first-push case (where the PR doesn't exist yet when the workflow fires).
+2. **Body Updates** (`merge-train-update-pr-body.yml`): Triggered on push to `merge-train/**` and `backport-to-*-staging` branches. Updates the PR body with meaningful commits (those containing PR references like `(#1234)`). The body wraps the commit list in `BEGIN_COMMIT_OVERRIDE` / `END_COMMIT_OVERRIDE` markers. Backport staging PRs also call `update-pr-body.sh` inline from `scripts/backport_to_staging.sh` to handle the first-push case (where the PR doesn't exist yet when the workflow fires).
 
 3. **Next Integration** (`merge-train-next-to-branches.yml`): Triggered on push to `next`. Merges `next` into each active merge-train branch via `scripts/merge-train/merge-next.sh`. Uses `continue-on-error: true` so a conflict in one branch does not block others. Skips branches whose PR already has auto-merge enabled.