@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/contract/interfaces/contract_data_source.ts

@@ -0,0 +1,52 @@
+import type { Fr } from '@aztec/foundation/fields';
+
+import { FunctionSelector } from '../../abi/index.js';
+import type { AztecAddress } from '../../aztec-address/index.js';
+import type { ContractClassPublic, PublicFunction } 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.
+   */
+  getBlockNumber(): Promise<number>;
+
+  /**
+   * Returns the contract class for a given contract class id, or undefined if not found.
+   * @param id - Contract class id.
+   */
+  getContractClass(id: Fr): Promise<ContractClassPublic | undefined>;
+
+  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.
+   */
+  getContract(address: AztecAddress): 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>;
+  /** Registers a function names. Useful for debugging. */
+  registerContractFunctionSignatures(address: AztecAddress, signatures: string[]): Promise<void>;
+}

package/src/contract/interfaces/contract_instance.ts

@@ -0,0 +1,47 @@
+import type { Fr } from '@aztec/foundation/fields';
+
+import { z } from 'zod';
+
+import type { AztecAddress } from '../../aztec-address/index.js';
+import { PublicKeys } from '../../keys/public_keys.js';
+import { type ZodFor, schemas } from '../../schemas/index.js';
+
+const VERSION = 1 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.
+ */
+export interface ContractInstance {
+  /** 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;
+  /** Public keys associated with this instance. */
+  publicKeys: PublicKeys;
+}
+
+export type ContractInstanceWithAddress = ContractInstance & { address: AztecAddress };
+
+export const ContractInstanceSchema = z.object({
+  version: z.literal(VERSION),
+  salt: schemas.Fr,
+  deployer: schemas.AztecAddress,
+  currentContractClassId: schemas.Fr,
+  originalContractClassId: schemas.Fr,
+  initializationHash: schemas.Fr,
+  publicKeys: PublicKeys.schema,
+}) satisfies ZodFor<ContractInstance>;
+
+export const ContractInstanceWithAddressSchema = ContractInstanceSchema.and(
+  z.object({ address: schemas.AztecAddress }),
+) satisfies ZodFor<ContractInstanceWithAddress>;

package/src/contract/interfaces/contract_instance_update.ts

@@ -0,0 +1,30 @@
+import type { Fr } from '@aztec/foundation/fields';
+
+import { z } from 'zod';
+
+import type { AztecAddress } from '../../aztec-address/index.js';
+import { type ZodFor, schemas } from '../../schemas/index.js';
+
+/**
+ * An update to a contract instance, changing its contract class.
+ */
+export interface ContractInstanceUpdate {
+  /** Identifier of the previous contract class for this instance */
+  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;
+}
+
+export type ContractInstanceUpdateWithAddress = ContractInstanceUpdate & { address: AztecAddress };
+
+export const ContractInstanceUpdateSchema = z.object({
+  prevContractClassId: schemas.Fr,
+  newContractClassId: schemas.Fr,
+  blockOfChange: z.number(),
+}) satisfies ZodFor<ContractInstanceUpdate>;
+
+export const ContractInstanceUpdateWithAddressSchema = ContractInstanceUpdateSchema.and(
+  z.object({ address: schemas.AztecAddress }),
+) satisfies ZodFor<ContractInstanceUpdateWithAddress>;

package/src/contract/interfaces/index.ts

@@ -0,0 +1,6 @@
+export * from './contract_class.js';
+export * from './contract_data_source.js';
+export * from './contract_instance.js';
+export * from './contract_instance_update.js';
+export * from './node-info.js';
+export * from './protocol_contract_addresses.js';

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

