@aztec-labs/wallets 6.0.0-nightly.20260829

package/src/embedded/store_encryption.ts

@@ -0,0 +1,146 @@
+/**
+ * Wallet-layer helpers for opening the embedded wallet's two encrypted stores (PXE + walletDB) as a cohesive unit.
+ *
+ * Sits on top of `@aztec-labs/kv-store/sqlite-opfs`'s typed `SqliteEncryptionError` and adds:
+ *
+ *   - `storeName: 'pxe' | 'wallet'`, telling callers WHICH store failed.
+ *   - Cleanup: when the wallet store fails to open, ensures the already-opened PXE store is closed before the error
+ *     surfaces, so callers don't leak the SAH Pool's OPFS lock.
+ */
+import type { Logger } from '@aztec-labs/foundation/log';
+import {
+  AztecSQLiteOPFSStore,
+  SqliteCorruptionError,
+  SqliteEncryptionError,
+  deletePoolDirectory,
+} from '@aztec-labs/kv-store/sqlite-opfs';
+
+/** Which of the embedded wallet's two stores failed to open. */
+export type EmbeddedStoreName = 'pxe' | 'wallet';
+
+/**
+ * Thrown by {@link openEncryptedEmbeddedStores} when one of the two stores cannot be decrypted with the supplied
+ * key. The original {@link SqliteEncryptionError} is preserved as `cause`.
+ */
+export class EmbeddedWalletEncryptionError extends Error {
+  readonly storeName: EmbeddedStoreName;
+
+  constructor(storeName: EmbeddedStoreName, opts: { cause: SqliteEncryptionError }) {
+    super(`Embedded wallet '${storeName}' store could not be decrypted with the provided key`, { cause: opts.cause });
+    this.name = 'EmbeddedWalletEncryptionError';
+    this.storeName = storeName;
+  }
+}
+
+/** Configuration for {@link openEncryptedEmbeddedStores}. */
+export interface OpenEncryptedEmbeddedStoresOptions {
+  pxe: { name: string; poolDirectory?: string };
+  wallet: { name: string; poolDirectory?: string };
+}
+
+/**
+ * Internal seam for tests to inject a fake store opener. Defaults to `AztecSQLiteOPFSStore.open`. Not part of the
+ * public API.
+ *
+ * @internal
+ */
+export type OpenSqliteEncryptedStoreFn = (
+  log: Logger,
+  name: string,
+  poolDirectory: string | undefined,
+  encryptionKey: Uint8Array,
+) => Promise<AztecSQLiteOPFSStore>;
+
+const defaultOpenStore: OpenSqliteEncryptedStoreFn = (log, name, poolDirectory, encryptionKey) =>
+  AztecSQLiteOPFSStore.open(log, name, false, poolDirectory, encryptionKey);
+
+/**
+ * Internal seam for tests to inject a fake store wiper. Defaults to removing the store's OPFS pool directory
+ * outright. Not part of the public API.
+ *
+ * @internal
+ */
+export type WipeSqliteStoreFn = (poolDirectory: string | undefined) => Promise<void>;
+
+/**
+ * Deletes a store's OPFS pool directory. Safe to call only after a *failed* open() — a live store's SAH pool holds
+ * a lock on the directory and the removal would reject. A store with no `poolDirectory` lives in the shared default
+ * pool, which we won't blow away (it would take unrelated stores with it), so wiping is a no-op there.
+ */
+const defaultWipeStore: WipeSqliteStoreFn = async poolDirectory => {
+  if (!poolDirectory) {
+    return;
+  }
+  await deletePoolDirectory(poolDirectory).catch(() => {
+    // Already gone / never created — nothing to wipe.
+  });
+};
+
+/**
+ * Opens the PXE and wallet stores in sequence, both encrypted with keys obtained from `getEncryptionKey`.
+ *
+ * The callback is invoked once per store (twice total per call) because `AztecSQLiteOPFSStore.open` *transfers*
+ * the key buffer to its worker. A single buffer would detach between the two opens.
+ *
+ * Failure modes:
+ *
+ *   - PXE store fails to decrypt → throws `EmbeddedWalletEncryptionError({ storeName: 'pxe', cause })`. No cleanup
+ *     needed (nothing was opened).
+ *   - Wallet store fails to decrypt → closes the already-opened PXE store then throws
+ *     `EmbeddedWalletEncryptionError({ storeName: 'wallet', cause })`.
+ *   - Any non-decrypt error during the wallet open → still closes PXE, then re-throws the original error unwrapped
+ *     (preserves callers' existing untyped error handling for non-encryption faults).
+ *
+ * @param config           - Per-store name/poolDirectory.
+ * @param getEncryptionKey - Returns a fresh 32-byte key per call (the buffer
+ *                           detaches on transfer, so each call must allocate).
+ * @param log              - Logger for both stores.
+ * @param openStore        - Internal test seam. Do not pass in production code.
+ */
+export async function openEncryptedEmbeddedStores(
+  config: OpenEncryptedEmbeddedStoresOptions,
+  getEncryptionKey: () => Promise<Uint8Array>,
+  log: Logger,
+  openStore: OpenSqliteEncryptedStoreFn = defaultOpenStore,
+  wipeStore: WipeSqliteStoreFn = defaultWipeStore,
+): Promise<{ pxeStore: AztecSQLiteOPFSStore; walletStore: AztecSQLiteOPFSStore }> {
+  const pxeStore = await openOneStore('pxe', config.pxe, getEncryptionKey, log, openStore, wipeStore);
+  try {
+    const walletStore = await openOneStore('wallet', config.wallet, getEncryptionKey, log, openStore, wipeStore);
+    return { pxeStore, walletStore };
+  } catch (err) {
+    // Cleanup is best-effort — if close() itself throws (e.g. worker already dead), swallow it so the original error
+    // surfaces unobstructed.
+    await pxeStore.close().catch(() => {});
+    throw err;
+  }
+}
+
+async function openOneStore(
+  storeName: EmbeddedStoreName,
+  { name, poolDirectory }: { name: string; poolDirectory?: string },
+  getEncryptionKey: () => Promise<Uint8Array>,
+  log: Logger,
+  openStore: OpenSqliteEncryptedStoreFn,
+  wipeStore: WipeSqliteStoreFn,
+): Promise<AztecSQLiteOPFSStore> {
+  const key = await getEncryptionKey();
+  try {
+    return await openStore(log, name, poolDirectory, key);
+  } catch (err) {
+    if (err instanceof SqliteEncryptionError && err.code === 'decrypt_failed') {
+      throw new EmbeddedWalletEncryptionError(storeName, { cause: err });
+    }
+    if (err instanceof SqliteCorruptionError) {
+      // A corrupt image is unrecoverable — no key or retry against the same bytes brings it back. Self-heal
+      // instead of dead-ending forever: wipe the store's OPFS directory (safe — the failed open left no SAH-pool
+      // lock behind) and reopen a fresh, empty one, so callers see a normal first-run rather than a permanent
+      // "database disk image is malformed" on every open.
+      log.warn(`Embedded wallet '${storeName}' store is corrupt (${err.message}); wiping and reopening fresh`);
+      await wipeStore(poolDirectory);
+      // open() transferred (detached) the previous key buffer, so fetch a fresh one for the reopen.
+      return await openStore(log, name, poolDirectory, await getEncryptionKey());
+    }
+    throw err;
+  }
+}

