# Aztec Accounts

> Use this skill when working with Aztec account implementations and lifecycle flows, including Schnorr/ECDSA account flavors, account abstraction entrypoints, transaction routing, key-store integration, deployment, and wallet reconstruction.

- Skill: `nethermindeth/aztec-accounts` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add nethermindeth/aztec-accounts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nethermindeth/aztec-accounts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- 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-accounts

---


# Aztec Account Lifecycle and Routing

## Overview

Use this skill for Aztec account implementation and account-lifecycle work.

Primary scope:

- choosing and implementing account flavors (`Schnorr`, `ECDSA`)
- deterministic account creation inputs (`secret`, `salt`, signing key/public key)
- deployment via `AccountManager` and wallet account helpers
- reconstructing accounts and wallets from existing material
- account abstraction entrypoints and tx routing behavior
- account self-funded deployment and fee routing
- key-store expectations for key derivation, validation, and app-secret derivation

Out of scope:

- generic contract deployment and app interaction flows that do not depend on account internals (use `aztec-js` or `aztec-deployment`)
- direct PXE debugging beyond account registration/sync expectations (use `aztec-pxe`)
- wallet-provider connectivity or extension transport work (use `aztec-wallet-sdk`)

## Required Repository State

Use the upstream repository and pin:

- Repo: `https://github.com/AztecProtocol/aztec-packages`
- Tag: `v4.2.0`
- Commit: `f8c89cf4345df6c4ca9e66ea9b738e96070abc5a`
- Primary roots:
  - `yarn-project/accounts`
  - `yarn-project/entrypoints`
  - `yarn-project/key-store`

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 `secret + salt + account flavor + signing key/public key` as the account identity tuple. Change any of them and the address changes.
- Prefer `Schnorr` for most production use cases, and `ECDSA` for Ethereum-style signer integrations.
- Distinguish the account secret from the signing key:
  - the secret derives the privacy/viewing/nullifier/tagging keys
  - the signing key authorizes authwits for the account contract
- Prefer eager account exports in Node.js. The `lazy` account modules explicitly note they are incompatible with Node.js at this pin.
- Base account contracts in `@aztec/accounts` only define account behavior; actual deploy/recovery lifecycle is wired through `AccountManager` and wallet helpers.
- Reconstruct accounts with the exact same flavor and key material used originally. Recovery is deterministic; it is not an address lookup service.
- When using bare `AccountManager.create(...)`, register the resulting instance/artifact with the wallet/PXE before relying on it for interactions.
- For self-funded deployment, understand that fee execution is wrapped back through the account entrypoint via `AccountEntrypointMetaPaymentMethod`.
- Key stores should gate key access and signatures with explicit user authorization; do not treat PXE as a secure private-key vault.

## Quick Start

```bash
# install core account-related packages
scripts/install_aztec_accounts_deps.sh npm
```

```typescript
import { Fr, GrumpkinScalar } from '@aztec/aztec.js/fields';
import { createAztecNodeClient, waitForNode } from '@aztec/aztec.js/node';
import { EmbeddedWallet } from '@aztec/wallets/embedded';

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

const wallet = await EmbeddedWallet.create(node);
const accountManager = await wallet.createSchnorrAccount(
  Fr.random(),
  Fr.random(),
  GrumpkinScalar.random(),
);

const deployMethod = await accountManager.getDeployMethod();
await deployMethod.send({ from: existingFundedAccountAddress });
console.log(accountManager.address.toString());
```

## Core Workflows

### 1. Choose the Right Account Flavor

- `SchnorrAccountContract`
  - Grumpkin signing key for auth
  - separate account secret for privacy keys
  - recommended default
- `EcdsaKAccountContract`
  - secp256k1 auth key
  - use for Ethereum-wallet style integrations
- `EcdsaRAccountContract`
  - secp256r1 auth key
  - use when the signer lives on P-256 infrastructure
- `EcdsaRSSHAccountContract`
  - secp256r1 auth via SSH agent signing
  - recovery depends on the same SSH public key identity

### 2. Compute and Inspect a Deterministic Account Before Deployment

- Use wallet helpers such as `EmbeddedWallet.createSchnorrAccount(...)` or `AccountManager.create(...)`.
- Read the predicted address and public keys from `accountManager.getCompleteAddress()`.
- For Schnorr-only address prediction without wallet setup, use `getSchnorrAccountContractAddress(secret, salt, signingKey?)`.
- Use `accountManager.getInstance()` when you need the contract instance definition before publishing.

### 3. Deploy an Account Contract

- Build the manager through wallet helpers or `AccountManager.create(...)`.
- Call `accountManager.getDeployMethod()`.
- Use an externally funded payer for the simplest flow:
  - `await deployMethod.send({ from: fundedAccountAddress })`
- Account deployments force `universalDeployment: true`.
- At this pin, deploy-account defaults also bias toward:
  - `skipClassPublication: true`
  - `skipInstancePublication: true`
  - `skipInitialization: false`
- `skipClassPublication: true` is unavailable for account contracts that expose public functions with a private initializer: v4.2.0 emits a separate public init nullifier via an auto-enqueued public call, which requires the account class to be published onchain.
- If the account is self-funding, `DeployAccountMethod` routes fee execution through `AccountEntrypointMetaPaymentMethod`.

