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

package/src/database-version/version_manager.ts

@@ -1,73 +1,26 @@
 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 { 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;
-  }
+import { DatabaseVersion } from './database_version.js';
 
-  /**
-   * 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));
-  }
+export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile' | 'rm' | 'mkdir'>;
 
-  /**
-   * Returns an empty instance
-   */
-  static empty() {
-    return new DatabaseVersion(0, EthAddress.ZERO);
-  }
-}
+export const DATABASE_VERSION_FILE_NAME = 'db_version';
+export type SchemaVersionMismatchPolicy = 'reset' | 'throw';
 
-export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile' | 'rm' | 'mkdir'>;
+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;
+  fileSystem?: DatabaseVersionManagerFs;
+  log?: Logger;
+};
 
 /**
  * A manager for handling database versioning and migrations.
@@ -75,11 +28,18 @@ export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile'
  * 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 schemaVersionMismatchPolicy: SchemaVersionMismatchPolicy;
+  private fileSystem: DatabaseVersionManagerFs;
+  private log: Logger;
+
   /**
    * Create a new version manager
    *
@@ -88,25 +48,39 @@ export class DatabaseVersionManager<T> {
    * @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 schemaVersionMismatchPolicy - Whether schema mismatches should reset data or throw
    * @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`),
-  ) {
+  constructor({
+    schemaVersion,
+    rollupAddress,
+    dataDirectory,
+    onOpen,
+    onUpgrade,
+    schemaVersionMismatchPolicy = 'reset',
+    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.schemaVersionMismatchPolicy = schemaVersionMismatchPolicy;
+    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 +94,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 +103,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();
@@ -143,17 +121,36 @@ export class DatabaseVersionManager<T> {
         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) {
-        this.log.info(
-          `Can't upgrade from version ${storedVersion.schemaVersion} to ${this.currentVersion}. Resetting database at ${this.dataDirectory}`,
-        );
+        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 {
-      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 +168,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 });

package/src/delayed_public_mutable/delayed_public_mutable_values.ts

@@ -0,0 +1,94 @@
+import { UPDATES_VALUE_SIZE } from '@aztec/constants';
+import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/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/constants';
+import { Fr } from '@aztec/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/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;
+    }
+  }
+}

package/src/deserialization/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Constants for deserialization bounds checking.
+ * These constants define maximum allowed sizes during deserialization
+ * to prevent DoS attacks via maliciously crafted messages.
+ */
+import { BLOBS_PER_CHECKPOINT, FIELDS_PER_BLOB } from '@aztec/constants';
+
+/** Max transactions per block for deserialization validation */
+export const MAX_TXS_PER_BLOCK = 2 ** 16;
+
+/** Max committee size - theoretical max from bitmap design (256 bytes × 8 bits) */
+export const MAX_COMMITTEE_SIZE = 2048;
+
+/** Max blocks per checkpoint */
+export const MAX_BLOCKS_PER_CHECKPOINT = 72;
+
+/** Max tx effects per body (based on blob capacity per checkpoint) */
+export const MAX_TX_EFFECTS_PER_BODY = BLOBS_PER_CHECKPOINT * FIELDS_PER_BLOB;
+
+/** Max block hash string length (hex: 0x + 64 chars, with generous headroom) */
+export const MAX_BLOCK_HASH_STRING_LENGTH = 128;

package/src/epoch-helpers/index.ts

