feat!: wallets package (#20360)

Deletes the `@aztec/test-wallet` package that was confusing and
dangerous. In hindsight, it was a bad idea.
`TestWallet` is now internal to `@aztec/end-to-end` and for external use
an `@aztec/wallets` package has been created.

The latter adds an `EmbeddedWallet` implementation for both Node and the
browser, with conditional exports for ease of use. It is a somewhat
opinionated implementation, but includes all our optimizations and it is
easily extended. I also think it will be good to have a reference
implementation to put out there and continuously improve.

Author: AztecBot

boxes/boxes/react/package.json

@@ -33,7 +33,7 @@
   "dependencies": {
     "@aztec/accounts": "latest",
     "@aztec/aztec.js": "latest",
-    "@aztec/test-wallet": "latest",
+    "@aztec/wallets": "latest",
     "classnames": "^2.3.2",
     "formik": "^2.4.3",
     "react": "^18.2.0",

boxes/boxes/react/src/config.ts

@@ -1,9 +1,7 @@
 import { getInitialTestAccountsData } from '@aztec/accounts/testing';
 import { AztecAddress } from '@aztec/aztec.js/addresses';
-import { createAztecNodeClient } from '@aztec/aztec.js/node';
 import type { Wallet } from '@aztec/aztec.js/wallet';
-import { getPXEConfig } from '@aztec/pxe/client/lazy';
-import { TestWallet } from '@aztec/test-wallet/client/lazy';
+import { EmbeddedWallet } from '@aztec/wallets/embedded';
 
 export class PrivateEnv {
   private wallet!: Wallet;
@@ -14,11 +12,7 @@ export class PrivateEnv {
   async init() {
     const nodeURL = process.env.AZTEC_NODE_URL ?? 'http://localhost:8080';
 
-    const aztecNode = await createAztecNodeClient(nodeURL);
-    const config = getPXEConfig();
-    config.dataDirectory = 'pxe';
-    config.proverEnabled = false;
-    const wallet = await TestWallet.create(aztecNode, config);
+    const wallet = await EmbeddedWallet.create(nodeURL);
 
     const [accountData] = await getInitialTestAccountsData();
     if (!accountData) {

boxes/boxes/vanilla/package.json

@@ -28,7 +28,7 @@
     "@aztec/wallet-sdk": "latest"
   },
   "devDependencies": {
-    "@aztec/test-wallet": "latest",
+    "@aztec/wallets": "latest",
     "@playwright/test": "1.49.0",
     "@types/node": "^22.15.17",
     "buffer": "^6.0.3",

boxes/boxes/vanilla/scripts/deploy.ts

@@ -12,35 +12,19 @@ import { createAztecNodeClient } from '@aztec/aztec.js/node';
 import type { DeployAccountOptions, Wallet } from '@aztec/aztec.js/wallet';
 import { type AztecNode } from '@aztec/aztec.js/node';
 import { SPONSORED_FPC_SALT } from '@aztec/constants';
-import { createStore } from '@aztec/kv-store/lmdb';
 import { SponsoredFPCContractArtifact } from '@aztec/noir-contracts.js/SponsoredFPC';
-import { getPXEConfig, PXE_DATA_SCHEMA_VERSION } from '@aztec/pxe/server';
 import { getDefaultInitializer } from '@aztec/stdlib/abi';
-import { TestWallet } from '@aztec/test-wallet/server';
+import { EmbeddedWallet } from '@aztec/wallets/embedded';
 import fs from 'fs';
 import path from 'path';
 // @ts-ignore
 import { PrivateVotingContract } from '../artifacts/PrivateVoting.ts';
 
 const AZTEC_NODE_URL = process.env.AZTEC_NODE_URL || 'http://localhost:8080';
-const PROVER_ENABLED = process.env.PROVER_ENABLED === 'false' ? false : true;
 const WRITE_ENV_FILE = process.env.WRITE_ENV_FILE === 'false' ? false : true;
 
-const PXE_STORE_DIR = path.join(import.meta.dirname, '.store');
-
 async function setupWallet(aztecNode: AztecNode) {
-  fs.rmSync(PXE_STORE_DIR, { recursive: true, force: true });
-
-  const store = await createStore('pxe', {
-    dataDirectory: PXE_STORE_DIR,
-    dataStoreMapSizeKb: 1e6,
-  }, PXE_DATA_SCHEMA_VERSION);
-
-  const config = getPXEConfig();
-  config.dataDirectory = 'pxe';
-  config.proverEnabled = PROVER_ENABLED;
-
-  return await TestWallet.create(aztecNode, config, { store });
+  return await EmbeddedWallet.create(aztecNode, { ephemeral: true });
 }
 
 async function getSponsoredPFCContract() {
@@ -54,7 +38,7 @@ async function getSponsoredPFCContract() {
   return instance;
 }
 
-async function createAccount(wallet: TestWallet) {
+async function createAccount(wallet: EmbeddedWallet) {
   const salt = Fr.random();
   const secretKey = Fr.random();
   const signingKey = Buffer.alloc(32, Fr.random().toBuffer());
@@ -169,9 +153,6 @@ async function createAccountAndDeployContract() {
   if (WRITE_ENV_FILE) {
     await writeEnvFile(deploymentInfo);
   }
-
-  // Clean up the PXE store
-  fs.rmSync(PXE_STORE_DIR, { recursive: true, force: true });
 }
 
 createAccountAndDeployContract().catch((error) => {

boxes/boxes/vite/package.json

@@ -18,7 +18,7 @@
     "@aztec/aztec.js": "latest",
     "@aztec/pxe": "latest",
     "@aztec/stdlib": "latest",
-    "@aztec/test-wallet": "latest",
+    "@aztec/wallets": "latest",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-toastify": "^10.0.6"

boxes/boxes/vite/src/config.ts

@@ -1,9 +1,7 @@
 import { getInitialTestAccountsData } from "@aztec/accounts/testing";
 import { AztecAddress } from '@aztec/aztec.js/addresses';
-import { createAztecNodeClient } from '@aztec/aztec.js/node';
 import { Wallet } from '@aztec/aztec.js/wallet';
-import { getPXEConfig } from "@aztec/pxe/client/lazy";
-import { TestWallet } from "@aztec/test-wallet/client/lazy";
+import { EmbeddedWallet } from '@aztec/wallets/embedded';
 
 export class PrivateEnv {
   private wallet!: Wallet;
@@ -14,11 +12,7 @@ export class PrivateEnv {
   async init() {
     const nodeURL = process.env.AZTEC_NODE_URL ?? "http://localhost:8080";
 
-    const aztecNode = await createAztecNodeClient(nodeURL);
-    const config = getPXEConfig();
-    config.dataDirectory = "pxe";
-    config.proverEnabled = false;
-    const wallet = await TestWallet.create(aztecNode, config);
+    const wallet = await EmbeddedWallet.create(nodeURL);
 
     const [accountData] = await getInitialTestAccountsData();
     if (!accountData) {

boxes/package.json

@@ -48,7 +48,7 @@
     "@aztec/archiver": "link:../yarn-project/archiver",
     "@aztec/sequencer-client": "link:../yarn-project/sequencer-client",
     "@aztec/p2p": "link:../yarn-project/p2p",
-    "@aztec/test-wallet": "link:../yarn-project/test-wallet",
+    "@aztec/wallets": "link:../yarn-project/wallets",
     "@aztec/wallet-sdk": "link:../yarn-project/wallet-sdk"
   },
   "dependencies": {

boxes/yarn.lock

@@ -88,15 +88,15 @@ __metadata:
   languageName: node
   linkType: soft
 
-"@aztec/test-wallet@link:../yarn-project/test-wallet::locator=%40aztec%2Fexamples%40workspace%3A.":
+"@aztec/wallet-sdk@link:../yarn-project/wallet-sdk::locator=%40aztec%2Fexamples%40workspace%3A.":
   version: 0.0.0-use.local
-  resolution: "@aztec/test-wallet@link:../yarn-project/test-wallet::locator=%40aztec%2Fexamples%40workspace%3A."
+  resolution: "@aztec/wallet-sdk@link:../yarn-project/wallet-sdk::locator=%40aztec%2Fexamples%40workspace%3A."
   languageName: node
   linkType: soft
 
-"@aztec/wallet-sdk@link:../yarn-project/wallet-sdk::locator=%40aztec%2Fexamples%40workspace%3A.":
+"@aztec/wallets@link:../yarn-project/wallets::locator=%40aztec%2Fexamples%40workspace%3A.":
   version: 0.0.0-use.local
-  resolution: "@aztec/wallet-sdk@link:../yarn-project/wallet-sdk::locator=%40aztec%2Fexamples%40workspace%3A."
+  resolution: "@aztec/wallets@link:../yarn-project/wallets::locator=%40aztec%2Fexamples%40workspace%3A."
   languageName: node
   linkType: soft
 
@@ -3769,7 +3769,7 @@ __metadata:
   dependencies:
     "@aztec/accounts": "npm:latest"
     "@aztec/aztec.js": "npm:latest"
-    "@aztec/test-wallet": "npm:latest"
+    "@aztec/wallets": "npm:latest"
     "@playwright/test": "npm:1.49.0"
     "@types/jest": "npm:^30.0.0"
     "@types/node": "npm:^22.15.17"
@@ -3826,8 +3826,8 @@ __metadata:
     "@aztec/noir-contracts.js": "npm:latest"
     "@aztec/pxe": "npm:latest"
     "@aztec/stdlib": "npm:latest"
-    "@aztec/test-wallet": "npm:latest"
     "@aztec/wallet-sdk": "npm:latest"
+    "@aztec/wallets": "npm:latest"
     "@playwright/test": "npm:1.49.0"
     "@types/node": "npm:^22.15.17"
     buffer: "npm:^6.0.3"
@@ -3852,7 +3852,7 @@ __metadata:
     "@aztec/aztec.js": "npm:latest"
     "@aztec/pxe": "npm:latest"
     "@aztec/stdlib": "npm:latest"
-    "@aztec/test-wallet": "npm:latest"
+    "@aztec/wallets": "npm:latest"
     "@eslint/js": "npm:^9.13.0"
     "@playwright/test": "npm:1.49.0"
     "@types/react": "npm:^18.3.12"

docs/CLAUDE.md

@@ -48,24 +48,26 @@ For development:
 
 The preprocessing system uses these environment variables:
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `RELEASE_TYPE` | Release type: `nightly`, `devnet`, `testnet`, `mainnet`, `ignition` | `nightly` |
-| `NIGHTLY_TAG` | Version for nightly builds (falls back to `COMMIT_TAG`) | `0.0.0-nightly.0` |
-| `DEVNET_TAG` | Version for devnet builds | `3.0.0-devnet.5` |
-| `TESTNET_TAG` | Version for testnet builds | `2.1.11` |
-| `MAINNET_TAG` | Version for mainnet/ignition builds | `2.1.11` |
-| `COMMIT_TAG` | Legacy variable, used as fallback for `NIGHTLY_TAG` | `next` |
+| Variable       | Description                                                         | Default           |
+| -------------- | ------------------------------------------------------------------- | ----------------- |
+| `RELEASE_TYPE` | Release type: `nightly`, `devnet`, `testnet`, `mainnet`, `ignition` | `nightly`         |
+| `NIGHTLY_TAG`  | Version for nightly builds (falls back to `COMMIT_TAG`)             | `0.0.0-nightly.0` |
+| `DEVNET_TAG`   | Version for devnet builds                                           | `3.0.0-devnet.5`  |
+| `TESTNET_TAG`  | Version for testnet builds                                          | `2.1.11`          |
+| `MAINNET_TAG`  | Version for mainnet/ignition builds                                 | `2.1.11`          |
+| `COMMIT_TAG`   | Legacy variable, used as fallback for `NIGHTLY_TAG`                 | `next`            |
 
 ### Preprocessing Macros
 
 **Release-type-aware macros:**
+
 - `#release_version` - Resolves to the version for the current `RELEASE_TYPE`:
   - `nightly` → `NIGHTLY_TAG`, `devnet` → `DEVNET_TAG`, `testnet` → `TESTNET_TAG`, `mainnet`/`ignition` → `MAINNET_TAG`
 - `#release_network` - Resolves to the network name for CLI `--network` flag:
   - `nightly` → `local-network`, `devnet` → `devnet`, `testnet` → `testnet`, `mainnet`/`ignition` → `mainnet`
 
 **Legacy macros:**
+
 - `#include_aztec_version` - Uses `COMMIT_TAG`
 - `#include_devnet_version`, `#include_testnet_version`, `#include_mainnet_version` - Version-specific macros
 
@@ -86,6 +88,7 @@ Default content
 **Supported conditions** (matching `RELEASE_TYPE` values): `nightly`, `devnet`, `testnet`, `mainnet`, `ignition`
 
 **Notes:**
+
 - Conditional blocks are processed before version macro substitution (so you can use version macros inside conditionals)
 - Nested conditionals are not supported
 - The `#else` block is optional
@@ -125,7 +128,8 @@ Two API reference systems generate documentation from source code:
 - **TypeScript API** (`static/typescript-api/`) - Generated from `yarn-project/` packages using TypeDoc
 
 The TypeScript API generation is configured in `scripts/typescript_api_generation/config.json` and documents:
-- Client SDKs: `aztec.js`, `accounts`, `pxe`, `wallet-sdk`, `test-wallet`, `entrypoints`
+
+- Client SDKs: `aztec.js`, `accounts`, `pxe`, `wallet-sdk`, `wallets`, `entrypoints`
 - Core Libraries: `stdlib`, `foundation`, `constants`
 
 ### Versioning System

docs/README.md

@@ -238,7 +238,7 @@ The TypeScript API reference is auto-generated from the `yarn-project/` packages
 
 **Documented packages:**
 
-- **Client SDKs:** `@aztec/aztec.js`, `@aztec/accounts`, `@aztec/pxe`, `@aztec/wallet-sdk`, `@aztec/test-wallet`, `@aztec/entrypoints`
+- **Client SDKs:** `@aztec/aztec.js`, `@aztec/accounts`, `@aztec/pxe`, `@aztec/wallet-sdk`, `@aztec/wallets`, `@aztec/entrypoints`
 - **Core Libraries:** `@aztec/stdlib`, `@aztec/foundation`, `@aztec/constants`
 
 **Prerequisites:** You need `yarn-project` to be built first (the bootstrap process handles this).
@@ -378,27 +378,27 @@ This value is used for mainnet and ignition releases.
 
 This macro is release-type-aware and automatically resolves to the appropriate version based on the `RELEASE_TYPE` environment variable:
 
-| RELEASE_TYPE | Resolves to | Example |
-|--------------|-------------|---------|
-| nightly | `NIGHTLY_TAG` (falls back to `COMMIT_TAG`) | `3.0.0-nightly.20251218` |
-| devnet | `DEVNET_TAG` | `3.0.0-devnet.5` |
-| testnet | `TESTNET_TAG` | `2.1.11` |
-| mainnet | `MAINNET_TAG` | `2.1.11` |
-| ignition | `MAINNET_TAG` | `2.1.11` |
+| RELEASE_TYPE | Resolves to                                | Example                  |
+| ------------ | ------------------------------------------ | ------------------------ |
+| nightly      | `NIGHTLY_TAG` (falls back to `COMMIT_TAG`) | `3.0.0-nightly.20251218` |
+| devnet       | `DEVNET_TAG`                               | `3.0.0-devnet.5`         |
+| testnet      | `TESTNET_TAG`                              | `2.1.11`                 |
+| mainnet      | `MAINNET_TAG`                              | `2.1.11`                 |
+| ignition     | `MAINNET_TAG`                              | `2.1.11`                 |
 
 Usage: `aztecprotocol/aztec:#release_version`
 
 ### `#release_network`
 
 This macro resolves to the network name for use with the `--network` CLI flag:
 
-| RELEASE_TYPE | Resolves to |
-|--------------|-------------|
-| nightly | `local-network` |
-| devnet | `devnet` |
-| testnet | `testnet` |
-| mainnet | `mainnet` |
-| ignition | `mainnet` |
+| RELEASE_TYPE | Resolves to     |
+| ------------ | --------------- |
+| nightly      | `local-network` |
+| devnet       | `devnet`        |
+| testnet      | `testnet`       |
+| mainnet      | `mainnet`       |
+| ignition     | `mainnet`       |
 
 Usage: `--network #release_network`
 
@@ -413,6 +413,7 @@ The `RELEASE_TYPE` environment variable controls which release type the document
 - `ignition` - For ignition releases (treated as mainnet)
 
 Example build commands:
+
 ```bash
 # Build for nightly (default)
 NIGHTLY_TAG=v3.0.0-nightly.20251218 yarn build
@@ -446,13 +447,15 @@ Default content if no condition matches
 ```
 
 **Supported conditions** (matching `RELEASE_TYPE` values):
+
 - `nightly` - True when `RELEASE_TYPE=nightly`
 - `devnet` - True when `RELEASE_TYPE=devnet`
 - `testnet` - True when `RELEASE_TYPE=testnet`
 - `mainnet` - True when `RELEASE_TYPE=mainnet` or `RELEASE_TYPE=ignition`
 - `ignition` - Alias for `mainnet`
 
 **Notes:**
+
 - Conditional blocks are processed before version macro substitution, so you can use version macros inside conditionals
 - Nested conditionals are not supported
 - The `else` block is optional
@@ -516,7 +519,6 @@ When documentation references source code files, the CI system can automatically
    ```
 
 2. **Automatic Detection**: During CI builds (`bootstrap.sh`), the system:
-
    - Extracts all referenced paths from documentation frontmatter
    - Checks if any referenced files (or files within referenced directories) changed in the current PR
    - Automatically requests `@AztecProtocol/devrel` as reviewers if:
@@ -532,6 +534,7 @@ When documentation references source code files, the CI system can automatically
 **Implementation**: The automation is handled by `scripts/check_doc_references.sh`, which runs as part of the docs CI pipeline.
 
 **Path Format**:
+
 - Paths must be absolute from the repository root (e.g., `yarn-project/...`, not `../../../../yarn-project/...`)
 - For individual files: `"path/to/file.ts"`
 - For directories (all files within): `"path/to/directory/*"`
@@ -556,24 +559,28 @@ Building on the DevRel review automation, the docs CI can analyze PRs and notify
    - The DevRel team can review and apply the changes manually
 
 **Requirements**:
+
 - `ANTHROPIC_API_KEY` must be set in CI secrets
 - `SLACK_BOT_TOKEN` must be set for Slack notifications
 - Claude Code CLI must be installed (`@anthropic-ai/claude-code`)
 - The PR must not be a draft
 
 **Environment Variables**:
+
 - `SLACK_DOC_UPDATE_CHANNEL` - Slack channel for notifications (default: `#devrel`)
 - `DRY_RUN=1` - Skip Slack notification, just print what would be sent
 
 **Implementation**: The automation is handled by `scripts/update_doc_references.sh`, which runs as part of the docs CI pipeline after `check_doc_references.sh`.
 
 **Script Architecture**:
+
 - `scripts/update_doc_references.sh` - Main script that orchestrates the workflow
 - `scripts/lib/extract_doc_references.sh` - Shared library for parsing frontmatter references
 - `scripts/lib/create_doc_update_pr.sh` - (Reserved for future use) PR creation logic
 - `scripts/test_update_doc_references.sh` - Local testing helper
 
 **Local Testing**:
+
 ```bash
 # Find a PR with referenced file changes and test
 ./scripts/test_update_doc_references.sh
@@ -583,6 +590,7 @@ LOCAL_TEST=1 DRY_RUN=1 ./scripts/update_doc_references.sh 19803
 ```
 
 **Limitations**:
+
 - Only analyzes documentation in the source folders (`docs-developers/`, `docs-network/`), not versioned docs
 - Suggested changes should always be reviewed by a human before applying
 - The AI may occasionally suggest unnecessary or incorrect changes