@aztec/stdlib 0.84.0-nightly.20250409 → 0.84.0-nightly.20250412

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/stdlib",
-  "version": "0.84.0-nightly.20250409",
+  "version": "0.84.0-nightly.20250412",
   "type": "module",
   "inherits": [
     "../package.common.json",
@@ -39,6 +39,7 @@
     "./stats": "./dest/stats/index.js",
     "./auth-witness": "./dest/auth_witness/index.js",
     "./block": "./dest/block/index.js",
+    "./block/test": "./dest/block/test/index.js",
     "./versioning": "./dest/versioning/index.js",
     "./interfaces/client": "./dest/interfaces/client.js",
     "./interfaces/server": "./dest/interfaces/server.js",
@@ -67,11 +68,11 @@
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}"
   },
   "dependencies": {
-    "@aztec/bb.js": "0.84.0-nightly.20250409",
-    "@aztec/blob-lib": "0.84.0-nightly.20250409",
-    "@aztec/constants": "0.84.0-nightly.20250409",
-    "@aztec/ethereum": "0.84.0-nightly.20250409",
-    "@aztec/foundation": "0.84.0-nightly.20250409",
+    "@aztec/bb.js": "0.84.0-nightly.20250412",
+    "@aztec/blob-lib": "0.84.0-nightly.20250412",
+    "@aztec/constants": "0.84.0-nightly.20250412",
+    "@aztec/ethereum": "0.84.0-nightly.20250412",
+    "@aztec/foundation": "0.84.0-nightly.20250412",
     "@google-cloud/storage": "^7.15.0",
     "lodash.chunk": "^4.2.0",
     "lodash.isequal": "^4.5.0",
@@ -84,6 +85,7 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@jest/expect": "^29.5.0",
     "@jest/globals": "^29.5.0",
     "@types/jest": "^29.5.0",
     "@types/lodash.chunk": "^4.2.9",

package/src/avm/avm.ts

@@ -10,7 +10,7 @@ import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
 import { MerkleTreeId } from '../trees/merkle_tree_id.js';
 import { NullifierLeafPreimage } from '../trees/nullifier_leaf.js';
 import { PublicDataTreeLeafPreimage } from '../trees/public_data_leaf.js';
-import { TreeSnapshots, type Tx } from '../tx/index.js';
+import { GlobalVariables, TreeSnapshots, type Tx } from '../tx/index.js';
 import { AvmCircuitPublicInputs } from './avm_circuit_public_inputs.js';
 import { serializeWithMessagePack } from './message_pack.js';
 
@@ -402,6 +402,7 @@ export class AvmEnqueuedCallHint {
 export class AvmTxHint {
   constructor(
     public readonly hash: string,
+    public readonly globalVariables: GlobalVariables,
     public readonly nonRevertibleAccumulatedData: {
       noteHashes: Fr[];
       nullifiers: Fr[];
@@ -429,6 +430,7 @@ export class AvmTxHint {
 
     return new AvmTxHint(
       txHash.hash.toString(),
+      tx.data.constants.historicalHeader.globalVariables,
       {
         noteHashes: tx.data.forPublic!.nonRevertibleAccumulatedData.noteHashes.filter(x => !x.isZero()),
         nullifiers: tx.data.forPublic!.nonRevertibleAccumulatedData.nullifiers.filter(x => !x.isZero()),
@@ -467,13 +469,22 @@ export class AvmTxHint {
   }
 
   static empty() {
-    return new AvmTxHint('', { noteHashes: [], nullifiers: [] }, { noteHashes: [], nullifiers: [] }, [], [], null);
+    return new AvmTxHint(
+      '',
+      GlobalVariables.empty(),
+      { noteHashes: [], nullifiers: [] },
+      { noteHashes: [], nullifiers: [] },
+      [],
+      [],
+      null,
+    );
   }
 
   static get schema() {
     return z
       .object({
         hash: z.string(),
+        globalVariables: GlobalVariables.schema,
         nonRevertibleAccumulatedData: z.object({
           noteHashes: schemas.Fr.array(),
           nullifiers: schemas.Fr.array(),
@@ -489,6 +500,7 @@ export class AvmTxHint {
       .transform(
         ({
           hash,
+          globalVariables,
           nonRevertibleAccumulatedData,
           revertibleAccumulatedData,
           setupEnqueuedCalls,
@@ -497,6 +509,7 @@ export class AvmTxHint {
         }) =>
           new AvmTxHint(
             hash,
+            globalVariables,
             nonRevertibleAccumulatedData,
             revertibleAccumulatedData,
             setupEnqueuedCalls,
@@ -515,6 +528,7 @@ export class AvmExecutionHints {
     public readonly contractClasses: AvmContractClassHint[] = [],
     public readonly bytecodeCommitments: AvmBytecodeCommitmentHint[] = [],
     // Merkle DB hints.
+    public startingTreeRoots: TreeSnapshots = TreeSnapshots.empty(),
     public readonly getSiblingPathHints: AvmGetSiblingPathHint[] = [],
     public readonly getPreviousValueIndexHints: AvmGetPreviousValueIndexHint[] = [],
     public readonly getLeafPreimageHintsPublicDataTree: AvmGetLeafPreimageHintPublicDataTree[] = [],
@@ -539,6 +553,7 @@ export class AvmExecutionHints {
         contractInstances: AvmContractInstanceHint.schema.array(),
         contractClasses: AvmContractClassHint.schema.array(),
         bytecodeCommitments: AvmBytecodeCommitmentHint.schema.array(),
+        startingTreeRoots: TreeSnapshots.schema,
         getSiblingPathHints: AvmGetSiblingPathHint.schema.array(),
         getPreviousValueIndexHints: AvmGetPreviousValueIndexHint.schema.array(),
         getLeafPreimageHintsPublicDataTree: AvmGetLeafPreimageHintPublicDataTree.schema.array(),
@@ -557,6 +572,7 @@ export class AvmExecutionHints {
           contractInstances,
           contractClasses,
           bytecodeCommitments,
+          startingTreeRoots,
           getSiblingPathHints,
           getPreviousValueIndexHints,
           getLeafPreimageHintsPublicDataTree,
@@ -574,6 +590,7 @@ export class AvmExecutionHints {
             contractInstances,
             contractClasses,
             bytecodeCommitments,
+            startingTreeRoots,
             getSiblingPathHints,
             getPreviousValueIndexHints,
             getLeafPreimageHintsPublicDataTree,

package/src/block/index.ts

@@ -1,5 +1,5 @@
 export * from './l2_block.js';
-export * from './l2_block_downloader/index.js';
+export * from './l2_block_stream/index.js';
 export * from './in_block.js';
 export * from './body.js';
 export * from './l2_block_number.js';

package/src/block/l2_block_source.ts

@@ -140,6 +140,14 @@ export type L2Tips = Record<L2BlockTag, L2BlockId>;
 /** Identifies a block by number and hash. */
 export type L2BlockId = z.infer<typeof L2BlockIdSchema>;
 
+/** Creates an L2 block id */
+export function makeL2BlockId(number: number, hash?: string): L2BlockId {
+  if (number !== 0 && !hash) {
+    throw new Error(`Hash is required for non-genesis blocks (got block number ${number})`);
+  }
+  return { number, hash: hash! };
+}
+
 // TODO(palla/schemas): This package should know what is the block hash of the genesis block 0.
 const L2BlockIdSchema = z.union([
   z.object({

package/src/block/l2_block_stream/index.ts

@@ -0,0 +1,3 @@
+export * from './interfaces.js';
+export * from './l2_block_stream.js';
+export * from './l2_tips_memory_store.js';

package/src/block/l2_block_stream/interfaces.ts

@@ -0,0 +1,33 @@
+import type { L2BlockId, L2Tips } from '../l2_block_source.js';
+import type { PublishedL2Block } from '../published_l2_block.js';
+
+/** Interface to the local view of the chain. Implemented by world-state and l2-tips-store. */
+export interface L2BlockStreamLocalDataProvider {
+  getL2BlockHash(number: number): Promise<string | undefined>;
+  getL2Tips(): Promise<L2Tips>;
+}
+
+/** Interface to a handler of events emitted. */
+export interface L2BlockStreamEventHandler {
+  handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void>;
+}
+
+export type L2BlockStreamEvent =
+  | /** Emits blocks added to the chain. */ {
+      type: 'blocks-added';
+      blocks: PublishedL2Block[];
+    }
+  | /** Reports last correct block (new tip of the unproven chain). */ {
+      type: 'chain-pruned';
+      block: L2BlockId;
+    }
+  | /** Reports new proven block. */ {
+      type: 'chain-proven';
+      block: L2BlockId;
+    }
+  | /** Reports new finalized block (proven and finalized on L1). */ {
+      type: 'chain-finalized';
+      block: L2BlockId;
+    };
+
+export type L2TipsStore = L2BlockStreamEventHandler & L2BlockStreamLocalDataProvider;

package/src/block/{l2_block_downloader → l2_block_stream}/l2_block_stream.ts

@@ -2,8 +2,8 @@ import { AbortError } from '@aztec/foundation/error';
 import { createLogger } from '@aztec/foundation/log';
 import { RunningPromise } from '@aztec/foundation/running-promise';
 
-import type { L2BlockId, L2BlockSource, L2Tips } from '../l2_block_source.js';
-import type { PublishedL2Block } from '../published_l2_block.js';
+import { type L2BlockId, type L2BlockSource, makeL2BlockId } from '../l2_block_source.js';
+import type { L2BlockStreamEvent, L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider } from './interfaces.js';
 
 /** Creates a stream of events for new blocks, chain tips updates, and reorgs, out of polling an archiver or a node. */
 export class L2BlockStream {
@@ -21,6 +21,8 @@ export class L2BlockStream {
       pollIntervalMS?: number;
       batchSize?: number;
       startingBlock?: number;
+      /** Instead of downloading all blocks, only fetch the smallest subset that results in reliable reorg detection. */
+      skipFinalized?: boolean;
     } = {},
   ) {
     this.runningPromise = new RunningPromise(() => this.work(), log, this.opts.pollIntervalMS ?? 1000);
@@ -72,14 +74,13 @@ export class L2BlockStream {
       }
 
       if (latestBlockNumber < localTips.latest.number) {
+        latestBlockNumber = Math.min(latestBlockNumber, sourceTips.latest.number); // see #13471
+        const hash = sourceCache.get(latestBlockNumber) ?? (await this.getBlockHashFromSource(latestBlockNumber));
+        if (latestBlockNumber !== 0 && !hash) {
+          throw new Error(`Block hash not found in block source for block number ${latestBlockNumber}`);
+        }
         this.log.verbose(`Reorg detected. Pruning blocks from ${latestBlockNumber + 1} to ${localTips.latest.number}.`);
-        await this.emitEvent({
-          type: 'chain-pruned',
-          block: {
-            number: latestBlockNumber,
-            hash: sourceCache.get(latestBlockNumber) ?? (await this.getBlockHashFromSource(latestBlockNumber))!,
-          },
-        });
+        await this.emitEvent({ type: 'chain-pruned', block: makeL2BlockId(latestBlockNumber, hash) });
       }
 
       // If we are just starting, use the starting block number from the options.
@@ -93,17 +94,26 @@ export class L2BlockStream {
         this.hasStarted = true;
       }
 
+      let nextBlockNumber = latestBlockNumber + 1;
+      if (this.opts.skipFinalized) {
+        // When skipping finalized blocks we need to provide reliable reorg detection while fetching as few blocks as
+        // possible. Finalized blocks cannot be reorged by definition, so we can skip most of them. We do need the very
+        // last finalized block however in order to guarantee that we will eventually find a block in which our local
+        // store matches the source.
+        // If the last finalized block is behind our local tip, there is nothing to skip.
+        nextBlockNumber = Math.max(sourceTips.finalized.number, nextBlockNumber);
+      }
+
       // Request new blocks from the source.
-      while (latestBlockNumber < sourceTips.latest.number) {
-        const from = latestBlockNumber + 1;
-        const limit = Math.min(this.opts.batchSize ?? 20, sourceTips.latest.number - from + 1);
-        this.log.trace(`Requesting blocks from ${from} limit ${limit} proven=${this.opts.proven}`);
-        const blocks = await this.l2BlockSource.getPublishedBlocks(from, limit, this.opts.proven);
+      while (nextBlockNumber <= sourceTips.latest.number) {
+        const limit = Math.min(this.opts.batchSize ?? 20, sourceTips.latest.number - nextBlockNumber + 1);
+        this.log.trace(`Requesting blocks from ${nextBlockNumber} limit ${limit} proven=${this.opts.proven}`);
+        const blocks = await this.l2BlockSource.getPublishedBlocks(nextBlockNumber, limit, this.opts.proven);
         if (blocks.length === 0) {
           break;
         }
         await this.emitEvent({ type: 'blocks-added', blocks });
-        latestBlockNumber = blocks.at(-1)!.block.number;
+        nextBlockNumber = blocks.at(-1)!.block.number + 1;
       }
 
       // Update the proven and finalized tips.
@@ -134,6 +144,15 @@ export class L2BlockStream {
       return true;
     }
     const localBlockHash = await this.localData.getL2BlockHash(blockNumber);
+    if (!localBlockHash && this.opts.skipFinalized) {
+      // Failing to find a block hash when skipping finalized blocks can be highly problematic as we'd potentially need
+      // to go all the way back to the genesis block to find a block in which we agree with the source (since we've
+      // potentially skipped all history). This means that stores that prune old blocks must be careful to leave no gaps
+      // when going back from latest block to the last finalized one.
+      this.log.error(`No local block hash for block number ${blockNumber}`);
+      throw new AbortError();
+    }
+
     const sourceBlockHashFromCache = args.sourceCache.get(blockNumber);
     const sourceBlockHash = args.sourceCache.get(blockNumber) ?? (await this.getBlockHashFromSource(blockNumber));
     if (!sourceBlockHashFromCache && sourceBlockHash) {
@@ -181,32 +200,3 @@ class BlockHashCache {
     return this.cache.get(blockNumber);
   }
 }
-
-/** Interface to the local view of the chain. Implemented by world-state and l2-tips-store. */
-export interface L2BlockStreamLocalDataProvider {
-  getL2BlockHash(number: number): Promise<string | undefined>;
-  getL2Tips(): Promise<L2Tips>;
-}
-
-/** Interface to a handler of events emitted. */
-export interface L2BlockStreamEventHandler {
-  handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void>;
-}
-
-export type L2BlockStreamEvent =
-  | /** Emits blocks added to the chain. */ {
-      type: 'blocks-added';
-      blocks: PublishedL2Block[];
-    }
-  | /** Reports last correct block (new tip of the unproven chain). */ {
-      type: 'chain-pruned';
-      block: L2BlockId;
-    }
-  | /** Reports new proven block. */ {
-      type: 'chain-proven';
-      block: L2BlockId;
-    }
-  | /** Reports new finalized block (proven and finalized on L1). */ {
-      type: 'chain-finalized';
-      block: L2BlockId;
-    };

package/src/block/l2_block_stream/l2_tips_memory_store.ts

@@ -0,0 +1,75 @@
+import type { L2Block } from '../l2_block.js';
+import type { L2BlockId, L2BlockTag, L2Tips } from '../l2_block_source.js';
+import type { L2BlockStreamEvent, L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider } from './interfaces.js';
+
+/**
+ * Stores currently synced L2 tips and unfinalized block hashes.
+ * @dev tests in kv-store/src/stores/l2_tips_memory_store.test.ts
+ */
+export class L2TipsMemoryStore implements L2BlockStreamEventHandler, L2BlockStreamLocalDataProvider {
+  protected readonly l2TipsStore: Map<L2BlockTag, number> = new Map();
+  protected readonly l2BlockHashesStore: Map<number, string> = new Map();
+
+  public getL2BlockHash(number: number): Promise<string | undefined> {
+    return Promise.resolve(this.l2BlockHashesStore.get(number));
+  }
+
+  public getL2Tips(): Promise<L2Tips> {
+    return Promise.resolve({
+      latest: this.getL2Tip('latest'),
+      finalized: this.getL2Tip('finalized'),
+      proven: this.getL2Tip('proven'),
+    });
+  }
+
+  private getL2Tip(tag: L2BlockTag): L2BlockId {
+    const blockNumber = this.l2TipsStore.get(tag);
+    if (blockNumber === undefined || blockNumber === 0) {
+      return { number: 0, hash: undefined };
+    }
+    const blockHash = this.l2BlockHashesStore.get(blockNumber);
+    if (!blockHash) {
+      throw new Error(`Block hash not found for block number ${blockNumber}`);
+    }
+
+    return { number: blockNumber, hash: blockHash };
+  }
+
+  public async handleBlockStreamEvent(event: L2BlockStreamEvent): Promise<void> {
+    switch (event.type) {
+      case 'blocks-added': {
+        const blocks = event.blocks.map(b => b.block);
+        for (const block of blocks) {
+          this.l2BlockHashesStore.set(block.number, await this.computeBlockHash(block));
+        }
+        this.l2TipsStore.set('latest', blocks.at(-1)!.number);
+        break;
+      }
+      case 'chain-pruned':
+        this.saveTag('latest', event.block);
+        break;
+      case 'chain-proven':
+        this.saveTag('proven', event.block);
+        break;
+      case 'chain-finalized':
+        this.saveTag('finalized', event.block);
+        for (const key of this.l2BlockHashesStore.keys()) {
+          if (key < event.block.number) {
+            this.l2BlockHashesStore.delete(key);
+          }
+        }
+        break;
+    }
+  }
+
+  protected saveTag(name: L2BlockTag, block: L2BlockId) {
+    this.l2TipsStore.set(name, block.number);
+    if (block.hash) {
+      this.l2BlockHashesStore.set(block.number, block.hash);
+    }
+  }
+
+  protected computeBlockHash(block: L2Block) {
+    return block.header.hash().then(hash => hash.toString());
+  }
+}

package/src/block/test/index.ts

@@ -0,0 +1 @@
+export * from './l2_tips_store_test_suite.js';

package/src/block/test/l2_tips_store_test_suite.ts

@@ -0,0 +1,87 @@
+import { times } from '@aztec/foundation/collection';
+import { Fr } from '@aztec/foundation/fields';
+import type { L2Block, L2BlockId, PublishedL2Block } from '@aztec/stdlib/block';
+import type { BlockHeader } from '@aztec/stdlib/tx';
+
+import { jestExpect as expect } from '@jest/expect';
+
+import type { L2TipsStore } from '../l2_block_stream/index.js';
+
+export function testL2TipsStore(makeTipsStore: () => Promise<L2TipsStore>) {
+  let tipsStore: L2TipsStore;
+
+  beforeEach(async () => {
+    tipsStore = await makeTipsStore();
+  });
+
+  const makeBlock = (number: number): PublishedL2Block => ({
+    block: { number, header: { hash: () => Promise.resolve(new Fr(number)) } as BlockHeader } as L2Block,
+    l1: { blockNumber: BigInt(number), blockHash: `0x${number}`, timestamp: BigInt(number) },
+    signatures: [],
+  });
+
+  const makeBlockId = (number: number): L2BlockId => ({
+    number,
+    hash: new Fr(number).toString(),
+  });
+
+  const makeTip = (number: number) => ({ number, hash: number === 0 ? undefined : new Fr(number).toString() });
+
+  const makeTips = (latest: number, proven: number, finalized: number) => ({
+    latest: makeTip(latest),
+    proven: makeTip(proven),
+    finalized: makeTip(finalized),
+  });
+
+  it('returns zero if no tips are stored', async () => {
+    const tips = await tipsStore.getL2Tips();
+    expect(tips).toEqual(makeTips(0, 0, 0));
+  });
+
+  it('stores chain tips', async () => {
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: times(20, i => makeBlock(i + 1)) });
+
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-finalized', block: makeBlockId(5) });
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(8) });
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-pruned', block: makeBlockId(10) });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips).toEqual(makeTips(10, 8, 5));
+  });
+
+  it('sets latest tip from blocks added', async () => {
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: times(3, i => makeBlock(i + 1)) });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips).toEqual(makeTips(3, 0, 0));
+
+    expect(await tipsStore.getL2BlockHash(1)).toEqual(new Fr(1).toString());
+    expect(await tipsStore.getL2BlockHash(2)).toEqual(new Fr(2).toString());
+    expect(await tipsStore.getL2BlockHash(3)).toEqual(new Fr(3).toString());
+  });
+
+  it('clears block hashes when setting finalized chain', async () => {
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: times(5, i => makeBlock(i + 1)) });
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(3) });
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-finalized', block: makeBlockId(3) });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips).toEqual(makeTips(5, 3, 3));
+
+    expect(await tipsStore.getL2BlockHash(1)).toBeUndefined();
+    expect(await tipsStore.getL2BlockHash(2)).toBeUndefined();
+
+    expect(await tipsStore.getL2BlockHash(3)).toEqual(new Fr(3).toString());
+    expect(await tipsStore.getL2BlockHash(4)).toEqual(new Fr(4).toString());
+    expect(await tipsStore.getL2BlockHash(5)).toEqual(new Fr(5).toString());
+  });
+
+  // Regression test for #13142
+  it('does not blow up when setting proven chain on an unseen block number', async () => {
+    await tipsStore.handleBlockStreamEvent({ type: 'blocks-added', blocks: [makeBlock(5)] });
+    await tipsStore.handleBlockStreamEvent({ type: 'chain-proven', block: makeBlockId(3) });
+
+    const tips = await tipsStore.getL2Tips();
+    expect(tips).toEqual(makeTips(5, 3, 0));
+  });
+}

package/src/database-version/version_manager.ts

@@ -1,6 +1,6 @@
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { jsonParseWithSchemaSync, jsonStringify } from '@aztec/foundation/json-rpc';
-import { createLogger } from '@aztec/foundation/log';
+import { type Logger, createLogger } from '@aztec/foundation/log';
 
 import fs from 'fs/promises';
 import { inspect } from 'node:util';
@@ -11,7 +11,12 @@ import { z } from 'zod';
  * Represents a version record for storing in a version file.
  */
 export class DatabaseVersion {
-  constructor(public readonly schemaVersion: number, public readonly rollupAddress: EthAddress) {}
+  constructor(
+    /** The version of the data on disk. Used to perform upgrades */
+    public readonly schemaVersion: number,
+    /** The rollup the data pertains to */
+    public readonly rollupAddress: EthAddress,
+  ) {}
 
   public toBuffer(): Buffer {
     return Buffer.from(jsonStringify(this));
@@ -66,7 +71,7 @@ export class DatabaseVersion {
   }
 
   public toString(): string {
-    return this.schemaVersion.toString();
+    return `DatabaseVersion{schemaVersion=${this.schemaVersion},rollupAddress=${this.rollupAddress}"}`;
   }
 
   /**
@@ -81,6 +86,16 @@ export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile'
 
 export const DATABASE_VERSION_FILE_NAME = 'db_version';
 
+export type DatabaseVersionManagerOptions<T> = {
+  schemaVersion: number;
+  rollupAddress: EthAddress;
+  dataDirectory: string;
+  onOpen: (dataDir: string) => Promise<T>;
+  onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
+  fileSystem?: DatabaseVersionManagerFs;
+  log?: Logger;
+};
+
 /**
  * A manager for handling database versioning and migrations.
  * This class will check the version of data in a directory and either
@@ -92,6 +107,12 @@ export class DatabaseVersionManager<T> {
   private readonly versionFile: string;
   private readonly currentVersion: DatabaseVersion;
 
+  private dataDirectory: string;
+  private onOpen: (dataDir: string) => Promise<T>;
+  private onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
+  private fileSystem: DatabaseVersionManagerFs;
+  private log: Logger;
+
   /**
    * Create a new version manager
    *
@@ -104,21 +125,27 @@ export class DatabaseVersionManager<T> {
    * @param log - Optional custom logger
    * @param options - Configuration options
    */
-  constructor(
-    schemaVersion: number,
-    rollupAddress: EthAddress,
-    private dataDirectory: string,
-    private onOpen: (dataDir: string) => Promise<T>,
-    private onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>,
-    private fileSystem: DatabaseVersionManagerFs = fs,
-    private log = createLogger(`foundation:version-manager`),
-  ) {
+  constructor({
+    schemaVersion,
+    rollupAddress,
+    dataDirectory,
+    onOpen,
+    onUpgrade,
+    fileSystem = fs,
+    log = createLogger(`foundation:version-manager`),
+  }: DatabaseVersionManagerOptions<T>) {
     if (schemaVersion < 1) {
       throw new TypeError(`Invalid schema version received: ${schemaVersion}`);
     }
 
-    this.versionFile = join(this.dataDirectory, DatabaseVersionManager.VERSION_FILE);
+    this.versionFile = join(dataDirectory, DatabaseVersionManager.VERSION_FILE);
     this.currentVersion = new DatabaseVersion(schemaVersion, rollupAddress);
+
+    this.dataDirectory = dataDirectory;
+    this.onOpen = onOpen;
+    this.onUpgrade = onUpgrade;
+    this.fileSystem = fileSystem;
+    this.log = log;
   }
 
   static async writeVersion(version: DatabaseVersion, dataDir: string, fileSystem: DatabaseVersionManagerFs = fs) {
@@ -137,6 +164,8 @@ export class DatabaseVersionManager<T> {
   public async open(): Promise<[T, boolean]> {
     // const storedVersion = await DatabaseVersion.readVersion(this.versionFile);
     let storedVersion: DatabaseVersion;
+    // a flag to suppress logs about 'resetting the data dir' when starting from an empty state
+    let shouldLogDataReset = true;
 
     try {
       const versionBuf = await this.fileSystem.readFile(this.versionFile);
@@ -144,6 +173,8 @@ export class DatabaseVersionManager<T> {
     } catch (err) {
       if (err && (err as Error & { code: string }).code === 'ENOENT') {
         storedVersion = DatabaseVersion.empty();
+        // only turn off these logs if the data dir didn't exist before
+        shouldLogDataReset = false;
       } else {
         this.log.warn(`Failed to read stored version information: ${err}. Defaulting to empty version`);
         storedVersion = DatabaseVersion.empty();
@@ -164,13 +195,21 @@ export class DatabaseVersionManager<T> {
           needsReset = true;
         }
       } else if (cmp !== 0) {
-        this.log.info(
-          `Can't upgrade from version ${storedVersion.schemaVersion} to ${this.currentVersion.schemaVersion}. Resetting database at ${this.dataDirectory}`,
-        );
+        if (shouldLogDataReset) {
+          this.log.info(
+            `Can't upgrade from version ${storedVersion} to ${this.currentVersion}. Resetting database at ${this.dataDirectory}`,
+          );
+        }
         needsReset = true;
       }
     } else {
-      this.log.warn('Rollup address changed, resetting data directory', { versionFile: this.versionFile });
+      if (shouldLogDataReset) {
+        this.log.warn('Rollup address has changed, resetting data directory', {
+          versionFile: this.versionFile,
+          storedVersion,
+          currentVersion: this.currentVersion,
+        });
+      }
       needsReset = true;
     }