@aztec/kv-store 0.0.1-commit.d431d1c → 0.0.1-commit.d58ff9d0

package/src/sqlite-opfs/store.ts

@@ -0,0 +1,330 @@
+import type { Logger } from '@aztec/foundation/log';
+import { SerialQueue } from '@aztec/foundation/queue';
+
+import type { AztecAsyncArray } from '../interfaces/array.js';
+import type { Key, StoreSize, Value } from '../interfaces/common.js';
+import type { AztecAsyncCounter } from '../interfaces/counter.js';
+import type { AztecAsyncMap } from '../interfaces/map.js';
+import type { AztecAsyncMultiMap } from '../interfaces/multi_map.js';
+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 { 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';
+import { quarantineDuplicatePool } from './pool_integrity.js';
+import { type PoolLockLease, acquirePoolLock, normalizePoolDirectory } from './pool_lock.js';
+import { SQLiteOPFSAztecSet } from './set.js';
+import { SQLiteOPFSAztecSingleton } from './singleton.js';
+
+/**
+ * Main-thread handle for a SQLite database persisted to OPFS via the `opfs-sahpool`
+ * VFS. Owns a dedicated Web Worker (the SAH Pool VFS requires Worker context) and
+ * routes every SQL op through it via typed postMessage RPC.
+ *
+ * Transaction ordering is guaranteed by a `SerialQueue` on the main thread combined
+ * with an `#inTx` flag: outside a `transactionAsync` block, each op acquires the
+ * queue for its own auto-commit; inside a block, the outer call holds the queue and
+ * nested ops bypass it to avoid deadlock.
+ */
+export class AztecSQLiteOPFSStore implements AztecAsyncKVStore {
+  readonly #worker: Worker;
+  readonly #pending = new Map<number, { resolve: (r: WorkerResponse) => void; reject: (err: Error) => void }>();
+  readonly #txQueue = new SerialQueue();
+  readonly #name: string;
+  readonly #log: Logger;
+  #nextId = 0;
+  #inTx = false;
+  #closed = false;
+  #workerFailed = false;
+
+  private constructor(
+    worker: Worker,
+    name: string,
+    log: Logger,
+    public readonly isEphemeral: boolean,
+    private readonly poolLock?: PoolLockLease,
+  ) {
+    this.#worker = worker;
+    this.#name = name;
+    this.#log = log;
+    this.#worker.onmessage = (ev: MessageEvent<WorkerResponse>) => {
+      const { id } = ev.data;
+      const handler = this.#pending.get(id);
+      if (!handler) {
+        this.#log.warn(`SQLite worker: no pending handler for id ${id}`);
+        return;
+      }
+      this.#pending.delete(id);
+      handler.resolve(ev.data);
+    };
+    this.#worker.onerror = ev => {
+      this.#workerFailed = true;
+      this.#log.error(`SQLite worker crashed: ${ev.message}`);
+      this.#rejectPending(`SQLite worker crashed: ${ev.message}`);
+    };
+    this.#txQueue.start();
+  }
+
+  /**
+   * Opens (or creates) a SQLite database stored in the OPFS SAH Pool. When `ephemeral`
+   * is true the database lives only in memory and is lost when the worker terminates.
+   * Pass `poolDirectory` to place the SAH Pool in a non-default OPFS subdirectory —
+   * required when multiple stores coexist in the same tab, because the SAH Pool holds
+   * an exclusive lock on its directory.
+   *
+   * Persistent stores hold an origin-wide Web Lock for the pool directory until close
+   * or delete. If another store instance already owns it, open fails immediately with
+   * `SqlitePoolBusyError`.
+   *
+   * Pass `encryptionKey` (exactly 32 bytes) to enable at-rest encryption via sqlite3mc's
+   * ChaCha20 page cipher. The key buffer is **transferred** to the worker — its
+   * ArrayBuffer detaches on the caller side after `postMessage`. This is intentional:
+   * the API encodes a one-key-one-owner invariant. A caller that wants to use the same
+   * key for multiple stores must explicitly clone it per call (e.g.
+   * `new Uint8Array(savedKey)`), making the duplication a visible, deliberate decision
+   * rather than a silent structured-clone operation. The default path (one `.open()`,
+   * one consumption of the key) leaves zero key bytes on the main thread after the call.
+   */
+  static async open(
+    log: Logger,
+    name?: string,
+    ephemeral: boolean = false,
+    poolDirectory?: string,
+    encryptionKey?: Uint8Array,
+  ): Promise<AztecSQLiteOPFSStore> {
+    if (encryptionKey !== undefined && encryptionKey.length !== 32) {
+      throw new SqliteEncryptionError(
+        'invalid_key_length',
+        `encryptionKey must be 32 bytes (got ${encryptionKey.length})`,
+      );
+    }
+    if (encryptionKey !== undefined && ephemeral) {
+      throw new SqliteEncryptionError(
+        'encryption_not_supported_for_ephemeral',
+        'encryptionKey is not supported for ephemeral (:memory:) stores',
+      );
+    }
+    const dbName = name && !ephemeral ? name : `tmp-${globalThis.crypto.getRandomValues(new Uint8Array(8)).join('')}`;
+    log.debug(
+      `Opening SQLite-OPFS ${ephemeral ? 'ephemeral ' : ''}${encryptionKey ? 'encrypted ' : ''}database ${dbName}`,
+    );
+    const effectivePoolDirectory = ephemeral ? undefined : normalizePoolDirectory(poolDirectory);
+    const poolLock = effectivePoolDirectory ? await acquirePoolLock(effectivePoolDirectory) : undefined;
+    let worker: Worker | undefined;
+    try {
+      if (effectivePoolDirectory) {
+        const quarantine = await quarantineDuplicatePool(effectivePoolDirectory);
+        if (quarantine) {
+          log.warn(`Quarantined SQLite-OPFS pool with duplicate logical file mappings`, quarantine);
+        }
+      }
+      worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
+      const store = new AztecSQLiteOPFSStore(worker, dbName, log, ephemeral, poolLock);
+      // Transfer (not clone) the key buffer to the worker so we don't leave a
+      // second copy on the main thread. Caveat: this detaches the caller's
+      // encryptionKey.buffer — subsequent reads from the same Uint8Array are empty.
+      const transfer = encryptionKey ? [encryptionKey.buffer as ArrayBuffer] : undefined;
+      await store.#sendRequest(
+        { type: 'init', id: store.#allocId(), dbName, ephemeral, poolDirectory: effectivePoolDirectory, encryptionKey },
+        transfer,
+      );
+      return store;
+    } catch (err) {
+      worker?.terminate();
+      await poolLock?.release();
+      throw err;
+    }
+  }
+
+  openMap<K extends Key, V extends Value>(name: string): AztecAsyncMap<K, V> {
+    return new SQLiteOPFSAztecMap<K, V>(this, name);
+  }
+
+  openSet<K extends Key>(name: string): AztecAsyncSet<K> {
+    return new SQLiteOPFSAztecSet<K>(this, name);
+  }
+
+  openMultiMap<K extends Key, V extends Value>(name: string): AztecAsyncMultiMap<K, V> {
+    return new SQLiteOPFSAztecMultiMap<K, V>(this, name);
+  }
+
+  openCounter<K extends Key>(_name: string): AztecAsyncCounter<K> {
+    throw new Error('Method not implemented.');
+  }
+
+  openArray<T extends Value>(name: string): AztecAsyncArray<T> {
+    return new SQLiteOPFSAztecArray<T>(this, name);
+  }
+
+  openSingleton<T extends Value>(name: string): AztecAsyncSingleton<T> {
+    return new SQLiteOPFSAztecSingleton<T>(this, name);
+  }
+
+  transactionAsync<T>(callback: () => Promise<T>): Promise<T> {
+    // Nested calls join the outer transaction — SQLite does not support nested BEGIN,
+    // and re-acquiring the SerialQueue while the outer call holds it would deadlock.
+    // Errors in the nested callback propagate to the outer catch, which rolls back the
+    // whole thing (the standard "nested tx = savepoint-free join" semantic).
+    if (this.#inTx) {
+      return callback();
+    }
+    return this.#txQueue.put(async () => {
+      this.#inTx = true;
+      await this.#sendRequest({ type: 'begin', id: this.#allocId() });
+      try {
+        const result = await callback();
+        await this.#sendRequest({ type: 'commit', id: this.#allocId() });
+        return result;
+      } catch (err) {
+        await this.#sendRequest({ type: 'rollback', id: this.#allocId() }).catch(rollbackErr =>
+          this.#log.warn(`SQLite ROLLBACK failed: ${rollbackErr instanceof Error ? rollbackErr.message : rollbackErr}`),
+        );
+        throw err;
+      } finally {
+        this.#inTx = false;
+      }
+    });
+  }
+
+  async clear(): Promise<void> {
+    await this.runAsync('DELETE FROM data');
+  }
+
+  async delete(): Promise<void> {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    try {
+      await this.#txQueue.end();
+      await this.#sendRequest({ type: 'deleteDb', id: this.#allocId(), dbName: this.#name }).catch(err =>
+        this.#log.warn(`SQLite deleteDb failed: ${err instanceof Error ? err.message : err}`),
+      );
+    } finally {
+      this.#worker.terminate();
+      this.#rejectPending('SQLite store deleted');
+      await this.poolLock?.release();
+    }
+  }
+
+  /**
+   * Placeholder — returns zeros to mirror the IndexedDB backend. SQLite exposes real
+   * numbers cheaply via `PRAGMA page_count` / `page_size` / `freelist_count` and
+   * `SELECT COUNT(*) FROM data`, which would populate `physicalFileSize`, `actualSize`,
+   * and `numItems` meaningfully (`mappingSize` stays 0 — it's an LMDB mmap concept).
+   * Upgrade when any caller actually consumes these values; all current consumers
+   * tolerate zeros.
+   */
+  estimateSize(): Promise<StoreSize> {
+    return Promise.resolve({ mappingSize: 0, physicalFileSize: 0, actualSize: 0, numItems: 0 });
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    try {
+      await this.#txQueue.end();
+      await this.#sendRequest({ type: 'close', id: this.#allocId() }).catch(() => {});
+    } finally {
+      this.#worker.terminate();
+      this.#rejectPending('SQLite store closed');
+      await this.poolLock?.release();
+    }
+  }
+
+  backupTo(_dstPath: string, _compact?: boolean): Promise<void> {
+    throw new Error('Method not implemented.');
+  }
+
+  /**
+   * Returns a raw SQLite image (bytes suitable for writing as a `.sqlite` file and
+   * opening in any SQLite tool). Works only for non-ephemeral DBs because the OPFS
+   * SAH Pool has to be initialized. Useful for inspection/debugging.
+   */
+  async exportDb(): Promise<Uint8Array> {
+    const resp = await this.#sendRequest({ type: 'export', id: this.#allocId() });
+    if (!('bytes' in resp) || !resp.bytes) {
+      throw new Error('exportDb: worker returned no bytes');
+    }
+    return resp.bytes;
+  }
+
+  /**
+   * Runs a write statement (INSERT/UPDATE/DELETE/DDL). If called inside a
+   * `transactionAsync` block, bypasses the queue; otherwise acquires it so the
+   * op runs in its own auto-commit.
+   */
+  runAsync(sql: string, bind?: SqlValue[]): Promise<{ changes: number }> {
+    const send = () =>
+      this.#sendRequest({ type: 'run', id: this.#allocId(), sql, bind }).then(r => ({
+        changes: 'changes' in r ? (r.changes ?? 0) : 0,
+      }));
+    return this.#inTx ? send() : this.#txQueue.put(send);
+  }
+
+  /** Runs a SELECT statement and returns rows in array row-mode. */
+  allAsync(sql: string, bind?: SqlValue[]): Promise<ResultRow[]> {
+    const send = () =>
+      this.#sendRequest({ type: 'all', id: this.#allocId(), sql, bind }).then(r => ('rows' in r ? (r.rows ?? []) : []));
+    return this.#inTx ? send() : this.#txQueue.put(send);
+  }
+
+  #allocId(): number {
+    return ++this.#nextId;
+  }
+
+  /**
+   * Reject any in-flight requests with `reason`, so callers awaiting a response to a
+   * request sent to a now-terminated worker don't hang forever. Called from
+   * close()/delete() and from the worker.onerror handler.
+   */
+  #rejectPending(reason: string): void {
+    if (this.#pending.size === 0) {
+      return;
+    }
+    const err = new Error(reason);
+    for (const { reject } of this.#pending.values()) {
+      reject(err);
+    }
+    this.#pending.clear();
+  }
+
+  #sendRequest(req: WorkerRequest, transfer?: Transferable[]): Promise<WorkerResponse> {
+    if (this.#workerFailed) {
+      return Promise.reject(new Error('SQLite worker has crashed'));
+    }
+    return new Promise<WorkerResponse>((resolve, reject) => {
+      this.#pending.set(req.id, {
+        resolve: resp => {
+          if (resp.type === 'err') {
+            // 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));
+            }
+          } else {
+            resolve(resp);
+          }
+        },
+        reject,
+      });
+      if (transfer && transfer.length > 0) {
+        this.#worker.postMessage(req, transfer);
+      } else {
+        this.#worker.postMessage(req);
+      }
+    });
+  }
+}