@@ -0,0 +1,33 @@
+import { type L1ContractAddresses, L1ContractAddressesSchema } from '@aztec/ethereum/l1-contract-addresses';
+import type { ZodFor } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import { type ProtocolContractAddresses, ProtocolContractAddressesSchema } from './protocol_contract_addresses.js';
+
+/** Provides basic information about the running node. */
+export interface NodeInfo {
+  /** Version as tracked in the aztec-packages repository. */
+  nodeVersion: string;
+  /** L1 chain id. */
+  l1ChainId: number;
+  /** Protocol version. */
+  protocolVersion: number;
+  /** The node's ENR. */
+  enr: string | undefined;
+  /** The deployed l1 contract addresses */
+  l1ContractAddresses: L1ContractAddresses;
+  /** Protocol contract addresses */
+  protocolContractAddresses: ProtocolContractAddresses;
+}
+
+export const NodeInfoSchema: ZodFor<NodeInfo> = z
+  .object({
+    nodeVersion: z.string(),
+    l1ChainId: z.number(),
+    protocolVersion: z.number(),
+    enr: z.string().optional(),
+    l1ContractAddresses: L1ContractAddressesSchema,
+    protocolContractAddresses: ProtocolContractAddressesSchema,
+  })
+  .transform(obj => ({ enr: undefined, ...obj }));

package/src/contract/interfaces/protocol_contract_addresses.ts

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

package/src/contract/partial_address.ts

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

package/src/contract/private_function.ts

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

package/src/contract/private_function_membership_proof.ts

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

package/src/contract/unconstrained_function_membership_proof.ts

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

package/src/epoch-helpers/index.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+
+import { type ZodFor, schemas } from '../schemas/index.js';
+
+export type L1RollupConstants = {
+  l1StartBlock: bigint;
+  l1GenesisTime: bigint;
+  slotDuration: number;
+  epochDuration: number;
+  ethereumSlotDuration: number;
+};
+
+export const EmptyL1RollupConstants: L1RollupConstants = {
+  l1StartBlock: 0n,
+  l1GenesisTime: 0n,
+  epochDuration: 1, // Not 0 to pervent division by zero
+  slotDuration: 1,
+  ethereumSlotDuration: 1,
+};
+
+export const L1RollupConstantsSchema = z.object({
+  l1StartBlock: schemas.BigInt,
+  l1GenesisTime: schemas.BigInt,
+  slotDuration: z.number(),
+  epochDuration: z.number(),
+  ethereumSlotDuration: z.number(),
+}) satisfies ZodFor<L1RollupConstants>;
+
+/** 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);
+}
+
+/** Returns the epoch number for a given timestamp. */
+export function getEpochNumberAtTimestamp(
+  ts: bigint,
+  constants: Pick<L1RollupConstants, 'epochDuration' | 'slotDuration' | 'l1GenesisTime'>,
+) {
+  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);
+}
+
+/** 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];
+}
+
+/**
+ * Returns the range of L1 timestamps (inclusive) for a given epoch number.
+ * Note that the endTimestamp is the start timestamp of the last L1 slot for the epoch.
+ */
+export function getTimestampRangeForEpoch(
+  epochNumber: bigint,
+  constants: Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'epochDuration' | 'ethereumSlotDuration'>,
+) {
+  const [startSlot, endSlot] = getSlotRangeForEpoch(epochNumber, constants);
+  const ethereumSlotsPerL2Slot = constants.slotDuration / constants.ethereumSlotDuration;
+  return [
+    constants.l1GenesisTime + startSlot * BigInt(constants.slotDuration),
+    constants.l1GenesisTime +
+      endSlot * BigInt(constants.slotDuration) +
+      BigInt((ethereumSlotsPerL2Slot - 1) * constants.ethereumSlotDuration),
+  ];
+}

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export * from './proving_error.js';
+export * from './simulation_error.js';

package/src/errors/proving_error.ts

@@ -0,0 +1,18 @@
+/**
+ * An error thrown when generating a proof fails.
+ */
+export class ProvingError extends Error {
+  public static readonly NAME = 'ProvingError';
+
+  /**
+   * Creates a new instance
+   * @param message - The error message.
+   * @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) {
+    super(message);
+    this.name = ProvingError.NAME;
+    this.cause = cause;
+  }
+}