@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/contract/private_function.ts

@@ -0,0 +1,51 @@
+import { DomainSeparator, FUNCTION_TREE_HEIGHT } from '@aztec-labs/constants';
+import { poseidon2Hash, poseidon2HashWithSeparator } from '@aztec-labs/foundation/crypto/poseidon';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { type MerkleTree, MerkleTreeCalculator } from '@aztec-labs/foundation/trees';
+
+import { computeMerkleHash } from '../hash/hash.js';
+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], DomainSeparator.PRIVATE_FUNCTION_LEAF)).toBuffer();
+}
+
+async function getPrivateFunctionTreeCalculator(): Promise<MerkleTreeCalculator> {
+  if (!privateFunctionTreeCalculator) {
+    const functionTreeZeroLeaf = (
+      await poseidon2Hash(new Array(PRIVATE_FUNCTION_SIZE).fill(0))
+    ).toBuffer() as Buffer<ArrayBuffer>;
+    privateFunctionTreeCalculator = await MerkleTreeCalculator.create(
+      FUNCTION_TREE_HEIGHT,
+      functionTreeZeroLeaf,
+      async (left, right) =>
+        (await computeMerkleHash(Fr.fromBuffer(left), Fr.fromBuffer(right))).toBuffer() as Buffer<ArrayBuffer>,
+    );
+  }
+  return privateFunctionTreeCalculator;
+}

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-labs/foundation';
+import { EthAddress } from '@aztec-labs/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/database_version.ts

@@ -0,0 +1,86 @@
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { jsonParseWithSchema, jsonStringify } from '@aztec-labs/foundation/json-rpc';
+import { z } from 'zod';
+
+/**
+ * Symbol for Node.js custom inspect. Using Symbol.for() is the documented way to
+ * reference this without importing node:util. In browsers, objects with this symbol
+ * simply won't have custom inspect behavior (which is fine).
+ * @see https://nodejs.org/api/util.html#utilinspectcustom
+ */
+const inspectCustomSymbol = Symbol.for('nodejs.util.inspect.custom');
+
+/**
+ * Represents a version record for storing in a version file.
+ */
+export class DatabaseVersion {
+  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));
+  }
+
+  public static fromBuffer(buf: Buffer): DatabaseVersion {
+    try {
+      return jsonParseWithSchema(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));
+  }
+
+  /** Allows for better introspection in Node.js console. Ignored in browser envs. */
+  public [inspectCustomSymbol](): string {
+    return this.toString();
+  }
+
+  public toString(): string {
+    return `DatabaseVersion{schemaVersion=${this.schemaVersion},rollupAddress=${this.rollupAddress}"}`;
+  }
+
+  /**
+   * Returns an empty instance
+   */
+  static empty() {
+    return new DatabaseVersion(0, EthAddress.ZERO);
+  }
+}

package/src/database-version/version_manager.ts

