Merge branch 'next' into ciara/docs-links

Author: ciaranightingale

.claude/README.md

@@ -0,0 +1,21 @@
+# `.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. 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/aztec-wallet.md

@@ -0,0 +1,244 @@
+---
+name: aztec-wallet
+description: |
+  Execute cli-wallet commands on live Aztec networks. Handles cli-wallet installation, account setup, contract deployment, function calls, state queries, and fee juice bridging. Receives pre-computed configuration from the aztec-wallet skill.
+---
+
+# Aztec Wallet Agent
+
+You execute `@aztec/cli-wallet` commands on live Aztec networks. You receive pre-computed configuration (network, RPC URL) and handle setup + command execution.
+
+## Input Format
+
+You receive:
+- `NETWORK`: Network name or "custom"
+- `RPC_URL`: HTTP RPC endpoint
+- `WORKING_DIR`: working directory
+- `PRIVATE_KEY`: Account secret key (default `0xc140de`)
+- `SALT`: Account salt (default `0`)
+- `COMMAND`: What to execute (natural language or cli-wallet command)
+
+## Execution Pattern
+
+**Always use script files** — never run inline bash commands. This keeps permission prompts clean and allows "always allow".
+
+There are two scripts, both written to `WORKING_DIR` using the Write tool:
+
+1. `install.sh` — one-time setup (version query + npm install). Run with `bash <WORKING_DIR>/install.sh`
+2. `run.sh` — env setup + account registration + command. Run with `bash <WORKING_DIR>/run.sh`
+
+Both commands are stable per network, so the user can "always allow" them.
+
+## Phase 1: Install cli-wallet
+
+**Always run this phase** — it queries the live node version and only reinstalls if the version changed.
+
+Create the directory if needed, **Write** `<WORKING_DIR>/install.sh`:
+
+```bash
+set -e
+cd "<WORKING_DIR>"
+RPC_URL="<RPC_URL>"
+
+# Check jq is available
+if ! command -v jq &>/dev/null; then
+  echo "ERROR: jq is required but not installed. Install it with: sudo apt-get install jq" >&2
+  exit 1
+fi
+
+# Query node version
+RESPONSE=$(curl -sf -X POST -H 'Content-type: application/json' \
+  --data '{"jsonrpc":"2.0","id":1,"method":"node_getNodeInfo"}' \
+  "$RPC_URL" 2>&1) || {
+  echo "ERROR: Could not reach node at $RPC_URL" >&2
+  echo "Response: $RESPONSE" >&2
+  exit 1
+}
+
+VERSION=$(echo "$RESPONSE" | jq -r '.result.nodeVersion')
+if [ -z "$VERSION" ] || [ "$VERSION" = "null" ]; then
+  echo "ERROR: Node returned unexpected response (no nodeVersion found)" >&2
+  echo "Response: $RESPONSE" >&2
+  exit 1
+fi
+echo "Node version: $VERSION"
+
+# Skip install if already on the correct version
+INSTALLED_VERSION=""
+if [ -f "node_modules/.bin/aztec-wallet" ]; then
+  INSTALLED_VERSION=$(node -e "console.log(require('@aztec/cli-wallet/package.json').version)" 2>/dev/null || true)
+fi
+
+if [ "$INSTALLED_VERSION" = "$VERSION" ]; then
+  echo "cli-wallet@$VERSION already installed, skipping"
+else
+  [ -n "$INSTALLED_VERSION" ] && echo "Upgrading cli-wallet from $INSTALLED_VERSION to $VERSION"
+  npm init -y >/dev/null 2>&1
+  npm install --no-fund --no-audit --save @aztec/cli-wallet@$VERSION 2>&1 | tail -5
+fi
+echo "DONE"
+```
+
+Then run: `bash <WORKING_DIR>/install.sh`
+
+## Phase 2: Execute Command
+
+**Write** `<WORKING_DIR>/run.sh` with env setup, account registration, and the command.
+
+Overwrite `run.sh` each time with the new command — the `bash <WORKING_DIR>/run.sh` prompt stays the same.
+
+```bash
+set -e
+RPC_URL="<RPC_URL>"
+PRIVATE_KEY="<PRIVATE_KEY>"
+SALT="<SALT>"
+WORKING_DIR="<WORKING_DIR>"
+INSTANCE_HASH=$(echo "$PRIVATE_KEY $SALT" | sha256sum | head -c 6)
+DATA_DIR="$WORKING_DIR/data_$INSTANCE_HASH"
+WAIT_STATUS="proposed"  # or checkpointed, proven
+LOG_LEVEL=warn
+
+mkdir -p "$DATA_DIR"
+CLI="$WORKING_DIR/node_modules/.bin/aztec-wallet -n $RPC_URL -d $DATA_DIR -p native"
+
+# --- Register account ---
+$CLI create-account -sk $PRIVATE_KEY -s $SALT -t schnorr -a default --register-only 2>&1 || true
+
+# --- Command ---
+<COMMAND_LINES>
+```
+
+Then run: `bash <WORKING_DIR>/run.sh`
+
+## Command-Specific Script Tails
+
+### status
+```bash
+echo "--- Account address ---"
+$CLI get-alias accounts 2>&1
+echo "--- Fee Juice Balance ---"
+$CLI get-fee-juice-balance accounts:default 2>&1 || true
+echo "--- Known Contracts ---"
+$CLI get-alias contracts 2>&1 || echo "  (none)"
+```
+
+**IMPORTANT**: When reporting status to the user, always print the **full, untruncated L2 address** (all 66 hex characters). Never abbreviate it as `0xdead...beef` — the user needs the complete address to bridge funds to it.
+
+**IMPORTANT**: When listing registered contracts, ignore the protocol contracts (addresses 0x01 through 0x06).
+
+### deploy
+```bash
+echo "=== Deploying <Artifact> ==="
+OUTPUT=$($CLI deploy <Artifact> --args <constructor-args> -f accounts:default -a <alias> --wait-for-status $WAIT_STATUS 2>&1)
+echo "$OUTPUT"
+echo ""
+echo "=== Registration Info (for use with a different wallet) ==="
+echo "Contract address: <extract from OUTPUT>"
+echo "Artifact: <Artifact>"
+echo "To register in another wallet:"
+echo "  aztec-wallet register-contract -ca <address> <Artifact> -a <alias>"
+```
+- Artifact: name from `@aztec/noir-contracts.js` (e.g. `TokenContract`) or file path
+- Auto-alias: lowercase, strip "Contract" suffix (`TokenContract` → `token`)
+- If no constructor args, omit `--args`
+- **Always** print registration info after deploy so the user can register the contract in a different wallet
+
+### send
+```bash
+$CLI send <function-name> -ca contracts:<alias-or-address> --args <args> -f accounts:default --wait-for-status $WAIT_STATUS 2>&1
+```
+- If contract not registered, add a `$CLI register-contract -ca <addr> <artifact>` line before the send
+- If no args, omit `--args`
+
+### Private token operations
+
+Private minting and private transfers do **not** require the recipient's account to be deployed on-chain. The sender just needs to register the recipient's address locally.
+
+**Setup**: Register the recipient in the sender's wallet before sending private tokens:
+```bash
+$CLI register-sender <recipient-address> -a <alias> 2>&1
+```
+
+**Mint to private balance**:
+```bash
+$CLI send mint_to_private -ca contracts:<alias> --args accounts:default <amount> -f accounts:default --wait-for-status $WAIT_STATUS 2>&1
+```
+
+**Private transfer**:
+```bash
+$CLI send transfer -ca contracts:<alias> --args <recipient-address> <amount> -f accounts:default --wait-for-status $WAIT_STATUS 2>&1
+```
+
+- Amounts must include decimals (e.g. 1000 tokens with 18 decimals → `1000000000000000000000`)
+- The recipient can receive private tokens without having their account deployed or having fee juice
+- The recipient will need a deployed account later to *spend* those tokens
+
+### simulate (read-only call)
+```bash
+$CLI simulate <function-name> -ca contracts:<alias-or-address> --args <args> -f accounts:default 2>&1
+```
+
+### bridge-fee-juice
+```bash
+$CLI bridge-fee-juice --amount <amount> --recipient accounts:default --wait 2>&1
+```
+- **Requires Sepolia ETH** on the L1 address derived from the private key — the command mints Fee Juice on L1 and bridges to L2, which costs L1 gas
+- If the L1 account has no Sepolia ETH, this will fail with `insufficient funds for transfer`
+- The `--recipient` flag can target any L2 address, not just the sender's own account
+
+### get-fee-juice-balance
+```bash
+$CLI get-fee-juice-balance accounts:default 2>&1
+```
+
+### Any other cli-wallet command
+```bash
+$CLI <command> <flags...> 2>&1
+```
+
+Available commands: `create-account`, `deploy-account`, `deploy`, `send`, `simulate`, `register-contract`, `register-sender`, `create-authwit`, `authorize-action`, `bridge-fee-juice`, `get-fee-juice-balance`, `get-alias`, `alias`, `create-secret`, `get-tx`, `profile`.
+
+## Alias Conventions
+
+- Account alias: `default` for the auto-created account
+- Contract alias: lowercase artifact name without "Contract" suffix
+- Use `accounts:<name>` and `contracts:<name>` prefix syntax in commands
+- If a value starts with `0x`, it's a raw address — use directly
+
+## Output
+
+For transactions, report:
+```
+Transaction: <hash>
+Status: <proposed|checkpointed>
+Local processing: <X>s
+Node inclusion: <X>s
+Fee: <amount>
+Block: <number>
+```
+
+For deploy, also report registration info:
+```
+To register in another wallet:
+  aztec-wallet register-contract -ca <full-address> <Artifact> -a <alias>
+```
+
+For queries/calls, report the returned value directly.
+
+## Error Handling
+
+- **RPC unreachable**: Report error, stop
+- **Account already exists**: Non-fatal (the `|| true` handles it), proceed
+- **Transaction fails**: Report full error, do not retry
+- **npm install fails**: Report error, suggest checking version on npm
+- **Artifact not found**: Report error, suggest checking `@aztec/noir-contracts.js`
+
+## Important Notes
+
+- **Shared WORKING_DIR**: Multiple agents with different private keys share the same `WORKING_DIR` (one per network). Per-account isolation is handled by `INSTANCE_HASH` which creates separate `data_$INSTANCE_HASH` subdirectories. Never create per-agent working directories — this wastes npm installs and breaks the intended design.
+- Default `--wait-for-status proposed` for deploy/send; user can request `checkpointed` or `proven`
+- Data directory is isolated per account (via INSTANCE_HASH) and per network — never touches `~/.aztec/wallet`
+- For private calls, the cli-wallet proves locally using the native prover
+- Slot duration is typically 72s — inclusion under 40s is normal, over 50s may indicate issues
+- Each phase runs as a separate bash command from `WORKING_DIR` — env vars must be re-exported each time
+- Always print full, untruncated addresses (all 66 hex chars) — never abbreviate

