@aztec/stdlib 0.0.1-commit.c31f2472 → 0.0.1-commit.c52d6e7

package/src/contract/interfaces/contract_instance.ts

@@ -6,44 +6,65 @@ import { AztecAddress } from '../../aztec-address/index.js';
 import { PublicKeys } from '../../keys/public_keys.js';
 import { schemas, zodFor } from '../../schemas/index.js';
 
-const VERSION = 1 as const;
+const VERSION = 2 as const;
 
 /**
- * A contract instance is a concrete deployment of a contract class. It always references a contract class,
- * which dictates what code it executes when called. It has state (both private and public), as well as an
- * address that acts as its identifier. It can be called into. It may have encryption and nullifying public keys.
+ * The address preimage of a contract instance: the immutable data that hashes to its address, i.e. everything a
+ * contract deployment commits to.
+ *
+ * Note that `originaContractClassId` is not necessarily the instance's _current_ class id, in case of upgrades: that
+ * one is not part of the preimage and is instead derived from chain state.
  */
-export interface ContractInstance {
+export interface ContractInstancePreimage {
   /** Version identifier. Initially one, bumped for any changes to the contract instance struct. */
   version: typeof VERSION;
   /** User-generated pseudorandom value for uniqueness. */
   salt: Fr;
   /** Optional deployer address or zero if this was a universal deploy. */
   deployer: AztecAddress;
-  /** Identifier of the contract class for this instance. */
-  currentContractClassId: Fr;
   /** Identifier of the original (at deployment) contract class for this instance */
   originalContractClassId: Fr;
   /** Hash of the selector and arguments to the constructor. */
   initializationHash: Fr;
+  /** Hash of Immutables Values the contract is deployed with. */
+  immutablesHash: Fr;
   /** Public keys associated with this instance. */
   publicKeys: PublicKeys;
 }
 
+/**
+ * The address preimage plus the current contract class id, which is chain-tracked state derived from the
+ * ContractInstanceRegistry (it equals the original class id unless the contract has been upgraded).
+ */
+export interface ContractInstance extends ContractInstancePreimage {
+  /** Identifier of the contract class this instance currently runs (as of some block). */
+  currentContractClassId: Fr;
+}
+
+export type ContractInstancePreimageWithAddress = ContractInstancePreimage & { address: AztecAddress };
+
 export type ContractInstanceWithAddress = ContractInstance & { address: AztecAddress };
 
-export const ContractInstanceSchema = zodFor<ContractInstance>()(
+export const ContractInstancePreimageSchema = zodFor<ContractInstancePreimage>()(
   z.object({
     version: z.literal(VERSION),
     salt: schemas.Fr,
     deployer: schemas.AztecAddress,
-    currentContractClassId: schemas.Fr,
     originalContractClassId: schemas.Fr,
     initializationHash: schemas.Fr,
+    immutablesHash: schemas.Fr,
     publicKeys: PublicKeys.schema,
   }),
 );
 
+export const ContractInstanceSchema = zodFor<ContractInstance>()(
+  ContractInstancePreimageSchema.and(z.object({ currentContractClassId: schemas.Fr })),
+);
+
+export const ContractInstancePreimageWithAddressSchema = zodFor<ContractInstancePreimageWithAddress>()(
+  ContractInstancePreimageSchema.and(z.object({ address: schemas.AztecAddress })),
+);
+
 export const ContractInstanceWithAddressSchema = zodFor<ContractInstanceWithAddress>()(
   ContractInstanceSchema.and(z.object({ address: schemas.AztecAddress })),
 );
@@ -54,12 +75,13 @@ export const ContractInstanceWithAddressSchema = zodFor<ContractInstanceWithAddr
  */
 export function contractInstanceFromPlainObject(obj: any): ContractInstance {
   return {
-    version: 1,
+    version: 2,
     salt: Fr.fromPlainObject(obj.salt),
     deployer: AztecAddress.fromPlainObject(obj.deployer),
     currentContractClassId: Fr.fromPlainObject(obj.currentContractClassId),
     originalContractClassId: Fr.fromPlainObject(obj.originalContractClassId),
     initializationHash: Fr.fromPlainObject(obj.initializationHash),
+    immutablesHash: Fr.fromPlainObject(obj.immutablesHash),
     publicKeys: PublicKeys.fromPlainObject(obj.publicKeys),
   };
 }

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

@@ -5,6 +5,12 @@ import { z } from 'zod';
 
 import { type ProtocolContractAddresses, ProtocolContractAddressesSchema } from './protocol_contract_addresses.js';
 
+/** Limits a single transaction may declare on a network. */
+export interface TxsLimits {
+  /** Maximum gas limits a single tx may declare: the smaller of the per-tx maximum and the per-block allocation. */
+  gas: { daGas: number; l2Gas: number };
+}
+
 /** Provides basic information about the running node. */
 export interface NodeInfo {
   /** Version as tracked in the aztec-packages repository. */
@@ -19,6 +25,10 @@ export interface NodeInfo {
   l1ContractAddresses: L1ContractAddresses;
   /** Protocol contract addresses */
   protocolContractAddresses: ProtocolContractAddresses;
+  /** Whether the node requires real proofs for transaction submission. */
+  realProofs: boolean;
+  /** Limits a single tx may declare on this network. Clients rely on this to set fallback gas limits. */
+  txsLimits: TxsLimits;
 }
 
 export const NodeInfoSchema: ZodFor<NodeInfo> = z
@@ -29,5 +39,9 @@ export const NodeInfoSchema: ZodFor<NodeInfo> = z
     enr: z.string().optional(),
     l1ContractAddresses: L1ContractAddressesSchema,
     protocolContractAddresses: ProtocolContractAddressesSchema,
+    realProofs: z.boolean(),
+    txsLimits: z.object({
+      gas: z.object({ daGas: z.number().int().nonnegative(), l2Gas: z.number().int().nonnegative() }),
+    }),
   })
   .transform(obj => ({ enr: undefined, ...obj }));

package/src/contract/partial_address.ts

@@ -1,7 +1,13 @@
 import type { Fr } from '@aztec/foundation/curves/bn254';
 
 /**
- * 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
+ * The contract-side preimage of an Aztec address, i.e. the commitment to a specific contract instance.
+ *
+ * A partial address commits to a contract's code and initialization
+ * (`hash(contract_class_id, salted_initialization_hash)`) but not to its keys. Combined with an account's `PublicKeys`,
+ * it fully determines the address: `address = (hash(public_keys_hash, partial_address) * G + Ivpk_m).x`. Two accounts
+ * therefore share an address only if they share both their public keys and their partial address.
+ *
+ * See `computePartialAddress` for the derivation.
  */
 export type PartialAddress = Fr;

package/src/contract/private_function.ts

@@ -1,8 +1,9 @@
-import { FUNCTION_TREE_HEIGHT, GeneratorIndex } from '@aztec/constants';
+import { DomainSeparator, FUNCTION_TREE_HEIGHT } from '@aztec/constants';
 import { poseidon2Hash, poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { type MerkleTree, MerkleTreeCalculator } from '@aztec/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
@@ -31,7 +32,7 @@ function computePrivateFunctionLeaves(fns: PrivateFunction[]): Promise<Buffer[]>
 
 /** Returns the leaf for a given private function. */
 export async function computePrivateFunctionLeaf(fn: PrivateFunction): Promise<Buffer> {
-  return (await poseidon2HashWithSeparator([fn.selector, fn.vkHash], GeneratorIndex.PRIVATE_FUNCTION_LEAF)).toBuffer();
+  return (await poseidon2HashWithSeparator([fn.selector, fn.vkHash], DomainSeparator.PRIVATE_FUNCTION_LEAF)).toBuffer();
 }
 
 async function getPrivateFunctionTreeCalculator(): Promise<MerkleTreeCalculator> {
@@ -42,7 +43,8 @@ async function getPrivateFunctionTreeCalculator(): Promise<MerkleTreeCalculator>
     privateFunctionTreeCalculator = await MerkleTreeCalculator.create(
       FUNCTION_TREE_HEIGHT,
       functionTreeZeroLeaf,
-      async (left, right) => (await poseidon2Hash([left, right])).toBuffer() as Buffer<ArrayBuffer>,
+      async (left, right) =>
+        (await computeMerkleHash(Fr.fromBuffer(left), Fr.fromBuffer(right))).toBuffer() as Buffer<ArrayBuffer>,
     );
   }
   return privateFunctionTreeCalculator;

package/src/database-version/database_version.ts

@@ -0,0 +1,87 @@
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { jsonParseWithSchema, jsonStringify } from '@aztec/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

@@ -1,90 +1,24 @@
 import { EthAddress } from '@aztec/foundation/eth-address';
-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';
 
-/**
- * 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. */
-  public [inspect.custom](): string {
-    return this.toString();
-  }
-
-  public toString(): string {
-    return `DatabaseVersion{schemaVersion=${this.schemaVersion},rollupAddress=${this.rollupAddress}"}`;
-  }
+import { DatabaseVersion } from './database_version.js';
 
-  /**
-   * Returns an empty instance
-   */
-  static empty() {
-    return new DatabaseVersion(0, EthAddress.ZERO);
-  }
-}
-
-export type DatabaseVersionManagerFs = Pick<typeof fs, 'readFile' | 'writeFile' | 'rm' | 'mkdir'>;
+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;
@@ -92,6 +26,8 @@ export type DatabaseVersionManagerOptions<T> = {
   dataDirectory: string;
   onOpen: (dataDir: string) => Promise<T>;
   onUpgrade?: (dataDir: string, currentVersion: number, latestVersion: number) => Promise<void>;
+  schemaVersionMismatchPolicy?: SchemaVersionMismatchPolicy;
+  versionFileReadFailurePolicy?: VersionFileReadFailurePolicy;
   fileSystem?: DatabaseVersionManagerFs;
   log?: Logger;
 };
@@ -110,6 +46,8 @@ export class DatabaseVersionManager<T> {
   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;
 
@@ -120,7 +58,11 @@ export class DatabaseVersionManager<T> {
    * @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 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
@@ -131,6 +73,8 @@ export class DatabaseVersionManager<T> {
     dataDirectory,
     onOpen,
     onUpgrade,
+    schemaVersionMismatchPolicy = 'reset',
+    versionFileReadFailurePolicy = 'reset',
     fileSystem = fs,
     log = createLogger(`foundation:version-manager`),
   }: DatabaseVersionManagerOptions<T>) {
@@ -144,13 +88,41 @@ export class DatabaseVersionManager<T> {
     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 });
-    return fileSystem.writeFile(join(dataDir, DatabaseVersionManager.VERSION_FILE), version.toBuffer());
+    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
+    }
   }
 
   /**
@@ -175,6 +147,17 @@ export class DatabaseVersionManager<T> {
         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();
@@ -191,10 +174,21 @@ 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) {
+        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}`,
@@ -218,10 +212,47 @@ export class DatabaseVersionManager<T> {
       await this.resetDataDirectory();
     }
 
-    // Write the current version to disk
-    await this.writeVersion();
+    // 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];
+  }
 
-    return [await this.onOpen(this.dataDirectory), 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}`);
+    }
   }
 
   /**

package/src/deserialization/index.ts

@@ -11,8 +11,41 @@ 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;
+/**
+ * Maximum number of L2 blocks in a provable checkpoint. Used for deserialization and when ingesting
+ * checkpoints already accepted by L1.
+ *
+ * This MUST be >= the number of blocks the proving system can carry, or a structurally-valid, provable
+ * checkpoint that L1 accepts would be rejected on ingest (`validateCheckpoint`) and wedge the archiver.
+ * The circuits and L1 impose no explicit per-checkpoint block count; the ceiling comes from the
+ * blob-field budget:
+ *
+ *   budget = BLOBS_PER_CHECKPOINT * FIELDS_PER_BLOB = 6 * 4096 = 24,576 fields
+ *
+ *   per-block minimal blob footprint:
+ *     first block  (may be empty)   = 7 fields   (NUM_FIRST_BLOCK_END_BLOB_FIELDS)
+ *     every other  (needs >= 1 tx)  = 6 + 4 = 10 fields
+ *                                     (NUM_BLOCK_END_BLOB_FIELDS + a 4-field minimal tx:
+ *                                      tx start marker + tx hash + fee + 1 mandatory nullifier)
+ *     + 1 checkpoint-end marker      (NUM_CHECKPOINT_END_MARKER_FIELDS)
+ *
+ *   max N:  7 + 10*(N - 1) + 1 <= 24,576  =>  10*(N - 1) <= 24,568  =>  N <= 2,457
+ *
+ * Only the first block may be empty; every other block needs >= 1 tx (the circuits have no empty-tx
+ * variant for non-first blocks), so 2457 is the largest provable checkpoint. The blob format can encode
+ * more blocks than this (up to ~4095 with all-empty blocks), but such a checkpoint is unprovable and
+ * can only reach L1 with a malicious committee supermajority — a terminal network compromise where a
+ * wedged archiver is an acceptable outcome. We therefore bound ingest to the provable maximum.
+ * Invariant checked by the unit test in deserialization.test.ts.
+ */
+export const MAX_CAPACITY_BLOCKS_PER_CHECKPOINT = 2457;
+
+/**
+ * Max blocks per checkpoint we are willing to build or attest to (conservative client policy, and the
+ * default block-count limit for `validateCheckpoint`). Distinct from {@link MAX_CAPACITY_BLOCKS_PER_CHECKPOINT},
+ * which is the higher ceiling we tolerate when deserializing checkpoints already accepted by L1.
+ */
+export const MAX_ATTESTABLE_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;