package/src/embedded/wallet_db.ts

@@ -0,0 +1,150 @@
+import type { Aliased } from '@aztec-labs/aztec.js/wallet';
+import { Fq, Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { LogFn } from '@aztec-labs/foundation/log';
+import type { AztecAsyncKVStore, AztecAsyncMap } from '@aztec-labs/kv-store';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+
+export const AccountTypes = ['schnorr', 'schnorr_initializerless', 'ecdsasecp256r1', 'ecdsasecp256k1'] as const;
+export type AccountType = (typeof AccountTypes)[number];
+
+function accountKey(field: string, address: AztecAddress | string): string {
+  return `${field}:${address.toString()}`;
+}
+
+/** Bump when the WalletDB layout changes; a new version selects a fresh store, leaving the old one intact. */
+export const WALLET_DATA_SCHEMA_VERSION = 1;
+
+export class WalletDB {
+  private accounts: AztecAsyncMap<string, Buffer>;
+  private aliases: AztecAsyncMap<string, Buffer>;
+
+  constructor(
+    private store: AztecAsyncKVStore,
+    private userLog: LogFn,
+  ) {
+    this.accounts = store.openMap<string, Buffer>('accounts');
+    this.aliases = store.openMap<string, Buffer>('aliases');
+  }
+
+  async storeAccount(
+    address: AztecAddress,
+    {
+      type,
+      secretKey,
+      salt,
+      alias,
+      signingKey,
+    }: {
+      type: AccountType;
+      secretKey: Fr;
+      salt: Fr;
+      signingKey: Fq | Buffer;
+      alias: string | undefined;
+    },
+    log: LogFn = this.userLog,
+  ) {
+    await this.store.transactionAsync(async () => {
+      if (alias) {
+        await this.aliases.set(`accounts:${alias}`, Buffer.from(address.toString()));
+      }
+      await this.accounts.set(accountKey('type', address), Buffer.from(type));
+      await this.accounts.set(accountKey('sk', address), secretKey.toBuffer());
+      await this.accounts.set(accountKey('salt', address), salt.toBuffer());
+      await this.accounts.set(
+        accountKey('signingKey', address),
+        'toBuffer' in signingKey ? signingKey.toBuffer() : signingKey,
+      );
+    });
+    log(`Account stored in database${alias ? ` with alias ${alias}` : ''}`);
+  }
+
+  async storeSender(address: AztecAddress, alias: string, log: LogFn = this.userLog) {
+    await this.aliases.set(`senders:${alias}`, Buffer.from(address.toString()));
+    log(`Sender stored in database with alias ${alias}`);
+  }
+
+  async retrieveAccount(address: AztecAddress | string) {
+    const secretKeyBuffer = await this.accounts.getAsync(accountKey('sk', address));
+    if (!secretKeyBuffer) {
+      throw new Error(`Account "${address.toString()}" does not exist on this wallet.`);
+    }
+    const [saltBuffer, typeBuffer, signingKey] = await Promise.all([
+      this.accounts.getAsync(accountKey('salt', address)),
+      this.accounts.getAsync(accountKey('type', address)),
+      this.accounts.getAsync(accountKey('signingKey', address)),
+    ]);
+    const secretKey = Fr.fromBuffer(secretKeyBuffer);
+    const salt = Fr.fromBuffer(saltBuffer!);
+    const type = typeBuffer!.toString('utf8') as AccountType;
+    return { address, secretKey, salt, type, signingKey: signingKey! };
+  }
+
+  async listAccounts(): Promise<Aliased<AztecAddress>[]> {
+    // Read aliases and account addresses in parallel using range queries
+    const [aliasesByAddress, accountAddresses] = await Promise.all([
+      this.#readAccountAliases(),
+      this.#readAccountAddresses(),
+    ]);
+
+    return accountAddresses.map(addressStr => ({
+      alias: aliasesByAddress.get(addressStr) ?? '',
+      item: AztecAddress.fromStringUnsafe(addressStr),
+    }));
+  }
+
+  async listSenders(): Promise<Aliased<AztecAddress>[]> {
+    const result: Aliased<AztecAddress>[] = [];
+    for await (const [alias, item] of this.aliases.entriesAsync({ start: 'senders:', end: 'senders:\uffff' })) {
+      result.push({
+        alias: alias.slice('senders:'.length),
+        item: AztecAddress.fromStringUnsafe(item.toString()),
+      });
+    }
+    return result;
+  }
+
+  async #readAccountAliases(): Promise<Map<string, string>> {
+    const aliasesByAddress = new Map<string, string>();
+    for await (const [alias, item] of this.aliases.entriesAsync({ start: 'accounts:', end: 'accounts:\uffff' })) {
+      const address = item.toString();
+      aliasesByAddress.set(address, alias.slice('accounts:'.length));
+    }
+    return aliasesByAddress;
+  }
+
+  async #readAccountAddresses(): Promise<string[]> {
+    const addresses: string[] = [];
+    // Range query on 'type:' prefix — one entry per account, avoids scanning sk/salt/signingKey entries
+    for await (const [key] of this.accounts.entriesAsync({ start: 'type:', end: 'type:\uffff' })) {
+      addresses.push(key.slice('type:'.length));
+    }
+    return addresses;
+  }
+
+  /**
+   * Deletes an account's stored data and every alias pointing at it atomically. Deletion is local to this store;
+   * any state the PXE holds for the account is unaffected.
+   */
+  async deleteAccount(address: AztecAddress) {
+    await this.store.transactionAsync(async () => {
+      await Promise.all([
+        this.accounts.delete(accountKey('sk', address)),
+        this.accounts.delete(accountKey('salt', address)),
+        this.accounts.delete(accountKey('type', address)),
+        this.accounts.delete(accountKey('signingKey', address)),
+      ]);
+
+      const aliasKeys: string[] = [];
+      for await (const [key, item] of this.aliases.entriesAsync({ start: 'accounts:', end: 'accounts:\uffff' })) {
+        if (item.toString() === address.toString()) {
+          aliasKeys.push(key);
+        }
+      }
+      await Promise.all(aliasKeys.map(key => this.aliases.delete(key)));
+    });
+  }
+
+  async close() {
+    await this.store.close();
+  }
+}

