@aztec/kv-store 0.0.1-commit.e3c1de76 → 0.0.1-commit.e57c76e

package/src/interfaces/multi_map_test_suite.ts

@@ -1,7 +1,5 @@
 import { toArray } from '@aztec/foundation/iterable';
 
-import { expect } from 'chai';
-
 import type { Key, Range } from './common.js';
 import type { AztecAsyncMultiMap, AztecMultiMap } from './multi_map.js';
 import type { AztecAsyncKVStore, AztecKVStore } from './store.js';
@@ -72,16 +70,16 @@ export function describeAztecMultiMap(
       await multiMap.set('foo', 'bar');
       await multiMap.set('baz', 'qux');
 
-      expect(await get('foo')).to.equal('bar');
-      expect(await get('baz')).to.equal('qux');
-      expect(await get('quux')).to.equal(undefined);
+      expect(await get('foo')).toBe('bar');
+      expect(await get('baz')).toBe('qux');
+      expect(await get('quux')).toBe(undefined);
     });
 
     it('should be able to set values if they do not exist', async () => {
-      expect(await multiMap.setIfNotExists('foo', 'bar')).to.equal(true);
-      expect(await multiMap.setIfNotExists('foo', 'baz')).to.equal(false);
+      expect(await multiMap.setIfNotExists('foo', 'bar')).toBe(true);
+      expect(await multiMap.setIfNotExists('foo', 'baz')).toBe(false);
 
-      expect(await get('foo')).to.equal('bar');
+      expect(await get('foo')).toBe('bar');
     });
 
     it('should be able to delete values', async () => {
@@ -90,29 +88,61 @@ export function describeAztecMultiMap(
 
       await multiMap.delete('foo');
 
-      expect(await get('foo')).to.equal(undefined);
-      expect(await get('baz')).to.equal('qux');
+      expect(await get('foo')).toBe(undefined);
+      expect(await get('baz')).toBe('qux');
     });
 
     it('should be able to get size of the map', async () => {
       await multiMap.set('foo', 'bar');
-      expect(await size()).to.equal(1);
+      expect(await size()).toBe(1);
       await multiMap.set('baz', 'qux');
-      expect(await size()).to.equal(2);
+      expect(await size()).toBe(2);
 
       await multiMap.delete('foo');
-      expect(await size()).to.equal(1);
+      expect(await size()).toBe(1);
+    });
+
+    it('returns 0 for empty multimap size', async () => {
+      expect(await size()).toBe(0);
+    });
+
+    it('calculates size correctly with multiple values per key', async () => {
+      expect(await size()).toBe(0);
+
+      // Add multiple values for same key
+      await multiMap.set('key1', 'value1');
+      expect(await size()).toBe(1);
+      await multiMap.set('key1', 'value2');
+      expect(await size()).toBe(2);
+      await multiMap.set('key1', 'value3');
+      expect(await size()).toBe(3);
+
+      // Add values for different key
+      await multiMap.set('key2', 'value4');
+      expect(await size()).toBe(4);
+
+      // Delete one value from key1
+      await multiMap.deleteValue('key1', 'value2');
+      expect(await size()).toBe(3);
+
+      // Delete entire key
+      await multiMap.delete('key1');
+      expect(await size()).toBe(1);
+
+      // Delete last key
+      await multiMap.delete('key2');
+      expect(await size()).toBe(0);
     });
 
     it('should be able to iterate over entries when there are no keys', async () => {
-      expect(await entries()).to.deep.equal([]);
+      expect(await entries()).toEqual([]);
     });
 
     it('should be able to iterate over entries', async () => {
       await multiMap.set('foo', 'bar');
       await multiMap.set('baz', 'qux');
 
-      expect(await entries()).to.deep.equal([
+      expect(await entries()).toEqual([
         ['baz', 'qux'],
         ['foo', 'bar'],
       ]);
@@ -122,28 +152,28 @@ export function describeAztecMultiMap(
       await multiMap.set('foo', 'bar');
       await multiMap.set('baz', 'quux');
 
-      expect(await values()).to.deep.equal(['quux', 'bar']);
+      expect(await values()).toEqual(['quux', 'bar']);
     });
 
     it('should be able to iterate over keys', async () => {
       await multiMap.set('foo', 'bar');
       await multiMap.set('baz', 'qux');
 
-      expect(await keys()).to.deep.equal(['baz', 'foo']);
+      expect(await keys()).toEqual(['baz', 'foo']);
     });
 
     it('should be able to get multiple values for a single key', async () => {
       await multiMap.set('foo', 'bar');
       await multiMap.set('foo', 'baz');
 
-      expect(await getValues('foo')).to.deep.equal(['bar', 'baz']);
+      expect(await getValues('foo')).toEqual(['bar', 'baz']);
     });
 
     it('should ignore multiple identical values', async () => {
       await multiMap.set('foo', 'bar');
       await multiMap.set('foo', 'bar');
 
-      expect(await getValues('foo')).to.deep.equal(['bar']);
+      expect(await getValues('foo')).toEqual(['bar']);
     });
 
     it('should be able to delete individual values for a single key', async () => {
@@ -153,22 +183,22 @@ export function describeAztecMultiMap(
 
       await multiMap.deleteValue('foo', '2');
 
-      expect(await getValues('foo')).to.deep.equal(['1', '3']);
+      expect(await getValues('foo')).toEqual(['1', '3']);
     });
 
     it('should be able to get size of the map with duplicate keys', async () => {
       await multiMap.set('foo', '1');
       await multiMap.set('foo', '2');
       await multiMap.set('foo', '3');
-      expect(await size()).to.equal(3);
+      expect(await size()).toBe(3);
 
       await multiMap.set('bar', '1');
       await multiMap.set('bar', '2');
       await multiMap.set('bar', '3');
-      expect(await size()).to.equal(6);
+      expect(await size()).toBe(6);
 
       await multiMap.deleteValue('foo', '2');
-      expect(await size()).to.equal(5);
+      expect(await size()).toBe(5);
     });
 
     it('should be able to delete the last and first values for a key', async () => {
@@ -178,11 +208,11 @@ export function describeAztecMultiMap(
 
       await multiMap.deleteValue('foo', '1');
 
-      expect(await getValues('foo')).to.deep.equal(['2', '3']);
+      expect(await getValues('foo')).toEqual(['2', '3']);
 
       await multiMap.deleteValue('foo', '3');
 
-      expect(await getValues('foo')).to.deep.equal(['2']);
+      expect(await getValues('foo')).toEqual(['2']);
     });
 
     it('should be able to fully clear a key', async () => {
@@ -194,7 +224,7 @@ export function describeAztecMultiMap(
       await multiMap.deleteValue('foo', '3');
       await multiMap.deleteValue('foo', '2');
 
-      expect(await getValues('foo')).to.deep.equal([]);
+      expect(await getValues('foo')).toEqual([]);
     });
 
     it('should be able to insert after deletion', async () => {
@@ -205,12 +235,12 @@ export function describeAztecMultiMap(
       await multiMap.deleteValue('foo', '2');
       await multiMap.set('foo', 'bar');
 
-      expect(await getValues('foo')).to.deep.equal(['1', '3', 'bar']);
+      expect(await getValues('foo')).toEqual(['1', '3', 'bar']);
 
       // Delete the just-added entry
       await multiMap.deleteValue('foo', 'bar');
 
-      expect(await getValues('foo')).to.deep.equal(['1', '3']);
+      expect(await getValues('foo')).toEqual(['1', '3']);
 
       // Reinsert the initially deleted key
       await multiMap.set('foo', '2');
@@ -218,7 +248,7 @@ export function describeAztecMultiMap(
       // LMDB and IndexedDB behave differently here, the former ordering by value and the latter by insertion. This is
       // fine because there is no expectation for values in a multimap to be ordered.
       const values = (await getValues('foo')).sort((a, b) => a.localeCompare(b));
-      expect(values).to.deep.equal(['1', '2', '3']);
+      expect(values).toEqual(['1', '2', '3']);
 
       // Fully clear the key
       await multiMap.deleteValue('foo', '1');
@@ -228,7 +258,7 @@ export function describeAztecMultiMap(
       // Insert some more
       await multiMap.set('foo', 'baz');
       await multiMap.set('foo', 'qux');
-      expect(await getValues('foo')).to.deep.equal(['baz', 'qux']);
+      expect(await getValues('foo')).toEqual(['baz', 'qux']);
     });
 
     it('supports range queries', async () => {
@@ -237,29 +267,29 @@ export function describeAztecMultiMap(
       await multiMap.set('c', 'c');
       await multiMap.set('d', 'd');
 
-      expect(await keys({ start: 'b', end: 'c' })).to.deep.equal(['b']);
-      expect(await keys({ start: 'b' })).to.deep.equal(['b', 'c', 'd']);
-      expect(await keys({ end: 'c' })).to.deep.equal(['a', 'b']);
-      expect(await keys({ start: 'b', end: 'c', reverse: true })).to.deep.equal(['c']);
-      expect(await keys({ start: 'b', limit: 1 })).to.deep.equal(['b']);
-      expect(await keys({ start: 'b', reverse: true })).to.deep.equal(['d', 'c']);
-      expect(await keys({ end: 'b', reverse: true })).to.deep.equal(['b', 'a']);
+      expect(await keys({ start: 'b', end: 'c' })).toEqual(['b']);
+      expect(await keys({ start: 'b' })).toEqual(['b', 'c', 'd']);
+      expect(await keys({ end: 'c' })).toEqual(['a', 'b']);
+      expect(await keys({ start: 'b', end: 'c', reverse: true })).toEqual(['c']);
+      expect(await keys({ start: 'b', limit: 1 })).toEqual(['b']);
+      expect(await keys({ start: 'b', reverse: true })).toEqual(['d', 'c']);
+      expect(await keys({ end: 'b', reverse: true })).toEqual(['b', 'a']);
     });
 
     it('returns 0 for missing key', async () => {
-      expect(await getValueCount('missing')).to.equal(0);
+      expect(await getValueCount('missing')).toBe(0);
     });
 
     it('counts a single value', async () => {
       await multiMap.set('foo', 'bar');
-      expect(await getValueCount('foo')).to.equal(1);
+      expect(await getValueCount('foo')).toBe(1);
     });
 
     it('counts multiple distinct values for same key', async () => {
       await multiMap.set('foo', 'bar');
       await multiMap.set('foo', 'baz');
       await multiMap.set('foo', 'qux');
-      expect(await getValueCount('foo')).to.equal(3);
+      expect(await getValueCount('foo')).toBe(3);
     });
 
     it('does not increase count for duplicate inserts', async () => {
@@ -267,42 +297,42 @@ export function describeAztecMultiMap(
       await multiMap.set('foo', 'bar');
       await multiMap.set('foo', 'baz');
       await multiMap.set('foo', 'baz');
-      expect(await getValueCount('foo')).to.equal(2);
-      expect(await getValues('foo')).to.have.members(['bar', 'baz']);
+      expect(await getValueCount('foo')).toBe(2);
+      expect((await getValues('foo')).sort()).toEqual(['bar', 'baz'].sort());
     });
 
     it('decrements when deleting a single value', async () => {
       await multiMap.set('foo', '1');
       await multiMap.set('foo', '2');
       await multiMap.set('foo', '3');
-      expect(await getValueCount('foo')).to.equal(3);
+      expect(await getValueCount('foo')).toBe(3);
       await multiMap.deleteValue('foo', '2');
-      expect(await getValueCount('foo')).to.equal(2);
-      expect(await getValues('foo')).to.have.members(['1', '3']);
+      expect(await getValueCount('foo')).toBe(2);
+      expect((await getValues('foo')).sort()).toEqual(['1', '3'].sort());
     });
 
     it('does not change count when deleting a non-existent value', async () => {
       await multiMap.set('foo', '1');
       await multiMap.set('foo', '3');
-      expect(await getValueCount('foo')).to.equal(2);
+      expect(await getValueCount('foo')).toBe(2);
       await multiMap.deleteValue('foo', '2');
-      expect(await getValueCount('foo')).to.equal(2);
+      expect(await getValueCount('foo')).toBe(2);
     });
 
     it('clears all values when deleting a key', async () => {
       await multiMap.set('foo', 'bar');
       await multiMap.set('foo', 'baz');
-      expect(await getValueCount('foo')).to.equal(2);
+      expect(await getValueCount('foo')).toBe(2);
       await multiMap.delete('foo');
-      expect(await getValueCount('foo')).to.equal(0);
-      expect(await getValues('foo')).to.deep.equal([]);
+      expect(await getValueCount('foo')).toBe(0);
+      expect(await getValues('foo')).toEqual([]);
     });
 
     it('count equals enumerated values length', async () => {
       await multiMap.set('foo', '1');
       await multiMap.set('foo', '2');
       const vals = await getValues('foo');
-      expect(await getValueCount('foo')).to.equal(vals.length);
+      expect(await getValueCount('foo')).toBe(vals.length);
     });
 
     it('sum of per-key counts equals total size', async () => {
@@ -316,27 +346,27 @@ export function describeAztecMultiMap(
       const uniqueKeys = Array.from(new Set(allKeys));
       const counts = await Promise.all(uniqueKeys.map(k => getValueCount(k)));
       const sum = counts.reduce((s, n) => s + n, 0);
-      expect(sum).to.equal(await size());
+      expect(sum).toBe(await size());
     });
 
     it('supports sparse slots: delete middle, reinsert new, count remains correct', async () => {
       await multiMap.set('foo', '1');
       await multiMap.set('foo', '2');
       await multiMap.set('foo', '3');
-      expect(await getValueCount('foo')).to.equal(3);
+      expect(await getValueCount('foo')).toBe(3);
       await multiMap.deleteValue('foo', '2');
-      expect(await getValueCount('foo')).to.equal(2);
+      expect(await getValueCount('foo')).toBe(2);
       await multiMap.set('foo', '4');
-      expect(await getValueCount('foo')).to.equal(3);
-      expect(await getValues('foo')).to.have.members(['1', '3', '4']);
+      expect(await getValueCount('foo')).toBe(3);
+      expect((await getValues('foo')).sort()).toEqual(['1', '3', '4'].sort());
     });
 
     it('multiple keys are independent', async () => {
       await multiMap.set('foo', '1');
       await multiMap.set('foo', '2');
       await multiMap.set('bar', '3');
-      expect(await getValueCount('foo')).to.equal(2);
-      expect(await getValueCount('bar')).to.equal(1);
+      expect(await getValueCount('foo')).toBe(2);
+      expect(await getValueCount('bar')).toBe(1);
     });
   });
 }

package/src/interfaces/set_test_suite.ts

@@ -1,7 +1,5 @@
 import { toArray } from '@aztec/foundation/iterable';
 
-import { expect } from 'chai';
-
 import type { Range } from './common.js';
 import type { AztecAsyncSet, AztecSet } from './set.js';
 import type { AztecAsyncKVStore, AztecKVStore } from './store.js';
@@ -41,9 +39,9 @@ export function describeAztecSet(
       await set.add('foo');
       await set.add('baz');
 
-      expect(await has('foo')).to.equal(true);
-      expect(await has('baz')).to.equal(true);
-      expect(await has('bar')).to.equal(false);
+      expect(await has('foo')).toBe(true);
+      expect(await has('baz')).toBe(true);
+      expect(await has('bar')).toBe(false);
     });
 
     it('should be able to delete values', async () => {
@@ -52,15 +50,15 @@ export function describeAztecSet(
 
       await set.delete('foo');
 
-      expect(await has('foo')).to.equal(false);
-      expect(await has('baz')).to.equal(true);
+      expect(await has('foo')).toBe(false);
+      expect(await has('baz')).toBe(true);
     });
 
     it('should be able to iterate over entries', async () => {
       await set.add('baz');
       await set.add('foo');
 
-      expect(await entries()).to.deep.equal(['baz', 'foo']);
+      expect(await entries()).toEqual(['baz', 'foo']);
     });
 
     it('supports range queries', async () => {
@@ -69,13 +67,13 @@ export function describeAztecSet(
       await set.add('c');
       await set.add('d');
 
-      expect(await entries({ start: 'b', end: 'c' })).to.deep.equal(['b']);
-      expect(await entries({ start: 'b' })).to.deep.equal(['b', 'c', 'd']);
-      expect(await entries({ end: 'c' })).to.deep.equal(['a', 'b']);
-      expect(await entries({ start: 'b', end: 'c', reverse: true })).to.deep.equal(['c']);
-      expect(await entries({ start: 'b', limit: 1 })).to.deep.equal(['b']);
-      expect(await entries({ start: 'b', reverse: true })).to.deep.equal(['d', 'c']);
-      expect(await entries({ end: 'b', reverse: true })).to.deep.equal(['b', 'a']);
+      expect(await entries({ start: 'b', end: 'c' })).toEqual(['b']);
+      expect(await entries({ start: 'b' })).toEqual(['b', 'c', 'd']);
+      expect(await entries({ end: 'c' })).toEqual(['a', 'b']);
+      expect(await entries({ start: 'b', end: 'c', reverse: true })).toEqual(['c']);
+      expect(await entries({ start: 'b', limit: 1 })).toEqual(['b']);
+      expect(await entries({ start: 'b', reverse: true })).toEqual(['d', 'c']);
+      expect(await entries({ end: 'b', reverse: true })).toEqual(['b', 'a']);
     });
   });
 }

package/src/interfaces/singleton_test_suite.ts

@@ -1,5 +1,3 @@
-import { expect } from 'chai';
-
 import type { AztecAsyncSingleton, AztecSingleton } from './singleton.js';
 import type { AztecAsyncKVStore, AztecKVStore } from './store.js';
 import { isSyncStore } from './utils.js';
@@ -29,18 +27,18 @@ export function describeAztecSingleton(
     }
 
     it('returns undefined if the value is not set', async () => {
-      expect(await get()).to.equal(undefined);
+      expect(await get()).toBe(undefined);
     });
 
     it('should be able to set and get values', async () => {
-      expect(await singleton.set('foo')).to.equal(true);
-      expect(await get()).to.equal('foo');
+      expect(await singleton.set('foo')).toBe(true);
+      expect(await get()).toBe('foo');
     });
 
     it('overwrites the value if it is set again', async () => {
-      expect(await singleton.set('foo')).to.equal(true);
-      expect(await singleton.set('bar')).to.equal(true);
-      expect(await get()).to.equal('bar');
+      expect(await singleton.set('foo')).toBe(true);
+      expect(await singleton.set('bar')).toBe(true);
+      expect(await get()).toBe('bar');
     });
   });
 }

package/src/lmdb/index.ts

@@ -1,8 +1,8 @@
 import { type Logger, createLogger } from '@aztec/foundation/log';
+import type { DataStoreConfig } from '@aztec/stdlib/kv-store';
 
 import { join } from 'path';
 
-import type { DataStoreConfig } from '../config.js';
 import { initStoreForRollupAndSchemaVersion } from '../utils.js';
 import { AztecLmdbStore } from './store.js';
 
@@ -26,8 +26,8 @@ export function createStore(
   );
 
   const store = AztecLmdbStore.open(dataDirectory, config.dataStoreMapSizeKb, false);
-  if (config.l1Contracts?.rollupAddress) {
-    return initStoreForRollupAndSchemaVersion(store, schemaVersion, config.l1Contracts.rollupAddress, log);
+  if (config.rollupAddress) {
+    return initStoreForRollupAndSchemaVersion(store, schemaVersion, config.rollupAddress, log);
   }
   return store;
 }

package/src/lmdb/store.ts

@@ -147,21 +147,25 @@ export class AztecLmdbStore implements AztecKVStore, AztecAsyncKVStore {
   }
 
   /**
-   * Clears all entries in the store & sub DBs.
+   * Clears all entries in the store & sub DBs atomically within a single transaction.
    */
   async clear() {
-    await this.#data.clearAsync();
-    await this.#multiMapData.clearAsync();
-    await this.#rootDb.clearAsync();
+    await this.#rootDb.transaction(async () => {
+      await this.#data.clearAsync();
+      await this.#multiMapData.clearAsync();
+      await this.#rootDb.clearAsync();
+    });
   }
 
   /**
-   * Drops the database & sub DBs.
+   * Drops the database & sub DBs atomically within a single transaction.
    */
   async drop() {
-    await this.#data.drop();
-    await this.#multiMapData.drop();
-    await this.#rootDb.drop();
+    await this.#rootDb.transaction(async () => {
+      await this.#data.drop();
+      await this.#multiMapData.drop();
+      await this.#rootDb.drop();
+    });
   }
 
   /**

package/src/lmdb-v2/factory.ts

@@ -1,24 +1,31 @@
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { type LoggerBindings, createLogger } from '@aztec/foundation/log';
-import { DatabaseVersionManager } from '@aztec/stdlib/database-version/manager';
+import { DatabaseVersionManager, type SchemaVersionMismatchPolicy } from '@aztec/stdlib/database-version/manager';
+import type { DataStoreConfig } from '@aztec/stdlib/kv-store';
 
-import { mkdir, mkdtemp, rm } from 'fs/promises';
+import { copyFile, mkdir, mkdtemp, rm } from 'fs/promises';
 import { tmpdir } from 'os';
 import { join } from 'path';
 
-import type { DataStoreConfig } from '../config.js';
 import { AztecLMDBStoreV2 } from './store.js';
 
 const MAX_READERS = 16;
 
+/** Optional versioning hooks for persistent LMDB stores. */
+export type CreateStoreOptions = {
+  onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
+  schemaVersionMismatchPolicy?: SchemaVersionMismatchPolicy;
+};
+
 export async function createStore(
   name: string,
   schemaVersion: number,
   config: DataStoreConfig,
   bindings?: LoggerBindings,
+  options: CreateStoreOptions = {},
 ): Promise<AztecLMDBStoreV2> {
   const log = createLogger('kv-store:lmdb-v2:' + name, bindings);
-  const { dataDirectory, l1Contracts } = config;
+  const { dataDirectory, rollupAddress: rollupFromConfig } = config;
 
   let store: AztecLMDBStoreV2;
   if (typeof dataDirectory !== 'undefined') {
@@ -26,7 +33,7 @@ export async function createStore(
     const subDir = join(dataDirectory, name);
     await mkdir(subDir, { recursive: true });
 
-    const rollupAddress = l1Contracts ? l1Contracts.rollupAddress : EthAddress.ZERO;
+    const rollupAddress = rollupFromConfig ?? EthAddress.ZERO;
 
     // Create a version manager
     const versionManager = new DatabaseVersionManager({
@@ -35,6 +42,8 @@ export async function createStore(
       dataDirectory: subDir,
       onOpen: dbDirectory =>
         AztecLMDBStoreV2.new(dbDirectory, config.dataStoreMapSizeKb, MAX_READERS, () => Promise.resolve(), bindings),
+      onUpgrade: options.onUpgrade,
+      schemaVersionMismatchPolicy: options.schemaVersionMismatchPolicy,
     });
 
     log.info(
@@ -48,9 +57,14 @@ export async function createStore(
   return store;
 }
 
+/**
+ * Open a persistent on-disk store rooted in OS tmpdir. Caller chooses whether to
+ * auto-remove the directory on close. Uses standard durable LMDB flags (fsync on
+ * every commit) — for full in-memory / NOSYNC semantics use `openEphemeralStore`.
+ */
 export async function openTmpStore(
   name: string,
-  ephemeral: boolean = true,
+  cleanupTmpDir: boolean = true,
   dbMapSizeKb = 10 * 1_024 * 1_024, // 10GB
   maxReaders = MAX_READERS,
   bindings?: LoggerBindings,
@@ -61,7 +75,7 @@ export async function openTmpStore(
 
   // pass a cleanup callback because process.on('beforeExit', cleanup) does not work under Jest
   const cleanup = async () => {
-    if (ephemeral) {
+    if (cleanupTmpDir) {
       try {
         await rm(dataDir, { recursive: true, force: true, maxRetries: 3 });
         log.debug(`Deleted temporary data store: ${dataDir}`);
@@ -73,9 +87,35 @@ export async function openTmpStore(
     }
   };
 
-  // For temporary stores, we don't need to worry about versioning
-  // as they are ephemeral and get cleaned up after use
-  return AztecLMDBStoreV2.new(dataDir, dbMapSizeKb, maxReaders, cleanup, bindings);
+  return AztecLMDBStoreV2.new(dataDir, dbMapSizeKb, maxReaders, cleanup, bindings, false);
+}
+
+/**
+ * Open a fully-ephemeral store: a fresh tmpdir backing file, LMDB opened with
+ * MDB_NOSYNC | MDB_NOMETASYNC (no fsync, kernel-only writeback), and the directory
+ * unconditionally removed on close. Intended for tests and worker-local scratch
+ * stores where durability is explicitly not desired.
+ */
+export async function openEphemeralStore(
+  name: string,
+  dbMapSizeKb = 10 * 1_024 * 1_024, // 10GB
+  maxReaders = MAX_READERS,
+  bindings?: LoggerBindings,
+): Promise<AztecLMDBStoreV2> {
+  const log = createLogger('kv-store:lmdb-v2:' + name, bindings);
+  const dataDir = await mkdtemp(join(tmpdir(), name + '-'));
+  log.debug(`Created ephemeral data store at: ${dataDir} with size: ${dbMapSizeKb} KB (LMDB v2)`);
+
+  const cleanup = async () => {
+    try {
+      await rm(dataDir, { recursive: true, force: true, maxRetries: 3 });
+      log.debug(`Deleted ephemeral data store: ${dataDir}`);
+    } catch (err) {
+      log.warn(`Failed to delete ephemeral data directory (LMDB v2) ${dataDir}: ${err}`);
+    }
+  };
+
+  return AztecLMDBStoreV2.new(dataDir, dbMapSizeKb, maxReaders, cleanup, bindings, true);
 }
 
 export async function openStoreAt(
@@ -89,6 +129,36 @@ export async function openStoreAt(
   return await AztecLMDBStoreV2.new(dataDir, dbMapSizeKb, maxReaders, undefined, bindings);
 }
 
+/**
+ * Open a fully-ephemeral store seeded from an existing `data.mdb` file. Creates a fresh tmpdir,
+ * copies `srcDataMdbPath` into it as `data.mdb`, opens with MDB_NOSYNC | MDB_NOMETASYNC, and
+ * removes the tmpdir on close. Intended for worker clones of a main-thread-built store — the
+ * source file is never written to.
+ */
+export async function cloneEphemeralStoreFrom(
+  srcDataMdbPath: string,
+  name: string,
+  dbMapSizeKb = 10 * 1_024 * 1_024, // 10GB
+  maxReaders = MAX_READERS,
+  bindings?: LoggerBindings,
+): Promise<AztecLMDBStoreV2> {
+  const log = createLogger('kv-store:lmdb-v2:' + name, bindings);
+  const dataDir = await mkdtemp(join(tmpdir(), name + '-'));
+  await copyFile(srcDataMdbPath, join(dataDir, 'data.mdb'));
+  log.debug(`Cloned ephemeral data store at: ${dataDir} from ${srcDataMdbPath} (LMDB v2)`);
+
+  const cleanup = async () => {
+    try {
+      await rm(dataDir, { recursive: true, force: true, maxRetries: 3 });
+      log.debug(`Deleted ephemeral data store: ${dataDir}`);
+    } catch (err) {
+      log.warn(`Failed to delete ephemeral data directory (LMDB v2) ${dataDir}: ${err}`);
+    }
+  };
+
+  return AztecLMDBStoreV2.new(dataDir, dbMapSizeKb, maxReaders, cleanup, bindings, true);
+}
+
 export async function openVersionedStoreAt(
   dataDirectory: string,
   schemaVersion: number,