# Aztec Pxe

> Use this skill when implementing or debugging direct PXE workflows in TypeScript, including private execution lifecycle, note discovery/synchronization, sender/recipient tagging, private events, scopes, and oracle/debug checks.

- Skill: `nethermindeth/aztec-pxe` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add nethermindeth/aztec-pxe`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nethermindeth/aztec-pxe/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: Proprietary. LICENSE.txt has complete terms
- Author: nethermindeth (https://skillmd.com/u/nethermindeth)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nethermindeth/aztec-pxe

---


# PXE Private Execution Operations

## Overview

Use this skill for direct `@aztec/pxe` work.

Primary scope:

- private execution lifecycle (`simulateTx`, `profileTx`, `proveTx`, `executeUtility`)
- note discovery/synchronization behavior and scope control
- sender/recipient tagging workflows
- private event retrieval and filter handling
- oracle compatibility checks and PXE debug helpers

Out of scope:

- Noir/Aztec.nr contract authoring (use `aztec-contracts`)
- generic Aztec.js app flows that do not need direct PXE control (use `aztec-js`)
- deployment-focused procedures (use `aztec-deployment`)

## Required Repository State

Use the upstream repository and pin:

- Repo: `https://github.com/AztecProtocol/aztec-packages`
- Tag: `v4.2.0`
- Commit: `f8c89cf4345df6c4ca9e66ea9b738e96070abc5a`
- Source root: `yarn-project/pxe`

Checkout example:

```bash
git clone https://github.com/AztecProtocol/aztec-packages.git
cd aztec-packages
git checkout v4.2.0
git status
```

Expected status includes `HEAD detached at v4.2.0`.

## Operating Rules

- Treat PXE as a serialized execution environment: high-level jobs are queued and run one-at-a-time.
- Always pass an explicit `scopes: AztecAddress[]` list; the `'ALL_SCOPES'` sentinel was removed. To emulate the old "see everything" behavior, pass the enumerated list of registered addresses: `scopes = (await pxe.getRegisteredAccounts()).map(a => a.address)`.
- Capsule access is enforced at the PXE level in v4.2.0: a contract touching capsules scoped to an address not in the tx's `scopes` list fails at runtime with `Scope 0x… is not in the allowed scopes list: [...]`. `AztecAddress::zero()` is always permitted (global scope).
- Register recipient accounts with `registerAccount(...)` before expecting note or private event visibility.
- Register counterpart senders with `registerSender(...)` when syncing tagged logs across peers.
- Use `simulateTx` before `proveTx`; only prove after simulation and sync checks pass.
- For private events, `filter.scopes` must be non-empty and block range follows `[fromBlock, toBlock)`.
- Use `debug.getNotes(...)` only for diagnostics; prefer contract utility functions for production reads.
- If oracle interface changes, run oracle version checks before trusting cross-version simulations.

## Quick Start

```bash
# install dependencies in your app
scripts/install_pxe_deps.sh npm

# check node reachability + optional pxe source path validation
scripts/preflight_pxe.sh http://localhost:8080 /path/to/aztec-packages/yarn-project/pxe
```

```typescript
import { createAztecNodeClient, waitForNode } from '@aztec/aztec.js/node';
import { createPXE, getPXEConfig } from '@aztec/pxe/server';

const node = createAztecNodeClient('http://localhost:8080');
await waitForNode(node);

const pxe = await createPXE(node, getPXEConfig(), {
  loggerActorLabel: 'app-pxe',
});
```

## Core Workflows

### 1. Boot PXE and Anchor State 

- Build node client and wait for JSON-RPC readiness.
- Create PXE via `createPXE(...)` from `@aztec/pxe/server` or `@aztec/pxe/client/lazy`.
- Use `getSyncedBlockHeader()` to confirm the current anchor block before execution.

### 2. Register Accounts, Senders, and Contract Data

- Register account recipients via `registerAccount(secretKey, partialAddress)`.
- Register known counterpart senders via `registerSender(senderAddress)`.
- Register artifacts/instances via `registerContractClass(...)` and `registerContract(...)`.
- Verify registration with `getRegisteredAccounts()`, `getSenders()`, `getContractInstance()`.

