@aztec/stdlib 0.0.0-test.0

package/src/contract/interfaces/protocol_contract_addresses.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+import type { AztecAddress } from '../../aztec-address/index.js';
+import { schemas } from '../../schemas/index.js';
+
+export const ProtocolContractsNames = [
+  'classRegisterer',
+  'feeJuice',
+  'instanceDeployer',
+  'multiCallEntrypoint',
+] as const;
+
+export type ProtocolContractAddresses = {
+  classRegisterer: AztecAddress;
+  feeJuice: AztecAddress;
+  instanceDeployer: AztecAddress;
+  multiCallEntrypoint: AztecAddress;
+};
+
+export const ProtocolContractAddressesSchema = z.object({
+  classRegisterer: schemas.AztecAddress,
+  feeJuice: schemas.AztecAddress,
+  instanceDeployer: schemas.AztecAddress,
+  multiCallEntrypoint: schemas.AztecAddress,
+});

package/src/contract/partial_address.ts

@@ -0,0 +1,7 @@
+import type { Fr } from '@aztec/foundation/fields';
+
+/**
+ * A type which along with public key forms a preimage of a contract address. See the link below for more details
+ * https://github.com/AztecProtocol/aztec-packages/blob/master/docs/docs/concepts/foundation/accounts/keys.md#addresses-partial-addresses-and-public-keys
+ */
+export type PartialAddress = Fr;

package/src/contract/private_function.ts

@@ -0,0 +1,47 @@
+import { FUNCTION_TREE_HEIGHT, GeneratorIndex } from '@aztec/constants';
+import { pedersenHash, poseidon2Hash, poseidon2HashWithSeparator } from '@aztec/foundation/crypto';
+import { Fr } from '@aztec/foundation/fields';
+import { type MerkleTree, MerkleTreeCalculator } from '@aztec/foundation/trees';
+
+import type { PrivateFunction } from './interfaces/contract_class.js';
+
+// Memoize the merkle tree calculators to avoid re-computing the zero-hash for each level in each call
+let privateFunctionTreeCalculator: MerkleTreeCalculator | undefined;
+
+const PRIVATE_FUNCTION_SIZE = 2;
+
+/** Returns a Merkle tree for the set of private functions in a contract. */
+export async function computePrivateFunctionsTree(fns: PrivateFunction[]): Promise<MerkleTree> {
+  const calculator = await getPrivateFunctionTreeCalculator();
+  const leaves = await computePrivateFunctionLeaves(fns);
+  return calculator.computeTree(leaves);
+}
+
+/** Returns the Merkle tree root for the set of private functions in a contract. */
+export async function computePrivateFunctionsRoot(fns: PrivateFunction[]): Promise<Fr> {
+  const calculator = await getPrivateFunctionTreeCalculator();
+  const leaves = await computePrivateFunctionLeaves(fns);
+  return Fr.fromBuffer(await calculator.computeTreeRoot(leaves));
+}
+
+function computePrivateFunctionLeaves(fns: PrivateFunction[]): Promise<Buffer[]> {
+  const leaves = [...fns].sort((a, b) => a.selector.value - b.selector.value);
+  return Promise.all(leaves.map(computePrivateFunctionLeaf));
+}
+
+/** Returns the leaf for a given private function. */
+export async function computePrivateFunctionLeaf(fn: PrivateFunction): Promise<Buffer> {
+  return (await poseidon2HashWithSeparator([fn.selector, fn.vkHash], GeneratorIndex.FUNCTION_LEAF)).toBuffer();
+}
+
+async function getPrivateFunctionTreeCalculator(): Promise<MerkleTreeCalculator> {
+  if (!privateFunctionTreeCalculator) {
+    const functionTreeZeroLeaf = (await pedersenHash(new Array(PRIVATE_FUNCTION_SIZE).fill(0))).toBuffer();
+    privateFunctionTreeCalculator = await MerkleTreeCalculator.create(
+      FUNCTION_TREE_HEIGHT,
+      functionTreeZeroLeaf,
+      async (left, right) => (await poseidon2Hash([left, right])).toBuffer(),
+    );
+  }
+  return privateFunctionTreeCalculator;
+}

