@aztec/kv-store 0.0.1-commit.9ef841308 → 0.0.1-commit.a5db02d

package/dest/stores/l2_tips_store.js

@@ -1,31 +1,26 @@
+import { CheckpointNumber } from '@aztec/foundation/branded-types';
 import { L2TipsStoreBase } from '@aztec/stdlib/block';
-import { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 /**
  * 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 {
     store;
     l2TipsStore;
+    l2TipCheckpointsStore;
     l2BlockHashesStore;
-    l2BlockNumberToCheckpointNumberStore;
-    l2CheckpointStore;
-    constructor(store, namespace){
-        super(), this.store = store;
+    constructor(store, namespace, initialBlockHash){
+        super(initialBlockHash), this.store = store;
         this.l2TipsStore = store.openMap([
             namespace,
             'l2_tips'
         ].join('_'));
-        this.l2BlockHashesStore = store.openMap([
-            namespace,
-            'l2_block_hashes'
-        ].join('_'));
-        this.l2BlockNumberToCheckpointNumberStore = store.openMap([
+        this.l2TipCheckpointsStore = store.openMap([
             namespace,
-            'l2_block_number_to_checkpoint_number'
+            'l2_tip_checkpoints'
         ].join('_'));
-        this.l2CheckpointStore = store.openMap([
+        this.l2BlockHashesStore = store.openMap([
             namespace,
-            'l2_checkpoint_store'
+            'l2_block_hashes'
         ].join('_'));
     }
     getTip(tag) {
@@ -34,6 +29,22 @@ import { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
     setTip(tag, blockNumber) {
         return this.l2TipsStore.set(tag, blockNumber);
     }
+    async getTipCheckpoint(tag) {
+        const stored = await this.l2TipCheckpointsStore.getAsync(tag);
+        if (stored === undefined) {
+            return undefined;
+        }
+        return {
+            number: CheckpointNumber(stored.number),
+            hash: stored.hash
+        };
+    }
+    setTipCheckpoint(tag, checkpoint) {
+        return this.l2TipCheckpointsStore.set(tag, {
+            number: checkpoint.number,
+            hash: checkpoint.hash
+        });
+    }
     getStoredBlockHash(blockNumber) {
         return this.l2BlockHashesStore.getAsync(blockNumber);
     }
@@ -47,36 +58,6 @@ import { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
             await this.l2BlockHashesStore.delete(key);
         }
     }
-    getCheckpointNumberForBlock(blockNumber) {
-        return this.l2BlockNumberToCheckpointNumberStore.getAsync(blockNumber);
-    }
-    setCheckpointNumberForBlock(blockNumber, checkpointNumber) {
-        return this.l2BlockNumberToCheckpointNumberStore.set(blockNumber, checkpointNumber);
-    }
-    async deleteBlockToCheckpointBefore(blockNumber) {
-        for await (const key of this.l2BlockNumberToCheckpointNumberStore.keysAsync({
-            end: blockNumber
-        })){
-            await this.l2BlockNumberToCheckpointNumberStore.delete(key);
-        }
-    }
-    async getCheckpoint(checkpointNumber) {
-        const buffer = await this.l2CheckpointStore.getAsync(checkpointNumber);
-        if (!buffer) {
-            return undefined;
-        }
-        return PublishedCheckpoint.fromBuffer(buffer);
-    }
-    saveCheckpointData(checkpoint) {
-        return this.l2CheckpointStore.set(checkpoint.checkpoint.number, checkpoint.toBuffer());
-    }
-    async deleteCheckpointsBefore(checkpointNumber) {
-        for await (const key of this.l2CheckpointStore.keysAsync({
-            end: checkpointNumber
-        })){
-            await this.l2CheckpointStore.delete(key);
-        }
-    }
     runInTransaction(fn) {
         return this.store.transactionAsync(fn);
     }

package/package.json

@@ -1,22 +1,34 @@
 {
   "name": "@aztec/kv-store",
-  "version": "0.0.1-commit.9ef841308",
+  "version": "0.0.1-commit.a5db02d",
   "type": "module",
   "exports": {
     ".": "./dest/interfaces/index.js",
     "./interfaces": "./dest/interfaces/index.js",
     "./lmdb": "./dest/lmdb/index.js",
     "./lmdb-v2": "./dest/lmdb-v2/index.js",
-    "./indexeddb": "./dest/indexeddb/index.js",
+    "./deprecated/indexeddb": "./dest/deprecated/indexeddb/index.js",
+    "./sqlite-opfs": "./dest/sqlite-opfs/index.js",
     "./stores": "./dest/stores/index.js"
   },
+  "imports": {
+    "#msgpackr": {
+      "browser": "msgpackr/index-no-eval",
+      "default": "msgpackr"
+    },
+    "#ordered-binary": {
+      "browser": "./dest/sqlite-opfs/internal/ordered-binary-browser.js",
+      "default": "ordered-binary"
+    }
+  },
   "scripts": {
     "build": "yarn clean && ../scripts/tsc.sh",
     "build:dev": "../scripts/tsc.sh --watch",
     "clean": "rm -rf ./dest .tsbuildinfo",
-    "test:node": "NODE_NO_WARNINGS=1 mocha --config ./.mocharc.json",
-    "test:browser": "vitest run --config ./vitest.config.ts",
-    "test": "yarn test:node && yarn test:browser",
+    "test:node": "vitest run --project node",
+    "test:browser": "bash scripts/run-browser-tests.sh",
+    "bench:browser": "VITE_BENCH=1 vitest run --project browser src/bench",
+    "test": "vitest run",
     "test:jest": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
   },
   "inherits": [
@@ -24,11 +36,12 @@
     "./package.local.json"
   ],
   "dependencies": {
-    "@aztec/constants": "0.0.1-commit.9ef841308",
-    "@aztec/ethereum": "0.0.1-commit.9ef841308",
-    "@aztec/foundation": "0.0.1-commit.9ef841308",
-    "@aztec/native": "0.0.1-commit.9ef841308",
-    "@aztec/stdlib": "0.0.1-commit.9ef841308",
+    "@aztec/constants": "0.0.1-commit.a5db02d",
+    "@aztec/ethereum": "0.0.1-commit.a5db02d",
+    "@aztec/foundation": "0.0.1-commit.a5db02d",
+    "@aztec/native": "0.0.1-commit.a5db02d",
+    "@aztec/sqlite3mc-wasm": "0.0.1-commit.a5db02d",
+    "@aztec/stdlib": "0.0.1-commit.a5db02d",
     "idb": "^8.0.0",
     "lmdb": "^3.2.0",
     "msgpackr": "^1.11.2",
@@ -37,23 +50,13 @@
   },
   "devDependencies": {
     "@jest/globals": "^30.0.0",
-    "@types/chai": "^5.0.1",
-    "@types/chai-as-promised": "^8.0.1",
     "@types/jest": "^30.0.0",
-    "@types/mocha": "^10.0.10",
-    "@types/mocha-each": "^2.0.4",
     "@types/node": "^22.15.17",
-    "@types/sinon": "^17.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260113.1",
     "@vitest/browser-playwright": "^4.0.0",
     "buffer": "^6.0.3",
-    "chai": "^5.1.2",
-    "chai-as-promised": "^8.0.1",
     "jest": "^30.0.0",
-    "mocha": "^10.8.2",
-    "mocha-each": "^2.0.1",
     "playwright": "1.49.0",
-    "sinon": "^19.0.2",
     "ts-node": "^10.9.1",
     "typescript": "^5.3.3",
     "util": "^0.12.5",

package/src/bench/shared_map_bench.ts

@@ -0,0 +1,111 @@
+import type { Logger } from '@aztec/foundation/log';
+import { Timer } from '@aztec/foundation/timer';
+
+import type { Key } from '../interfaces/common.js';
+import type { AztecAsyncMap } from '../interfaces/map.js';
+import type { AztecAsyncKVStore } from '../interfaces/store.js';
+
+/** One benchmark measurement. */
+export type BenchResult = {
+  /** Benchmark name (includes the backend prefix for disambiguation). */
+  name: string;
+  value: number;
+  unit: 'ms' | 'us';
+};
+
+export type BenchReporter = (results: BenchResult[]) => void | Promise<void>;
+
+/**
+ * Runs the standard Map benchmark suite against any `AztecAsyncKVStore` backend,
+ * populates `results`, and calls `reporter` in `afterAll`.
+ *
+ * Kept free of Node-only deps (`fs`, `path`) so the same runner works under
+ * vitest-browser for IndexedDB and SQLite-OPFS.
+ */
+export function describeAztecMapBench(
+  backendPrefix: string,
+  getStore: () => Promise<AztecAsyncKVStore>,
+  logger: Logger,
+  reporter: BenchReporter,
+) {
+  describe(`${backendPrefix} Map benchmarks`, () => {
+    let store: AztecAsyncKVStore;
+    let map: AztecAsyncMap<Key, string>;
+
+    const results: BenchResult[] = [];
+
+    const generateKeyValuePairs = (count: number, offset = 0) => {
+      const keys = Array.from({ length: count }, (_, i) => `key-${i + offset}`);
+      const values = Array.from({ length: count }, (_, i) => `value-${i + offset}`);
+      return keys.map((key, i) => ({ key, value: values[i] }));
+    };
+
+    const record = (name: string, value: number, unit: BenchResult['unit']) => {
+      results.push({ name: `${backendPrefix}/Map/${name}`, value, unit });
+    };
+
+    beforeEach(async () => {
+      store = await getStore();
+      map = store.openMap<Key, string>('test');
+    });
+
+    afterEach(async () => {
+      await store.delete();
+    });
+
+    afterAll(async () => {
+      const pretty = results.map(r => `${r.name}: ${r.value.toFixed(2)} ${r.unit}`).join('\n');
+      logger.info(`\n${pretty}\n`);
+      await reporter(results);
+    });
+
+    it('adds individual values', async () => {
+      const pairs = generateKeyValuePairs(1000);
+      const timer = new Timer();
+      for (const pair of pairs) {
+        await map.set(pair.key, pair.value);
+      }
+      record('Individual insertion', timer.ms() / pairs.length, 'ms');
+    });
+
+    it('adds batched values', async () => {
+      const batches = Array.from({ length: 100 }, (_, i) => generateKeyValuePairs(1000, i * 1000));
+      const timer = new Timer();
+      for (const batch of batches) {
+        await map.setMany(batch);
+      }
+      record(`Batch insertion of ${batches[0].length} items`, timer.ms() / batches.length, 'ms');
+    });
+
+    it('reads individual values', async () => {
+      const pairs = generateKeyValuePairs(10000);
+      await map.setMany(pairs);
+      const timer = new Timer();
+      for (const pair of pairs) {
+        await map.getAsync(pair.key);
+      }
+      record('Individual read', (timer.ms() * 1000) / pairs.length, 'us');
+    });
+
+    it('reads via a cursor', async () => {
+      const pairs = generateKeyValuePairs(10000);
+      await map.setMany(pairs);
+      const timer = new Timer();
+      for await (const _ of map.entriesAsync()) {
+        // consume
+      }
+      record(`Iterator per item read of ${pairs.length} items`, (timer.ms() * 1000) / pairs.length, 'us');
+    });
+
+    it('reads the size of the map', async () => {
+      const numIterations = 1000;
+      const pairs = generateKeyValuePairs(10000);
+      await map.setMany(pairs);
+      const timer = new Timer();
+      for (let i = 0; i < numIterations; i++) {
+        await map.sizeAsync();
+      }
+      record(`Read size of ${pairs.length} items`, (timer.ms() * 1000) / numIterations, 'us');
+    });
+  });
+}

package/src/{indexeddb → deprecated/indexeddb}/array.ts

@@ -1,8 +1,8 @@
 import type { IDBPDatabase, IDBPObjectStore } from 'idb';
 import { hash } from 'ohash';
 
-import type { AztecAsyncArray } from '../interfaces/array.js';
-import type { Value } from '../interfaces/common.js';
+import type { AztecAsyncArray } from '../../interfaces/array.js';
+import type { Value } from '../../interfaces/common.js';
 import type { AztecIDBSchema } from './store.js';
 
 /**

package/src/deprecated/indexeddb/index.ts

@@ -0,0 +1,12 @@
+import { createLogger } from '@aztec/foundation/log';
+
+import { AztecIndexedDBStore } from './store.js';
+
+export { AztecIndexedDBStore } from './store.js';
+
+/**
+ * @deprecated The IndexedDB backend is being retired. Use `@aztec/kv-store/sqlite-opfs` instead.
+ */
+export function openTmpStore(ephemeral: boolean = false): Promise<AztecIndexedDBStore> {
+  return AztecIndexedDBStore.open(createLogger('kv-store:indexeddb'), undefined, ephemeral);
+}

package/src/{indexeddb → deprecated/indexeddb}/map.ts

@@ -1,8 +1,8 @@
 import type { IDBPDatabase, IDBPObjectStore } from 'idb';
 import { hash } from 'ohash';
 
-import type { Key, Range, Value } from '../interfaces/common.js';
-import type { AztecAsyncMap } from '../interfaces/map.js';
+import type { Key, Range, Value } from '../../interfaces/common.js';
+import type { AztecAsyncMap } from '../../interfaces/map.js';
 import type { AztecIDBSchema } from './store.js';
 
 /**

package/src/{indexeddb → deprecated/indexeddb}/multi_map.ts

@@ -1,7 +1,7 @@
 import { hash } from 'ohash';
 
-import type { Key, Value } from '../interfaces/common.js';
-import type { AztecAsyncMultiMap } from '../interfaces/multi_map.js';
+import type { Key, Value } from '../../interfaces/common.js';
+import type { AztecAsyncMultiMap } from '../../interfaces/multi_map.js';
 import { IndexedDBAztecMap } from './map.js';
 
 /**

package/src/{indexeddb → deprecated/indexeddb}/set.ts

@@ -1,7 +1,7 @@
 import type { IDBPDatabase, IDBPObjectStore } from 'idb';
 
-import type { Key, Range } from '../interfaces/common.js';
-import type { AztecAsyncSet } from '../interfaces/set.js';
+import type { Key, Range } from '../../interfaces/common.js';
+import type { AztecAsyncSet } from '../../interfaces/set.js';
 import { IndexedDBAztecMap } from './map.js';
 import type { AztecIDBSchema } from './store.js';
 

package/src/{indexeddb → deprecated/indexeddb}/singleton.ts

@@ -1,8 +1,8 @@
 import type { IDBPDatabase, IDBPObjectStore } from 'idb';
 import { hash } from 'ohash';
 
-import type { Value } from '../interfaces/common.js';
-import type { AztecAsyncSingleton } from '../interfaces/singleton.js';
+import type { Value } from '../../interfaces/common.js';
+import type { AztecAsyncSingleton } from '../../interfaces/singleton.js';
 import type { AztecIDBSchema } from './store.js';
 
 /**

package/src/{indexeddb → deprecated/indexeddb}/store.ts

@@ -3,14 +3,14 @@ import { SerialQueue } from '@aztec/foundation/queue';
 
 import { type DBSchema, type IDBPDatabase, deleteDB, openDB } from 'idb';
 
-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 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 { IndexedDBAztecArray } from './array.js';
 import { IndexedDBAztecMap } from './map.js';
 import { IndexedDBAztecMultiMap } from './multi_map.js';
@@ -41,8 +41,9 @@ export interface AztecIDBSchema extends DBSchema {
 
 /**
  * A key-value store backed by IndexedDB.
+ *
+ * @deprecated The IndexedDB backend is being retired. Use `@aztec/kv-store/sqlite-opfs` instead.
  */
-
 export class AztecIndexedDBStore implements AztecAsyncKVStore {
   #rootDB: IDBPDatabase<AztecIDBSchema>;
   #name: string;

package/src/interfaces/array_test_suite.ts

@@ -1,7 +1,5 @@
 import { toArray } from '@aztec/foundation/iterable';
 
-import { expect } from 'chai';
-
 import type { AztecArray, AztecAsyncArray } from './array.js';
 import type { AztecAsyncKVStore, AztecKVStore } from './store.js';
 import { isSyncStore } from './utils.js';
@@ -53,12 +51,12 @@ export function describeAztecArray(
       await arr.push(2);
       await arr.push(3);
 
-      expect(await length()).to.equal(3);
+      expect(await length()).toBe(3);
 
-      expect(await arr.pop()).to.equal(3);
-      expect(await arr.pop()).to.equal(2);
-      expect(await arr.pop()).to.equal(1);
-      expect(await arr.pop()).to.equal(undefined);
+      expect(await arr.pop()).toBe(3);
+      expect(await arr.pop()).toBe(2);
+      expect(await arr.pop()).toBe(1);
+      expect(await arr.pop()).toBe(undefined);
     });
 
     it('should be able to get values by index', async () => {
@@ -66,14 +64,14 @@ export function describeAztecArray(
       await arr.push(2);
       await arr.push(3);
 
-      expect(await at(0)).to.equal(1);
-      expect(await at(1)).to.equal(2);
-      expect(await at(2)).to.equal(3);
-      expect(await at(3)).to.equal(undefined);
-      expect(await at(-1)).to.equal(3);
-      expect(await at(-2)).to.equal(2);
-      expect(await at(-3)).to.equal(1);
-      expect(await at(-4)).to.equal(undefined);
+      expect(await at(0)).toBe(1);
+      expect(await at(1)).toBe(2);
+      expect(await at(2)).toBe(3);
+      expect(await at(3)).toBe(undefined);
+      expect(await at(-1)).toBe(3);
+      expect(await at(-2)).toBe(2);
+      expect(await at(-3)).toBe(1);
+      expect(await at(-4)).toBe(undefined);
     });
 
     it('should be able to set values by index', async () => {
@@ -81,27 +79,27 @@ export function describeAztecArray(
       await arr.push(2);
       await arr.push(3);
 
-      expect(await arr.setAt(0, 4)).to.equal(true);
-      expect(await arr.setAt(1, 5)).to.equal(true);
-      expect(await arr.setAt(2, 6)).to.equal(true);
+      expect(await arr.setAt(0, 4)).toBe(true);
+      expect(await arr.setAt(1, 5)).toBe(true);
+      expect(await arr.setAt(2, 6)).toBe(true);
 
-      expect(await arr.setAt(3, 7)).to.equal(false);
+      expect(await arr.setAt(3, 7)).toBe(false);
 
-      expect(await at(0)).to.equal(4);
-      expect(await at(1)).to.equal(5);
-      expect(await at(2)).to.equal(6);
-      expect(await at(3)).to.equal(undefined);
+      expect(await at(0)).toBe(4);
+      expect(await at(1)).toBe(5);
+      expect(await at(2)).toBe(6);
+      expect(await at(3)).toBe(undefined);
 
-      expect(await arr.setAt(-1, 8)).to.equal(true);
-      expect(await arr.setAt(-2, 9)).to.equal(true);
-      expect(await arr.setAt(-3, 10)).to.equal(true);
+      expect(await arr.setAt(-1, 8)).toBe(true);
+      expect(await arr.setAt(-2, 9)).toBe(true);
+      expect(await arr.setAt(-3, 10)).toBe(true);
 
-      expect(await arr.setAt(-4, 11)).to.equal(false);
+      expect(await arr.setAt(-4, 11)).toBe(false);
 
-      expect(await at(-1)).to.equal(8);
-      expect(await at(-2)).to.equal(9);
-      expect(await at(-3)).to.equal(10);
-      expect(await at(-4)).to.equal(undefined);
+      expect(await at(-1)).toBe(8);
+      expect(await at(-2)).toBe(9);
+      expect(await at(-3)).toBe(10);
+      expect(await at(-4)).toBe(undefined);
     });
 
     it('should be able to iterate over values', async () => {
@@ -109,8 +107,8 @@ export function describeAztecArray(
       await arr.push(2);
       await arr.push(3);
 
-      expect(await values()).to.deep.equal([1, 2, 3]);
-      expect(await entries()).to.deep.equal([
+      expect(await values()).toEqual([1, 2, 3]);
+      expect(await entries()).toEqual([
         [0, 1],
         [1, 2],
         [2, 3],
@@ -123,8 +121,8 @@ export function describeAztecArray(
       await arr.push(3);
 
       const arr2 = store.openArray<number>('test');
-      expect(await length(arr2)).to.equal(3);
-      expect(await values(arr2)).to.deep.equal(await values());
+      expect(await length(arr2)).toBe(3);
+      expect(await values(arr2)).toEqual(await values());
     });
   });
 }

package/src/interfaces/index.ts

@@ -6,4 +6,4 @@ export * from './store.js';
 export * from './set.js';
 export * from './multi_map.js';
 export { mapRange } from './common.js';
-export type { CustomRange, Range, StoreSize } from './common.js';
+export type { CustomRange, Key, Range, StoreSize } from './common.js';