@@ -0,0 +1,290 @@
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { type Logger, createLogger } from '@aztec-labs/foundation/log';
+import fs from 'fs/promises';
+import { join } from 'path';
+
+import { DatabaseVersion } from './database_version.js';
+
+export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'rm' | 'mkdir' | 'rename' | 'open'>;
+
+export const DATABASE_VERSION_FILE_NAME = 'db_version';
+export type SchemaVersionMismatchPolicy = 'reset' | 'throw';
+
+/**
+ * How to react when the version file exists but cannot be read (permissions, IO error, truncation).
+ * `'reset'` (default) treats the store as unversioned and lets the reset path run — safe for stores
+ * where an empty state is legitimate. `'throw'` refuses to open, leaving data untouched — required
+ * for protection stores (e.g. signing protection) that must never be silently wiped by a transient
+ * filesystem error. A genuinely missing file (ENOENT) is a first boot and is never affected by this.
+ */
+export type VersionFileReadFailurePolicy = 'reset' | 'throw';
+
+export type DatabaseVersionManagerOptions<T> = {
+  schemaVersion: number;
+  rollupAddress: EthAddress;
+  dataDirectory: string;
+  onOpen: (dataDir: string) => Promise<T>;
+  onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
+  schemaVersionMismatchPolicy?: SchemaVersionMismatchPolicy;
+  versionFileReadFailurePolicy?: VersionFileReadFailurePolicy;
+  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 = 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 schemaVersionMismatchPolicy: SchemaVersionMismatchPolicy;
+  private versionFileReadFailurePolicy: VersionFileReadFailurePolicy;
+  private fileSystem: DatabaseVersionManagerFs;
+  private log: Logger;
+
+  /**
+   * 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. Must be idempotent: since the version marker is written only after a successful open, a crash after
+   *   onUpgrade but before the marker is written re-runs onUpgrade on the next start.
+   * @param schemaVersionMismatchPolicy - Whether schema mismatches should reset data or throw
+   * @param versionFileReadFailurePolicy - Whether an unreadable (non-missing) version file should reset data or throw
+   * @param fileSystem - An interface to access the filesystem
+   * @param log - Optional custom logger
+   * @param options - Configuration options
+   */
+  constructor({
+    schemaVersion,
+    rollupAddress,
+    dataDirectory,
+    onOpen,
+    onUpgrade,
+    schemaVersionMismatchPolicy = 'reset',
+    versionFileReadFailurePolicy = 'reset',
+    fileSystem = fs,
+    log = createLogger(`foundation:version-manager`),
+  }: DatabaseVersionManagerOptions<T>) {
+    if (schemaVersion < 1) {
+      throw new TypeError(`Invalid schema version received: ${schemaVersion}`);
+    }
+
+    this.versionFile = join(dataDirectory, DatabaseVersionManager.VERSION_FILE);
+    this.currentVersion = new DatabaseVersion(schemaVersion, rollupAddress);
+
+    this.dataDirectory = dataDirectory;
+    this.onOpen = onOpen;
+    this.onUpgrade = onUpgrade;
+    this.schemaVersionMismatchPolicy = schemaVersionMismatchPolicy;
+    this.versionFileReadFailurePolicy = versionFileReadFailurePolicy;
+    this.fileSystem = fileSystem;
+    this.log = log;
+  }
+
+  static async writeVersion(version: DatabaseVersion, dataDir: string, fileSystem: DatabaseVersionManagerFs = fs) {
+    await fileSystem.mkdir(dataDir, { recursive: true });
+    const finalPath = join(dataDir, DatabaseVersionManager.VERSION_FILE);
+    const tmpPath = `${finalPath}.tmp`;
+
+    // Atomic durable write: fill a temp file, fsync it, then rename it into place. The marker only
+    // becomes visible under its final name once its bytes are durably on disk, so a crash mid-write
+    // can never leave a "valid" version file sitting over an empty or partially-populated data dir.
+    const handle = await fileSystem.open(tmpPath, 'w');
+    try {
+      await handle.writeFile(version.toBuffer());
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await fileSystem.rename(tmpPath, finalPath);
+
+    // Best-effort fsync of the containing directory so the rename itself survives a crash. Not all
+    // filesystems support directory fsync, so a failure here is non-fatal.
+    try {
+      const dirHandle = await fileSystem.open(dataDir, 'r');
+      try {
+        await dirHandle.sync();
+      } finally {
+        await dirHandle.close();
+      }
+    } catch {
+      // directory fsync is best-effort
+    }
+  }
+
+  /**
+   * 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;
+    // 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);
+      storedVersion = DatabaseVersion.fromBuffer(versionBuf);
+    } 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 if (this.versionFileReadFailurePolicy === 'throw') {
+        // The version file exists but could not be read/parsed (permissions, IO error, truncation).
+        // Treating this as "unversioned" would reset the data directory, silently wiping a store that
+        // must fail closed. Refuse to open instead, leaving the data untouched for the operator.
+        const code = (err as Error & { code?: string })?.code;
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(
+          `Failed to read database version file at ${this.versionFile} (${code ?? 'unknown error'}: ${message}). ` +
+            `Refusing to open the database; data was NOT reset. Resolve the underlying filesystem error and retry.`,
+          { cause: err },
+        );
+      } 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) {
+          if (this.schemaVersionMismatchPolicy === 'throw') {
+            throw new Error(
+              `Failed to upgrade database at ${this.dataDirectory} from schema version ${storedVersion.schemaVersion} to ${this.currentVersion.schemaVersion}`,
+              { cause: error },
+            );
+          }
+          this.log.error(`Failed to upgrade: ${error}. Falling back to reset.`);
+          needsReset = true;
+        }
+      } else if (cmp !== 0) {
+        if (this.schemaVersionMismatchPolicy === 'throw') {
+          throw new Error(
+            `Cannot open database at ${this.dataDirectory}: stored schema version ${storedVersion.schemaVersion} is incompatible with expected schema version ${this.currentVersion.schemaVersion}`,
+          );
+        }
+        if (shouldLogDataReset) {
+          this.log.info(
+            `Can't upgrade from version ${storedVersion} to ${this.currentVersion}. Resetting database at ${this.dataDirectory}`,
+          );
+        }
+        needsReset = true;
+      }
+    } else {
+      if (shouldLogDataReset) {
+        this.log.warn('Rollup address has changed, resetting data directory', {
+          versionFile: this.versionFile,
+          storedVersion,
+          currentVersion: this.currentVersion,
+        });
+      }
+      needsReset = true;
+    }
+
+    // Handle reset if needed
+    if (needsReset) {
+      await this.resetDataDirectory();
+    }
+
+    // Open the database first, then record the version marker. Writing the marker only after a
+    // successful open makes it a post-commit record: if the process crashes between the reset and a
+    // durable open, no marker is left behind, so the next startup re-runs the reset instead of
+    // trusting a marker that sits over empty or partially-initialized data.
+    const instance = await this.onOpen(this.dataDirectory);
+
+    // Only (re)write the marker when it would actually change — first boot, reset, or upgrade. On a
+    // normal boot it already matches, so skipping avoids an unnecessary fsync (and the directory
+    // write permission the temp-file+rename needs) and, more importantly, any window where a
+    // marker-write failure would orphan the database we just opened.
+    if (!storedVersion.equals(this.currentVersion)) {
+      try {
+        await this.writeVersion();
+      } catch (err) {
+        // The database opened but recording the marker failed; close the freshly opened instance so
+        // we do not leak its file handles / locks before propagating the failure.
+        await this.closeQuietly(instance);
+        throw err;
+      }
+    }
+
+    return [instance, needsReset];
+  }
+
+  /**
+   * Best-effort close of a just-opened database instance, used to avoid leaking handles/locks when a
+   * post-open step fails. Swallows close errors so the original failure is the one that propagates.
+   */
+  private async closeQuietly(instance: T): Promise<void> {
+    const closable = instance as
+      | { close?: () => Promise<void> | void; [Symbol.asyncDispose]?: () => Promise<void> }
+      | undefined;
+    const dispose = closable?.close ?? closable?.[Symbol.asyncDispose];
+    if (typeof dispose !== 'function') {
+      return;
+    }
+    try {
+      await dispose.call(closable);
+    } catch (err) {
+      this.log.warn(`Failed to close database after version-write failure: ${err}`);
+    }
+  }
+
+  /**
+   * Writes the current version to the version file
+   */
+  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
+   */
+  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 });
+    } 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;
+  }
+}