package/src/contract/private_function_membership_proof.ts

@@ -0,0 +1,167 @@
+import { poseidon2Hash } from '@aztec/foundation/crypto';
+import { Fr } from '@aztec/foundation/fields';
+import { createLogger } from '@aztec/foundation/log';
+import { computeRootFromSiblingPath } from '@aztec/foundation/trees';
+
+import { type ContractArtifact, FunctionSelector, FunctionType } from '../abi/index.js';
+import {
+  computeArtifactFunctionTree,
+  computeArtifactHash,
+  computeArtifactHashPreimage,
+  computeFunctionArtifactHash,
+  computeFunctionMetadataHash,
+  getArtifactMerkleTreeHasher,
+} from './artifact_hash.js';
+import { getContractClassPrivateFunctionFromArtifact } from './contract_class.js';
+import type {
+  ContractClassPublic,
+  ExecutablePrivateFunctionWithMembershipProof,
+  PrivateFunctionMembershipProof,
+} from './interfaces/index.js';
+import { computePrivateFunctionLeaf, computePrivateFunctionsTree } from './private_function.js';
+
+/**
+ * Creates a membership proof for a private function in a contract class, to be verified via `isValidPrivateFunctionMembershipProof`.
+ * @param selector - Selector of the function to create the proof for.
+ * @param artifact - Artifact of the contract class where the function is defined.
+ */
+export async function createPrivateFunctionMembershipProof(
+  selector: FunctionSelector,
+  artifact: ContractArtifact,
+): Promise<PrivateFunctionMembershipProof> {
+  const log = createLogger('circuits:function_membership_proof');
+
+  // Locate private function definition and artifact
+  const privateFunctions = artifact.functions.filter(fn => fn.functionType === FunctionType.PRIVATE);
+  const privateFunctionsFromArtifact = await Promise.all(
+    privateFunctions.map(getContractClassPrivateFunctionFromArtifact),
+  );
+  const privateFunction = privateFunctionsFromArtifact.find(fn => fn.selector.equals(selector));
+  const privateFunctionsAndSelectors = await Promise.all(
+    privateFunctions.map(async fn => ({
+      fn,
+      selector: await FunctionSelector.fromNameAndParameters(fn.name, fn.parameters),
+    })),
+  );
+  const privateFunctionArtifact = privateFunctionsAndSelectors.find(fnAndSelector =>
+    selector.equals(fnAndSelector.selector),
+  )?.fn;
+  if (!privateFunction || !privateFunctionArtifact) {
+    throw new Error(`Private function with selector ${selector.toString()} not found`);
+  }
+
+  // Compute preimage for the artifact hash
+  const { unconstrainedFunctionRoot: unconstrainedFunctionsArtifactTreeRoot, metadataHash: artifactMetadataHash } =
+    await computeArtifactHashPreimage(artifact);
+
+  // We need two sibling paths because private function information is split across two trees:
+  // The "private function tree" captures the selectors and verification keys, and is used in the kernel circuit for verifying the proof generated by the app circuit.
+  const functionLeaf = await computePrivateFunctionLeaf(privateFunction);
+  const functionsTree = await computePrivateFunctionsTree(privateFunctionsFromArtifact);
+  const functionsTreeLeafIndex = functionsTree.getIndex(functionLeaf);
+  const functionsTreeSiblingPath = functionsTree.getSiblingPath(functionsTreeLeafIndex).map(Fr.fromBuffer);
+
+  // And the "artifact tree" captures function bytecode and metadata, and is used by the pxe to check that its executing the code it's supposed to be executing, but it never goes into circuits.
+  const functionMetadataHash = computeFunctionMetadataHash(privateFunctionArtifact);
+  const functionArtifactHash = await computeFunctionArtifactHash({ ...privateFunctionArtifact, functionMetadataHash });
+  const artifactTree = (await computeArtifactFunctionTree(artifact, FunctionType.PRIVATE))!;
+  const artifactTreeLeafIndex = artifactTree.getIndex(functionArtifactHash.toBuffer());
+  const artifactTreeSiblingPath = artifactTree.getSiblingPath(artifactTreeLeafIndex).map(Fr.fromBuffer);
+
+  log.debug(`Computed proof for private function with selector ${selector.toString()}`, {
+    functionArtifactHash,
+    functionMetadataHash,
+    functionLeaf: '0x' + functionLeaf.toString('hex'),
+    artifactMetadataHash,
+    privateFunctionsTreeRoot: '0x' + functionsTree.root.toString('hex'),
+    unconstrainedFunctionsArtifactTreeRoot,
+    artifactFunctionTreeSiblingPath: artifactTreeSiblingPath.map(fr => fr.toString()).join(','),
+    privateFunctionTreeSiblingPath: functionsTreeSiblingPath.map(fr => fr.toString()).join(','),
+  });
+
+  return {
+    artifactTreeSiblingPath,
+    artifactTreeLeafIndex,
+    artifactMetadataHash,
+    functionMetadataHash,
+    unconstrainedFunctionsArtifactTreeRoot,
+    privateFunctionTreeSiblingPath: functionsTreeSiblingPath,
+    privateFunctionTreeLeafIndex: functionsTreeLeafIndex,
+  };
+}
+
+/**
+ * Verifies that a private function with a membership proof as emitted by the ClassRegisterer contract is valid,
+ * as defined in the protocol specs at contract-deployment/classes:
+ *
+ * ```
+ * // Load contract class from local db
+ * contract_class = db.get_contract_class(contract_class_id)
+ *
+ * // Compute function leaf and assert it belongs to the private functions tree
+ * function_leaf = pedersen([selector as Field, vk_hash], GENERATOR__FUNCTION_LEAF)
+ * computed_private_function_tree_root = compute_root(function_leaf, private_function_tree_sibling_path)
+ * assert computed_private_function_tree_root == contract_class.private_function_root
+ *
+ * // Compute artifact leaf and assert it belongs to the artifact
+ * artifact_function_leaf = sha256(selector, metadata_hash, sha256(bytecode))
+ * computed_artifact_private_function_tree_root = compute_root(artifact_function_leaf, artifact_function_tree_sibling_path)
+ * computed_artifact_hash = sha256(computed_artifact_private_function_tree_root, unconstrained_functions_artifact_tree_root, artifact_metadata_hash)
+ * assert computed_artifact_hash == contract_class.artifact_hash
+ * ```
+ * @param fn - Function to check membership proof for.
+ * @param contractClass - In which contract class the function is expected to be.
+ */
+export async function isValidPrivateFunctionMembershipProof(
+  fn: ExecutablePrivateFunctionWithMembershipProof,
+  contractClass: Pick<ContractClassPublic, 'privateFunctionsRoot' | 'artifactHash'>,
+) {
+  const log = createLogger('circuits:function_membership_proof');
+
+  // Check private function tree membership
+  const functionLeaf = await computePrivateFunctionLeaf(fn);
+  const rootBuffer = await computeRootFromSiblingPath(
+    functionLeaf,
+    fn.privateFunctionTreeSiblingPath.map(fr => fr.toBuffer()),
+    fn.privateFunctionTreeLeafIndex,
+    async (left, right) => (await poseidon2Hash([left, right])).toBuffer(),
+  );
+  const computedPrivateFunctionTreeRoot = Fr.fromBuffer(rootBuffer);
+  if (!contractClass.privateFunctionsRoot.equals(computedPrivateFunctionTreeRoot)) {
+    log.debug(`Private function tree root mismatch`, {
+      expectedPrivateFunctionTreeRoot: contractClass.privateFunctionsRoot,
+      computedPrivateFunctionTreeRoot: computedPrivateFunctionTreeRoot,
+      computedFunctionLeaf: '0x' + functionLeaf.toString('hex'),
+    });
+    return false;
+  }
+
+  // Check artifact hash
+  const functionArtifactHash = await computeFunctionArtifactHash(fn);
+  const computedArtifactPrivateFunctionTreeRootBuffer = await computeRootFromSiblingPath(
+    functionArtifactHash.toBuffer(),
+    fn.artifactTreeSiblingPath.map(fr => fr.toBuffer()),
+    fn.artifactTreeLeafIndex,
+    getArtifactMerkleTreeHasher(),
+  );
+  const computedArtifactPrivateFunctionTreeRoot = Fr.fromBuffer(computedArtifactPrivateFunctionTreeRootBuffer);
+  const computedArtifactHash = await computeArtifactHash({
+    privateFunctionRoot: computedArtifactPrivateFunctionTreeRoot,
+    unconstrainedFunctionRoot: fn.unconstrainedFunctionsArtifactTreeRoot,
+    metadataHash: fn.artifactMetadataHash,
+  });
+  if (!contractClass.artifactHash.equals(computedArtifactHash)) {
+    log.debug(`Artifact hash mismatch`, {
+      expected: contractClass.artifactHash,
+      computedArtifactHash,
+      computedFunctionArtifactHash: functionArtifactHash,
+      computedArtifactPrivateFunctionTreeRoot,
+      unconstrainedFunctionRoot: fn.unconstrainedFunctionsArtifactTreeRoot,
+      metadataHash: fn.artifactMetadataHash,
+      artifactFunctionTreeSiblingPath: fn.artifactTreeSiblingPath.map(fr => fr.toString()).join(','),
+    });
+    return false;
+  }
+
+  return true;
+}