### 4. Reconstruct an Existing Account or Wallet

- Recovery is deterministic:
  - same secret
  - same salt
  - same account flavor
  - same signing key or signing public key material
- Embedded wallet pattern:
  - recreate the wallet
  - call the same `createSchnorrAccount(...)`, `createECDSAKAccount(...)`, or `createECDSARAccount(...)`
  - the wallet re-registers the account contract instance/artifact and rebuilds the same address
- Lower-level pattern:
  - instantiate the account contract class directly
  - call `AccountManager.create(wallet, secret, contract, salt)`
  - register the instance/artifact with the wallet or PXE
  - call `getAccount()` for the runtime account object

### 5. Understand Account Abstraction Routing

- `DefaultAccountContract` wires a `BaseAccount` around `DefaultAccountEntrypoint`.
- `DefaultAccountEntrypoint`:
  - encodes app calls into an account `entrypoint(...)` payload
  - injects auth witnesses for the encoded call hash
  - applies tx options such as `cancellable`, `txNonce`, and fee-routing mode
- `DefaultEntrypoint`:
  - direct single-call private entrypoint
  - rejects multi-call payloads
- `DefaultMultiCallEntrypoint`:
  - wraps multiple calls through the protocol multicall entrypoint
  - used by `SignerlessAccount`
- Use the account entrypoint whenever the account contract must authorize or fee-route the action.

### 6. Fee Routing Semantics

- `AccountFeePaymentMethodOptions` controls how the account entrypoint treats fees:
  - `EXTERNAL`
  - `PREEXISTING_FEE_JUICE`
  - `FEE_JUICE_WITH_CLAIM`
- `AccountEntrypointMetaPaymentMethod` computes these automatically when self-funding deployment:
  - no inner calls => preexisting Fee Juice
  - inner fee-claim calls => Fee Juice with claim
  - external payer => external
- For self-deployment, deployment payload construction happens before fee payload wrapping so the account contract can exist before paying.

### 7. Key-Store Integration Expectations

- `KeyStore` is a secure input component for PXE, not just a convenience map.
- Core responsibilities:
  - create/add accounts from a secret and partial address
  - persist master secret keys and public keys by account
  - derive app-scoped secrets for kernel validation
  - answer key-validation requests without exposing unnecessary material
- Important methods:
  - `createAccount()`
  - `addAccount(sk, partialAddress)`
  - `getAccounts()` / `hasAccount(account)`
  - `getKeyValidationRequest(pkMHash, contractAddress)`
  - `getMasterIncomingViewingSecretKey(account)`
  - `getAppOutgoingViewingSecretKey(account, app)`
  - `getMasterSecretKey(pkM)`
  - `accountHasKey(account, pkMHash)`
- Key-store UX/security expectation from the package README:
  - prompt before signatures or sensitive key release
  - protect stored secrets with encryption and recovery controls

### 8. Testing and Local-Network Helpers

- `@aztec/accounts/testing` exposes deterministic/local-network-friendly helpers:
  - `getInitialTestAccountsData()`
  - `generateSchnorrAccounts(numberOfAccounts)`
- Use these when you need known account secrets, salts, signing keys, and predicted addresses for tests.

### 9. README vs Code Surface

- The pinned `yarn-project/accounts/README.md` still shows `getSchnorrAccount(...)` and `getSchnorrWallet(...)`.
- The current code surface in this pin is centered on:
  - account contract classes in `@aztec/accounts/*`
  - address helpers such as `getSchnorrAccountContractAddress(...)`
  - lifecycle wiring through wallet helpers and `AccountManager`
- Prefer code-backed patterns from `reference.md` and `patterns.md` over the README snippets when they differ.

## Tooling / Commands

```bash
# preflight node/package-manager checks and optional source-tree validation
scripts/preflight_aztec_accounts.sh [node-url] [aztec-packages-dir]

# install account-related SDK packages
scripts/install_aztec_accounts_deps.sh <npm|yarn|pnpm> [version]

# summarize exports and core source anchors from an aztec-packages checkout
scripts/summarize_accounts_surface.sh <aztec-packages-dir>

# run package tests for accounts, entrypoints, and key-store
scripts/run_accounts_tests.sh <aztec-packages-dir> [accounts|entrypoints|key-store]
```

## Edge Cases and Failure Handling

- Recreated account address does not match expected address:
verify the exact flavor, secret, salt, and signing key/public key used for the original account.
- Account can be computed locally but cannot see notes/events:
the instance/artifact or account registration path was likely not re-established in the wallet/PXE.
- `getDeployMethod()` throws about missing initializer:
that account contract does not expose an initializer path at this pin.
- Self-funded account deployment fails:
inspect the wrapped payment method and resulting `AccountFeePaymentMethodOptions`.
- `lazy` account modules fail under Node:
expected at this pin; switch to eager imports.
- SSH-backed ECDSA recovery fails:
confirm the same SSH public-key identity is available to the agent.

## Next Steps / Related Files

- Use `reference.md` for the pinned source map and API/file coverage.
- Use `patterns.md` for reusable deployment and reconstruction snippets.
- Use `scripts/` for repeatable setup, inspection, and test workflows.