package/src/delayed_public_mutable/delayed_public_mutable_values.ts

@@ -0,0 +1,94 @@
+import { UPDATES_VALUE_SIZE } from '@aztec-labs/constants';
+import { poseidon2Hash } from '@aztec-labs/foundation/crypto/poseidon';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader, FieldReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+
+import { ScheduledDelayChange } from './scheduled_delay_change.js';
+import { ScheduledValueChange } from './scheduled_value_change.js';
+
+export const DELAYED_PUBLIC_MUTABLE_VALUES_LEN = 2 * UPDATES_VALUE_SIZE + 1;
+
+export class DelayedPublicMutableValues {
+  constructor(
+    public svc: ScheduledValueChange,
+    public sdc: ScheduledDelayChange,
+  ) {}
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+
+    const firstField = reader.readField().toBigInt();
+
+    // Extract fields for ScheduledValueChange
+    const svcPre = reader.readFieldArray(UPDATES_VALUE_SIZE);
+    const svcPost = reader.readFieldArray(UPDATES_VALUE_SIZE);
+    const svcTimestampOfChange = firstField & 0xffffffffn;
+    const svc = new ScheduledValueChange(svcPre, svcPost, svcTimestampOfChange);
+
+    // Extract fields for ScheduledDelayChange from first field
+    const sdcTimestampOfChange = (firstField >> 32n) & 0xffffffffn;
+    const sdcIsPostSome = (firstField >> 64n) & 1n;
+    const sdcPost = (firstField >> 72n) & 0xffffffffn;
+    const sdcIsPreSome = (firstField >> 104n) & 1n;
+    const sdcPre = (firstField >> 112n) & 0xffffffffn;
+
+    const sdc = new ScheduledDelayChange(
+      sdcIsPreSome ? sdcPre : undefined,
+      sdcIsPostSome ? sdcPost : undefined,
+      sdcTimestampOfChange,
+    );
+
+    return new this(svc, sdc);
+  }
+
+  toFields(): Fr[] {
+    // Pack format matches Noir implementation:
+    // [ sdc.pre_inner: u32 | sdc.pre_is_some: u8 | sdc.post_inner: u32 | sdc.post_is_some: u8 | sdc.timestamp_of_change: u32 | svc.timestamp_of_change: u32 ]
+    let firstField = this.svc.timestampOfChange;
+    firstField |= this.sdc.timestampOfChange << 32n;
+    firstField |= (this.sdc.post === undefined ? 0n : 1n) << 64n;
+    firstField |= BigInt(this.sdc.post || 0) << 72n;
+    firstField |= (this.sdc.pre === undefined ? 0n : 1n) << 104n;
+    firstField |= BigInt(this.sdc.pre || 0) << 112n;
+
+    return [new Fr(firstField), ...this.svc.previous, ...this.svc.post];
+  }
+
+  toBuffer(): Buffer {
+    return serializeToBuffer(this.toFields());
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader, valueSize: number): DelayedPublicMutableValues {
+    const reader = BufferReader.asReader(buffer);
+    return DelayedPublicMutableValues.fromFields(reader.readArray(2 * valueSize + 1, Fr));
+  }
+
+  static empty(valueSize: number) {
+    return new this(ScheduledValueChange.empty(valueSize), ScheduledDelayChange.empty());
+  }
+
+  static async readFromTree(delayedPublicMutableSlot: Fr, readStorage: (storageSlot: Fr) => Promise<Fr>) {
+    const fieldPromises = Array.from({ length: DELAYED_PUBLIC_MUTABLE_VALUES_LEN }).map((_, i) =>
+      readStorage(delayedPublicMutableSlot.add(new Fr(i))),
+    );
+    return DelayedPublicMutableValues.fromFields(await Promise.all(fieldPromises));
+  }
+
+  isEmpty(): boolean {
+    return this.svc.isEmpty() && this.sdc.isEmpty();
+  }
+
+  writeToTree(delayedPublicMutableSlot: Fr, storageWrite: (storageSlot: Fr, value: Fr) => Promise<void>) {
+    const fieldPromises = this.toFields().map((field, i) =>
+      storageWrite(delayedPublicMutableSlot.add(new Fr(i)), field),
+    );
+
+    return Promise.all(fieldPromises);
+  }
+
+  async hash(): Promise<Fr> {
+    const fields = this.toFields();
+    const hash = await poseidon2Hash(fields);
+    return hash;
+  }
+}