package/src/contract/unconstrained_function_membership_proof.ts

@@ -0,0 +1,118 @@
+import { Fr } from '@aztec/foundation/fields';
+import { createLogger } from '@aztec/foundation/log';
+import { computeRootFromSiblingPath } from '@aztec/foundation/trees';
+
+import { type ContractArtifact, FunctionSelector, FunctionType } from '../abi/index.js';
+import {
+  computeArtifactFunctionTree,
+  computeArtifactHash,
+  computeArtifactHashPreimage,
+  computeFunctionArtifactHash,
+  computeFunctionMetadataHash,
+  getArtifactMerkleTreeHasher,
+} from './artifact_hash.js';
+import type {
+  ContractClassPublic,
+  UnconstrainedFunctionMembershipProof,
+  UnconstrainedFunctionWithMembershipProof,
+} from './interfaces/index.js';
+
+/**
+ * Creates a membership proof for an unconstrained function in a contract class, to be verified via `isValidUnconstrainedFunctionMembershipProof`.
+ * @param selector - Selector of the function to create the proof for.
+ * @param artifact - Artifact of the contract class where the function is defined.
+ */
+export async function createUnconstrainedFunctionMembershipProof(
+  selector: FunctionSelector,
+  artifact: ContractArtifact,
+): Promise<UnconstrainedFunctionMembershipProof> {
+  const log = createLogger('circuits:function_membership_proof');
+
+  // Locate function artifact
+  const uncontrainedFunctions = artifact.functions.filter(fn => fn.functionType === FunctionType.UNCONSTRAINED);
+  const unconstrainedFunctionsAndSelectors = await Promise.all(
+    uncontrainedFunctions.map(async fn => ({ fn, selector: await FunctionSelector.fromNameAndParameters(fn) })),
+  );
+  const fn = unconstrainedFunctionsAndSelectors.find(fnAndSelector => selector.equals(fnAndSelector.selector))?.fn;
+  if (!fn) {
+    throw new Error(`Unconstrained function with selector ${selector.toString()} not found`);
+  }
+  // Compute preimage for the artifact hash
+  const { privateFunctionRoot: privateFunctionsArtifactTreeRoot, metadataHash: artifactMetadataHash } =
+    await computeArtifactHashPreimage(artifact);
+
+  // Compute the sibling path for the "artifact tree"
+  const functionMetadataHash = computeFunctionMetadataHash(fn);
+  const functionArtifactHash = await computeFunctionArtifactHash({ ...fn, functionMetadataHash });
+  const artifactTree = (await computeArtifactFunctionTree(artifact, FunctionType.UNCONSTRAINED))!;
+  const artifactTreeLeafIndex = artifactTree.getIndex(functionArtifactHash.toBuffer());
+  const artifactTreeSiblingPath = artifactTree.getSiblingPath(artifactTreeLeafIndex).map(Fr.fromBuffer);
+
+  log.debug(`Computed proof for unconstrained function with selector ${selector.toString()}`, {
+    functionArtifactHash,
+    functionMetadataHash,
+    artifactMetadataHash,
+    artifactFunctionTreeSiblingPath: artifactTreeSiblingPath.map(fr => fr.toString()).join(','),
+    privateFunctionsArtifactTreeRoot,
+  });
+
+  return {
+    artifactTreeSiblingPath,
+    artifactTreeLeafIndex,
+    artifactMetadataHash,
+    functionMetadataHash,
+    privateFunctionsArtifactTreeRoot,
+  };
+}
+
+/**
+ * Verifies that an unconstrained function with a membership proof as emitted by the ClassRegisterer contract is valid,
+ * as defined in the protocol specs at contract-deployment/classes:
+ *
+ * ```
+ * // Load contract class from local db
+ * contract_class = db.get_contract_class(contract_class_id)
+ *
+ * // Compute artifact leaf and assert it belongs to the artifact
+ * artifact_function_leaf = sha256(selector, metadata_hash, sha256(bytecode))
+ * computed_artifact_unconstrained_function_tree_root = compute_root(artifact_function_leaf, artifact_function_tree_sibling_path, artifact_function_tree_leaf_index)
+ * computed_artifact_hash = sha256(private_functions_artifact_tree_root, computed_artifact_unconstrained_function_tree_root, artifact_metadata_hash)
+ * assert computed_artifact_hash == contract_class.artifact_hash
+ * ```
+ * @param fn - Function to check membership proof for.
+ * @param contractClass - In which contract class the function is expected to be.
+ */
+export async function isValidUnconstrainedFunctionMembershipProof(
+  fn: UnconstrainedFunctionWithMembershipProof,
+  contractClass: Pick<ContractClassPublic, 'artifactHash'>,
+) {
+  const log = createLogger('circuits:function_membership_proof');
+
+  const functionArtifactHash = await computeFunctionArtifactHash(fn);
+  const computedArtifactFunctionTreeRootBuffer = await computeRootFromSiblingPath(
+    functionArtifactHash.toBuffer(),
+    fn.artifactTreeSiblingPath.map(fr => fr.toBuffer()),
+    fn.artifactTreeLeafIndex,
+    getArtifactMerkleTreeHasher(),
+  );
+  const computedArtifactFunctionTreeRoot = Fr.fromBuffer(computedArtifactFunctionTreeRootBuffer);
+  const computedArtifactHash = await computeArtifactHash({
+    privateFunctionRoot: fn.privateFunctionsArtifactTreeRoot,
+    unconstrainedFunctionRoot: computedArtifactFunctionTreeRoot,
+    metadataHash: fn.artifactMetadataHash,
+  });
+  if (!contractClass.artifactHash.equals(computedArtifactHash)) {
+    log.debug(`Artifact hash mismatch`, {
+      expected: contractClass.artifactHash,
+      computedArtifactHash,
+      computedFunctionArtifactHash: functionArtifactHash,
+      computedArtifactFunctionTreeRoot,
+      privateFunctionsArtifactTreeRoot: fn.privateFunctionsArtifactTreeRoot,
+      metadataHash: fn.artifactMetadataHash,
+      artifactFunctionTreeSiblingPath: fn.artifactTreeSiblingPath.map(fr => fr.toString()).join(','),
+    });
+    return false;
+  }
+
+  return true;
+}

