@aztec-labs/wallets 6.0.0-nightly.20260829

package/src/embedded/embedded_wallet.ts

@@ -0,0 +1,481 @@
+import { type Account, NO_FROM } from '@aztec-labs/aztec.js/account';
+import { CallAuthorizationRequest } from '@aztec-labs/aztec.js/authorization';
+import {
+  ContractFunctionInteraction,
+  type InteractionWaitOptions,
+  NO_WAIT,
+  type SendReturn,
+  type WaitOpts,
+} from '@aztec-labs/aztec.js/contracts';
+import type { AztecNodeClientOptions } from '@aztec-labs/aztec.js/node';
+import type {
+  Aliased,
+  ExecuteUtilityOptions,
+  PrivateEvent,
+  PrivateEventFilter,
+  ProfileOptions,
+  SendOptions,
+  SimulateOptions,
+} from '@aztec-labs/aztec.js/wallet';
+import { AccountManager, TxSimulationResultWithAppOffset } from '@aztec-labs/aztec.js/wallet';
+import type { DefaultAccountEntrypointOptions } from '@aztec-labs/entrypoints/account';
+import { DefaultEntrypoint } from '@aztec-labs/entrypoints/default';
+import { poseidon2Hash } from '@aztec-labs/foundation/crypto/poseidon';
+import { Schnorr } from '@aztec-labs/foundation/crypto/schnorr';
+import { Fq, Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { Logger } from '@aztec-labs/foundation/log';
+import type { AztecAsyncKVStore } from '@aztec-labs/kv-store';
+import type { PXEConfig, PXECreationOptions } from '@aztec-labs/pxe/client/lazy';
+import type { PXE } from '@aztec-labs/pxe/server';
+import type { EventMetadataDefinition, FunctionCall } from '@aztec-labs/stdlib/abi';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import { getContractClassFromArtifact } from '@aztec-labs/stdlib/contract';
+import { GasSettings } from '@aztec-labs/stdlib/gas';
+import type { AztecNode } from '@aztec-labs/stdlib/interfaces/client';
+import {
+  type ContractOverrides,
+  ExecutionPayload,
+  SimulationOverrides,
+  type TxExecutionRequest,
+  type TxProfileResult,
+  TxStatus,
+  type UtilityExecutionResult,
+  collectOffchainEffects,
+  mergeExecutionPayloads,
+} from '@aztec-labs/stdlib/tx';
+import { BaseWallet, type SimulateViaEntrypointOptions, getGasLimits } from '@aztec-labs/wallet-sdk/base-wallet';
+
+import type { AccountContractsProvider } from './account-contract-providers/types.js';
+import { type AccountType, WalletDB } from './wallet_db.js';
+
+/** Options for the PXE instance created by the EmbeddedWallet. */
+export type EmbeddedWalletPXEOptions = Partial<PXEConfig> & PXECreationOptions;
+
+/** Splits a unified EmbeddedWalletPXEOptions into PXEConfig overrides and PXECreationOptions. */
+export function splitPxeOptions(pxe?: EmbeddedWalletPXEOptions): {
+  config: Partial<PXEConfig>;
+  creation: PXECreationOptions;
+} {
+  if (!pxe) {
+    return { config: {}, creation: {} };
+  }
+  const { loggers, loggerActorLabel, proverOrOptions, store, simulator, hooks, preloadedContractsProvider, ...config } =
+    pxe;
+  return {
+    config,
+    creation: { loggers, loggerActorLabel, proverOrOptions, store, simulator, hooks, preloadedContractsProvider },
+  };
+}
+
+/** Options for the EmbeddedWallet's own DB (accounts, senders — distinct from PXE state). */
+export type EmbeddedWalletDBOptions = {
+  /** Override the wallet DB backend. If omitted, an IndexedDB (browser) / LMDB (node) store is created. */
+  store?: AztecAsyncKVStore;
+};
+
+export type EmbeddedWalletOptions = {
+  /** Parent logger. Child loggers are derived via createChild() for each subsystem. */
+  logger?: Logger;
+  /** Use ephemeral (in-memory) stores. Data will not persist across sessions. */
+  ephemeral?: boolean;
+  /** PXE configuration and dependency overrides (custom store, prover, simulator). */
+  pxe?: EmbeddedWalletPXEOptions;
+  /** Wallet DB dependency overrides (custom store). */
+  walletDb?: EmbeddedWalletDBOptions;
+  /** JSON-RPC client options used when the wallet is created from a node URL. */
+  nodeClientOptions?: AztecNodeClientOptions;
+  /**
+   * Override PXE configuration.
+   * @deprecated Use `pxe` instead.
+   */
+  pxeConfig?: Partial<PXEConfig>;
+  /**
+   * Advanced PXE creation options (custom store, prover, simulator).
+   * @deprecated Use `pxe` instead.
+   */
+  pxeOptions?: PXECreationOptions;
+};
+
+const DEFAULT_ESTIMATED_GAS_PADDING = 0.1;
+
+export class EmbeddedWallet extends BaseWallet {
+  protected estimatedGasPadding = DEFAULT_ESTIMATED_GAS_PADDING;
+
+  // Stub class ids, populated on wallet startup
+  // to avoid redundant work per simulation
+  protected stubClassIds = new Map<AccountType, Fr>();
+
+  constructor(
+    pxe: PXE,
+    aztecNode: AztecNode,
+    protected walletDB: WalletDB,
+    protected accountContracts: AccountContractsProvider,
+    log?: Logger,
+  ) {
+    super(pxe, aztecNode, log);
+  }
+
+  protected async getAccountFromAddress(address: AztecAddress): Promise<Account> {
+    const { secretKey, salt, signingKey, type } = await this.walletDB.retrieveAccount(address);
+    const accountManager = await this.createAccountInternal(type, secretKey, salt, signingKey);
+    const account = await accountManager.getAccount();
+
+    if (!account) {
+      throw new Error(`Account not found in wallet for address: ${address}`);
+    }
+
+    return account;
+  }
+
+  getAccounts(): Promise<Aliased<AztecAddress>[]> {
+    return this.walletDB.listAccounts();
+  }
+
+  override async registerSender(address: AztecAddress, alias: string) {
+    await this.walletDB.storeSender(address, alias);
+    await this.pxe.registerTaggingSecretSource({ kind: 'address-derived', sender: address });
+    return address;
+  }
+
+  override async getAddressBook(): Promise<Aliased<AztecAddress>[]> {
+    const sources = await this.pxe.getTaggingSecretSources({ kind: 'address-derived' });
+    const senders = sources.map(source => source.sender);
+    const storedSenders = await this.walletDB.listSenders();
+    for (const storedSender of storedSenders) {
+      if (senders.findIndex(sender => sender.equals(storedSender.item)) === -1) {
+        await this.pxe.registerTaggingSecretSource({ kind: 'address-derived', sender: storedSender.item });
+      }
+    }
+    return storedSenders;
+  }
+
+  /**
+   * Overrides the base sendTx to add a pre-simulation step before the actual send. The simulation
+   * estimates actual gas usage and captures call authorization requests to generate
+   * the necessary authwitnesses.
+   */
+  public override async sendTx<W extends InteractionWaitOptions = undefined>(
+    executionPayload: ExecutionPayload,
+    opts: SendOptions<W>,
+  ): Promise<SendReturn<W>> {
+    // PXE has autoSync disabled by the embedded wallet entrypoints, so we sync once here to cover
+    // both the inner simulateTx (via simulateViaEntrypoint) and the proveTx that super.sendTx
+    await this.pxe.sync();
+    const feeOptions = await this.completeFeeOptions({
+      from: opts.from,
+      feePayer: executionPayload.feePayer,
+      gasSettings: opts.fee?.gasSettings,
+      forEstimation: true,
+    });
+
+    // Simulate the transaction first to estimate gas and capture required
+    // private authwitnesses based on offchain effects.
+    const simulationResult = await this.simulateViaEntrypoint(executionPayload, {
+      from: opts.from,
+      feeOptions,
+      additionalScopes: opts.additionalScopes,
+      skipTxValidation: true,
+      sendMessagesAs: opts.sendMessagesAs,
+    });
+
+    const offchainEffects = collectOffchainEffects(simulationResult.privateExecutionResult);
+    const authWitnesses = await Promise.all(
+      offchainEffects.map(async effect => {
+        try {
+          const authRequest = await CallAuthorizationRequest.fromFields(effect.data);
+          return this.createAuthWit(authRequest.onBehalfOf, {
+            consumer: effect.contractAddress,
+            innerHash: authRequest.innerHash,
+          });
+        } catch {
+          return undefined;
+        }
+      }),
+    );
+    for (const authwit of authWitnesses) {
+      if (authwit) {
+        executionPayload.authWitnesses.push(authwit);
+      }
+    }
+    const maxTxGasLimits = await this.getMaxTxGasLimits();
+    const estimated = getGasLimits(simulationResult.gasUsed, maxTxGasLimits, this.estimatedGasPadding);
+    this.log.verbose(
+      `Estimated gas limits for tx: DA=${estimated.gasLimits.daGas} L2=${estimated.gasLimits.l2Gas} teardownDA=${estimated.teardownGasLimits.daGas} teardownL2=${estimated.teardownGasLimits.l2Gas}`,
+    );
+    const gasSettings = GasSettings.from({
+      ...opts.fee?.gasSettings,
+      maxFeesPerGas: feeOptions.gasSettings.maxFeesPerGas,
+      maxPriorityFeesPerGas: feeOptions.gasSettings.maxPriorityFeesPerGas,
+      gasLimits: opts.fee?.gasSettings?.gasLimits ?? estimated.gasLimits,
+      teardownGasLimits: opts.fee?.gasSettings?.teardownGasLimits ?? estimated.teardownGasLimits,
+    });
+    let wait: InteractionWaitOptions = opts.wait;
+    if (wait !== NO_WAIT) {
+      const callerWaitOpts: WaitOpts = typeof wait === 'object' ? wait : {};
+      wait = {
+        ...callerWaitOpts,
+        // Default to PROPOSED so the wait returns as soon as the tx lands in a proposed L2 block,
+        // rather than waiting until the end of the slot for the checkpoint to be published to L1.
+        // This is what makes MBPS (Multiple Blocks Per Slot) actually improve UX: with CHECKPOINTED
+        // we'd block until L1 inclusion regardless of how early in the slot the tx was sequenced.
+        // The tradeoff is a weaker guarantee — a proposed block only becomes canonical once it (or
+        // a later block in the same slot) is checkpointed, so a tx could be re-orged out if the
+        // proposer fails to publish to L1 (which should be rare, since they'd get slashed for it).
+        waitForStatus: callerWaitOpts.waitForStatus ?? TxStatus.PROPOSED,
+      };
+    }
+    return super.sendTx(executionPayload, {
+      ...opts,
+      wait: wait as W,
+      fee: { ...opts.fee, gasSettings },
+    });
+  }
+
+  /**
+   * Overrides the base simulateTx to drive PXE syncing explicitly. The PXE created by the embedded
+   * wallet has autoSync disabled (so we can share one sync across simulate+send in sendTx); for
+   * standalone simulations we still need a fresh anchor block, which we provide here.
+   */
+  public override async simulateTx(
+    executionPayload: ExecutionPayload,
+    opts: SimulateOptions,
+  ): Promise<TxSimulationResultWithAppOffset> {
+    await this.pxe.sync();
+    return super.simulateTx(executionPayload, opts);
+  }
+
+  public override async profileTx(executionPayload: ExecutionPayload, opts: ProfileOptions): Promise<TxProfileResult> {
+    await this.pxe.sync();
+    return super.profileTx(executionPayload, opts);
+  }
+
+  public override async executeUtility(
+    call: FunctionCall,
+    opts: ExecuteUtilityOptions,
+  ): Promise<UtilityExecutionResult> {
+    await this.pxe.sync();
+    return super.executeUtility(call, opts);
+  }
+
+  public override async getPrivateEvents<T>(
+    eventDef: EventMetadataDefinition,
+    eventFilter: PrivateEventFilter,
+  ): Promise<PrivateEvent<T>[]> {
+    await this.pxe.sync();
+    return super.getPrivateEvents<T>(eventDef, eventFilter);
+  }
+
+  /**
+   * Hashes and registers the stub class for every supported account type with PXE, populating
+   * stubClassIds. Called on wallet initialization.
+   */
+  async initStubClasses(): Promise<void> {
+    const schnorrArtifact = await this.accountContracts.getStubAccountContractArtifact('schnorr');
+    const { id: schnorrClassId } = await getContractClassFromArtifact(schnorrArtifact);
+    await this.pxe.registerContractClass(schnorrArtifact);
+
+    // ecdsa stubs share the same class id
+    const ecdsaArtifact = await this.accountContracts.getStubAccountContractArtifact('ecdsasecp256r1');
+    const { id: ecdsaClassId } = await getContractClassFromArtifact(ecdsaArtifact);
+    await this.pxe.registerContractClass(ecdsaArtifact);
+
+    this.stubClassIds.set('schnorr', schnorrClassId);
+    this.stubClassIds.set('schnorr_initializerless', schnorrClassId);
+    this.stubClassIds.set('ecdsasecp256k1', ecdsaClassId);
+    this.stubClassIds.set('ecdsasecp256r1', ecdsaClassId);
+  }
+
+  /**
+   * Builds contract overrides for all provided addresses by replacing their account contracts with stub implementations.
+   * Uses a type-specific stub artifact so that the stub's constructor selector matches the real account's constructor.
+   */
+  protected async buildAccountOverrides(addresses: AztecAddress[]): Promise<ContractOverrides> {
+    const accounts = await this.getAccounts();
+    const contracts: ContractOverrides = {};
+
+    const filtered = accounts.filter(acc => addresses.some(addr => addr.equals(acc.item)));
+
+    for (const account of filtered) {
+      const address = account.item;
+      const { type } = await this.walletDB.retrieveAccount(address);
+      const stubClassId = this.stubClassIds.get(type);
+      if (!stubClassId) {
+        throw new Error(
+          `Stub class for account type '${type}' was not registered at wallet init. This is a bug — initStubClasses should cover every supported AccountType.`,
+        );
+      }
+
+      const originalAccount = await this.getAccountFromAddress(address);
+      const completeAddress = originalAccount.getCompleteAddress();
+      const contractInstance = await this.pxe.getContractInstance(completeAddress.address);
+      if (!contractInstance) {
+        throw new Error(
+          `No contract instance found for address: ${completeAddress.address} during account override building. This is a bug!`,
+        );
+      }
+
+      contracts[address.toString()] = {
+        instance: { ...contractInstance, currentContractClassId: stubClassId },
+      };
+    }
+
+    return contracts;
+  }
+
+  /**
+   * Simulates calls via a stub account entrypoint, bypassing real account authorization.
+   * This allows kernelless simulation with contract overrides, skipping expensive
+   * private kernel circuit execution.
+   */
+  protected override async simulateViaEntrypoint(
+    executionPayload: ExecutionPayload,
+    opts: SimulateViaEntrypointOptions,
+  ): Promise<TxSimulationResultWithAppOffset> {
+    const { from, feeOptions, additionalScopes, skipTxValidation, skipFeeEnforcement, sendMessagesAs } = opts;
+    const scopes = this.scopesFrom(from, additionalScopes ?? [], sendMessagesAs);
+
+    const feeExecutionPayload = await feeOptions.walletFeePaymentMethod?.getExecutionPayload();
+    const finalExecutionPayload = feeExecutionPayload
+      ? mergeExecutionPayloads([feeExecutionPayload, executionPayload])
+      : executionPayload;
+    const chainInfo = await this.getChainInfo();
+
+    const accountOverrides = await this.buildAccountOverrides(scopes);
+    const overrides = new SimulationOverrides({ contracts: accountOverrides });
+
+    let txRequest: TxExecutionRequest;
+    if (from === NO_FROM) {
+      const entrypoint = new DefaultEntrypoint();
+      txRequest = await entrypoint.createTxExecutionRequest(finalExecutionPayload, feeOptions.gasSettings, chainInfo);
+    } else {
+      const { type } = await this.walletDB.retrieveAccount(from);
+      const originalAccount = await this.getAccountFromAddress(from);
+      const completeAddress = originalAccount.getCompleteAddress();
+      const account = await this.accountContracts.createStubAccount(completeAddress, type);
+      const executionOptions: DefaultAccountEntrypointOptions = {
+        txNonce: Fr.random(),
+        cancellable: this.cancellableTransactions,
+        // If from is an address, feeOptions include the way the account contract should handle the fee payment
+        feePaymentMethodOptions: feeOptions.accountFeePaymentMethodOptions!,
+      };
+      txRequest = await account.createTxExecutionRequest(
+        finalExecutionPayload,
+        feeOptions.gasSettings,
+        chainInfo,
+        executionOptions,
+      );
+    }
+
+    const result = await this.pxe.simulateTx(txRequest, {
+      simulatePublic: true,
+      skipFeeEnforcement,
+      skipTxValidation,
+      overrides,
+      scopes,
+      senderForTags: this.senderForTagsFrom(from, sendMessagesAs),
+    });
+    const appCallOffset = await this.computeAppCallOffset(from, feeOptions);
+    return TxSimulationResultWithAppOffset.fromResultAndOffset(result, appCallOffset);
+  }
+
+  protected async createAccountInternal(
+    type: AccountType,
+    secret: Fr,
+    salt: Fr,
+    signingKey: Buffer,
+  ): Promise<AccountManager> {
+    let contract;
+    let immutablesHash;
+    let publicKey;
+    switch (type) {
+      case 'schnorr': {
+        contract = await this.accountContracts.getSchnorrAccountContract(Fq.fromBuffer(signingKey));
+        break;
+      }
+      case 'schnorr_initializerless': {
+        contract = await this.accountContracts.getSchnorrInitializerlessAccountContract(Fq.fromBuffer(signingKey));
+        publicKey = await new Schnorr().computePublicKey(Fq.fromBuffer(signingKey));
+        immutablesHash = await poseidon2Hash([publicKey.x, publicKey.y]);
+        break;
+      }
+      case 'ecdsasecp256k1': {
+        contract = await this.accountContracts.getEcdsaKAccountContract(signingKey);
+        break;
+      }
+      case 'ecdsasecp256r1': {
+        contract = await this.accountContracts.getEcdsaRAccountContract(signingKey);
+        break;
+      }
+      default: {
+        throw new Error(`Unknown account type ${type}`);
+      }
+    }
+
+    const accountManager = await AccountManager.create(this, secret, contract, { salt, immutablesHash });
+
+    const instance = accountManager.getInstance();
+    const existingInstance = await this.pxe.getContractInstance(instance.address);
+    if (!existingInstance) {
+      const existingArtifact = await this.pxe.getContractArtifact(instance.currentContractClassId);
+      const artifact = existingArtifact ?? (await accountManager.getAccountContract().getContractArtifact());
+      await this.registerContract(
+        instance,
+        !existingArtifact ? await accountManager.getAccountContract().getContractArtifact() : undefined,
+        accountManager.getSecretKey(),
+      );
+      if (type === 'schnorr_initializerless') {
+        const constructor = artifact.functions.find(f => f.name === 'constructor');
+        if (!constructor) {
+          throw new Error('Could not create SchnorrInitializerlessAccountContract: constructor ABI not found');
+        }
+        const storeCall = new ContractFunctionInteraction(this, instance.address, constructor, [
+          publicKey!.x,
+          publicKey!.y,
+        ]);
+        await storeCall.simulate({ from: instance.address });
+      }
+    }
+    return accountManager;
+  }
+
+  async createAndStoreAccount(
+    alias: string,
+    type: AccountType,
+    secret: Fr,
+    salt: Fr,
+    signingKey: Buffer,
+  ): Promise<AccountManager> {
+    const accountManager = await this.createAccountInternal(type, secret, salt, signingKey);
+    await this.walletDB.storeAccount(accountManager.address, { type, secretKey: secret, salt, alias, signingKey });
+    return accountManager;
+  }
+
+  createSchnorrAccount(secret: Fr, salt: Fr, signingKey: Fq, alias?: string): Promise<AccountManager> {
+    return this.createAndStoreAccount(alias ?? '', 'schnorr', secret, salt, signingKey.toBuffer());
+  }
+
+  createSchnorrInitializerlessAccount(secret: Fr, salt: Fr, signingKey: Fq, alias?: string): Promise<AccountManager> {
+    return this.createAndStoreAccount(alias ?? '', 'schnorr_initializerless', secret, salt, signingKey.toBuffer());
+  }
+
+  createECDSARAccount(secret: Fr, salt: Fr, signingKey: Buffer, alias?: string): Promise<AccountManager> {
+    return this.createAndStoreAccount(alias ?? '', 'ecdsasecp256r1', secret, salt, signingKey);
+  }
+
+  createECDSAKAccount(secret: Fr, salt: Fr, signingKey: Buffer, alias?: string): Promise<AccountManager> {
+    return this.createAndStoreAccount(alias ?? '', 'ecdsasecp256k1', secret, salt, signingKey);
+  }
+
+  setMinFeePadding(value?: number) {
+    this.minFeePadding = value ?? 0.5;
+  }
+
+  setEstimatedGasPadding(value?: number) {
+    this.estimatedGasPadding = value ?? DEFAULT_ESTIMATED_GAS_PADDING;
+  }
+
+  async stop(): Promise<void> {
+    await this.pxe.stop();
+    await this.walletDB.close();
+  }
+}

package/src/embedded/entrypoints/browser.ts

@@ -0,0 +1,93 @@
+import type { AztecNode } from '@aztec-labs/aztec.js/node';
+import { type Logger, createLogger } from '@aztec-labs/foundation/log';
+import { openTmpStore } from '@aztec-labs/kv-store/sqlite-opfs';
+import { type PXE, type PXECreationOptions, createPXE, openBrowserStore } from '@aztec-labs/pxe/client/lazy';
+import { type PXEConfig, getPXEConfig } from '@aztec-labs/pxe/config';
+import { getStandardAuthRegistry } from '@aztec-labs/standard-contracts/auth-registry/lazy';
+import { getStandardHandshakeRegistry } from '@aztec-labs/standard-contracts/handshake-registry/lazy';
+import { getStandardMultiCallEntrypoint } from '@aztec-labs/standard-contracts/multi-call-entrypoint/lazy';
+
+import { LazyAccountContractsProvider } from '../account-contract-providers/lazy.js';
+import type { AccountContractsProvider } from '../account-contract-providers/types.js';
+import { EmbeddedWallet, type EmbeddedWalletOptions, splitPxeOptions } from '../embedded_wallet.js';
+import { WALLET_DATA_SCHEMA_VERSION, WalletDB } from '../wallet_db.js';
+import { resolveAztecNode } from './resolve_aztec_node.js';
+
+export class BrowserEmbeddedWallet extends EmbeddedWallet {
+  static async create<T extends BrowserEmbeddedWallet = BrowserEmbeddedWallet>(
+    this: new (
+      pxe: PXE,
+      aztecNode: AztecNode,
+      walletDB: WalletDB,
+      accountContracts: AccountContractsProvider,
+      log?: Logger,
+    ) => T,
+    nodeOrUrl: string | AztecNode,
+    options: EmbeddedWalletOptions = {},
+  ): Promise<T> {
+    const rootLogger = options.logger ?? createLogger('embedded-wallet');
+
+    const aztecNode = resolveAztecNode(nodeOrUrl, options.nodeClientOptions);
+
+    // Support both the new unified `pxe` option and the deprecated `pxeConfig`/`pxeOptions`.
+    const { config: pxeConfigFromPxe, creation: pxeCreationFromPxe } = splitPxeOptions(options.pxe);
+    const mergedConfigOverrides = { ...options.pxeConfig, ...pxeConfigFromPxe };
+    const mergedCreationOverrides: PXECreationOptions = { ...options.pxeOptions, ...pxeCreationFromPxe };
+
+    const pxeConfig: PXEConfig = Object.assign(getPXEConfig(), {
+      proverEnabled: mergedConfigOverrides.proverEnabled,
+      // Unused in the browser: sqlite-opfs keys stores by name, not directory.
+      dataDirectory: 'pxe_data',
+      autoSync: false,
+      ...mergedConfigOverrides,
+    });
+
+    if (options.ephemeral) {
+      delete pxeConfig.dataDirectory;
+    }
+
+    const pxeOptions: PXECreationOptions = {
+      ...mergedCreationOverrides,
+      preloadedContractsProvider: mergedCreationOverrides.preloadedContractsProvider ?? {
+        getPreloadedContracts: async () => [
+          await getStandardMultiCallEntrypoint(),
+          await getStandardAuthRegistry(),
+          await getStandardHandshakeRegistry(),
+        ],
+      },
+      loggers: {
+        store: rootLogger.createChild('pxe:data'),
+        pxe: rootLogger.createChild('pxe:service'),
+        prover: rootLogger.createChild('pxe:prover'),
+        ...mergedCreationOverrides.loggers,
+      },
+    };
+
+    const pxe = await createPXE(aztecNode, pxeConfig, pxeOptions);
+
+    let walletDBStore = options.walletDb?.store;
+    if (!walletDBStore) {
+      if (options.ephemeral) {
+        walletDBStore = await openTmpStore(true);
+      } else {
+        const { l1ChainId, l1ContractAddresses } = await aztecNode.getNodeInfo();
+        walletDBStore = await openBrowserStore(
+          'wallet_data',
+          WALLET_DATA_SCHEMA_VERSION,
+          { l1ChainId, rollupAddress: l1ContractAddresses.rollupAddress },
+          rootLogger.createChild('wallet:data'),
+        );
+      }
+    }
+    const walletDB = new WalletDB(walletDBStore, rootLogger.createChild('wallet:db').info);
+
+    const wallet = new this(pxe, aztecNode, walletDB, new LazyAccountContractsProvider(), rootLogger) as T;
+    await wallet.initStubClasses();
+    return wallet;
+  }
+}
+
+export { BrowserEmbeddedWallet as EmbeddedWallet };
+export type { EmbeddedWalletOptions, EmbeddedWalletPXEOptions } from '../embedded_wallet.js';
+export { WalletDB } from '../wallet_db.js';
+export type { AccountType } from '../wallet_db.js';

package/src/embedded/entrypoints/node.ts

@@ -0,0 +1,100 @@
+import { type Logger, createLogger } from '@aztec-labs/foundation/log';
+import { openTmpStore } from '@aztec-labs/kv-store/lmdb-v2';
+import { type PXEConfig, getPXEConfig } from '@aztec-labs/pxe/config';
+import { type PXE, type PXECreationOptions, createPXE, openStore } from '@aztec-labs/pxe/server';
+import { getStandardAuthRegistry } from '@aztec-labs/standard-contracts/auth-registry';
+import { getStandardHandshakeRegistry } from '@aztec-labs/standard-contracts/handshake-registry';
+import { getStandardMultiCallEntrypoint } from '@aztec-labs/standard-contracts/multi-call-entrypoint';
+import type { AztecNode } from '@aztec-labs/stdlib/interfaces/client';
+
+import { BundleAccountContractsProvider } from '../account-contract-providers/bundle.js';
+import type { AccountContractsProvider } from '../account-contract-providers/types.js';
+import { EmbeddedWallet, type EmbeddedWalletOptions, splitPxeOptions } from '../embedded_wallet.js';
+import { WALLET_DATA_SCHEMA_VERSION, WalletDB } from '../wallet_db.js';
+import { resolveAztecNode } from './resolve_aztec_node.js';
+
+const DEFAULT_WALLET_DATA_DIRECTORY = 'aztec-wallet-data';
+
+export class NodeEmbeddedWallet extends EmbeddedWallet {
+  static async create<T extends NodeEmbeddedWallet = NodeEmbeddedWallet>(
+    this: new (
+      pxe: PXE,
+      aztecNode: AztecNode,
+      walletDB: WalletDB,
+      accountContracts: AccountContractsProvider,
+      log?: Logger,
+    ) => T,
+    nodeOrUrl: string | AztecNode,
+    options: EmbeddedWalletOptions = {},
+  ): Promise<T> {
+    const rootLogger = options.logger ?? createLogger('embedded-wallet');
+
+    const aztecNode = resolveAztecNode(nodeOrUrl, options.nodeClientOptions);
+
+    // Support both the new unified `pxe` option and the deprecated `pxeConfig`/`pxeOptions`.
+    const { config: pxeConfigFromPxe, creation: pxeCreationFromPxe } = splitPxeOptions(options.pxe);
+    const mergedConfigOverrides = { ...options.pxeConfig, ...pxeConfigFromPxe };
+    const mergedCreationOverrides: PXECreationOptions = { ...options.pxeOptions, ...pxeCreationFromPxe };
+
+    const pxeConfig: PXEConfig = Object.assign(getPXEConfig(), {
+      proverEnabled: mergedConfigOverrides.proverEnabled,
+      dataDirectory: DEFAULT_WALLET_DATA_DIRECTORY,
+      autoSync: false,
+      ...mergedConfigOverrides,
+    });
+
+    if (options.ephemeral) {
+      delete pxeConfig.dataDirectory;
+    }
+
+    const pxeOptions: PXECreationOptions = {
+      ...mergedCreationOverrides,
+      preloadedContractsProvider: mergedCreationOverrides.preloadedContractsProvider ?? {
+        getPreloadedContracts: async () => [
+          await getStandardMultiCallEntrypoint(),
+          await getStandardAuthRegistry(),
+          await getStandardHandshakeRegistry(),
+        ],
+      },
+      loggers: {
+        store: rootLogger.createChild('pxe:data'),
+        pxe: rootLogger.createChild('pxe:service'),
+        prover: rootLogger.createChild('pxe:prover'),
+        ...mergedCreationOverrides.loggers,
+      },
+    };
+
+    const pxe = await createPXE(aztecNode, pxeConfig, pxeOptions);
+
+    let walletDBStore = options.walletDb?.store;
+    if (!walletDBStore) {
+      const bindings = rootLogger.createChild('wallet:data').getBindings();
+      if (options.ephemeral) {
+        walletDBStore = await openTmpStore('wallet_data', true, undefined, undefined, bindings);
+      } else {
+        const { l1ChainId, l1ContractAddresses } = await aztecNode.getNodeInfo();
+        walletDBStore = await openStore(
+          'wallet_data',
+          WALLET_DATA_SCHEMA_VERSION,
+          {
+            dataDirectory: pxeConfig.dataDirectory ?? DEFAULT_WALLET_DATA_DIRECTORY,
+            dataStoreMapSizeKb: pxeConfig.dataStoreMapSizeKb,
+            l1ChainId,
+            rollupAddress: l1ContractAddresses.rollupAddress,
+          },
+          bindings,
+        );
+      }
+    }
+    const walletDB = new WalletDB(walletDBStore, rootLogger.createChild('wallet:db').info);
+
+    const wallet = new this(pxe, aztecNode, walletDB, new BundleAccountContractsProvider(), rootLogger) as T;
+    await wallet.initStubClasses();
+    return wallet;
+  }
+}
+
+export { NodeEmbeddedWallet as EmbeddedWallet };
+export type { EmbeddedWalletOptions, EmbeddedWalletPXEOptions } from '../embedded_wallet.js';
+export { WalletDB } from '../wallet_db.js';
+export type { AccountType } from '../wallet_db.js';

package/src/embedded/entrypoints/resolve_aztec_node.ts

@@ -0,0 +1,10 @@
+import {
+  type AztecNode,
+  type AztecNodeClientOptions,
+  createAztecNodeClient,
+} from '@aztec-labs/stdlib/interfaces/client';
+
+/** Returns a provided node or creates a JSON-RPC client for a node URL. */
+export function resolveAztecNode(nodeOrUrl: string | AztecNode, nodeClientOptions?: AztecNodeClientOptions): AztecNode {
+  return typeof nodeOrUrl === 'string' ? createAztecNodeClient(nodeOrUrl, nodeClientOptions) : nodeOrUrl;
+}