package/src/delayed_public_mutable/delayed_public_mutable_values_with_hash.ts

@@ -0,0 +1,38 @@
+import { UPDATED_CLASS_IDS_SLOT } from '@aztec-labs/constants';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+import { deriveStorageSlotInMap } from '../hash/map_slot.js';
+import { DELAYED_PUBLIC_MUTABLE_VALUES_LEN, DelayedPublicMutableValues } from './delayed_public_mutable_values.js';
+import { ScheduledDelayChange } from './scheduled_delay_change.js';
+import { ScheduledValueChange } from './scheduled_value_change.js';
+
+export class DelayedPublicMutableValuesWithHash {
+  private dpmv: DelayedPublicMutableValues;
+
+  constructor(svc: ScheduledValueChange, sdc: ScheduledDelayChange) {
+    this.dpmv = new DelayedPublicMutableValues(svc, sdc);
+  }
+
+  async toFields(): Promise<Fr[]> {
+    return [...this.dpmv.toFields(), await this.dpmv.hash()];
+  }
+
+  async writeToTree(delayedPublicMutableSlot: Fr, storageWrite: (storageSlot: Fr, value: Fr) => Promise<void>) {
+    const fields = await this.toFields();
+
+    for (let i = 0; i < fields.length; i++) {
+      await storageWrite(delayedPublicMutableSlot.add(new Fr(i)), fields[i]);
+    }
+  }
+
+  static async getContractUpdateSlots(contractAddress: AztecAddress) {
+    const delayedPublicMutableSlot = await deriveStorageSlotInMap(new Fr(UPDATED_CLASS_IDS_SLOT), contractAddress);
+    const delayedPublicMutableHashSlot = delayedPublicMutableSlot.add(new Fr(DELAYED_PUBLIC_MUTABLE_VALUES_LEN));
+
+    return {
+      delayedPublicMutableSlot,
+      delayedPublicMutableHashSlot,
+    };
+  }
+}