package/src/database-version/README.md

@@ -0,0 +1,63 @@
+# Version Manager
+
+The Version Manager helps manage database migrations and version compatibility across different versions of the software.
+
+## Features
+
+- Track database schema versions
+- Handle migrations between versions
+- Reset database when necessary (incompatible versions, rollup address change)
+- Simple, clean API for version management
+
+## Usage
+
+```typescript
+import { version } from '@aztec/foundation';
+import { EthAddress } from '@aztec/foundation/eth-address';
+
+// Define your current database version
+const DB_VERSION = 3;
+const rollupAddress = EthAddress.fromString('0x1234567890123456789012345678901234567890');
+
+// Create version manager for your service
+const versionManager = new version.VersionManager(DB_VERSION, rollupAddress, {
+  dataDir: '/path/to/data',
+  serviceName: 'my-database',
+});
+
+// When initializing your database
+await versionManager.checkVersionAndHandle(
+  // Called when a reset is needed
+  async () => {
+    // Initialize a fresh database
+    await initializeFreshDatabase();
+  },
+  // Called when an upgrade is needed (optional)
+  async (oldVersion, newVersion) => {
+    if (oldVersion === 1 && newVersion === 2) {
+      // Migrate from version 1 to 2
+      await migrateV1ToV2();
+    } else if (oldVersion === 2 && newVersion === 3) {
+      // Migrate from version 2 to 3
+      await migrateV2ToV3();
+    } else {
+      // Unsupported migration path, will fall back to reset
+      throw new Error(`Cannot upgrade from ${oldVersion} to ${newVersion}`);
+    }
+  },
+);
+
+// Get the data directory for your service
+const dataDir = versionManager.getDataDirectory();
+```
+
+## Automatic Reset Conditions
+
+The database will be reset in the following conditions:
+
+1. No version information exists (first run)
+2. Rollup address has changed
+3. Version has changed and no upgrade callback is provided
+4. Upgrade callback throws an error
+
+When a reset occurs, the data directory is deleted and recreated, and the reset callback is called to initialize a fresh database.

