@aztec/kv-store 0.0.0-test.0 → 0.0.1-commit.0208eb9

package/src/lmdb-v2/store.ts

@@ -1,19 +1,20 @@
-import { type Logger, createLogger } from '@aztec/foundation/log';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec/foundation/log';
 import { Semaphore, SerialQueue } from '@aztec/foundation/queue';
 import { MsgpackChannel, NativeLMDBStore } from '@aztec/native';
 
 import { AsyncLocalStorage } from 'async_hooks';
-import { rm } from 'fs/promises';
+import { mkdir, rm } from 'fs/promises';
 
 import type { AztecAsyncArray } from '../interfaces/array.js';
-import type { Key, StoreSize } from '../interfaces/common.js';
+import type { Key, StoreSize, Value } from '../interfaces/common.js';
 import type { AztecAsyncCounter } from '../interfaces/counter.js';
-import type { AztecAsyncMap, AztecAsyncMultiMap } from '../interfaces/map.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 { LMDBArray } from './array.js';
-import { LMDBMap, LMDBMultiMap } from './map.js';
+import { LMDBMap } from './map.js';
 import {
   Database,
   type LMDBMessageChannel,
@@ -21,10 +22,14 @@ import {
   type LMDBRequestBody,
   type LMDBResponseBody,
 } from './message.js';
+import { LMDBMultiMap } from './multi_map.js';
 import { ReadTransaction } from './read_transaction.js';
+import { LMDBSet } from './set.js';
 import { LMDBSingleValue } from './singleton.js';
 import { WriteTransaction } from './write_transaction.js';
 
+export { execInReadTx, execInWriteTx } from './tx-helpers.js';
+
 export class AztecLMDBStoreV2 implements AztecAsyncKVStore, LMDBMessageChannel {
   private open = false;
   private channel: MsgpackChannel<LMDBMessageType, LMDBRequestBody, LMDBResponseBody>;
@@ -70,13 +75,19 @@ export class AztecLMDBStoreV2 implements AztecAsyncKVStore, LMDBMessageChannel {
     dbMapSizeKb: number = 10 * 1024 * 1024,
     maxReaders: number = 16,
     cleanup?: () => Promise<void>,
-    log = createLogger('kv-store:lmdb-v2'),
+    bindings?: LoggerBindings,
   ) {
+    const log = createLogger('kv-store:lmdb-v2', bindings);
     const db = new AztecLMDBStoreV2(dataDir, dbMapSizeKb, maxReaders, log, cleanup);
     await db.start();
     return db;
   }
 
+  public async backupTo(dstPath: string, compact = true) {
+    await mkdir(dstPath, { recursive: true });
+    await this.channel.sendMessage(LMDBMessageType.COPY_STORE, { dstPath, compact });
+  }
+
   public getReadTx(): ReadTransaction {
     if (!this.open) {
       throw new Error('Store is closed');
@@ -92,24 +103,24 @@ export class AztecLMDBStoreV2 implements AztecAsyncKVStore, LMDBMessageChannel {
     return currentWrite;
   }
 
-  openMap<K extends Key, V>(name: string): AztecAsyncMap<K, V> {
+  openMap<K extends Key, V extends Value>(name: string): AztecAsyncMap<K, V> {
     return new LMDBMap(this, name);
   }
 
-  openMultiMap<K extends Key, V>(name: string): AztecAsyncMultiMap<K, V> {
+  openMultiMap<K extends Key, V extends Value>(name: string): AztecAsyncMultiMap<K, V> {
     return new LMDBMultiMap(this, name);
   }
 
-  openSingleton<T>(name: string): AztecAsyncSingleton<T> {
+  openSingleton<T extends Value>(name: string): AztecAsyncSingleton<T> {
     return new LMDBSingleValue(this, name);
   }
 
-  openArray<T>(name: string): AztecAsyncArray<T> {
+  openArray<T extends Value>(name: string): AztecAsyncArray<T> {
     return new LMDBArray(this, name);
   }
 
-  openSet<K extends Key>(_name: string): AztecAsyncSet<K> {
-    throw new Error('Not implemented');
+  openSet<K extends Key>(name: string): AztecAsyncSet<K> {
+    return new LMDBSet(this, name);
   }
 
   openCounter<K extends Key>(_name: string): AztecAsyncCounter<K> {
@@ -150,10 +161,6 @@ export class AztecLMDBStoreV2 implements AztecAsyncKVStore, LMDBMessageChannel {
     return Promise.resolve();
   }
 
-  fork(): Promise<AztecAsyncKVStore> {
-    throw new Error('Not implemented');
-  }
-
   async delete(): Promise<void> {
     await this.close();
     await rm(this.dataDir, { recursive: true, force: true, maxRetries: 3 });
@@ -204,34 +211,9 @@ export class AztecLMDBStoreV2 implements AztecAsyncKVStore, LMDBMessageChannel {
     const resp = await this.sendMessage(LMDBMessageType.STATS, undefined);
     return {
       mappingSize: Number(resp.dbMapSizeBytes),
+      physicalFileSize: Number(resp.dbPhysicalFileSizeBytes),
       actualSize: resp.stats.reduce((s, db) => Number(db.totalUsedSize) + s, 0),
       numItems: resp.stats.reduce((s, db) => Number(db.numDataItems) + s, 0),
     };
   }
 }
-
-export function execInWriteTx<T>(store: AztecLMDBStoreV2, fn: (tx: WriteTransaction) => Promise<T>): Promise<T> {
-  const currentWrite = store.getCurrentWriteTx();
-  if (currentWrite) {
-    return fn(currentWrite);
-  } else {
-    return store.transactionAsync(fn);
-  }
-}
-
-export async function execInReadTx<T>(
-  store: AztecLMDBStoreV2,
-  fn: (tx: ReadTransaction) => T | Promise<T>,
-): Promise<T> {
-  const currentWrite = store.getCurrentWriteTx();
-  if (currentWrite) {
-    return await fn(currentWrite);
-  } else {
-    const tx = store.getReadTx();
-    try {
-      return await fn(tx);
-    } finally {
-      tx.close();
-    }
-  }
-}

package/src/lmdb-v2/tx-helpers.ts

@@ -0,0 +1,29 @@
+import type { ReadTransaction } from './read_transaction.js';
+import type { AztecLMDBStoreV2 } from './store.js';
+import type { WriteTransaction } from './write_transaction.js';
+
+export function execInWriteTx<T>(store: AztecLMDBStoreV2, fn: (tx: WriteTransaction) => Promise<T>): Promise<T> {
+  const currentWrite = store.getCurrentWriteTx();
+  if (currentWrite) {
+    return fn(currentWrite);
+  } else {
+    return store.transactionAsync(fn);
+  }
+}
+
+export async function execInReadTx<T>(
+  store: AztecLMDBStoreV2,
+  fn: (tx: ReadTransaction) => T | Promise<T>,
+): Promise<T> {
+  const currentWrite = store.getCurrentWriteTx();
+  if (currentWrite) {
+    return await fn(currentWrite);
+  } else {
+    const tx = store.getReadTx();
+    try {
+      return await fn(tx);
+    } finally {
+      tx.close();
+    }
+  }
+}

package/src/lmdb-v2/utils.ts

@@ -2,124 +2,6 @@ import { MAXIMUM_KEY, fromBufferKey, toBufferKey } from 'ordered-binary';
 
 import type { Key } from '../interfaces/common.js';
 
-type Cmp<T> = (a: T, b: T) => -1 | 0 | 1;
-
-export function dedupeSortedArray<T>(arr: T[], cmp: Cmp<T>): void {
-  for (let i = 0; i < arr.length; i++) {
-    let j = i + 1;
-    for (; j < arr.length; j++) {
-      const res = cmp(arr[i], arr[j]);
-      if (res === 0) {
-        continue;
-      } else if (res < 0) {
-        break;
-      } else {
-        throw new Error('Array not sorted');
-      }
-    }
-
-    if (j - i > 1) {
-      arr.splice(i + 1, j - i - 1);
-    }
-  }
-}
-
-export function insertIntoSortedArray<T>(arr: T[], item: T, cmp: (a: T, b: T) => number): void {
-  let left = 0;
-  let right = arr.length;
-
-  while (left < right) {
-    const mid = (left + right) >> 1;
-    const comparison = cmp(arr[mid], item);
-
-    if (comparison < 0) {
-      left = mid + 1;
-    } else {
-      right = mid;
-    }
-  }
-
-  arr.splice(left, 0, item);
-}
-
-export function findIndexInSortedArray<T, N>(values: T[], needle: N, cmp: (a: T, b: N) => number): number {
-  let start = 0;
-  let end = values.length - 1;
-
-  while (start <= end) {
-    const mid = start + (((end - start) / 2) | 0);
-    const res = cmp(values[mid], needle);
-    if (res === 0) {
-      return mid;
-    } else if (res > 0) {
-      end = mid - 1;
-    } else {
-      start = mid + 1;
-    }
-  }
-
-  return -1;
-}
-
-export function findInSortedArray<T, N>(values: T[], needle: N, cmp: (a: T, b: N) => number): T | undefined {
-  const idx = findIndexInSortedArray(values, needle, cmp);
-  return idx > -1 ? values[idx] : undefined;
-}
-
-export function removeAnyOf<T, N>(arr: T[], vals: N[], cmp: (a: T, b: N) => -1 | 0 | 1): void {
-  let writeIdx = 0;
-  let readIdx = 0;
-  let valIdx = 0;
-
-  while (readIdx < arr.length && valIdx < vals.length) {
-    const comparison = cmp(arr[readIdx], vals[valIdx]);
-
-    if (comparison < 0) {
-      arr[writeIdx++] = arr[readIdx++];
-    } else if (comparison > 0) {
-      valIdx++;
-    } else {
-      readIdx++;
-    }
-  }
-
-  while (readIdx < arr.length) {
-    arr[writeIdx++] = arr[readIdx++];
-  }
-
-  arr.length = writeIdx;
-}
-
-export function removeFromSortedArray<T, N>(arr: T[], val: N, cmp: (a: T, b: N) => -1 | 0 | 1) {
-  const idx = findIndexInSortedArray(arr, val, cmp);
-  if (idx > -1) {
-    arr.splice(idx, 1);
-  }
-}
-
-export function merge<T>(arr: T[], toInsert: T[], cmp: (a: T, b: T) => -1 | 0 | 1): void {
-  const result = new Array<T>(arr.length + toInsert.length);
-  let i = 0,
-    j = 0,
-    k = 0;
-
-  while (i < arr.length && j < toInsert.length) {
-    result[k++] = cmp(arr[i], toInsert[j]) <= 0 ? arr[i++] : toInsert[j++];
-  }
-
-  while (i < arr.length) {
-    result[k++] = arr[i++];
-  }
-  while (j < toInsert.length) {
-    result[k++] = toInsert[j++];
-  }
-
-  for (i = 0; i < result.length; i++) {
-    arr[i] = result[i];
-  }
-  arr.length = result.length;
-}
-
 export function keyCmp(a: [Uint8Array, Uint8Array[] | null], b: [Uint8Array, Uint8Array[] | null]): -1 | 0 | 1 {
   return Buffer.compare(a[0], b[0]);
 }

package/src/lmdb-v2/write_transaction.ts

@@ -1,16 +1,16 @@
-import { type Batch, Database, LMDBMessageType } from './message.js';
-import { ReadTransaction } from './read_transaction.js';
 import {
   dedupeSortedArray,
   findInSortedArray,
   findIndexInSortedArray,
   insertIntoSortedArray,
-  keyCmp,
   merge,
   removeAnyOf,
   removeFromSortedArray,
-  singleKeyCmp,
-} from './utils.js';
+} from '@aztec/foundation/array';
+
+import { type Batch, Database, LMDBMessageType } from './message.js';
+import { ReadTransaction } from './read_transaction.js';
+import { keyCmp, singleKeyCmp } from './utils.js';
 
 export class WriteTransaction extends ReadTransaction {
   // exposed for tests
@@ -44,7 +44,7 @@ export class WriteTransaction extends ReadTransaction {
   remove(key: Uint8Array): Promise<void> {
     const removeEntryIndex = findIndexInSortedArray(this.dataBatch.removeEntries, key, singleKeyCmp);
     if (removeEntryIndex === -1) {
-      this.dataBatch.removeEntries.push([key, null]);
+      insertIntoSortedArray(this.dataBatch.removeEntries, [key, null], keyCmp);
     }
 
     const addEntryIndex = findIndexInSortedArray(this.dataBatch.addEntries, key, singleKeyCmp);
@@ -163,7 +163,7 @@ export class WriteTransaction extends ReadTransaction {
 
   public override async *iterate(
     startKey: Uint8Array,
-    endKey?: Uint8Array | undefined,
+    endKey?: Uint8Array,
     reverse?: boolean,
     limit?: number,
   ): AsyncIterable<[Uint8Array, Uint8Array]> {
@@ -181,7 +181,7 @@ export class WriteTransaction extends ReadTransaction {
 
   public override async *iterateIndex(
     startKey: Uint8Array,
-    endKey?: Uint8Array | undefined,
+    endKey?: Uint8Array,
     reverse?: boolean,
     limit?: number,
   ): AsyncIterable<[Uint8Array, Uint8Array[]]> {
@@ -218,8 +218,9 @@ export class WriteTransaction extends ReadTransaction {
   ): AsyncIterable<[Uint8Array, T]> {
     this.assertIsOpen();
 
-    // make a copy of this in case we're running in reverse
+    // Snapshot both add and remove entries at the start of iteration to ensure consistency
     const uncommittedEntries = [...batch.addEntries];
+    const removeEntries = [...batch.removeEntries];
     // used to check we're in the right order when comparing between a key and uncommittedEntries
     let cmpDirection = -1;
     if (reverse) {
@@ -262,7 +263,7 @@ export class WriteTransaction extends ReadTransaction {
         break;
       }
 
-      const toRemove = findInSortedArray(batch.removeEntries, key, singleKeyCmp);
+      const toRemove = findInSortedArray(removeEntries, key, singleKeyCmp);
 
       // at this point we've either exhausted all uncommitted entries,
       // we reached a key strictly greater/smaller than `key`

package/src/stores/index.ts

@@ -1 +1,3 @@
 export * from './l2_tips_store.js';
+
+export { L2TipsMemoryStore, type L2TipsStore } from '@aztec/stdlib/block';

package/src/stores/l2_tips_store.ts

@@ -1,70 +1,88 @@
-import type {
-  L2BlockId,
-  L2BlockStreamEvent,
-  L2BlockStreamEventHandler,
-  L2BlockStreamLocalDataProvider,
-  L2BlockTag,
-  L2Tips,
-} from '@aztec/stdlib/block';
+import { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import { type L2BlockTag, L2TipsStoreBase } from '@aztec/stdlib/block';
+import { PublishedCheckpoint } from '@aztec/stdlib/checkpoint';
 
 import type { AztecAsyncMap } from '../interfaces/map.js';
 import type { AztecAsyncKVStore } from '../interfaces/store.js';
 
-/** Stores currently synced L2 tips and unfinalized block hashes. */
-export class L2TipsStore implements L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider {
-  private readonly l2TipsStore: AztecAsyncMap<L2BlockTag, number>;
-  private readonly l2BlockHashesStore: AztecAsyncMap<number, 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 l2BlockHashesStore: AztecAsyncMap<BlockNumber, string>;
+  private readonly l2BlockNumberToCheckpointNumberStore: AztecAsyncMap<BlockNumber, CheckpointNumber>;
+  private readonly l2CheckpointStore: AztecAsyncMap<CheckpointNumber, Buffer>;
 
-  constructor(store: AztecAsyncKVStore, namespace: string) {
+  constructor(
+    private store: AztecAsyncKVStore,
+    namespace: string,
+  ) {
+    super();
     this.l2TipsStore = store.openMap([namespace, 'l2_tips'].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('_'));
   }
 
-  public getL2BlockHash(number: number): Promise<string | undefined> {
-    return this.l2BlockHashesStore.getAsync(number);
+  protected getTip(tag: L2BlockTag): Promise<BlockNumber | undefined> {
+    return this.l2TipsStore.getAsync(tag);
   }
 
-  public async getL2Tips(): Promise<L2Tips> {
-    return {
-      latest: await this.getL2Tip('latest'),
-      finalized: await this.getL2Tip('finalized'),
-      proven: await this.getL2Tip('proven'),
-    };
+  protected setTip(tag: L2BlockTag, blockNumber: BlockNumber): Promise<void> {
+    return this.l2TipsStore.set(tag, blockNumber);
   }
 
-  private async getL2Tip(tag: L2BlockTag): Promise<L2BlockId> {
-    const blockNumber = await this.l2TipsStore.getAsync(tag);
-    if (blockNumber === undefined || blockNumber === 0) {
-      return { number: 0, hash: undefined };
+  protected getStoredBlockHash(blockNumber: BlockNumber): Promise<string | undefined> {
+    return this.l2BlockHashesStore.getAsync(blockNumber);
+  }
+
+  protected setBlockHash(blockNumber: BlockNumber, hash: string): Promise<void> {
+    return this.l2BlockHashesStore.set(blockNumber, hash);
+  }
+
+  protected async deleteBlockHashesBefore(blockNumber: BlockNumber): Promise<void> {
+    for await (const key of this.l2BlockHashesStore.keysAsync({ end: blockNumber })) {
+      await this.l2BlockHashesStore.delete(key);
+    }
+  }
+
+  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);
     }
-    const blockHash = await this.l2BlockHashesStore.getAsync(blockNumber);
-    if (!blockHash) {
-      throw new Error(`Block hash not found for block number ${blockNumber}`);
+  }
+
+  protected async getCheckpoint(checkpointNumber: CheckpointNumber): Promise<PublishedCheckpoint | undefined> {
+    const buffer = await this.l2CheckpointStore.getAsync(checkpointNumber);
+    if (!buffer) {
+      return undefined;
     }
+    return PublishedCheckpoint.fromBuffer(buffer);
+  }
 
-    return { number: blockNumber, hash: blockHash };
+  protected saveCheckpointData(checkpoint: PublishedCheckpoint): Promise<void> {
+    return this.l2CheckpointStore.set(checkpoint.checkpoint.number, checkpoint.toBuffer());
   }
 
-  public async handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void> {
-    switch (event.type) {
-      case 'blocks-added':
-        for (const block of event.blocks) {
-          await this.l2BlockHashesStore.set(block.number, (await block.header.hash()).toString());
-        }
-        await this.l2TipsStore.set('latest', event.blocks.at(-1)!.number);
-        break;
-      case 'chain-pruned':
-        await this.l2TipsStore.set('latest', event.blockNumber);
-        break;
-      case 'chain-proven':
-        await this.l2TipsStore.set('proven', event.blockNumber);
-        break;
-      case 'chain-finalized':
-        await this.l2TipsStore.set('finalized', event.blockNumber);
-        for await (const key of this.l2BlockHashesStore.keysAsync({ end: event.blockNumber })) {
-          await this.l2BlockHashesStore.delete(key);
-        }
-        break;
+  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);
+  }
 }

package/src/utils.ts

@@ -1,40 +1,98 @@
-import type { EthAddress } from '@aztec/foundation/eth-address';
+import { EthAddress } from '@aztec/foundation/eth-address';
 import type { Logger } from '@aztec/foundation/log';
+import { DatabaseVersion } from '@aztec/stdlib/database-version/version';
 
 import type { AztecAsyncSingleton, AztecSingleton } from './interfaces/singleton.js';
 import type { AztecAsyncKVStore, AztecKVStore } from './interfaces/store.js';
 import { isSyncStore } from './interfaces/utils.js';
 
 /**
- * Clears the store if the rollup address does not match the one stored in the database.
- * This is to prevent data from being accidentally shared between different rollup instances.
+ * Clears the store if the schema version or rollup address does not match the one stored in the database.
+ * Also clears if migrating from an older store format that didn't track schema version.
+ * This is to prevent data from being accidentally mixed up between different rollup instances or schema versions.
  * @param store - The store to check
+ * @param targetSchemaVersion - The current schema version
  * @param rollupAddress - The ETH address of the rollup contract
- * @returns A promise that resolves when the store is cleared, or rejects if the rollup address does not match
+ * @param log - Optional logger
+ * @returns The store (cleared if necessary)
  */
-export async function initStoreForRollup<T extends AztecKVStore | AztecAsyncKVStore>(
+export async function initStoreForRollupAndSchemaVersion<T extends AztecKVStore | AztecAsyncKVStore>(
   store: T,
-  rollupAddress: EthAddress,
+  schemaVersion: number | undefined,
+  rollupAddress: EthAddress | undefined,
   log?: Logger,
 ): Promise<T> {
-  if (!rollupAddress) {
-    throw new Error('Rollup address is required');
-  }
-  const rollupAddressValue = store.openSingleton<ReturnType<EthAddress['toString']>>('rollupAddress');
-  const rollupAddressString = rollupAddress.toString();
-  const storedRollupAddressString = isSyncStore(store)
-    ? (rollupAddressValue as AztecSingleton<ReturnType<EthAddress['toString']>>).get()
-    : await (rollupAddressValue as AztecAsyncSingleton<ReturnType<EthAddress['toString']>>).getAsync();
-
-  if (typeof storedRollupAddressString !== 'undefined' && storedRollupAddressString !== rollupAddressString) {
-    log?.warn(`Rollup address mismatch. Clearing entire database...`, {
-      expected: rollupAddressString,
-      found: storedRollupAddressString,
-    });
+  const targetSchemaVersion = schemaVersion ?? 0;
+  const targetRollupAddress = rollupAddress ?? EthAddress.ZERO;
+  const targetDatabaseVersion = new DatabaseVersion(targetSchemaVersion, targetRollupAddress);
+
+  // DB version: database schema version + rollup address combined)
+  const dbVersion = store.openSingleton<string>('dbVersion');
+
+  const storedDatabaseVersion = isSyncStore(store)
+    ? (dbVersion as AztecSingleton<string>).get()
+    : await (dbVersion as AztecAsyncSingleton<string>).getAsync();
+
+  // Check if this is an old format store (has rollupAddress singleton but no dbVersion)
+  const oldRollupSingleton = store.openSingleton<string>('rollupAddress');
+  const hasOldFormat = isSyncStore(store)
+    ? !storedDatabaseVersion && !!(oldRollupSingleton as AztecSingleton<string>).get()
+    : !storedDatabaseVersion && !!(await (oldRollupSingleton as AztecAsyncSingleton<string>).getAsync());
 
+  if (
+    hasOldFormat ||
+    doesStoreNeedToBeCleared(
+      targetDatabaseVersion,
+      storedDatabaseVersion,
+      targetSchemaVersion,
+      targetRollupAddress,
+      log,
+    )
+  ) {
+    if (hasOldFormat) {
+      log?.warn('Detected old store format without dbVersion, clearing database');
+    }
     await store.clear();
   }
 
-  await rollupAddressValue.set(rollupAddressString);
+  await dbVersion.set(targetDatabaseVersion.toBuffer().toString('utf-8'));
+
   return store;
 }
+
+function doesStoreNeedToBeCleared(
+  targetDatabaseVersion: DatabaseVersion,
+  storedDatabaseVersion: string | undefined,
+  targetSchemaVersion: number,
+  targetRollupAddress: EthAddress,
+  log?: Logger,
+) {
+  if (storedDatabaseVersion) {
+    try {
+      const storedVersion = DatabaseVersion.fromBuffer(Buffer.from(storedDatabaseVersion, 'utf-8'));
+      const cmp = storedVersion.cmp(targetDatabaseVersion);
+
+      if (cmp === undefined) {
+        log?.warn('Rollup address changed, clearing database', {
+          stored: storedVersion.rollupAddress.toString(),
+          current: targetRollupAddress.toString(),
+        });
+        return true;
+      }
+
+      if (cmp !== 0) {
+        log?.warn('Schema version changed, clearing database', {
+          stored: storedVersion.schemaVersion,
+          current: targetSchemaVersion,
+        });
+
+        return true;
+      }
+    } catch (err) {
+      log?.warn('Failed to parse stored version, clearing database', { err });
+      return true;
+    }
+  }
+
+  return false;
+}

package/dest/interfaces/store_test_suite.d.ts

@@ -1,3 +0,0 @@
-import type { AztecAsyncKVStore, AztecKVStore } from './store.js';
-export declare function describeAztecStore(testName: string, getPersistentStore: () => Promise<AztecKVStore | AztecAsyncKVStore>, getPersistentNoPathStore: () => Promise<AztecKVStore | AztecAsyncKVStore>, getEphemeralStore: () => Promise<AztecKVStore | AztecAsyncKVStore>): void;
-//# sourceMappingURL=store_test_suite.d.ts.map

package/dest/interfaces/store_test_suite.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"store_test_suite.d.ts","sourceRoot":"","sources":["../../src/interfaces/store_test_suite.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAGlE,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,kBAAkB,EAAE,MAAM,OAAO,CAAC,YAAY,GAAG,iBAAiB,CAAC,EACnE,wBAAwB,EAAE,MAAM,OAAO,CAAC,YAAY,GAAG,iBAAiB,CAAC,EACzE,iBAAiB,EAAE,MAAM,OAAO,CAAC,YAAY,GAAG,iBAAiB,CAAC,QA6CnE"}

package/dest/interfaces/store_test_suite.js

@@ -1,37 +0,0 @@
-import { expect } from 'chai';
-import { isSyncStore } from './utils.js';
-export function describeAztecStore(testName, getPersistentStore, getPersistentNoPathStore, getEphemeralStore) {
-    describe(testName, ()=>{
-        async function get(store, singleton) {
-            return isSyncStore(store) ? singleton.get() : await singleton.getAsync();
-        }
-        const itForks = async (store)=>{
-            const singleton = store.openSingleton('singleton');
-            await singleton.set('foo');
-            const forkedStore = await store.fork();
-            const forkedSingleton = forkedStore.openSingleton('singleton');
-            expect(await get(store, singleton)).to.equal('foo');
-            await forkedSingleton.set('bar');
-            expect(await get(store, singleton)).to.equal('foo');
-            expect(await get(forkedStore, forkedSingleton)).to.equal('bar');
-            await forkedSingleton.delete();
-            expect(await get(store, singleton)).to.equal('foo');
-            await forkedStore.delete();
-        };
-        it('forks a persistent store', async ()=>{
-            const store = await getPersistentStore();
-            await itForks(store);
-            await store.delete();
-        });
-        it('forks a persistent store with no path', async ()=>{
-            const store = await getPersistentNoPathStore();
-            await itForks(store);
-            await store.delete();
-        });
-        it('forks an ephemeral store', async ()=>{
-            const store = await getEphemeralStore();
-            await itForks(store);
-            await store.delete();
-        });
-    });
-}