.claude/agents/network-logs.md

@@ -62,10 +62,31 @@ You can read this output directly — no parsing needed.
 --format='table[no-heading](timestamp, resource.labels.pod_name, jsonPayload.message.slice(0,150))'
 ```
 
+## Cluster Mapping
+
+Aztec runs two GKE clusters:
+
+| Cluster | Aztec namespaces |
+|---------|-----------------|
+| `aztec-gke-private` | `mainnet` (ignition — active), `next-net`, `staging-ignition`, `staging-public`, and various test/scenario namespaces |
+| `aztec-gke-public` | `mainnet` (public — currently in standby), `testnet`, and other public-facing infrastructure |
+
+**Important: `mainnet` exists in BOTH clusters.**
+- The **private** cluster's `mainnet` runs the **ignition** network (active, fisherman mode).
+- The **public** cluster's `mainnet` is the next rollup upgrade (currently in standby, waiting for L1 contract alignment). It also runs in fisherman mode.
+
+When querying `mainnet`, you MUST include a `resource.labels.cluster_name` filter to disambiguate:
+- If the user says "mainnet" without qualification, query the **private** cluster (ignition) by default — it's the active one.
+- If the user says "mainnet public", "public cluster mainnet", or "mainnet on public", query the **public** cluster.
+- If uncertain, query **both** clusters in parallel and report results separately.
+
+For all other namespaces, the cluster filter is optional but recommended for clarity.
+
 ## GCP Log Structure
 
 Aztec network logs use:
 - `resource.type="k8s_container"`
+- `resource.labels.cluster_name` — the GKE cluster (`aztec-gke-private` or `aztec-gke-public`)
 - `resource.labels.namespace_name` — the deployment namespace
 - `resource.labels.pod_name` — the specific pod
 - `resource.labels.container_name` — usually `aztec`
@@ -91,7 +112,8 @@ Pods follow the pattern `{namespace}-{component}-{index}`:
 
 ## Deployment-Specific Notes
 
-- **next-net** redeploys every morning at ~4am UTC. Always use timestamp range filters (not `--freshness`) when querying next-net for a specific date, and expect logs to only cover a single instance of the network.
+- **next-net** redeploys every morning at ~4am UTC. Always use timestamp range filters (not `--freshness`) when querying next-net for a specific date, and expect logs to only cover a single instance of the network. Because next-net resets daily, its block height should start near 0 after ~4am UTC. If you are running a morning healthcheck and the block height is unexpectedly large (e.g., hundreds or thousands), flag this as an error — it likely means the nightly redeploy failed and the network is running a stale instance.
+- **mainnet** (both private/ignition and public) does not run sequencer validators. Both deployments run in **fisherman mode**: nodes simulate building a block for every slot but never actually submit the L1 transaction. This means you will see "built block" or similar messages but no "Published checkpoint" or L1 submission logs. Errors with hash `0xf3e591ac` are a known artifact of fisherman mode and are safe to ignore. See the Cluster Mapping section above for how to disambiguate between the two mainnet deployments.
 
 ## Filter Building
 
@@ -203,6 +225,7 @@ gcloud logging read '
   NOT jsonPayload.message=~"No active peers"
   NOT jsonPayload.message=~"Not enough txs"
   NOT jsonPayload.message=~"StateView contract not found"
+  NOT jsonPayload.message=~"[Bb]lob"
 ' --limit=100 --format='table[no-heading](timestamp.date("%H:%M:%S"), resource.labels.pod_name, jsonPayload.severity, jsonPayload.module, jsonPayload.message.slice(0,180))' --freshness=<freshness> --project=<project>
 ```
 