package/src/testing.ts

@@ -0,0 +1,37 @@
+import type { InitialAccountData } from '@aztec-labs/accounts/testing';
+import { getInitialTestAccountsData } from '@aztec-labs/accounts/testing/lazy';
+import type { AccountManager } from '@aztec-labs/aztec.js/wallet';
+import type { Fq, Fr } from '@aztec-labs/foundation/curves/bn254';
+import { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+
+interface WalletWithSchnorrAccounts {
+  createSchnorrInitializerlessAccount(secret: Fr, salt: Fr, signingKey: Fq, alias?: string): Promise<AccountManager>;
+}
+
+/**
+ * Creates the given (genesis-funded) test accounts as initializerless schnorr accounts. Initializerless
+ * accounts need no deployment tx — creating one registers the instance and materializes its immutable keys
+ * locally — so the accounts are usable as soon as they are created, funded via genesis at their addresses.
+ */
+export async function createFundedInitializerlessAccounts(
+  wallet: WalletWithSchnorrAccounts,
+  accountsData: InitialAccountData[],
+) {
+  const accountManagers = [];
+  for (const { secret, salt, signingKey } of accountsData) {
+    accountManagers.push(await wallet.createSchnorrInitializerlessAccount(secret, salt, signingKey));
+  }
+  return accountManagers;
+}
+
+export async function registerInitialLocalNetworkAccountsInWallet(
+  wallet: WalletWithSchnorrAccounts,
+): Promise<AztecAddress[]> {
+  const testAccounts = await getInitialTestAccountsData();
+  return Promise.all(
+    testAccounts.map(async account => {
+      return (await wallet.createSchnorrInitializerlessAccount(account.secret, account.salt, account.signingKey))
+        .address;
+    }),
+  );
+}