package/src/sqlite-opfs/worker.ts

@@ -0,0 +1,259 @@
+/// <reference lib="webworker" />
+import sqlite3InitModule, { type Database, type SAHPoolUtil, type Sqlite3Static } from '@aztec/sqlite3mc-wasm';
+
+import { SqliteEncryptionError, type SqliteEncryptionErrorCode, isDecryptFailureMessage } from './errors.js';
+import type { ResultRow, SqlValue, WorkerRequest, WorkerResponse } from './messages.js';
+import { DEFAULT_SAH_POOL_DIRECTORY } from './pool_lock.js';
+
+const SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS data (
+    slot TEXT NOT NULL PRIMARY KEY,
+    container TEXT NOT NULL,
+    key BLOB NOT NULL,
+    key_count INTEGER NOT NULL,
+    hash TEXT NOT NULL,
+    value BLOB
+  ) WITHOUT ROWID;
+
+  CREATE INDEX IF NOT EXISTS idx_container_key ON data(container, key);
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_container_key_count ON data(container, key, key_count);
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_container_key_hash ON data(container, key, hash);
+`;
+
+const SAH_POOL_VFS_NAME = 'aztec-kv-opfs';
+const MC_SAH_POOL_VFS_NAME = `multipleciphers-${SAH_POOL_VFS_NAME}`;
+
+let sqlite3: Sqlite3Static | undefined;
+let pool: SAHPoolUtil | undefined;
+let db: Database | undefined;
+let dbPath: string | undefined;
+
+async function ensurePool(directory: string): Promise<SAHPoolUtil> {
+  const s = (sqlite3 ??= await sqlite3InitModule());
+  if (!pool) {
+    pool = await s.installOpfsSAHPoolVfs({
+      name: SAH_POOL_VFS_NAME,
+      directory,
+      initialCapacity: 8,
+    });
+    // Register a sqlite3mc-wrapped VFS pointing at our SAH Pool VFS.
+    // Encrypted DBs must be opened through this wrapper so sqlite3mc can
+    // intercept file I/O; plain DBs continue using the SAH Pool VFS directly.
+    // The wrapper name is `multipleciphers-<underlying>`.
+    (s.capi as unknown as { sqlite3mc_vfs_create(name: string, makeDefault: number): number }).sqlite3mc_vfs_create(
+      SAH_POOL_VFS_NAME,
+      0,
+    );
+  }
+  return pool!;
+}
+
+/**
+ * Applies sqlite3mc's ChaCha20 page cipher using a pre-derived 32-byte key.
+ * The PRAGMAs must run before any schema DDL so sqlite3mc can decrypt existing
+ * pages and encrypt new ones. Zeroes the caller-held key array after the PRAGMA
+ * completes to minimize residency of the raw key bytes outside sqlite3mc's heap.
+ */
+function applyEncryptionKey(conn: Database, key: Uint8Array): void {
+  const hex = Array.from(key, b => b.toString(16).padStart(2, '0')).join('');
+  conn.exec(`PRAGMA cipher = 'chacha20'`);
+  conn.exec(`PRAGMA key = "x'${hex}'"`);
+  key.fill(0);
+}
+
+async function handleInit(
+  dbName: string,
+  ephemeral: boolean,
+  directory?: string,
+  encryptionKey?: Uint8Array,
+): Promise<void> {
+  const s = (sqlite3 ??= await sqlite3InitModule());
+  if (encryptionKey !== undefined && ephemeral) {
+    throw new SqliteEncryptionError(
+      'encryption_not_supported_for_ephemeral',
+      'encryptionKey is not supported for ephemeral (:memory:) stores',
+    );
+  }
+  if (ephemeral) {
+    db = new s.oo1.DB(':memory:', 'c');
+  } else {
+    const activePool = await ensurePool(directory ?? DEFAULT_SAH_POOL_DIRECTORY);
+    dbPath = normalizeDbPath(dbName);
+    if (encryptionKey !== undefined) {
+      const conn = new s.oo1.DB({ filename: dbPath, flags: 'c', vfs: MC_SAH_POOL_VFS_NAME });
+      db = conn;
+      applyEncryptionKey(conn, encryptionKey);
+    } else {
+      db = new activePool.OpfsSAHPoolDb(dbPath);
+    }
+  }
+  runSql(SCHEMA_SQL);
+}
+
+function handleClose(): void {
+  try {
+    db?.close();
+  } finally {
+    db = undefined;
+    dbPath = undefined;
+    releasePool();
+  }
+}
+
+/**
+ * Releases the SAH pool's OPFS sync access handles before the terminal RPC is acked. Worker
+ * termination releases them only asynchronously, so without this a caller that deletes or reopens
+ * the store directory right after close()/delete() resolves races Chromium's cleanup
+ * (NoModificationAllowedError from removeEntry, or a hang installing a new pool on the directory).
+ * pauseVfs releases the handles without touching file contents; the worker is terminated right
+ * after, so the pool is never resumed.
+ */
+function releasePool(): void {
+  pool?.pauseVfs();
+  pool = undefined;
+}
+
+async function handleExport(): Promise<Uint8Array> {
+  if (!db || !dbPath) {
+    throw new Error('SQLite worker: no database open to export');
+  }
+  if (!pool) {
+    throw new Error('SQLite worker: no SAH Pool available (ephemeral DBs cannot be exported)');
+  }
+  return await pool.exportFile(dbPath);
+}
+
+function handleDeleteDb(dbName: string): void {
+  const path = normalizeDbPath(dbName);
+  if (db && dbPath === path) {
+    db.close();
+    db = undefined;
+    dbPath = undefined;
+  }
+  // Ephemeral :memory: DBs never back a file — skip installing a pool just to unlink
+  // nothing. installOpfsSAHPoolVfs acquires an exclusive lock on the OPFS SAH
+  // directory, and under heavy test churn that can contend with workers from
+  // previous tests whose OPFS handles Chromium hasn't yet released, hanging the RPC
+  // and then the whole test run.
+  if (!pool) {
+    return;
+  }
+  try {
+    pool.unlink(path);
+  } catch {
+    // File may not exist; ignore.
+  }
+  // Guarded because pauseVfs refuses (SQLITE_MISUSE) while any file is open through the VFS.
+  if (!db) {
+    releasePool();
+  }
+}
+
+function requireDb(): Database {
+  if (!db) {
+    throw new Error('SQLite worker: no database open');
+  }
+  return db;
+}
+
+function runSql(sql: string, bind?: SqlValue[]): { changes: number } {
+  const conn = requireDb();
+  conn.exec({ sql, bind });
+  return { changes: conn.changes() };
+}
+
+function selectAll(sql: string, bind?: SqlValue[]): ResultRow[] {
+  const conn = requireDb();
+  const rows: ResultRow[] = [];
+  conn.exec({ sql, bind, rowMode: 'array', resultRows: rows });
+  return rows;
+}
+
+function normalizeDbPath(dbName: string): string {
+  return dbName.startsWith('/') ? dbName : `/${dbName}`;
+}
+
+function respond(msg: WorkerResponse): void {
+  (self as DedicatedWorkerGlobalScope).postMessage(msg);
+}
+
+(self as DedicatedWorkerGlobalScope).onmessage = async (ev: MessageEvent<WorkerRequest>) => {
+  const req = ev.data;
+  try {
+    switch (req.type) {
+      case 'init':
+        await handleInit(req.dbName, req.ephemeral, req.poolDirectory, req.encryptionKey);
+        return respond({ type: 'ok', id: req.id });
+      case 'close':
+        handleClose();
+        return respond({ type: 'ok', id: req.id });
+      case 'deleteDb':
+        handleDeleteDb(req.dbName);
+        return respond({ type: 'ok', id: req.id });
+      case 'run': {
+        const { changes } = runSql(req.sql, req.bind);
+        return respond({ type: 'ok', id: req.id, changes });
+      }
+      case 'all': {
+        const rows = selectAll(req.sql, req.bind);
+        return respond({ type: 'ok', id: req.id, rows });
+      }
+      case 'export': {
+        const bytes = await handleExport();
+        return respond({ type: 'ok', id: req.id, bytes });
+      }
+      case 'begin':
+        runSql('BEGIN');
+        return respond({ type: 'ok', id: req.id });
+      case 'commit':
+        runSql('COMMIT');
+        return respond({ type: 'ok', id: req.id });
+      case 'rollback':
+        runSql('ROLLBACK');
+        return respond({ type: 'ok', id: req.id });
+      default: {
+        const _exhaustive: never = req;
+        throw new Error(`Unknown request: ${JSON.stringify(_exhaustive)}`);
+      }
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const encryptionCode = detectEncryptionCode(req, err, message);
+    if (req.type === 'init') {
+      try {
+        handleClose();
+      } catch {
+        // The main thread terminates this worker after a failed init, which releases any remaining OPFS handles.
+      }
+    }
+    respond({ type: 'err', id: req.id, message, encryptionCode });
+  }
+};
+
+/**
+ * Maps a thrown error during request handling to a typed encryption code, so the
+ * main thread can re-hydrate it as a {@link SqliteEncryptionError}. Returns
+ * `undefined` for non-encryption errors (preserves the existing untyped path).
+ *
+ * Two sources:
+ *   - The error was already a `SqliteEncryptionError` (pre-flight throws inside
+ *     this worker — e.g. ephemeral + encryptionKey). Forward its code as-is.
+ *   - The error came from SQLite/sqlite3mc with a known decrypt-failure message
+ *     during an `init` request. Both "wrong key supplied" and "no key supplied
+ *     to an encrypted DB" surface as SQLITE_NOTADB ("file is not a database") —
+ *     we don't constrain on `req.encryptionKey` because the no-key-on-encrypted-DB
+ *     case is exactly when the caller most needs the typed signal.
+ */
+function detectEncryptionCode(
+  req: WorkerRequest,
+  err: unknown,
+  message: string,
+): SqliteEncryptionErrorCode | undefined {
+  if (err instanceof SqliteEncryptionError) {
+    return err.code;
+  }
+  if (req.type === 'init' && isDecryptFailureMessage(message)) {
+    return 'decrypt_failed';
+  }
+  return undefined;
+}

package/src/stores/l2_tips_store.ts

@@ -1,31 +1,30 @@
 import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
-import { type L2BlockTag, L2TipsStoreBase } from '@aztec/stdlib/block';
-import { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
+import { type BlockHash, type CheckpointId, type L2BlockTag, L2TipsStoreBase } from '@aztec/stdlib/block';
 
 import type { AztecAsyncMap } from '../interfaces/map.js';
 import type { AztecAsyncKVStore } from '../interfaces/store.js';
 
+/** Serialized form of a per-tip checkpoint id stored in the KV store. */
+type StoredCheckpointId = { number: number; hash: string };
+
 /**
  * Persistent implementation of L2 tips store backed by a KV store.
  * Used by nodes that need to persist chain state across restarts.
  */
 export class L2TipsKVStore extends L2TipsStoreBase {
   private readonly l2TipsStore: AztecAsyncMap<L2BlockTag, BlockNumber>;
+  private readonly l2TipCheckpointsStore: AztecAsyncMap<L2BlockTag, StoredCheckpointId>;
   private readonly l2BlockHashesStore: AztecAsyncMap<BlockNumber, string>;
-  private readonly l2BlockNumberToCheckpointNumberStore: AztecAsyncMap<BlockNumber, CheckpointNumber>;
-  private readonly l2CheckpointStore: AztecAsyncMap<CheckpointNumber, Buffer>;
 
   constructor(
     private store: AztecAsyncKVStore,
     namespace: string,
+    initialBlockHash: BlockHash,
   ) {
-    super();
+    super(initialBlockHash);
     this.l2TipsStore = store.openMap([namespace, 'l2_tips'].join('_'));
+    this.l2TipCheckpointsStore = store.openMap([namespace, 'l2_tip_checkpoints'].join('_'));
     this.l2BlockHashesStore = store.openMap([namespace, 'l2_block_hashes'].join('_'));
-    this.l2BlockNumberToCheckpointNumberStore = store.openMap(
-      [namespace, 'l2_block_number_to_checkpoint_number'].join('_'),
-    );
-    this.l2CheckpointStore = store.openMap([namespace, 'l2_checkpoint_store'].join('_'));
   }
 
   protected getTip(tag: L2BlockTag): Promise<BlockNumber | undefined> {
@@ -36,6 +35,18 @@ export class L2TipsKVStore extends L2TipsStoreBase {
     return this.l2TipsStore.set(tag, blockNumber);
   }
 
+  protected async getTipCheckpoint(tag: L2BlockTag): Promise<CheckpointId | undefined> {
+    const stored = await this.l2TipCheckpointsStore.getAsync(tag);
+    if (stored === undefined) {
+      return undefined;
+    }
+    return { number: CheckpointNumber(stored.number), hash: stored.hash };
+  }
+
+  protected setTipCheckpoint(tag: L2BlockTag, checkpoint: CheckpointId): Promise<void> {
+    return this.l2TipCheckpointsStore.set(tag, { number: checkpoint.number, hash: checkpoint.hash });
+  }
+
   protected getStoredBlockHash(blockNumber: BlockNumber): Promise<string | undefined> {
     return this.l2BlockHashesStore.getAsync(blockNumber);
   }
@@ -50,38 +61,6 @@ export class L2TipsKVStore extends L2TipsStoreBase {
     }
   }
 
-  protected getCheckpointNumberForBlock(blockNumber: BlockNumber): Promise<CheckpointNumber | undefined> {
-    return this.l2BlockNumberToCheckpointNumberStore.getAsync(blockNumber);
-  }
-
-  protected setCheckpointNumberForBlock(blockNumber: BlockNumber, checkpointNumber: CheckpointNumber): Promise<void> {
-    return this.l2BlockNumberToCheckpointNumberStore.set(blockNumber, checkpointNumber);
-  }
-
-  protected async deleteBlockToCheckpointBefore(blockNumber: BlockNumber): Promise<void> {
-    for await (const key of this.l2BlockNumberToCheckpointNumberStore.keysAsync({ end: blockNumber })) {
-      await this.l2BlockNumberToCheckpointNumberStore.delete(key);
-    }
-  }
-
-  protected async getCheckpoint(checkpointNumber: CheckpointNumber): Promise<PublishedCheckpoint | undefined> {
-    const buffer = await this.l2CheckpointStore.getAsync(checkpointNumber);
-    if (!buffer) {
-      return undefined;
-    }
-    return PublishedCheckpoint.fromBuffer(buffer);
-  }
-
-  protected saveCheckpointData(checkpoint: PublishedCheckpoint): Promise<void> {
-    return this.l2CheckpointStore.set(checkpoint.checkpoint.number, checkpoint.toBuffer());
-  }
-
-  protected async deleteCheckpointsBefore(checkpointNumber: CheckpointNumber): Promise<void> {
-    for await (const key of this.l2CheckpointStore.keysAsync({ end: checkpointNumber })) {
-      await this.l2CheckpointStore.delete(key);
-    }
-  }
-
   protected runInTransaction<T>(fn: () => Promise<T>): Promise<T> {
     return this.store.transactionAsync(fn);
   }