aztec-accounts

star 8

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.

NethermindEth By NethermindEth schedule Updated 4/18/2026
play_arrow Run Skill in Manus View GitHub

name: aztec-accounts description: 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. license: Proprietary. LICENSE.txt has complete terms compatibility: Pinned to aztec-packages v4.2.0 (commit f8c89cf4345df6c4ca9e66ea9b738e96070abc5a). metadata: version_label: v4.2.0 commit_sha: f8c89cf4345df6c4ca9e66ea9b738e96070abc5a source_map: aztec-packages/yarn-project/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:

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

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

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

# 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.
Install via CLI
npx skills add https://github.com/NethermindEth/aztec-skills --skill aztec-accounts
Repository Details
star Stars 8
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
NethermindEth
NethermindEth Explore all skills →