@aztec/stdlib 0.0.0-test.1 → 0.0.1-commit.b655e406

package/src/contract/interfaces/contract_class.ts

@@ -15,13 +15,14 @@ const VERSION = 1 as const;
 export interface ContractClass {
   /** Version of the contract class. */
   version: typeof VERSION;
-  /** Hash of the contract artifact. The specification of this hash is not enforced by the protocol. Should include commitments to unconstrained code and compilation metadata. Intended to be used by clients to verify that an off-chain fetched artifact matches a registered class. */
+  /**
+   * Hash of the contract artifact. The specification of this hash is not enforced by the protocol. Should include
+   * commitments to code of utility functions and compilation metadata. Intended to be used by clients to verify that
+   * an offchain fetched artifact matches a registered class.
+   */
   artifactHash: Fr;
   /** List of individual private functions, constructors included. */
   privateFunctions: PrivateFunction[];
-  // TODO(https://github.com/AztecProtocol/aztec-packages/issues/8985): Remove public functions.
-  /** Contains the public_dispatch function (and only that) if there's any public code in the contract. */
-  publicFunctions: PublicFunction[];
   /** Bytecode for the public_dispatch function, or empty. */
   packedBytecode: Buffer;
 }
@@ -49,38 +50,25 @@ const ExecutablePrivateFunctionSchema = PrivateFunctionSchema.and(
   z.object({ bytecode: schemas.Buffer }),
 ) satisfies ZodFor<ExecutablePrivateFunction>;
 