### 3. Run Private Execution Lifecycle

- `simulateTx(txRequest, opts)` for private (and optional public) simulation.
  - `opts.overrides?: SimulationOverrides` injects simulation-time contract instances/artifacts (useful for testing).
- `profileTx(txRequest, { profileMode, scopes })` for execution/gate diagnostics.
  - `profileMode` values: `'full'` | `'execution-steps'` | `'gates'`.
- `proveTx(txRequest, scopes)` only after simulation correctness is confirmed.
  - Returns `TxProvingResult`; `publicInputs` is non-optional on the result.
- `executeUtility(functionCall, { authwits, scopes })` for utility paths and sync-state calls.

### 4. Note Discovery and Synchronization

- PXE sync occurs before simulation/event operations; keep one execution flow per state transition.
- Contract sync is scope-aware; `[]` scopes deny access and skip sync.
- Use `debug.sync()` to force an explicit sync checkpoint when diagnosing stale state.
- Use `debug.getNotes({ contractAddress, owner?, storageSlot?, status?, siloedNullifier?, scopes })` for note-level diagnostics.

### 5. Tagging (Sender / Recipient)

- Sender-side index progression is maintained per directional secret `(sender, recipient, contract)`.
- Recipient-side log loading scans bounded windows of tagging indexes and updates aged/finalized indices.
- Registering sender addresses improves recipient decryption coverage for incoming private logs.
- If tags are reused unexpectedly, inspect pending/finalized index movement and tx inclusion timing.

### 6. Private Events

- Retrieve private events via `getPrivateEvents(eventSelector, filter)`.
- Required filter fields:
- `contractAddress`
- `scopes` (non-empty)
- Optional filters: `txHash`, `fromBlock`, `toBlock` (`toBlock` exclusive).
- If events are missing, ensure account registration, scope inclusion, and anchor sync point.

### 7. Oracle and Debug Workflows

- Verify oracle compatibility with `scripts/check_oracle_version.sh` against your pinned `aztec-packages` checkout.
- Use `utilityLog` outputs and simulation traces (`profileTx`) to localize oracle call failures.
- Treat `PXEDebugUtils` APIs as unstable and diagnostics-only.

### 8. Shutdown and Resource Hygiene

- Call `pxe.stop()` on teardown to end queued jobs cleanly.
- Preserve persistent store state across sessions when reproducing note/tagging issues.

## Tooling / Commands

```bash
# preflight node/package manager/source checks
scripts/preflight_pxe.sh [node-url] [pxe-dir]

# install core PXE dependencies
scripts/install_pxe_deps.sh <npm|yarn|pnpm> [version]

# wait for node JSON-RPC readiness
scripts/wait_for_aztec_node.sh <node-url> [timeout-seconds] [interval-seconds]

# run a TypeScript example via tsx
scripts/run_pxe_example.sh <entry-file.ts> [-- <extra-args...>]

# summarize pxe package exports + method surfaces
scripts/summarize_pxe_surface.sh <aztec-packages-dir>

# run @aztec/pxe package tests
scripts/run_pxe_tests.sh <aztec-packages-dir> [test-path-pattern]

# run oracle interface compatibility check
scripts/check_oracle_version.sh <aztec-packages-dir>
```

## Edge Cases and Failure Handling

- `At least one scope is required to get private events`:
provide non-empty `filter.scopes`.
- Missing private notes/events despite successful tx:
verify recipient account registration and scope membership.
- `Incompatible oracle version` error:
run oracle version check and align Aztec.nr/PXE versions.
- Simulations appear stale after chain changes:
force `debug.sync()` and re-run with fresh anchor block.
- Interleaved requests behave unpredictably:
avoid app-side concurrent PXE operation bursts; serialize user flows.
- Tagging sync does not advance:
verify sender registration and inspect finalized/aged tagging index windows.

## Next Steps / Related Files

- Use `reference.md` for source map and API/file coverage.
- Use `patterns.md` for reusable workflow snippets.
- Use `scripts/` for repeatable diagnostics and verification.