@aztec/wallet-sdk 0.0.1-commit.f2ce05ee → 0.0.1-commit.f5d02921e

package/src/base-wallet/base_wallet.ts

@@ -1,20 +1,28 @@
-import type { Account } from '@aztec/aztec.js/account';
+import type { Account, NoFrom } from '@aztec/aztec.js/account';
+import { NO_FROM } from '@aztec/aztec.js/account';
 import type { CallIntent, IntentInnerHash } from '@aztec/aztec.js/authorization';
-import { type InteractionWaitOptions, NO_WAIT, type SendReturn } from '@aztec/aztec.js/contracts';
+import {
+  type InteractionWaitOptions,
+  NO_WAIT,
+  type SendReturn,
+  extractOffchainOutput,
+} from '@aztec/aztec.js/contracts';
 import type { FeePaymentMethod } from '@aztec/aztec.js/fee';
 import { waitForTx } from '@aztec/aztec.js/node';
-import type {
-  Aliased,
-  AppCapabilities,
-  BatchResults,
-  BatchedMethod,
-  PrivateEvent,
-  PrivateEventFilter,
-  ProfileOptions,
-  SendOptions,
-  SimulateOptions,
-  Wallet,
-  WalletCapabilities,
+import {
+  type Aliased,
+  type AppCapabilities,
+  type BatchResults,
+  type BatchedMethod,
+  ContractInitializationStatus,
+  type ExecuteUtilityOptions,
+  type PrivateEvent,
+  type PrivateEventFilter,
+  type ProfileOptions,
+  type SendOptions,
+  type SimulateOptions,
+  type Wallet,
+  type WalletCapabilities,
 } from '@aztec/aztec.js/wallet';
 import {
   GAS_ESTIMATION_DA_GAS_LIMIT,
@@ -23,10 +31,12 @@ import {
   GAS_ESTIMATION_TEARDOWN_L2_GAS_LIMIT,
 } from '@aztec/constants';
 import { AccountFeePaymentMethodOptions, type DefaultAccountEntrypointOptions } from '@aztec/entrypoints/account';
+import { DefaultEntrypoint } from '@aztec/entrypoints/default';
 import type { ChainInfo } from '@aztec/entrypoints/interfaces';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
 import type { FieldsOf } from '@aztec/foundation/types';
+import { type AccessScopes, displayDebugLogs } from '@aztec/pxe/client/lazy';
 import type { PXE, PackedPrivateEvent } from '@aztec/pxe/server';
 import {
   type ContractArtifact,
@@ -35,7 +45,7 @@ import {
   decodeFromAbi,
 } from '@aztec/stdlib/abi';
 import type { AuthWitness } from '@aztec/stdlib/auth-witness';
-import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
 import {
   type ContractInstanceWithAddress,
   computePartialAddress,
@@ -43,13 +53,17 @@ import {
 } from '@aztec/stdlib/contract';
 import { SimulationError } from '@aztec/stdlib/errors';
 import { Gas, GasSettings } from '@aztec/stdlib/gas';
-import { siloNullifier } from '@aztec/stdlib/hash';
+import {
+  computeSiloedPrivateInitializationNullifier,
+  computeSiloedPublicInitializationNullifier,
+} from '@aztec/stdlib/hash';
 import type { AztecNode } from '@aztec/stdlib/interfaces/client';
 import {
+  BlockHeader,
   type TxExecutionRequest,
   type TxProfileResult,
   TxSimulationResult,
-  type UtilitySimulationResult,
+  type UtilityExecutionResult,
 } from '@aztec/stdlib/tx';
 import { ExecutionPayload, mergeExecutionPayloads } from '@aztec/stdlib/tx';
 
@@ -67,17 +81,25 @@ export type FeeOptions = {
    */
   walletFeePaymentMethod?: FeePaymentMethod;
   /** Configuration options for the account to properly handle the selected fee payment method */
-  accountFeePaymentMethodOptions: AccountFeePaymentMethodOptions;
+  accountFeePaymentMethodOptions?: AccountFeePaymentMethodOptions;
   /** The gas settings to use for the transaction */
   gasSettings: GasSettings;
 };
 
+/** Options for `simulateViaEntrypoint`. */
+export type SimulateViaEntrypointOptions = Pick<
+  SimulateOptions,
+  'from' | 'additionalScopes' | 'skipTxValidation' | 'skipFeeEnforcement'
+> & {
+  /** Fee options for the entrypoint */
+  feeOptions: FeeOptions;
+  /** Scopes to use for the simulation */
+  scopes: AccessScopes;
+};
 /**
  * A base class for Wallet implementations
  */
 export abstract class BaseWallet implements Wallet {
-  protected log = createLogger('wallet-sdk:base_wallet');
-
   protected minFeePadding = 0.5;
   protected cancellableTransactions = false;
 
@@ -85,8 +107,15 @@ export abstract class BaseWallet implements Wallet {
   protected constructor(
     protected readonly pxe: PXE,
     protected readonly aztecNode: AztecNode,
+    protected log = createLogger('wallet-sdk:base_wallet'),
   ) {}
 
+  protected scopesFrom(from: AztecAddress | NoFrom, additionalScopes: AztecAddress[] = []): AztecAddress[] {
+    const allScopes = from === NO_FROM ? additionalScopes : [from, ...additionalScopes];
+    const scopeSet = new Set(allScopes.map(address => address.toString()));
+    return [...scopeSet].map(AztecAddress.fromString);
+  }
+
   protected abstract getAccountFromAddress(address: AztecAddress): Promise<Account>;
 
   abstract getAccounts(): Promise<Aliased<AztecAddress>[]>;
@@ -110,26 +139,33 @@ export abstract class BaseWallet implements Wallet {
 
   protected async createTxExecutionRequestFromPayloadAndFee(
     executionPayload: ExecutionPayload,
-    from: AztecAddress,
+    from: AztecAddress | NoFrom,
     feeOptions: FeeOptions,
   ): Promise<TxExecutionRequest> {
     const feeExecutionPayload = await feeOptions.walletFeePaymentMethod?.getExecutionPayload();
-    const executionOptions: DefaultAccountEntrypointOptions = {
-      txNonce: Fr.random(),
-      cancellable: this.cancellableTransactions,
-      feePaymentMethodOptions: feeOptions.accountFeePaymentMethodOptions,
-    };
     const finalExecutionPayload = feeExecutionPayload
       ? mergeExecutionPayloads([feeExecutionPayload, executionPayload])
       : executionPayload;
-    const fromAccount = await this.getAccountFromAddress(from);
     const chainInfo = await this.getChainInfo();
-    return fromAccount.createTxExecutionRequest(
-      finalExecutionPayload,
-      feeOptions.gasSettings,
-      chainInfo,
-      executionOptions,
-    );
+
+    if (from === NO_FROM) {
+      const entrypoint = new DefaultEntrypoint();
+      return entrypoint.createTxExecutionRequest(finalExecutionPayload, feeOptions.gasSettings, chainInfo);
+    } else {
+      const fromAccount = await this.getAccountFromAddress(from);
+      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!,
+      };
+      return fromAccount.createTxExecutionRequest(
+        finalExecutionPayload,
+        feeOptions.gasSettings,
+        chainInfo,
+        executionOptions,
+      );
+    }
   }
 
   public async createAuthWit(
@@ -184,23 +220,27 @@ export abstract class BaseWallet implements Wallet {
    * @returns - Complete fee options that can be used to create a transaction execution request
    */
   protected async completeFeeOptions(
-    from: AztecAddress,
+    from: AztecAddress | NoFrom,
     feePayer?: AztecAddress,
     gasSettings?: Partial<FieldsOf<GasSettings>>,
   ): Promise<FeeOptions> {
     const maxFeesPerGas =
       gasSettings?.maxFeesPerGas ?? (await this.aztecNode.getCurrentMinFees()).mul(1 + this.minFeePadding);
     let accountFeePaymentMethodOptions;
-    // The transaction does not include a fee payment method, so we set the flag
-    // for the account to use its fee juice balance
-    if (!feePayer) {
-      accountFeePaymentMethodOptions = AccountFeePaymentMethodOptions.PREEXISTING_FEE_JUICE;
-    } else {
-      // The transaction includes fee payment method, so we check if we are the fee payer for it
-      // (this can only happen if the embedded payment method is FeeJuiceWithClaim)
-      accountFeePaymentMethodOptions = from.equals(feePayer)
-        ? AccountFeePaymentMethodOptions.FEE_JUICE_WITH_CLAIM
-        : AccountFeePaymentMethodOptions.EXTERNAL;
+    // If from is an address, we need to determine the appropriate fee payment method options for the
+    // account contract entrypoint to use
+    if (from !== NO_FROM) {
+      if (!feePayer) {
+        // The transaction does not include a fee payment method, so we set the flag
+        // for the account to use its fee juice balance
+        accountFeePaymentMethodOptions = AccountFeePaymentMethodOptions.PREEXISTING_FEE_JUICE;
+      } else {
+        // The transaction includes fee payment method, so we check if we are the fee payer for it
+        // (this can only happen if the embedded payment method is FeeJuiceWithClaim)
+        accountFeePaymentMethodOptions = from.equals(feePayer)
+          ? AccountFeePaymentMethodOptions.FEE_JUICE_WITH_CLAIM
+          : AccountFeePaymentMethodOptions.EXTERNAL;
+      }
     }
     const fullGasSettings: GasSettings = GasSettings.default({ ...gasSettings, maxFeesPerGas });
     this.log.debug(`Using L2 gas settings`, fullGasSettings);
@@ -220,7 +260,7 @@ export abstract class BaseWallet implements Wallet {
    * @param gasSettings - User-provided partial gas settings
    */
   protected async completeFeeOptionsForEstimation(
-    from: AztecAddress,
+    from: AztecAddress | NoFrom,
     feePayer?: AztecAddress,
     gasSettings?: Partial<FieldsOf<GasSettings>>,
   ) {
@@ -287,20 +327,20 @@ export abstract class BaseWallet implements Wallet {
   /**
    * Simulates calls through the standard PXE path (account entrypoint).
    * @param executionPayload - The execution payload to simulate.
-   * @param from - The sender address.
-   * @param feeOptions - Fee options for the transaction.
-   * @param skipTxValidation - Whether to skip tx validation.
-   * @param skipFeeEnforcement - Whether to skip fee enforcement.
+   * @param opts - Simulation options.
    */
-  protected async simulateViaEntrypoint(
-    executionPayload: ExecutionPayload,
-    from: AztecAddress,
-    feeOptions: FeeOptions,
-    skipTxValidation?: boolean,
-    skipFeeEnforcement?: boolean,
-  ) {
-    const txRequest = await this.createTxExecutionRequestFromPayloadAndFee(executionPayload, from, feeOptions);
-    return this.pxe.simulateTx(txRequest, true /* simulatePublic */, skipTxValidation, skipFeeEnforcement);
+  protected async simulateViaEntrypoint(executionPayload: ExecutionPayload, opts: SimulateViaEntrypointOptions) {
+    const txRequest = await this.createTxExecutionRequestFromPayloadAndFee(
+      executionPayload,
+      opts.from,
+      opts.feeOptions,
+    );
+    return this.pxe.simulateTx(txRequest, {
+      simulatePublic: true,
+      skipTxValidation: opts.skipTxValidation,
+      skipFeeEnforcement: opts.skipFeeEnforcement,
+      scopes: opts.scopes,
+    });
   }
 
   /**
@@ -319,28 +359,37 @@ export abstract class BaseWallet implements Wallet {
     const remainingPayload = { ...executionPayload, calls: remainingCalls };
 
     const chainInfo = await this.getChainInfo();
-    const blockHeader = await this.pxe.getSyncedBlockHeader();
+    let blockHeader: BlockHeader;
+    // PXE might not be synced yet, so we pull the latest header from the node
+    // To keep things consistent, we'll always try with PXE first
+    try {
+      blockHeader = await this.pxe.getSyncedBlockHeader();
+    } catch {
+      blockHeader = (await this.aztecNode.getBlockHeader())!;
+    }
 
+    const simulationOrigin = opts.from === NO_FROM ? AztecAddress.ZERO : opts.from;
     const [optimizedResults, normalResult] = await Promise.all([
       optimizableCalls.length > 0
         ? simulateViaNode(
             this.aztecNode,
             optimizableCalls,
-            opts.from,
+            simulationOrigin,
             chainInfo,
             feeOptions.gasSettings,
             blockHeader,
             opts.skipFeeEnforcement ?? true,
+            this.getContractName.bind(this),
           )
         : Promise.resolve([]),
       remainingCalls.length > 0
-        ? this.simulateViaEntrypoint(
-            remainingPayload,
-            opts.from,
+        ? this.simulateViaEntrypoint(remainingPayload, {
+            from: opts.from,
             feeOptions,
-            opts.skipTxValidation,
-            opts.skipFeeEnforcement ?? true,
-          )
+            scopes: this.scopesFrom(opts.from, opts.additionalScopes),
+            skipTxValidation: opts.skipTxValidation,
+            skipFeeEnforcement: opts.skipFeeEnforcement ?? true,
+          })
         : Promise.resolve(null),
     ]);
 
@@ -350,7 +399,11 @@ export abstract class BaseWallet implements Wallet {
   async profileTx(executionPayload: ExecutionPayload, opts: ProfileOptions): Promise<TxProfileResult> {
     const feeOptions = await this.completeFeeOptions(opts.from, executionPayload.feePayer, opts.fee?.gasSettings);
     const txRequest = await this.createTxExecutionRequestFromPayloadAndFee(executionPayload, opts.from, feeOptions);
-    return this.pxe.profileTx(txRequest, opts.profileMode, opts.skipProofGeneration ?? true);
+    return this.pxe.profileTx(txRequest, {
+      profileMode: opts.profileMode,
+      skipProofGeneration: opts.skipProofGeneration ?? true,
+      scopes: this.scopesFrom(opts.from, opts.additionalScopes),
+    });
   }
 
   public async sendTx<W extends InteractionWaitOptions = undefined>(
@@ -359,7 +412,11 @@ export abstract class BaseWallet implements Wallet {
   ): Promise<SendReturn<W>> {
     const feeOptions = await this.completeFeeOptions(opts.from, executionPayload.feePayer, opts.fee?.gasSettings);
     const txRequest = await this.createTxExecutionRequestFromPayloadAndFee(executionPayload, opts.from, feeOptions);
-    const provenTx = await this.pxe.proveTx(txRequest);
+    const provenTx = await this.pxe.proveTx(txRequest, this.scopesFrom(opts.from, opts.additionalScopes));
+    const offchainOutput = extractOffchainOutput(
+      provenTx.getOffchainEffects(),
+      provenTx.publicInputs.constants.anchorBlockHeader.globalVariables.timestamp,
+    );
     const tx = await provenTx.toTx();
     const txHash = tx.getTxHash();
     if (await this.aztecNode.getTxEffect(txHash)) {
@@ -373,12 +430,32 @@ export abstract class BaseWallet implements Wallet {
 
     // If wait is NO_WAIT, return txHash immediately
     if (opts.wait === NO_WAIT) {
-      return txHash as SendReturn<W>;
+      return { txHash, ...offchainOutput } as SendReturn<W>;
     }
 
     // Otherwise, wait for the full receipt (default behavior on wait: undefined)
     const waitOpts = typeof opts.wait === 'object' ? opts.wait : undefined;
-    return (await waitForTx(this.aztecNode, txHash, waitOpts)) as SendReturn<W>;
+    const receipt = await waitForTx(this.aztecNode, txHash, waitOpts);
+
+    // Display debug logs from public execution if present (served in test mode only)
+    if (receipt.debugLogs?.length) {
+      await displayDebugLogs(receipt.debugLogs, this.getContractName.bind(this));
+    }
+
+    return { receipt, ...offchainOutput } as SendReturn<W>;
+  }
+
+  /**
+   * Resolves a contract address to a human-readable name via PXE, if available.
+   * @param address - The contract address to resolve.
+   */
+  protected async getContractName(address: AztecAddress): Promise<string | undefined> {
+    const instance = await this.pxe.getContractInstance(address);
+    if (!instance) {
+      return undefined;
+    }
+    const artifact = await this.pxe.getContractArtifact(instance.currentContractClassId);
+    return artifact?.name;
   }
 
   protected contextualizeError(err: Error, ...context: string[]): Error {
@@ -395,8 +472,8 @@ export abstract class BaseWallet implements Wallet {
     return err;
   }
 
-  simulateUtility(call: FunctionCall, authwits?: AuthWitness[]): Promise<UtilitySimulationResult> {
-    return this.pxe.simulateUtility(call, authwits);
+  executeUtility(call: FunctionCall, opts: ExecuteUtilityOptions): Promise<UtilityExecutionResult> {
+    return this.pxe.executeUtility(call, { authwits: opts.authWitnesses, scopes: opts.scopes });
   }
 
   async getPrivateEvents<T>(
@@ -419,17 +496,39 @@ export abstract class BaseWallet implements Wallet {
     return decodedEvents;
   }
 
+  /**
+   * Returns metadata about a contract, including whether it has been initialized, published, and updated.
+   * @param address - The contract address to query.
+   */
   async getContractMetadata(address: AztecAddress) {
     const instance = await this.pxe.getContractInstance(address);
-    const initNullifier = await siloNullifier(address, address.toField());
-    const publiclyRegisteredContract = await this.aztecNode.getContract(address);
-    const initNullifierMembershipWitness = await this.aztecNode.getNullifierMembershipWitness('latest', initNullifier);
+    const publiclyRegisteredContractPromise = this.aztecNode.getContract(address);
+
+    let initializationStatus: ContractInitializationStatus;
+    if (instance) {
+      // We have the instance, so we can compute the private initialization nullifier (which includes init_hash and is
+      // emitted by both private and public initializers) and get a definitive INITIALIZED/UNINITIALIZED answer.
+      const initNullifier = await computeSiloedPrivateInitializationNullifier(address, instance.initializationHash);
+      const witness = await this.aztecNode.getNullifierMembershipWitness('latest', initNullifier);
+      initializationStatus = witness
+        ? ContractInitializationStatus.INITIALIZED
+        : ContractInitializationStatus.UNINITIALIZED;
+    } else {
+      // Without the instance we lack the init_hash needed for the private nullifier. We fall back to checking the
+      // public initialization nullifier (computed from address alone). Not all contracts emit it (only those with
+      // public functions that require initialization checks), so its absence doesn't mean the contract is
+      // uninitialized.
+      const publicNullifier = await computeSiloedPublicInitializationNullifier(address);
+      const witness = await this.aztecNode.getNullifierMembershipWitness('latest', publicNullifier);
+      initializationStatus = witness ? ContractInitializationStatus.INITIALIZED : ContractInitializationStatus.UNKNOWN;
+    }
+    const publiclyRegisteredContract = await publiclyRegisteredContractPromise;
     const isContractUpdated =
       publiclyRegisteredContract &&
       !publiclyRegisteredContract.currentContractClassId.equals(publiclyRegisteredContract.originalContractClassId);
     return {
       instance: instance ?? undefined,
-      isContractInitialized: !!initNullifierMembershipWitness,
+      initializationStatus,
       isContractPublished: !!publiclyRegisteredContract,
       isContractUpdated: !!isContractUpdated,
       updatedContractClassId: isContractUpdated ? publiclyRegisteredContract.currentContractClassId : undefined,

package/src/base-wallet/index.ts

@@ -1,2 +1,2 @@
-export { BaseWallet, type FeeOptions } from './base_wallet.js';
+export { BaseWallet, type FeeOptions, type SimulateViaEntrypointOptions } from './base_wallet.js';
 export { simulateViaNode, buildMergedSimulationResult, extractOptimizablePublicStaticCalls } from './utils.js';

package/src/base-wallet/utils.ts

@@ -4,6 +4,8 @@ import type { ChainInfo } from '@aztec/entrypoints/interfaces';
 import { makeTuple } from '@aztec/foundation/array';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import type { Tuple } from '@aztec/foundation/serialize';
+import type { ContractNameResolver } from '@aztec/pxe/client/lazy';
+import { displayDebugLogs } from '@aztec/pxe/client/lazy';
 import { generateSimulatedProvingResult } from '@aztec/pxe/simulator';
 import { type FunctionCall, FunctionSelector } from '@aztec/stdlib/abi';
 import type { AztecAddress } from '@aztec/stdlib/aztec-address';
@@ -72,6 +74,7 @@ async function simulateBatchViaNode(
   gasSettings: GasSettings,
   blockHeader: BlockHeader,
   skipFeeEnforcement: boolean,
+  getContractName: ContractNameResolver,
 ): Promise<TxSimulationResult> {
   const txContext = new TxContext(chainInfo.chainId, chainInfo.version, gasSettings);
 
@@ -126,6 +129,7 @@ async function simulateBatchViaNode(
   const provingResult = await generateSimulatedProvingResult(
     privateResult,
     (_contractAddress: AztecAddress, _functionSelector: FunctionSelector) => Promise.resolve(''),
+    node,
     1, // minRevertibleSideEffectCounter
   );
 
@@ -144,6 +148,9 @@ async function simulateBatchViaNode(
     throw publicOutput.revertReason;
   }
 
+  // Display debug logs from the public simulation.
+  await displayDebugLogs(publicOutput.debugLogs, getContractName);
+
   return new TxSimulationResult(privateResult, provingResult.publicInputs, publicOutput, undefined);
 }
 
@@ -168,6 +175,7 @@ export async function simulateViaNode(
   gasSettings: GasSettings,
   blockHeader: BlockHeader,
   skipFeeEnforcement: boolean = true,
+  getContractName: ContractNameResolver,
 ): Promise<TxSimulationResult[]> {
   const batches: FunctionCall[][] = [];
 
@@ -186,6 +194,7 @@ export async function simulateViaNode(
       gasSettings,
       blockHeader,
       skipFeeEnforcement,
+      getContractName,
     );
     results.push(result);
   }

package/src/crypto.ts

@@ -497,3 +497,107 @@ export function hashToEmoji(hash: string, count: number = DEFAULT_EMOJI_GRID_SIZ
   }
   return emojis.join('');
 }
+
+// ─── Passphrase-based encryption (PBKDF2 + AES-256-GCM) ───────────────────
+
+/** Default PBKDF2 iteration count. High to compensate for short PINs (~1-2s on modern hardware). */
+const DEFAULT_PBKDF2_ITERATIONS = 2_000_000;
+const PBKDF2_SALT_BYTES = 16;
+const PBKDF2_IV_BYTES = 12;
+
+/**
+ * Derives an AES-256-GCM key from a passphrase using PBKDF2-SHA256.
+ *
+ * @param passphrase - The user-provided passphrase or PIN
+ * @param salt - Random salt bytes
+ * @param iterations - PBKDF2 iteration count (default: 2,000,000)
+ * @returns An AES-256-GCM CryptoKey
+ */
+export async function deriveKeyFromPassphrase(
+  passphrase: string,
+  salt: Uint8Array,
+  iterations: number = DEFAULT_PBKDF2_ITERATIONS,
+): Promise<CryptoKey> {
+  const keyMaterial = await crypto.subtle.importKey('raw', new TextEncoder().encode(passphrase), 'PBKDF2', false, [
+    'deriveKey',
+  ]);
+  return crypto.subtle.deriveKey(
+    { name: 'PBKDF2', salt: salt as BufferSource, iterations, hash: 'SHA-256' },
+    keyMaterial,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+/**
+ * Encrypts arbitrary bytes with a passphrase using PBKDF2 + AES-256-GCM.
+ *
+ * Output layout: `[salt (16)] [iv (12)] [ciphertext (...)]`
+ *
+ * @param plaintext - Data to encrypt
+ * @param passphrase - User passphrase or PIN
+ * @param iterations - PBKDF2 iteration count (default: 2,000,000)
+ * @returns A Uint8Array containing salt + iv + ciphertext
+ */
+export async function encryptWithPassphrase(
+  plaintext: Uint8Array,
+  passphrase: string,
+  iterations: number = DEFAULT_PBKDF2_ITERATIONS,
+): Promise<Uint8Array> {
+  const salt = crypto.getRandomValues(new Uint8Array(PBKDF2_SALT_BYTES));
+  const iv = crypto.getRandomValues(new Uint8Array(PBKDF2_IV_BYTES));
+  const key = await deriveKeyFromPassphrase(passphrase, salt, iterations);
+  const ciphertext = new Uint8Array(
+    await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintext as BufferSource),
+  );
+  const result = new Uint8Array(PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES + ciphertext.length);
+  result.set(salt, 0);
+  result.set(iv, PBKDF2_SALT_BYTES);
+  result.set(ciphertext, PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES);
+  return result;
+}
+
+/**
+ * Decrypts data produced by {@link encryptWithPassphrase}.
+ *
+ * @param data - The encrypted blob (salt + iv + ciphertext)
+ * @param passphrase - The passphrase used during encryption
+ * @param iterations - PBKDF2 iteration count (must match encryption)
+ * @returns The decrypted plaintext bytes
+ * @throws On wrong passphrase (AES-GCM auth tag mismatch)
+ */
+export async function decryptWithPassphrase(
+  data: Uint8Array,
+  passphrase: string,
+  iterations: number = DEFAULT_PBKDF2_ITERATIONS,
+): Promise<Uint8Array> {
+  const salt = data.slice(0, PBKDF2_SALT_BYTES);
+  const iv = data.slice(PBKDF2_SALT_BYTES, PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES);
+  const ciphertext = data.slice(PBKDF2_SALT_BYTES + PBKDF2_IV_BYTES);
+  const key = await deriveKeyFromPassphrase(passphrase, salt, iterations);
+  return new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext as BufferSource));
+}
+
+/**
+ * Converts a Uint8Array to a base64 string.
+ */
+export function uint8ToBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const b of bytes) {
+    binary += String.fromCharCode(b);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Converts a base64 string to a Uint8Array.
+ */
+export function base64ToUint8(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/extension/provider/extension_wallet.ts

@@ -6,7 +6,7 @@ import { schemaHasMethod } from '@aztec/foundation/schemas';
 import type { FunctionsOf } from '@aztec/foundation/types';
 
 import { type EncryptedPayload, decrypt, encrypt } from '../../crypto.js';
-import { type WalletMessage, WalletMessageType, type WalletResponse } from '../../types.js';
+import { type DisconnectCallback, type WalletMessage, WalletMessageType, type WalletResponse } from '../../types.js';
 
 /**
  * Internal type representing a wallet method call before encryption.
@@ -19,11 +19,6 @@ type WalletMethodCall = {
   args: unknown[];
 };
 
-/**
- * Callback type for wallet disconnect events.
- */
-export type DisconnectCallback = () => void;
-
 /**
  * A wallet implementation that communicates with browser extension wallets
  * using an encrypted MessageChannel.
@@ -109,7 +104,7 @@ export class ExtensionWallet {
     sharedKey: CryptoKey,
     chainInfo: ChainInfo,
     appId: string,
-  ): Wallet {
+  ): ExtensionWallet {
     const wallet = new ExtensionWallet(chainInfo, appId, extensionId, port, sharedKey);
 
     // Set up message handler for encrypted responses and unencrypted control messages
@@ -127,8 +122,10 @@ export class ExtensionWallet {
     wallet.port.start();
 
     return new Proxy(wallet, {
-      get: (target, prop) => {
-        if (schemaHasMethod(WalletSchema, prop.toString())) {
+      get: (target, prop, receiver) => {
+        if (prop === 'asWallet') {
+          return () => receiver as unknown as Wallet;
+        } else if (schemaHasMethod(WalletSchema, prop.toString())) {
           return async (...args: unknown[]) => {
             const result = await target.postMessage({
               type: prop.toString() as keyof FunctionsOf<Wallet>,
@@ -140,7 +137,13 @@ export class ExtensionWallet {
           return target[prop as keyof ExtensionWallet];
         }
       },
-    }) as unknown as Wallet;
+    });
+  }
+
+  asWallet(): Wallet {
+    // Overridden by the proxy in create() to return the proxy itself.
+    // This body is never reached when accessed through create().
+    return this as unknown as Wallet;
   }
 
   /**

package/src/extension/provider/index.ts

@@ -1,4 +1,4 @@
-export { ExtensionWallet, type DisconnectCallback } from './extension_wallet.js';
+export { ExtensionWallet } from './extension_wallet.js';
 export {
   ExtensionProvider,
   type DiscoveredWallet,