package/src/epoch-helpers/index.ts

@@ -11,6 +11,8 @@ export type L1RollupConstants = {
   epochDuration: number;
   ethereumSlotDuration: number;
   proofSubmissionEpochs: number;
+  targetCommitteeSize: number;
+  rollupManaLimit: number;
 };
 
 export const EmptyL1RollupConstants: L1RollupConstants = {
@@ -20,6 +22,8 @@ export const EmptyL1RollupConstants: L1RollupConstants = {
   slotDuration: 1,
   ethereumSlotDuration: 1,
   proofSubmissionEpochs: 1,
+  targetCommitteeSize: 48,
+  rollupManaLimit: Number.MAX_SAFE_INTEGER,
 };
 
 export const L1RollupConstantsSchema = zodFor<L1RollupConstants>()(
@@ -30,6 +34,8 @@ export const L1RollupConstantsSchema = zodFor<L1RollupConstants>()(
     epochDuration: z.number(),
     ethereumSlotDuration: z.number(),
     proofSubmissionEpochs: z.number(),
+    targetCommitteeSize: z.number(),
+    rollupManaLimit: z.number(),
   }),
 );
 
@@ -51,6 +57,25 @@ export function getSlotAtTimestamp(
     : 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,
@@ -137,6 +162,11 @@ export function getProofSubmissionDeadlineTimestamp(
   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,