-/** Public function definition within a contract class. */
-export interface PublicFunction {
-  /** Selector of the function. Calculated as the hash of the method name and parameters. The specification of this is not enforced by the protocol. */
-  selector: FunctionSelector;
-  /** Public bytecode. */
-  bytecode: Buffer;
-}
-
-export const PublicFunctionSchema = z.object({
-  selector: FunctionSelector.schema,
-  bytecode: schemas.Buffer,
-}) satisfies ZodFor<PublicFunction>;
-
-/** Unconstrained function definition. */
-export interface UnconstrainedFunction {
+/** Utility function definition. */
+export interface UtilityFunction {
   /** Selector of the function. Calculated as the hash of the method name and parameters. The specification of this is not enforced by the protocol. */
   selector: FunctionSelector;
   /** Brillig. */
   bytecode: Buffer;
 }
 
-const UnconstrainedFunctionSchema = z.object({
+const UtilityFunctionSchema = z.object({
   /** lala */
   selector: FunctionSelector.schema,
   bytecode: schemas.Buffer,
-}) satisfies ZodFor<UnconstrainedFunction>;
+}) satisfies ZodFor<UtilityFunction>;
 
 /** Sibling paths and sibling commitments for proving membership of a private function within a contract class. */
 export type PrivateFunctionMembershipProof = {
   artifactMetadataHash: Fr;
   functionMetadataHash: Fr;
-  unconstrainedFunctionsArtifactTreeRoot: Fr;
+  utilityFunctionsTreeRoot: Fr;
   privateFunctionTreeSiblingPath: Fr[];
   privateFunctionTreeLeafIndex: number;
   artifactTreeSiblingPath: Fr[];
@@ -90,18 +78,18 @@ export type PrivateFunctionMembershipProof = {
 const PrivateFunctionMembershipProofSchema = z.object({
   artifactMetadataHash: schemas.Fr,
   functionMetadataHash: schemas.Fr,
-  unconstrainedFunctionsArtifactTreeRoot: schemas.Fr,
+  utilityFunctionsTreeRoot: schemas.Fr,
   privateFunctionTreeSiblingPath: z.array(schemas.Fr),
   privateFunctionTreeLeafIndex: schemas.Integer,
   artifactTreeSiblingPath: z.array(schemas.Fr),
   artifactTreeLeafIndex: schemas.Integer,
 }) satisfies ZodFor<PrivateFunctionMembershipProof>;
 
-/** A private function with a memebership proof. */
+/** A private function with a membership proof. */
 export type ExecutablePrivateFunctionWithMembershipProof = ExecutablePrivateFunction & PrivateFunctionMembershipProof;
 
-/** Sibling paths and commitments for proving membership of an unconstrained function within a contract class. */
-export type UnconstrainedFunctionMembershipProof = {
+/** Sibling paths and commitments for proving membership of a utility  function within a contract class. */
+export type UtilityFunctionMembershipProof = {
   artifactMetadataHash: Fr;
   functionMetadataHash: Fr;
   privateFunctionsArtifactTreeRoot: Fr;
@@ -109,22 +97,21 @@ export type UnconstrainedFunctionMembershipProof = {
   artifactTreeLeafIndex: number;
 };
 
-const UnconstrainedFunctionMembershipProofSchema = z.object({
+const UtilityFunctionMembershipProofSchema = z.object({
   artifactMetadataHash: schemas.Fr,
   functionMetadataHash: schemas.Fr,
   privateFunctionsArtifactTreeRoot: schemas.Fr,
   artifactTreeSiblingPath: z.array(schemas.Fr),
   artifactTreeLeafIndex: schemas.Integer,
-}) satisfies ZodFor<UnconstrainedFunctionMembershipProof>;
+}) satisfies ZodFor<UtilityFunctionMembershipProof>;
 
-/** An unconstrained function with a membership proof. */
-export type UnconstrainedFunctionWithMembershipProof = UnconstrainedFunction & UnconstrainedFunctionMembershipProof;
+/** A utility function with a membership proof. */
+export type UtilityFunctionWithMembershipProof = UtilityFunction & UtilityFunctionMembershipProof;
 
 export const ContractClassSchema = z.object({
   version: z.literal(VERSION),
   artifactHash: schemas.Fr,
   privateFunctions: z.array(PrivateFunctionSchema),
-  publicFunctions: z.array(PublicFunctionSchema),
   packedBytecode: schemas.Buffer,
 }) satisfies ZodFor<ContractClass>;
 
@@ -145,13 +132,14 @@ export const ContractClassWithIdSchema = ContractClassSchema.extend({
   id: schemas.Fr,
 }) satisfies ZodFor<ContractClassWithId>;
 
-/** A contract class with public bytecode information, and optional private and unconstrained. */
+/** A contract class with public bytecode information, and optional private and utility functions. */
 export type ContractClassPublic = {
   privateFunctions: ExecutablePrivateFunctionWithMembershipProof[];
-  unconstrainedFunctions: UnconstrainedFunctionWithMembershipProof[];
+  utilityFunctions: UtilityFunctionWithMembershipProof[];
 } & Pick<ContractClassCommitments, 'id' | 'privateFunctionsRoot'> &
   Omit<ContractClass, 'privateFunctions'>;
-export type ContractClassWithCommitment = ContractClassPublic &
+
+export type ContractClassPublicWithCommitment = ContractClassPublic &
   Pick<ContractClassCommitments, 'publicBytecodeCommitment'>;
 
 export const ContractClassPublicSchema = z
@@ -159,7 +147,7 @@ export const ContractClassPublicSchema = z
     id: schemas.Fr,
     privateFunctionsRoot: schemas.Fr,
     privateFunctions: z.array(ExecutablePrivateFunctionSchema.and(PrivateFunctionMembershipProofSchema)),
-    unconstrainedFunctions: z.array(UnconstrainedFunctionSchema.and(UnconstrainedFunctionMembershipProofSchema)),
+    utilityFunctions: z.array(UtilityFunctionSchema.and(UtilityFunctionMembershipProofSchema)),
   })
   .and(ContractClassSchema.omit({ privateFunctions: true })) satisfies ZodFor<ContractClassPublic>;
 

package/src/contract/interfaces/contract_data_source.ts

@@ -1,19 +1,12 @@
 import type { Fr } from '@aztec/foundation/fields';
 
-import { FunctionSelector } from '../../abi/index.js';
+import type { FunctionSelector } from '../../abi/index.js';
 import type { AztecAddress } from '../../aztec-address/index.js';
-import type { ContractClassPublic, PublicFunction } from './contract_class.js';
+import type { UInt64 } from '../../types/shared.js';
+import type { ContractClassPublic } from './contract_class.js';
 import type { ContractInstanceWithAddress } from './contract_instance.js';
 
 export interface ContractDataSource {
-  /**
-   * Returns a contract's encoded public function, given its function selector.
-   * @param address - The contract aztec address.
-   * @param selector - The function's selector.
-   * @returns The function's data.
-   */
-  getPublicFunction(address: AztecAddress, selector: FunctionSelector): Promise<PublicFunction | undefined>;
-
   /**
    * Gets the number of the latest L2 block processed by the implementation.
    * @returns The number of the latest L2 block processed by the implementation.
@@ -28,25 +21,23 @@ export interface ContractDataSource {
 
   getBytecodeCommitment(id: Fr): Promise<Fr | undefined>;
 
-  /**
-   * Adds a contract class to the database.
-   * TODO(#10007): Remove this method
-   */
-  addContractClass(contractClass: ContractClassPublic): Promise<void>;
-
   /**
    * Returns a publicly deployed contract instance given its address.
    * @param address - Address of the deployed contract.
+   * @param timestamp - Timestamp at which to retrieve the contract instance. If not provided, the latest block should
+   * be used.
+   * TODO(#15170): Fix the implementations ignoring the timestamp param and make timestamp required.
    */
-  getContract(address: AztecAddress): Promise<ContractInstanceWithAddress | undefined>;
+  getContract(address: AztecAddress, timestamp?: UInt64): Promise<ContractInstanceWithAddress | undefined>;
 
   /**
    * Returns the list of all class ids known.
    */
   getContractClassIds(): Promise<Fr[]>;
 
-  /** Returns a function's name */
-  getContractFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string | undefined>;
+  /** Returns a function's name. It's only available if provided by calling `registerContractFunctionSignatures`. */
+  getDebugFunctionName(address: AztecAddress, selector: FunctionSelector): Promise<string | undefined>;
+
   /** Registers a function names. Useful for debugging. */
-  registerContractFunctionSignatures(address: AztecAddress, signatures: string[]): Promise<void>;
+  registerContractFunctionSignatures(signatures: string[]): Promise<void>;
 }

package/src/contract/interfaces/contract_instance_update.ts

@@ -4,6 +4,7 @@ import { z } from 'zod';
 
 import type { AztecAddress } from '../../aztec-address/index.js';
 import { type ZodFor, schemas } from '../../schemas/index.js';
+import type { UInt64 } from '../../types/shared.js';
 
 /**
  * An update to a contract instance, changing its contract class.
@@ -13,8 +14,8 @@ export interface ContractInstanceUpdate {
   prevContractClassId: Fr;
   /** Identifier of the new contract class for this instance. */
   newContractClassId: Fr;
-  /** The block number where the contract class in use will be the new one */
-  blockOfChange: number;
+  /** The timestamp at which the contract class in use will be the new one */
+  timestampOfChange: UInt64;
 }
 
 export type ContractInstanceUpdateWithAddress = ContractInstanceUpdate & { address: AztecAddress };
@@ -22,7 +23,7 @@ export type ContractInstanceUpdateWithAddress = ContractInstanceUpdate & { addre
 export const ContractInstanceUpdateSchema = z.object({
   prevContractClassId: schemas.Fr,
   newContractClassId: schemas.Fr,
-  blockOfChange: z.number().int().nonnegative(),
+  timestampOfChange: schemas.BigInt,
 }) satisfies ZodFor<ContractInstanceUpdate>;
 
 export const ContractInstanceUpdateWithAddressSchema = ContractInstanceUpdateSchema.and(

package/src/contract/interfaces/node-info.ts

@@ -11,8 +11,8 @@ export interface NodeInfo {
   nodeVersion: string;
   /** L1 chain id. */
   l1ChainId: number;
-  /** Protocol version. */
-  protocolVersion: number;
+  /** Rollup version. */
+  rollupVersion: number;
   /** The node's ENR. */
   enr: string | undefined;
   /** The deployed l1 contract addresses */
@@ -25,7 +25,7 @@ export const NodeInfoSchema: ZodFor<NodeInfo> = z
   .object({
     nodeVersion: z.string(),
     l1ChainId: z.number().int().nonnegative(),
-    protocolVersion: z.number().int().nonnegative(),
+    rollupVersion: z.number().int().nonnegative(),
     enr: z.string().optional(),
     l1ContractAddresses: L1ContractAddressesSchema,
     protocolContractAddresses: ProtocolContractAddressesSchema,

package/src/contract/interfaces/protocol_contract_addresses.ts

@@ -3,23 +3,18 @@ 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 const ProtocolContractsNames = ['classRegistry', 'feeJuice', 'instanceRegistry', 'multiCallEntrypoint'] as const;
 
 export type ProtocolContractAddresses = {
-  classRegisterer: AztecAddress;
+  classRegistry: AztecAddress;
   feeJuice: AztecAddress;
-  instanceDeployer: AztecAddress;
+  instanceRegistry: AztecAddress;
   multiCallEntrypoint: AztecAddress;
 };
 
 export const ProtocolContractAddressesSchema = z.object({
-  classRegisterer: schemas.AztecAddress,
+  classRegistry: schemas.AztecAddress,
   feeJuice: schemas.AztecAddress,
-  instanceDeployer: schemas.AztecAddress,
+  instanceRegistry: schemas.AztecAddress,
   multiCallEntrypoint: schemas.AztecAddress,
 });

package/src/contract/private_function.ts

@@ -36,11 +36,13 @@ export async function computePrivateFunctionLeaf(fn: PrivateFunction): Promise<B
 
 async function getPrivateFunctionTreeCalculator(): Promise<MerkleTreeCalculator> {
   if (!privateFunctionTreeCalculator) {
-    const functionTreeZeroLeaf = (await pedersenHash(new Array(PRIVATE_FUNCTION_SIZE).fill(0))).toBuffer();
+    const functionTreeZeroLeaf = (
+      await pedersenHash(new Array(PRIVATE_FUNCTION_SIZE).fill(0))
+    ).toBuffer() as Buffer<ArrayBuffer>;
     privateFunctionTreeCalculator = await MerkleTreeCalculator.create(
       FUNCTION_TREE_HEIGHT,
       functionTreeZeroLeaf,
-      async (left, right) => (await poseidon2Hash([left, right])).toBuffer(),
+      async (left, right) => (await poseidon2Hash([left, right])).toBuffer() as Buffer<ArrayBuffer>,
     );
   }
   return privateFunctionTreeCalculator;

package/src/contract/private_function_membership_proof.ts

@@ -51,7 +51,7 @@ export async function createPrivateFunctionMembershipProof(
   }
 
   // Compute preimage for the artifact hash
-  const { unconstrainedFunctionRoot: unconstrainedFunctionsArtifactTreeRoot, metadataHash: artifactMetadataHash } =
+  const { utilityFunctionRoot: utilityFunctionsTreeRoot, metadataHash: artifactMetadataHash } =
     await computeArtifactHashPreimage(artifact);
 
   // We need two sibling paths because private function information is split across two trees:
@@ -74,7 +74,7 @@ export async function createPrivateFunctionMembershipProof(
     functionLeaf: '0x' + functionLeaf.toString('hex'),
     artifactMetadataHash,
     privateFunctionsTreeRoot: '0x' + functionsTree.root.toString('hex'),
-    unconstrainedFunctionsArtifactTreeRoot,
+    utilityFunctionsTreeRoot,
     artifactFunctionTreeSiblingPath: artifactTreeSiblingPath.map(fr => fr.toString()).join(','),
     privateFunctionTreeSiblingPath: functionsTreeSiblingPath.map(fr => fr.toString()).join(','),
   });
@@ -84,14 +84,14 @@ export async function createPrivateFunctionMembershipProof(
     artifactTreeLeafIndex,
     artifactMetadataHash,
     functionMetadataHash,
-    unconstrainedFunctionsArtifactTreeRoot,
+    utilityFunctionsTreeRoot,
     privateFunctionTreeSiblingPath: functionsTreeSiblingPath,
     privateFunctionTreeLeafIndex: functionsTreeLeafIndex,
   };
 }
 
 /**
- * Verifies that a private function with a membership proof as emitted by the ClassRegisterer contract is valid,
+ * Verifies that a private function with a membership proof as emitted by the ClassRegistry contract is valid,
  * as defined in the protocol specs at contract-deployment/classes:
  *
  * ```
@@ -106,7 +106,7 @@ export async function createPrivateFunctionMembershipProof(
  * // 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)
+ * computed_artifact_hash = sha256(computed_artifact_private_function_tree_root, utility_functions_artifact_tree_root, artifact_metadata_hash)
  * assert computed_artifact_hash == contract_class.artifact_hash
  * ```
  * @param fn - Function to check membership proof for.
@@ -147,7 +147,7 @@ export async function isValidPrivateFunctionMembershipProof(
   const computedArtifactPrivateFunctionTreeRoot = Fr.fromBuffer(computedArtifactPrivateFunctionTreeRootBuffer);
   const computedArtifactHash = await computeArtifactHash({
     privateFunctionRoot: computedArtifactPrivateFunctionTreeRoot,
-    unconstrainedFunctionRoot: fn.unconstrainedFunctionsArtifactTreeRoot,
+    utilityFunctionRoot: fn.utilityFunctionsTreeRoot,
     metadataHash: fn.artifactMetadataHash,
   });
   if (!contractClass.artifactHash.equals(computedArtifactHash)) {
@@ -156,7 +156,7 @@ export async function isValidPrivateFunctionMembershipProof(
       computedArtifactHash,
       computedFunctionArtifactHash: functionArtifactHash,
       computedArtifactPrivateFunctionTreeRoot,
-      unconstrainedFunctionRoot: fn.unconstrainedFunctionsArtifactTreeRoot,
+      utilityFunctionRoot: fn.utilityFunctionsTreeRoot,
       metadataHash: fn.artifactMetadataHash,
       artifactFunctionTreeSiblingPath: fn.artifactTreeSiblingPath.map(fr => fr.toString()).join(','),
     });

package/src/contract/{unconstrained_function_membership_proof.ts → utility_function_membership_proof.ts}

@@ -13,29 +13,29 @@ import {
 } from './artifact_hash.js';
 import type {
   ContractClassPublic,
-  UnconstrainedFunctionMembershipProof,
-  UnconstrainedFunctionWithMembershipProof,
+  UtilityFunctionMembershipProof,
+  UtilityFunctionWithMembershipProof,
 } from './interfaces/index.js';
 
 /**
- * Creates a membership proof for an unconstrained function in a contract class, to be verified via `isValidUnconstrainedFunctionMembershipProof`.
+ * Creates a membership proof for a utility  function in a contract class, to be verified via `isValidUtilityFunctionMembershipProof`.
  * @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(
+export async function createUtilityFunctionMembershipProof(
   selector: FunctionSelector,
   artifact: ContractArtifact,
-): Promise<UnconstrainedFunctionMembershipProof> {
+): Promise<UtilityFunctionMembershipProof> {
   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 utilityFunctions = artifact.functions.filter(fn => fn.functionType === FunctionType.UTILITY);
+  const utilityFunctionsAndSelectors = await Promise.all(
+    utilityFunctions.map(async fn => ({ fn, selector: await FunctionSelector.fromNameAndParameters(fn) })),
   );
-  const fn = unconstrainedFunctionsAndSelectors.find(fnAndSelector => selector.equals(fnAndSelector.selector))?.fn;
+  const fn = utilityFunctionsAndSelectors.find(fnAndSelector => selector.equals(fnAndSelector.selector))?.fn;
   if (!fn) {
-    throw new Error(`Unconstrained function with selector ${selector.toString()} not found`);
+    throw new Error(`Utility function with selector ${selector.toString()} not found`);
   }
   // Compute preimage for the artifact hash
   const { privateFunctionRoot: privateFunctionsArtifactTreeRoot, metadataHash: artifactMetadataHash } =
@@ -44,11 +44,11 @@ export async function createUnconstrainedFunctionMembershipProof(
   // 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 artifactTree = (await computeArtifactFunctionTree(artifact, FunctionType.UTILITY))!;
   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()}`, {
+  log.debug(`Computed proof for utility function with selector ${selector.toString()}`, {
     functionArtifactHash,
     functionMetadataHash,
     artifactMetadataHash,
@@ -66,7 +66,7 @@ export async function createUnconstrainedFunctionMembershipProof(
 }
 
 /**
- * Verifies that an unconstrained function with a membership proof as emitted by the ClassRegisterer contract is valid,
+ * Verifies that a utility  function with a membership proof as emitted by the ClassRegistry contract is valid,
  * as defined in the protocol specs at contract-deployment/classes:
  *
  * ```
@@ -75,15 +75,15 @@ export async function createUnconstrainedFunctionMembershipProof(
  *
  * // 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)
+ * computed_artifact_utility_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_utility_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,
+export async function isValidUtilityFunctionMembershipProof(
+  fn: UtilityFunctionWithMembershipProof,
   contractClass: Pick<ContractClassPublic, 'artifactHash'>,
 ) {
   const log = createLogger('circuits:function_membership_proof');
@@ -98,7 +98,7 @@ export async function isValidUnconstrainedFunctionMembershipProof(
   const computedArtifactFunctionTreeRoot = Fr.fromBuffer(computedArtifactFunctionTreeRootBuffer);
   const computedArtifactHash = await computeArtifactHash({
     privateFunctionRoot: fn.privateFunctionsArtifactTreeRoot,
-    unconstrainedFunctionRoot: computedArtifactFunctionTreeRoot,
+    utilityFunctionRoot: computedArtifactFunctionTreeRoot,
     metadataHash: fn.artifactMetadataHash,
   });
   if (!contractClass.artifactHash.equals(computedArtifactHash)) {

package/src/database-version/version_manager.ts

@@ -1,8 +1,9 @@
 import { EthAddress } from '@aztec/foundation/eth-address';
-import { jsonParseWithSchemaSync, jsonStringify } from '@aztec/foundation/json-rpc';
-import { createLogger } from '@aztec/foundation/log';
+import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
+import { type Logger, createLogger } from '@aztec/foundation/log';
 
 import fs from 'fs/promises';
+import { inspect } from 'node:util';
 import { join } from 'path';
 import { z } from 'zod';
 
@@ -10,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));
@@ -18,7 +24,7 @@ export class DatabaseVersion {
 
   public static fromBuffer(buf: Buffer): DatabaseVersion {
     try {
-      return jsonParseWithSchemaSync(buf.toString('utf-8'), DatabaseVersion.schema);
+      return jsonParseWithSchema(buf.toString('utf-8'), DatabaseVersion.schema);
     } catch (err) {
       throw new Error(`Failed to deserialize version information: ${err}`, { cause: err });
     }
@@ -59,6 +65,15 @@ export class DatabaseVersion {
       .transform(({ schemaVersion, rollupAddress }) => new DatabaseVersion(schemaVersion, rollupAddress));
   }
 
+  /** Allows for better introspection. */
+  public [inspect.custom](): string {
+    return this.toString();
+  }
+
+  public toString(): string {
+    return `DatabaseVersion{schemaVersion=${this.schemaVersion},rollupAddress=${this.rollupAddress}"}`;
+  }
+
   /**
    * Returns an empty instance
    */
@@ -69,17 +84,35 @@ export class DatabaseVersion {
 
 export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile' | 'rm' | 'mkdir'>;
 
+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
  * reset or upgrade based on version compatibility.
  */
 export class DatabaseVersionManager<T> {
-  public static readonly VERSION_FILE = 'db_version';
+  public static readonly VERSION_FILE = DATABASE_VERSION_FILE_NAME;
 
   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
    *
@@ -92,21 +125,32 @@ 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) {
+    await fileSystem.mkdir(dataDir, { recursive: true });
+    return fileSystem.writeFile(join(dataDir, DatabaseVersionManager.VERSION_FILE), version.toBuffer());
   }
 
   /**
@@ -120,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);
@@ -127,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();
@@ -147,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}. 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');
+      if (shouldLogDataReset) {
+        this.log.warn('Rollup address has changed, resetting data directory', {
+          versionFile: this.versionFile,
+          storedVersion,
+          currentVersion: this.currentVersion,
+        });
+      }
       needsReset = true;
     }
 
@@ -171,17 +227,14 @@ export class DatabaseVersionManager<T> {
   /**
    * 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());
+  public writeVersion(dir?: string): Promise<void> {
+    return DatabaseVersionManager.writeVersion(this.currentVersion, dir ?? this.dataDirectory, this.fileSystem);
   }
 
   /**
    * Resets the data directory by deleting it and recreating it
    */
-  private async resetDataDirectory(): Promise<void> {
+  public 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 });