@@ -291,6 +314,20 @@ Then synthesize into a single status report covering:
 
 This is the most common query pattern — prefer this composite approach over individual queries when the user asks for general status.
 
+### 11. Multi-Network Healthcheck
+
+When the user asks for a healthcheck across multiple networks (e.g., "how are all the networks doing?"), query each network in parallel and present results as a **summary table**:
+
+```
+| Network   | Status | Block Height | Last Block | Proving | Notes |
+|-----------|--------|--------------|------------|---------|-------|
+| testnet   | ✅ OK  | 1234         | 2m ago     | Epoch 5 | —     |
+| next-net  | ✅ OK  | 45           | 1m ago     | Epoch 1 | —     |
+| mainnet   | ✅ OK  | 890          | 3m ago     | N/A     | Fisherman mode |
+```
+
+Use ✅ for healthy, ⚠️ for degraded, ❌ for down/erroring. Follow the table with brief per-network details only if there are issues worth calling out. Remember deployment-specific notes: next-net resets daily (check block height is reasonable for time of day), mainnet runs in fisherman mode (no L1 submissions, `0xf3e591ac` errors are expected).
+
 ## Known Noise Patterns
 
 These patterns appear frequently and are usually harmless — exclude or downplay them:
@@ -302,6 +339,8 @@ These patterns appear frequently and are usually harmless — exclude or downpla
 - `No active peers to send requests to` — P2P reqresp on isolated nodes (e.g., blob-sink)
 - `Not enough txs to build block` — Normal when transaction volume is low
 - `StateView contract not found` — Price oracle warning; Uniswap V4 StateView only exists on mainnet, so all other networks emit this. Safe to ignore unless namespace is `mainnet`
+- **Blob-related errors** — Errors related to blobs (e.g., blob fetching failures, blob unavailability) are generally expected and safe to ignore. Since the Fusaka hard fork, regular consensus nodes can no longer serve blob data, and we run a couple of these nodes. Exclude or downplay blob errors unless the user is specifically investigating blob issues.
+- `0xf3e591ac` — Fisherman mode error on mainnet. Safe to ignore (see Deployment-Specific Notes).
 
 ## Reference Tool