@@ -1,6 +1,8 @@
+import { EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
+
 import { z } from 'zod';
 
-import { type ZodFor, schemas } from '../schemas/index.js';
+import { schemas, zodFor } from '../schemas/index.js';
 
 export type L1RollupConstants = {
   l1StartBlock: bigint;
@@ -8,6 +10,9 @@ export type L1RollupConstants = {
   slotDuration: number;
   epochDuration: number;
   ethereumSlotDuration: number;
+  proofSubmissionEpochs: number;
+  targetCommitteeSize: number;
+  rollupManaLimit: number;
 };
 
 export const EmptyL1RollupConstants: L1RollupConstants = {
@@ -16,38 +21,90 @@ export const EmptyL1RollupConstants: L1RollupConstants = {
   epochDuration: 1, // Not 0 to pervent division by zero
   slotDuration: 1,
   ethereumSlotDuration: 1,
+  proofSubmissionEpochs: 1,
+  targetCommitteeSize: 48,
+  rollupManaLimit: Number.MAX_SAFE_INTEGER,
 };
 
-export const L1RollupConstantsSchema = z.object({
-  l1StartBlock: schemas.BigInt,
-  l1GenesisTime: schemas.BigInt,
-  slotDuration: z.number(),
-  epochDuration: z.number(),
-  ethereumSlotDuration: z.number(),
-}) satisfies ZodFor<L1RollupConstants>;
+export const L1RollupConstantsSchema = zodFor<L1RollupConstants>()(
+  z.object({
+    l1StartBlock: schemas.BigInt,
+    l1GenesisTime: schemas.BigInt,
+    slotDuration: z.number(),
+    epochDuration: z.number(),
+    ethereumSlotDuration: z.number(),
+    proofSubmissionEpochs: z.number(),
+    targetCommitteeSize: z.number(),
+    rollupManaLimit: z.number(),
+  }),
+);
+
+/** Returns the timestamp for a given L2 slot. */
+export function getTimestampForSlot(
+  slot: SlotNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'>,
+) {
+  return constants.l1GenesisTime + BigInt(slot) * BigInt(constants.slotDuration);
+}
 
 /** Returns the slot number for a given timestamp. */
-export function getSlotAtTimestamp(ts: bigint, constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'>) {
-  return ts < constants.l1GenesisTime ? 0n : (ts - constants.l1GenesisTime) / BigInt(constants.slotDuration);
+export function getSlotAtTimestamp(
+  ts: bigint,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'>,
+): SlotNumber {
+  return ts < constants.l1GenesisTime
+    ? SlotNumber.ZERO
+    : SlotNumber.fromBigInt((ts - constants.l1GenesisTime) / BigInt(constants.slotDuration));
+}
+
+/** Returns the timestamp of the next L1 slot boundary after the given wall-clock time. */
+export function getNextL1SlotTimestamp(
+  nowInSeconds: number,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'ethereumSlotDuration'>,
+): bigint {
+  const now = BigInt(nowInSeconds);
+  const elapsed = now - constants.l1GenesisTime;
+  const currentL1Slot = elapsed / BigInt(constants.ethereumSlotDuration);
+  return constants.l1GenesisTime + (currentL1Slot + 1n) * BigInt(constants.ethereumSlotDuration);
+}
+
+/** Returns the timestamp of the last L1 slot within a given L2 slot. */
+export function getLastL1SlotTimestampForL2Slot(
+  slot: SlotNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>,
+): bigint {
+  return getTimestampForSlot(slot, constants) + BigInt(constants.slotDuration - constants.ethereumSlotDuration);
+}
+
+/** Returns the L2 slot number at the next L1 block based on the current timestamp. */
+export function getSlotAtNextL1Block(
+  currentL1Timestamp: bigint,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>,
+): SlotNumber {
+  const nextL1BlockTimestamp = currentL1Timestamp + BigInt(constants.ethereumSlotDuration);
+  return getSlotAtTimestamp(nextL1BlockTimestamp, constants);
 }
 
 /** Returns the epoch number for a given timestamp. */
 export function getEpochNumberAtTimestamp(
   ts: bigint,
   constants: Pick<L1RollupConstants, 'epochDuration' | 'slotDuration' | 'l1GenesisTime'>,
-) {
+): EpochNumber {
   return getEpochAtSlot(getSlotAtTimestamp(ts, constants), constants);
 }
 
 /** Returns the epoch number for a given slot. */
-export function getEpochAtSlot(slot: bigint, constants: Pick<L1RollupConstants, 'epochDuration'>) {
-  return slot / BigInt(constants.epochDuration);
+export function getEpochAtSlot(slot: SlotNumber, constants: Pick<L1RollupConstants, 'epochDuration'>): EpochNumber {
+  return EpochNumber.fromBigInt(BigInt(slot) / BigInt(constants.epochDuration));
 }
 
 /** Returns the range of L2 slots (inclusive) for a given epoch number. */
-export function getSlotRangeForEpoch(epochNumber: bigint, constants: Pick<L1RollupConstants, 'epochDuration'>) {
-  const startSlot = epochNumber * BigInt(constants.epochDuration);
-  return [startSlot, startSlot + BigInt(constants.epochDuration) - 1n];
+export function getSlotRangeForEpoch(
+  epochNumber: EpochNumber,
+  constants: Pick<L1RollupConstants, 'epochDuration'>,
+): [SlotNumber, SlotNumber] {
+  const startSlot = SlotNumber(Number(epochNumber) * constants.epochDuration);
+  return [startSlot, SlotNumber(startSlot + constants.epochDuration - 1)];
 }
 
 /**
@@ -55,15 +112,65 @@ export function getSlotRangeForEpoch(epochNumber: bigint, constants: Pick<L1Roll
  * Note that the endTimestamp is the start timestamp of the last L1 slot for the epoch.
  */
 export function getTimestampRangeForEpoch(
-  epochNumber: bigint,
+  epochNumber: EpochNumber,
   constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'epochDuration' | 'ethereumSlotDuration'>,
-) {
+): [bigint, bigint] {
   const [startSlot, endSlot] = getSlotRangeForEpoch(epochNumber, constants);
   const ethereumSlotsPerL2Slot = constants.slotDuration / constants.ethereumSlotDuration;
   return [
-    constants.l1GenesisTime + startSlot * BigInt(constants.slotDuration),
+    constants.l1GenesisTime + BigInt(startSlot) * BigInt(constants.slotDuration),
     constants.l1GenesisTime +
-      endSlot * BigInt(constants.slotDuration) +
+      BigInt(endSlot) * BigInt(constants.slotDuration) +
       BigInt((ethereumSlotsPerL2Slot - 1) * constants.ethereumSlotDuration),
   ];
 }
+
+/**
+ * Returns the start timestamp for a given epoch number.
+ */
+export function getStartTimestampForEpoch(
+  epochNumber: EpochNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'epochDuration'>,
+) {
+  const [startSlot] = getSlotRangeForEpoch(epochNumber, constants);
+  return getTimestampForSlot(startSlot, constants);
+}
+
+/**
+ * Returns the epoch number at which proofs are no longer accepted for a given epoch.
+ * See l1-contracts/src/core/libraries/TimeLib.sol
+ */
+export function getProofSubmissionDeadlineEpoch(
+  epochNumber: EpochNumber,
+  constants: Pick<L1RollupConstants, 'proofSubmissionEpochs'>,
+): EpochNumber {
+  return EpochNumber(epochNumber + constants.proofSubmissionEpochs + 1);
+}
+
+/**
+ * Returns the deadline timestamp (in seconds) for submitting a proof for a given epoch.
+ * Computed as the start of the given epoch plus the proof submission window.
+ */
+export function getProofSubmissionDeadlineTimestamp(
+  epochNumber: EpochNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'epochDuration' | 'proofSubmissionEpochs'>,
+) {
+  // See l1-contracts/src/core/libraries/TimeLib.sol:
+  // return toSlots(_a) + Slot.wrap(store.epochDuration * (store.proofSubmissionEpochs + 1));
+  const deadlineEpoch = getProofSubmissionDeadlineEpoch(epochNumber, constants);
+  const [deadlineSlot] = getSlotRangeForEpoch(deadlineEpoch, constants);
+  return getTimestampForSlot(deadlineSlot, constants);
+}
+
+/** Computes the quorum size required for a committee (⌊2n/3⌋ + 1). */
+export function computeQuorum(committeeSize: number): number {
+  return Math.floor((committeeSize * 2) / 3) + 1;
+}
+
+/** Returns the timestamp to start building a block for a given L2 slot. Computed as the start timestamp of the slot minus one L1 slot duration. */
+export function getSlotStartBuildTimestamp(
+  slotNumber: SlotNumber,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'ethereumSlotDuration'>,
+): number {
+  return Number(constants.l1GenesisTime) + slotNumber * constants.slotDuration - constants.ethereumSlotDuration;
+}

package/src/errors/proving_error.ts

@@ -10,7 +10,11 @@ export class ProvingError extends Error {
    * @param cause - The cause of the error.
    * @param retry - Whether the proof should be retried.
    */
-  constructor(message: string, cause?: unknown, public readonly retry: boolean = false) {
+  constructor(
+    message: string,
+    cause?: unknown,
+    public readonly retry: boolean = false,
+  ) {
     super(message);
     this.name = ProvingError.NAME;
     this.cause = cause;