Merge remote-tracking branch 'origin/merge-train/spartan-v5' into phil/a-1418-prover-node-make-epoch-proving-robust-to-prune-induced-fork

Author: PhilWindle

docs/examples/ts/aztecjs_runner/run.sh

@@ -115,7 +115,7 @@ setup_project() {
         [ ${#NPM_DEPS[@]} -gt 0 ] && yarn_add_with_retry "${NPM_DEPS[@]}"
     fi
 
-    yarn_add_with_retry -D typescript tsx
+    yarn_add_with_retry -D typescript@^5.3.3 tsx
 
     # Copy tsconfig
     cp "$EXAMPLES_DIR/tsconfig.template.json" tsconfig.json

yarn-project/kv-store/src/sqlite-opfs/errors.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+
+import { isCorruptionMessage, isDecryptFailureMessage } from './errors.js';
+
+/**
+ * The two classifiers must stay disjoint: a decrypt failure (wrong/missing key)
+ * is recoverable by re-keying, whereas a corrupt image is not. Mixing them would
+ * make the worker mis-tag failures and consumers take the wrong recovery path.
+ */
+describe('sqlite-opfs error classification', () => {
+  it('classifies SQLITE_CORRUPT / malformed-image messages as corruption', () => {
+    expect(isCorruptionMessage('SQLITE_CORRUPT: sqlite3 result code 11: database disk image is malformed')).toBe(true);
+    expect(isCorruptionMessage('database disk image is malformed')).toBe(true);
+  });
+
+  it('does not classify decrypt-failure messages as corruption', () => {
+    expect(isCorruptionMessage('file is not a database')).toBe(false);
+    expect(isCorruptionMessage('file is encrypted or is not a database')).toBe(false);
+  });
+
+  it('classifies sqlite3mc decrypt-failure messages as decrypt failures', () => {
+    expect(isDecryptFailureMessage('file is not a database')).toBe(true);
+    expect(isDecryptFailureMessage('file is encrypted or is not a database')).toBe(true);
+  });
+
+  it('does not classify corruption messages as decrypt failures', () => {
+    expect(isDecryptFailureMessage('database disk image is malformed')).toBe(false);
+    expect(isDecryptFailureMessage('SQLITE_CORRUPT: sqlite3 result code 11')).toBe(false);
+  });
+});

yarn-project/kv-store/src/sqlite-opfs/errors.ts

@@ -42,3 +42,37 @@ const SQLITE3MC_DECRYPT_ERROR_PATTERNS: readonly RegExp[] = [
 export function isDecryptFailureMessage(message: string): boolean {
   return SQLITE3MC_DECRYPT_ERROR_PATTERNS.some(p => p.test(message));
 }
+
+/**
+ * Error thrown by sqlite-opfs when the on-disk database image is corrupt
+ * (`SQLITE_CORRUPT`, result code 11 — "database disk image is malformed").
+ *
+ * Distinct from {@link SqliteEncryptionError}: no key recovers a corrupt image,
+ * so there is nothing to retry. The only escape is to delete the store and start
+ * fresh, so consumers pattern-match on `instanceof SqliteCorruptionError` to wipe
+ * and reopen rather than surfacing a dead-end error.
+ **/
+export class SqliteCorruptionError extends Error {
+  constructor(message: string, opts?: { cause?: unknown }) {
+    super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
+    this.name = 'SqliteCorruptionError';
+  }
+}
+
+/**
+ * Strings/codes raised by SQLite when a database image is corrupt. Kept disjoint
+ * from {@link SQLITE3MC_DECRYPT_ERROR_PATTERNS}: "file is not a database"
+ * (SQLITE_NOTADB) is the decrypt signal, whereas a malformed image is the
+ * genuinely-unrecoverable SQLITE_CORRUPT.
+ **/
+const SQLITE_CORRUPTION_ERROR_PATTERNS: readonly RegExp[] = [
+  /database disk image is malformed/i,
+  /\bSQLITE_CORRUPT\b/i,
+];
+
+/**
+ * Returns `true` if `message` matches one of the known SQLite corruption strings.
+ **/
+export function isCorruptionMessage(message: string): boolean {
+  return SQLITE_CORRUPTION_ERROR_PATTERNS.some(p => p.test(message));
+}

yarn-project/kv-store/src/sqlite-opfs/index.ts

@@ -3,7 +3,7 @@ import { createLogger } from '@aztec/foundation/log';
 import { AztecSQLiteOPFSStore } from './store.js';
 
 export { AztecSQLiteOPFSStore } from './store.js';
-export { SqliteEncryptionError } from './errors.js';
+export { SqliteCorruptionError, SqliteEncryptionError } from './errors.js';
 export type { SqliteEncryptionErrorCode } from './errors.js';
 export { OPFS_POOL_DIR_PREFIX, deleteStore, listStores, storePoolDirectory } from './manage.js';
 

yarn-project/kv-store/src/sqlite-opfs/store.ts

@@ -10,7 +10,7 @@ import type { AztecAsyncSet } from '../interfaces/set.js';
 import type { AztecAsyncSingleton } from '../interfaces/singleton.js';
 import type { AztecAsyncKVStore } from '../interfaces/store.js';
 import { SQLiteOPFSAztecArray } from './array.js';
-import { SqliteEncryptionError } from './errors.js';
+import { SqliteCorruptionError, SqliteEncryptionError, isCorruptionMessage } from './errors.js';
 import { SQLiteOPFSAztecMap } from './map.js';
 import type { ResultRow, SqlValue, WorkerRequest, WorkerResponse } from './messages.js';
 import { SQLiteOPFSAztecMultiMap } from './multi_map.js';
@@ -272,11 +272,15 @@ export class AztecSQLiteOPFSStore implements AztecAsyncKVStore {
       this.#pending.set(req.id, {
         resolve: resp => {
           if (resp.type === 'err') {
-            // Re-hydrate encryption-shaped errors as the typed class so consumers
-            // can pattern-match on `instanceof SqliteEncryptionError`. Plain
-            // errors stay plain — the wire protocol only tags encryption paths.
+            // Re-hydrate typed errors so consumers can pattern-match on
+            // `instanceof`. Encryption is tagged on the wire (some cases are
+            // pre-flight throws with no message to match); corruption is a
+            // single unambiguous message, so we classify it here rather than
+            // adding a redundant wire field. Everything else stays a plain Error.
             if (resp.encryptionCode !== undefined) {
               reject(new SqliteEncryptionError(resp.encryptionCode, resp.message));
+            } else if (isCorruptionMessage(resp.message)) {
+              reject(new SqliteCorruptionError(resp.message));
             } else {
               reject(new Error(resp.message));
             }

yarn-project/pxe/src/entrypoints/client/store.ts

@@ -1,6 +1,11 @@
 import type { EthAddress } from '@aztec/foundation/eth-address';
 import { type Logger, createLogger } from '@aztec/foundation/log';
-import { AztecSQLiteOPFSStore, storePoolDirectory } from '@aztec/kv-store/sqlite-opfs';
+import {
+  AztecSQLiteOPFSStore,
+  SqliteCorruptionError,
+  deleteStore,
+  storePoolDirectory,
+} from '@aztec/kv-store/sqlite-opfs';
 
 import { assertStoreIdentity, effectiveStoreName } from '../../storage/store_identity.js';
 
@@ -21,12 +26,23 @@ export async function openBrowserStore(
     storeName,
     dataStoreMapSizeKb: config.dataStoreMapSizeKb,
   });
-  const store = await AztecSQLiteOPFSStore.open(
-    createLogger('kv-store:sqlite-opfs'),
-    storeName,
-    false,
-    storePoolDirectory(storeName),
-  );
+  const openStore = () =>
+    AztecSQLiteOPFSStore.open(createLogger('kv-store:sqlite-opfs'), storeName, false, storePoolDirectory(storeName));
+
+  let store: AztecSQLiteOPFSStore;
+  try {
+    store = await openStore();
+  } catch (err) {
+    if (!(err instanceof SqliteCorruptionError)) {
+      throw err;
+    }
+    // A corrupt image is unrecoverable — no retry against the same bytes helps. Wipe the store's OPFS directory
+    // (safe: the failed open left no SAH-pool lock behind) and reopen a fresh, empty one, so the browser self-heals
+    // into a normal first-run rather than dead-ending on "database disk image is malformed" every load.
+    log.warn(`${storeName} store is corrupt (${err.message}); wiping and reopening fresh`);
+    await deleteStore(storeName);
+    store = await openStore();
+  }
   try {
     await assertStoreIdentity(store, storeName, identity);
   } catch (err) {

yarn-project/wallets/src/embedded/store_encryption.test.ts

@@ -6,11 +6,12 @@
  */
 import type { Logger } from '@aztec/foundation/log';
 import type { AztecSQLiteOPFSStore } from '@aztec/kv-store/sqlite-opfs';
-import { SqliteEncryptionError } from '@aztec/kv-store/sqlite-opfs';
+import { SqliteCorruptionError, SqliteEncryptionError } from '@aztec/kv-store/sqlite-opfs';
 
 import {
   EmbeddedWalletEncryptionError,
   type OpenSqliteEncryptedStoreFn,
+  type WipeSqliteStoreFn,
   openEncryptedEmbeddedStores,
 } from './store_encryption.js';
 
@@ -189,4 +190,54 @@ describe('openEncryptedEmbeddedStores', () => {
 
     expect(keyProvider.callCount).toBe(2);
   });
+
+  it('wipes the corrupt store and reopens it fresh', async () => {
+    const pxe = makeMockStore();
+    const wallet = makeMockStore();
+    const wiped: (string | undefined)[] = [];
+    const wipeStore: WipeSqliteStoreFn = poolDirectory => {
+      wiped.push(poolDirectory);
+      return Promise.resolve();
+    };
+    let pxeOpens = 0;
+    const openStore: OpenSqliteEncryptedStoreFn = (_log, name) => {
+      if (name === 'pxe_data') {
+        pxeOpens++;
+        // First open hits a malformed image; the reopen (after wipe) succeeds.
+        return pxeOpens === 1
+          ? Promise.reject(new SqliteCorruptionError('database disk image is malformed'))
+          : Promise.resolve(pxe.store);
+      }
+      return Promise.resolve(wallet.store);
+    };
+
+    const result = await openEncryptedEmbeddedStores(
+      config,
+      makeKeyProvider().getKey,
+      noopLogger,
+      openStore,
+      wipeStore,
+    );
+
+    expect(result.pxeStore).toBe(pxe.store);
+    expect(result.walletStore).toBe(wallet.store);
+    // Only the corrupt store's own directory is wiped, and the store is reopened once.
+    expect(wiped).toEqual(['/pxe']);
+    expect(pxeOpens).toBe(2);
+  });
+
+  it('rethrows corruption if the store is still corrupt after a wipe (no retry loop)', async () => {
+    const stillCorrupt = new SqliteCorruptionError('database disk image is malformed');
+    const openStore: OpenSqliteEncryptedStoreFn = () => Promise.reject(stillCorrupt);
+    const wipeStore: WipeSqliteStoreFn = () => Promise.resolve();
+
+    let caught: unknown;
+    try {
+      await openEncryptedEmbeddedStores(config, makeKeyProvider().getKey, noopLogger, openStore, wipeStore);
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBe(stillCorrupt);
+  });
 });

yarn-project/wallets/src/embedded/store_encryption.ts

@@ -8,7 +8,7 @@
  *     surfaces, so callers don't leak the SAH Pool's OPFS lock.
  */
 import type { Logger } from '@aztec/foundation/log';
-import { AztecSQLiteOPFSStore, SqliteEncryptionError } from '@aztec/kv-store/sqlite-opfs';
+import { AztecSQLiteOPFSStore, SqliteCorruptionError, SqliteEncryptionError } from '@aztec/kv-store/sqlite-opfs';
 
 /** Which of the embedded wallet's two stores failed to open. */
 export type EmbeddedStoreName = 'pxe' | 'wallet';
@@ -49,6 +49,29 @@ export type OpenSqliteEncryptedStoreFn = (
 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;
+  }
+  const root = await navigator.storage.getDirectory();
+  await root.removeEntry(poolDirectory, { recursive: true }).catch(() => {
+    // Already gone / never created — nothing to wipe.
+  });
+};
+
 /**
  * Opens the PXE and wallet stores in sequence, both encrypted with keys obtained from `getEncryptionKey`.
  *
@@ -75,10 +98,11 @@ export async function openEncryptedEmbeddedStores(
   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);
+  const pxeStore = await openOneStore('pxe', config.pxe, getEncryptionKey, log, openStore, wipeStore);
   try {
-    const walletStore = await openOneStore('wallet', config.wallet, getEncryptionKey, log, openStore);
+    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
@@ -94,6 +118,7 @@ async function openOneStore(
   getEncryptionKey: () => Promise<Uint8Array>,
   log: Logger,
   openStore: OpenSqliteEncryptedStoreFn,
+  wipeStore: WipeSqliteStoreFn,
 ): Promise<AztecSQLiteOPFSStore> {
   const key = await getEncryptionKey();
   try {
@@ -102,6 +127,16 @@ async function openOneStore(
     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;
   }
 }