package/src/delayed_public_mutable/index.ts

@@ -0,0 +1,4 @@
+export * from './scheduled_delay_change.js';
+export * from './scheduled_value_change.js';
+export * from './delayed_public_mutable_values.js';
+export * from './delayed_public_mutable_values_with_hash.js';

package/src/delayed_public_mutable/scheduled_delay_change.ts

@@ -0,0 +1,17 @@
+import type { UInt64 } from '../types/shared.js';
+
+export class ScheduledDelayChange {
+  constructor(
+    public pre: UInt64 | undefined,
+    public post: UInt64 | undefined,
+    public timestampOfChange: UInt64,
+  ) {}
+
+  static empty() {
+    return new this(undefined, undefined, 0n);
+  }
+
+  isEmpty(): boolean {
+    return this.pre === undefined && this.post === undefined && this.timestampOfChange === 0n;
+  }
+}

package/src/delayed_public_mutable/scheduled_value_change.ts

@@ -0,0 +1,31 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+
+import type { UInt64 } from '../types/shared.js';
+
+export class ScheduledValueChange {
+  constructor(
+    public previous: Fr[],
+    public post: Fr[],
+    public timestampOfChange: UInt64,
+  ) {
+    if (this.previous.length !== this.post.length) {
+      throw new Error('Previous and post must have the same length');
+    }
+  }
+
+  static empty(valueSize: number) {
+    return new this(Array(valueSize).fill(new Fr(0)), Array(valueSize).fill(new Fr(0)), 0n);
+  }
+
+  isEmpty(): boolean {
+    return this.previous.every(v => v.isZero()) && this.post.every(v => v.isZero()) && this.timestampOfChange === 0n;
+  }
+
+  getCurrentAt(timestamp: UInt64) {
+    if (timestamp < this.timestampOfChange) {
+      return this.previous;
+    } else {
+      return this.post;
+    }
+  }
+}