package/src/database-version/index.ts

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

package/src/database-version/version_manager.ts

@@ -0,0 +1,207 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { jsonParseWithSchemaSync, jsonStringify } from '@aztec/foundation/json-rpc';
+import { createLogger } from '@aztec/foundation/log';
+
+import fs from 'fs/promises';
+import { join } from 'path';
+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) {}
+
+  public toBuffer(): Buffer {
+    return Buffer.from(jsonStringify(this));
+  }
+
+  public static fromBuffer(buf: Buffer): DatabaseVersion {
+    try {
+      return jsonParseWithSchemaSync(buf.toString('utf-8'), DatabaseVersion.schema);
+    } catch (err) {
+      throw new Error(`Failed to deserialize version information: ${err}`, { cause: err });
+    }
+  }
+
+  /**
+   * Compares two versions. If the rollups addresses are different then it returns undefined
+   */
+  public cmp(other: DatabaseVersion): undefined | -1 | 0 | 1 {
+    if (this.rollupAddress.equals(other.rollupAddress)) {
+      if (this.schemaVersion < other.schemaVersion) {
+        return -1;
+      } else if (this.schemaVersion > other.schemaVersion) {
+        return 1;
+      } else {
+        return 0;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Checks if two versions exactly match
+   */
+  public equals(other: DatabaseVersion): boolean {
+    return this.cmp(other) === 0;
+  }
+
+  /**
+   * Returns the schema for this class
+   */
+  static get schema() {
+    return z
+      .object({
+        schemaVersion: z.number(),
+        rollupAddress: EthAddress.schema,
+      })
+      .transform(({ schemaVersion, rollupAddress }) => new DatabaseVersion(schemaVersion, rollupAddress));
+  }
+
+  /**
+   * Returns an empty instance
+   */
+  static empty() {
+    return new DatabaseVersion(0, EthAddress.ZERO);
+  }
+}
+
+export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile' | 'rm' | 'mkdir'>;
+
+/**
+ * A manager for handling database versioning and migrations.
+ * This class will check the version of data in a directory and either
+ * reset or upgrade based on version compatibility.
+ */
+export class DatabaseVersionManager<T> {
+  public static readonly VERSION_FILE = 'db_version';
+
+  private readonly versionFile: string;
+  private readonly currentVersion: DatabaseVersion;
+
+  /**
+   * Create a new version manager
+   *
+   * @param schemaVersion - The current version of the application
+   * @param rollupAddress - The rollup contract address
+   * @param dataDirectory - The directory where version information will be stored
+   * @param onOpen - A callback to the open the database at the given location
+   * @param onUpgrade - An optional callback to upgrade the database before opening. If not provided it will reset the database
+   * @param fileSystem - An interface to access the filesystem
+   * @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`),
+  ) {
+    if (schemaVersion < 1) {
+      throw new TypeError(`Invalid schema version received: ${schemaVersion}`);
+    }
+
+    this.versionFile = join(this.dataDirectory, DatabaseVersionManager.VERSION_FILE);
+    this.currentVersion = new DatabaseVersion(schemaVersion, rollupAddress);
+  }
+
+  /**
+   * Checks the stored version against the current version and handles the outcome
+   * by either resetting the data directory or calling an upgrade function
+   *
+   * @param onReset - Function to call when a full reset is needed
+   * @param onUpgrade - Function to call when an upgrade is needed
+   * @returns True if data was reset, false if upgraded or no change needed
+   */
+  public async open(): Promise<[T, boolean]> {
+    // const storedVersion = await DatabaseVersion.readVersion(this.versionFile);
+    let storedVersion: DatabaseVersion;
+
+    try {
+      const versionBuf = await this.fileSystem.readFile(this.versionFile);
+      storedVersion = DatabaseVersion.fromBuffer(versionBuf);
+    } catch (err) {
+      if (err && (err as Error & { code: string }).code === 'ENOENT') {
+        storedVersion = DatabaseVersion.empty();
+      } else {
+        this.log.warn(`Failed to read stored version information: ${err}. Defaulting to empty version`);
+        storedVersion = DatabaseVersion.empty();
+      }
+    }
+
+    const cmp = storedVersion.cmp(this.currentVersion);
+    let needsReset = false;
+
+    if (typeof cmp === 'number') {
+      // only allow forward upgrades
+      if (cmp === -1 && this.onUpgrade) {
+        this.log.info(`Upgrading from version ${storedVersion.schemaVersion} to ${this.currentVersion.schemaVersion}`);
+        try {
+          await this.onUpgrade(this.dataDirectory, storedVersion.schemaVersion, this.currentVersion.schemaVersion);
+        } catch (error) {
+          this.log.error(`Failed to upgrade: ${error}. Falling back to reset.`);
+          needsReset = true;
+        }
+      } else if (cmp !== 0) {
+        this.log.info(
+          `Can't upgrade from version ${storedVersion.schemaVersion} to ${this.currentVersion}. Resetting database at ${this.dataDirectory}`,
+        );
+        needsReset = true;
+      }
+    } else {
+      this.log.warn('Rollup address changed, resetting data directory');
+      needsReset = true;
+    }
+
+    // Handle reset if needed
+    if (needsReset) {
+      await this.resetDataDirectory();
+    }
+
+    // Write the current version to disk
+    await this.writeVersion();
+
+    return [await this.onOpen(this.dataDirectory), needsReset];
+  }
+
+  /**
+   * Writes the current version to the version file
+   */
+  private async writeVersion(): Promise<void> {
+    // Ensure the directory exists
+    await this.fileSystem.mkdir(this.dataDirectory, { recursive: true });
+    // Write the version file
+    await this.fileSystem.writeFile(this.versionFile, this.currentVersion.toBuffer());
+  }
+
+  /**
+   * Resets the data directory by deleting it and recreating it
+   */
+  private async resetDataDirectory(): Promise<void> {
+    try {
+      await this.fileSystem.rm(this.dataDirectory, { recursive: true, force: true, maxRetries: 3 });
+      await this.fileSystem.mkdir(this.dataDirectory, { recursive: true });
+    } catch (err) {
+      this.log.error(`Failed to reset data directory: ${err}`);
+      throw new Error(`Failed to reset data directory: ${err}`, { cause: err });
+    }
+  }
+
+  /**
+   * Get the data directory path
+   */
+  public getDataDirectory(): string {
+    return this.dataDirectory;
+  }
+
+  /**
+   * Get the current version number
+   */
+  public getSchemaVersion(): number {
+    return this.currentVersion.schemaVersion;
+  }
+}