@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/interfaces/private_kernel_prover.ts

@@ -0,0 +1,301 @@
+import type {
+  HidingKernelToPublicPrivateInputs,
+  HidingKernelToRollupPrivateInputs,
+  PrivateExecutionStep,
+  PrivateKernelCircuitPublicInputs,
+  PrivateKernelInit2CircuitPrivateInputs,
+  PrivateKernelInit3CircuitPrivateInputs,
+  PrivateKernelInit4CircuitPrivateInputs,
+  PrivateKernelInit5CircuitPrivateInputs,
+  PrivateKernelInitCircuitPrivateInputs,
+  PrivateKernelInner2CircuitPrivateInputs,
+  PrivateKernelInner3CircuitPrivateInputs,
+  PrivateKernelInner4CircuitPrivateInputs,
+  PrivateKernelInner5CircuitPrivateInputs,
+  PrivateKernelInnerCircuitPrivateInputs,
+  PrivateKernelResetCircuitPrivateInputs,
+  PrivateKernelResetTailCircuitPrivateInputs,
+  PrivateKernelSimulateOutput,
+  PrivateKernelTailCircuitPublicInputs,
+} from '../kernel/index.js';
+import type { ChonkProofWithPublicInputs } from '../proofs/chonk_proof.js';
+
+/**
+ * PrivateKernelProver provides functionality to simulate and validate circuits, and retrieve
+ * siloed commitments necessary for maintaining transaction privacy and security on the network.
+ */
+export interface PrivateKernelProver {
+  /**
+   * Creates a proof output for a given signed transaction request and private call data for the first iteration.
+   *
+   * @param privateKernelInputsInit - The private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateInitOutput(
+    privateKernelInputsInit: PrivateKernelInitCircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes the first kernel iteration without generating a proof.
+   *
+   * @param privateKernelInputsInit - The private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and an empty kernel proof.
+   */
+  simulateInit(
+    privateKernelInputsInit: PrivateKernelInitCircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output for a batched first iteration that processes two app calls in a single
+   * private kernel circuit.
+   *
+   * @param privateKernelInputsInit2 - The batched private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateInit2Output(
+    privateKernelInputsInit2: PrivateKernelInit2CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes the batched first kernel iteration (two app calls) without generating a proof.
+   *
+   * @param privateKernelInputsInit2 - The batched private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and an empty kernel proof.
+   */
+  simulateInit2(
+    privateKernelInputsInit2: PrivateKernelInit2CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output for a batched first iteration that processes three app calls in a single
+   * private kernel circuit.
+   *
+   * @param privateKernelInputsInit3 - The batched private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateInit3Output(
+    privateKernelInputsInit3: PrivateKernelInit3CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes the batched first kernel iteration (three app calls) without generating a proof.
+   *
+   * @param privateKernelInputsInit3 - The batched private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and an empty kernel proof.
+   */
+  simulateInit3(
+    privateKernelInputsInit3: PrivateKernelInit3CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output for a batched first iteration that processes four app calls in a single
+   * private kernel circuit.
+   *
+   * @param privateKernelInputsInit4 - The batched private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateInit4Output(
+    privateKernelInputsInit4: PrivateKernelInit4CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes the batched first kernel iteration (four app calls) without generating a proof.
+   *
+   * @param privateKernelInputsInit4 - The batched private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and an empty kernel proof.
+   */
+  simulateInit4(
+    privateKernelInputsInit4: PrivateKernelInit4CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output for a batched first iteration that processes five app calls in a single
+   * private kernel circuit.
+   *
+   * @param privateKernelInputsInit5 - The batched private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateInit5Output(
+    privateKernelInputsInit5: PrivateKernelInit5CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes the batched first kernel iteration (five app calls) without generating a proof.
+   *
+   * @param privateKernelInputsInit5 - The batched private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and an empty kernel proof.
+   */
+  simulateInit5(
+    privateKernelInputsInit5: PrivateKernelInit5CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output for a given previous kernel data and private call data for an inner iteration.
+   *
+   * @param privateKernelInputsInner - The private input data structure for the inner iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateInnerOutput(
+    privateKernelInputsInner: PrivateKernelInnerCircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes an inner kernel iteration without generating a proof.
+   *
+   * @param privateKernelInputsInit - The private data structure for the initial iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and an empty kernel proof.
+   */
+  simulateInner(
+    privateKernelInputsInner: PrivateKernelInnerCircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output for a batched inner iteration that processes two app calls in a single
+   * private kernel circuit.
+   *
+   * @param privateKernelInputsInner2 - The batched private data structure for the inner iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateInner2Output(
+    privateKernelInputsInner2: PrivateKernelInner2CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes the batched inner kernel iteration (two app calls) without generating a proof.
+   *
+   * @param privateKernelInputsInner2 - The batched private data structure for the inner iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and an empty kernel proof.
+   */
+  simulateInner2(
+    privateKernelInputsInner2: PrivateKernelInner2CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output for a batched inner iteration that processes three app calls in a single
+   * private kernel circuit.
+   *
+   * @param privateKernelInputsInner3 - The batched private data structure for the inner iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateInner3Output(
+    privateKernelInputsInner3: PrivateKernelInner3CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes the batched inner kernel iteration (three app calls) without generating a proof.
+   *
+   * @param privateKernelInputsInner3 - The batched private data structure for the inner iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and an empty kernel proof.
+   */
+  simulateInner3(
+    privateKernelInputsInner3: PrivateKernelInner3CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output for a batched inner iteration that processes four app calls in a single
+   * private kernel circuit.
+   *
+   * @param privateKernelInputsInner4 - The batched private data structure for the inner iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateInner4Output(
+    privateKernelInputsInner4: PrivateKernelInner4CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes the batched inner kernel iteration (four app calls) without generating a proof.
+   *
+   * @param privateKernelInputsInner4 - The batched private data structure for the inner iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and an empty kernel proof.
+   */
+  simulateInner4(
+    privateKernelInputsInner4: PrivateKernelInner4CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output for a batched inner iteration that processes five app calls in a single
+   * private kernel circuit.
+   *
+   * @param privateKernelInputsInner5 - The batched private data structure for the inner iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateInner5Output(
+    privateKernelInputsInner5: PrivateKernelInner5CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes the batched inner kernel iteration (five app calls) without generating a proof.
+   *
+   * @param privateKernelInputsInner5 - The batched private data structure for the inner iteration.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and an empty kernel proof.
+   */
+  simulateInner5(
+    privateKernelInputsInner5: PrivateKernelInner5CircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output by resetting the arrays using the reset circuit.
+   *
+   * @param privateKernelInputsTail - The private input data structure for the reset circuit.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs and the kernel proof.
+   */
+  generateResetOutput(
+    privateKernelInputsReset: PrivateKernelResetCircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Executes the reset circuit without generating a proof
+   *
+   * @param privateKernelInputsTail - The private input data structure for the reset circuit.
+   * @returns A Promise resolving to a ProofOutput object containing public inputs an empty kernel proof.
+   */
+  simulateReset(
+    privateKernelInputsReset: PrivateKernelResetCircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelCircuitPublicInputs>>;
+
+  /**
+   * Creates a proof output for the terminal reset+tail step. Dispatches to the rollup-bound or
+   * public-bound family based on `inputs.isForPublic()`.
+   *
+   * @param privateKernelInputs - Reset hints, dimensions, and tail params.
+   * @returns A Promise resolving to a ProofOutput containing the tail-shaped public inputs.
+   */
+  generateResetTailOutput(
+    privateKernelInputs: PrivateKernelResetTailCircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelTailCircuitPublicInputs>>;
+
+  /**
+   * Simulates the terminal reset+tail step without generating a proof.
+   */
+  simulateResetTail(
+    privateKernelInputs: PrivateKernelResetTailCircuitPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelTailCircuitPublicInputs>>;
+
+  generateHidingToRollupOutput(
+    inputs: HidingKernelToRollupPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelTailCircuitPublicInputs>>;
+
+  generateHidingToPublicOutput(
+    inputs: HidingKernelToPublicPrivateInputs,
+  ): Promise<PrivateKernelSimulateOutput<PrivateKernelTailCircuitPublicInputs>>;
+
+  /**
+   * Based of a program stack, create a folding proof.
+   * @param acirs The program bytecode.
+   * @param witnessStack The witnessses for each program bytecode.
+   */
+  createChonkProof(executionSteps: PrivateExecutionStep[]): Promise<ChonkProofWithPublicInputs>;
+
+  /**
+   * Compute the gate count for a given circuit.
+   * @param bytecode - The circuit bytecode in gzipped bincode format
+   * @param circuitName - The name of the circuit
+   * @param circuitKind - The circuit kind expected by the Chonk backend
+   * @returns A Promise resolving to the gate count
+   */
+  computeGateCountForCircuit(
+    bytecode: Buffer,
+    circuitName: string,
+    circuitKind: PrivateExecutionStep['kind'],
+  ): Promise<number>;
+}

package/src/interfaces/processed-tx-handler.ts

@@ -0,0 +1,10 @@
+import type { ProcessedTx } from '../tx/processed_tx.js';
+
+/** Receives processed txs as part of block simulation or proving. */
+export interface ProcessedTxHandler {
+  /**
+   * Handles processed txs.
+   * @param txs - The transactions to be handled.
+   */
+  addTxs(txs: ProcessedTx[]): Promise<void>;
+}

package/src/interfaces/prover-agent.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+import type { ApiSchemaFor } from '../schemas/index.js';
+
+export const ProverAgentStatusSchema = z.discriminatedUnion('status', [
+  z.object({ status: z.literal('stopped') }),
+  z.object({ status: z.literal('running') }),
+  z.object({ status: z.literal('proving'), jobId: z.string(), proofType: z.number(), startedAtISO: z.string() }),
+]);
+
+export type ProverAgentStatus = z.infer<typeof ProverAgentStatusSchema>;
+
+export interface ProverAgentApi {
+  getStatus(): Promise<unknown>;
+}
+
+export const ProverAgentApiSchema: ApiSchemaFor<ProverAgentApi> = {
+  getStatus: z.function({ input: z.tuple([]), output: ProverAgentStatusSchema }),
+};

package/src/interfaces/prover-broker.ts

@@ -0,0 +1,112 @@
+import type { EpochNumber } from '@aztec-labs/foundation/branded-types';
+
+import type { ProvingRequestType } from '../proofs/proving_request_type.js';
+import type { ProofUri, ProvingJob, ProvingJobId, ProvingJobStatus } from './proving-job.js';
+
+/**
+ * An interface for the proving orchestrator. The producer uses this to enqueue jobs for agents
+ */
+export interface ProvingJobProducer {
+  /**
+   * Enqueues a proving job
+   * @param job - The job to enqueue
+   */
+  enqueueProvingJob(job: ProvingJob): Promise<ProvingJobStatus>;
+
+  /**
+   * Cancels a proving job.
+   * @param id - The ID of the job to cancel
+   */
+  cancelProvingJob(id: ProvingJobId): Promise<void>;
+
+  /**
+   * Returns the current status fof the proving job
+   * @param id - The ID of the job to get the status of
+   */
+  getProvingJobStatus(id: ProvingJobId): Promise<ProvingJobStatus>;
+
+  /**
+   * Returns the ids of jobs that have been completed since the last call
+   * Also returns the set of provided job ids that are completed
+   * @param ids - The set of job ids to check for completion
+   */
+  getCompletedJobs(ids: ProvingJobId[]): Promise<ProvingJobId[]>;
+}
+
+export type ProvingJobFilter = {
+  allowList: ProvingRequestType[];
+};
+
+export type GetProvingJobResponse = {
+  job: ProvingJob;
+  time: number;
+};
+
+/**
+ * An interface for proving agents to request jobs and report results
+ */
+export interface ProvingJobConsumer {
+  /**
+   * Gets a proving job to work on
+   * @param filter - Optional filter for the type of job to get
+   */
+  getProvingJob(filter?: ProvingJobFilter): Promise<GetProvingJobResponse | undefined>;
+
+  /**
+   * Marks a proving job as successful
+   * @param id - The ID of the job to report success for
+   * @param result - The result of the job
+   */
+  reportProvingJobSuccess(
+    id: ProvingJobId,
+    result: ProofUri,
+    filter?: ProvingJobFilter,
+  ): Promise<GetProvingJobResponse | undefined>;
+
+  /**
+   * Marks a proving job as errored
+   * @param id - The ID of the job to report an error for
+   * @param err - The error that occurred while processing the job
+   * @param retry - Whether to retry the job
+   */
+  reportProvingJobError(
+    id: ProvingJobId,
+    err: string,
+    retry?: boolean,
+    filter?: ProvingJobFilter,
+  ): Promise<GetProvingJobResponse | undefined>;
+
+  /**
+   * Sends a heartbeat to the broker to indicate that the agent is still working on the given proving job
+   * @param id - The ID of the job to report progress for
+   * @param startedAt - The unix epoch when the job was started
+   * @param filter - Optional filter for the type of job to get
+   */
+  reportProvingJobProgress(
+    id: ProvingJobId,
+    startedAt: number,
+    filter?: ProvingJobFilter,
+  ): Promise<GetProvingJobResponse | undefined>;
+}
+
+export interface ProvingJobBroker extends ProvingJobProducer, ProvingJobConsumer {}
+
+/**
+ * Debug interface for replaying proving jobs from stored inputs.
+ * Used for benchmarking different agent configurations against the same workload.
+ */
+export interface ProvingJobBrokerDebug {
+  /**
+   * Replays a proving job by re-enqueuing it with inputs from the configured proof store.
+   * The proof type is parsed from the job ID (format: epoch:typeName:hash).
+   * @param jobId - The original job ID to replay
+   * @param epochNumber - The epoch number to assign
+   * @param inputsUri - The proof inputs location
+   */
+  replayProvingJob(
+    jobId: ProvingJobId,
+    type: ProvingRequestType,
+    epochNumber: EpochNumber,
+    inputsUri: ProofUri,
+  ): Promise<ProvingJobStatus>;
+}

package/src/interfaces/prover-client.ts

@@ -0,0 +1,153 @@
+import { type ConfigMappingsType, booleanConfigHelper, numberConfigHelper } from '@aztec-labs/foundation/config';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { z } from 'zod';
+
+import { schemas, zodFor } from '../schemas/index.js';
+import type { TxHash } from '../tx/tx_hash.js';
+import type { ProvingJobConsumer } from './prover-broker.js';
+
+export type ActualProverConfig = {
+  /** Whether to construct real proofs */
+  realProofs: boolean;
+  /** The type of artificial delay to introduce */
+  proverTestDelayType: 'fixed' | 'realistic';
+  /** If using fixed delay, the time each operation takes. */
+  proverTestDelayMs: number;
+  /** If using realistic delays, what percentage of realistic times to apply. */
+  proverTestDelayFactor: number;
+  /**
+   * Whether to abort pending proving jobs when the orchestrator is cancelled.
+   * When false (default), jobs remain in the broker queue and can be reused on restart/reorg.
+   * When true, jobs are explicitly cancelled with the broker, which prevents reuse.
+   */
+  cancelJobsOnStop: boolean;
+  /** Max concurrent jobs the orchestrator serializes and enqueues to the broker. */
+  enqueueConcurrency: number;
+};
+
+/**
+ * The prover configuration.
+ */
+export type ProverConfig = ActualProverConfig & {
+  /** The URL to the Aztec node to take proving jobs from */
+  nodeUrl?: string;
+  /** Identifier of the prover */
+  proverId?: EthAddress;
+  /** Number of proving agents to start within the prover. */
+  proverAgentCount: number;
+  /** Where to store proving request. Must be accessible to both prover node and agents. If not set will inline-encode the parameters */
+  proofStore?: string;
+  /** Store for failed proof inputs. */
+  failedProofStore?: string;
+};
+
+export const ProverConfigSchema = zodFor<ProverConfig>()(
+  z.object({
+    nodeUrl: z.string().optional(),
+    realProofs: z.boolean(),
+    proverId: schemas.EthAddress.optional(),
+    proverTestDelayType: z.enum(['fixed', 'realistic']),
+    proverTestDelayMs: z.number(),
+    proverTestDelayFactor: z.number(),
+    proverAgentCount: z.number(),
+    proofStore: z.string().optional(),
+    failedProofStore: z.string().optional(),
+    cancelJobsOnStop: z.boolean(),
+    enqueueConcurrency: z.number(),
+  }),
+);
+
+export const proverConfigMappings: ConfigMappingsType<ProverConfig> = {
+  nodeUrl: {
+    env: 'AZTEC_NODE_URL',
+    description: 'The URL to the Aztec node to take proving jobs from',
+  },
+  realProofs: {
+    env: 'PROVER_REAL_PROOFS',
+    description: 'Whether to construct real proofs',
+    ...booleanConfigHelper(true),
+  },
+  proverId: {
+    env: 'PROVER_ID',
+    parseEnv: (val: string) => parseProverId(val),
+    description: 'Hex value that identifies the prover. Defaults to the address used for submitting proofs if not set.',
+  },
+  proverTestDelayType: {
+    env: 'PROVER_TEST_DELAY_TYPE',
+    description: 'The type of artificial delay to introduce',
+  },
+  proverTestDelayMs: {
+    env: 'PROVER_TEST_DELAY_MS',
+    description: 'Artificial delay to introduce to all operations to the test prover.',
+    ...numberConfigHelper(0),
+  },
+  proverTestDelayFactor: {
+    env: 'PROVER_TEST_DELAY_FACTOR',
+    description: 'If using realistic delays, what percentage of realistic times to apply.',
+    ...numberConfigHelper(1),
+  },
+  proverAgentCount: {
+    env: 'PROVER_AGENT_COUNT',
+    description: 'The number of prover agents to start',
+    ...numberConfigHelper(1),
+  },
+  proofStore: {
+    env: 'PROVER_PROOF_STORE',
+    description: 'Optional proof input store for the prover',
+  },
+  failedProofStore: {
+    env: 'PROVER_FAILED_PROOF_STORE',
+    description:
+      'Store for failed proof inputs. Google cloud storage is only supported at the moment. Set this value as gs://bucket-name/path/to/store.',
+  },
+  cancelJobsOnStop: {
+    env: 'PROVER_CANCEL_JOBS_ON_STOP',
+    description:
+      'Whether to abort pending proving jobs when the orchestrator is cancelled. ' +
+      'When false (default), jobs remain in the broker queue and can be reused on restart/reorg. ' +
+      'When true, jobs are explicitly cancelled with the broker, which prevents reuse.',
+    ...booleanConfigHelper(false),
+  },
+  enqueueConcurrency: {
+    env: 'PROVER_ENQUEUE_CONCURRENCY',
+    description: 'Max concurrent jobs the orchestrator serializes and enqueues to the broker.',
+    ...numberConfigHelper(50),
+  },
+};
+
+function parseProverId(str: string) {
+  return EthAddress.fromString(str);
+}
+
+/**
+ * The interface to the prover client.
+ * Provides the ability to generate proofs and build rollups.
+ *
+ */
+export interface EpochProverManager {
+  start(): Promise<void>;
+
+  stop(): Promise<void>;
+
+  getProvingJobSource(): ProvingJobConsumer;
+
+  getProverId(): EthAddress;
+
+  updateProverConfig(config: Partial<ProverConfig>): Promise<void>;
+}
+
+export class BlockProofError extends Error {
+  static #name = 'BlockProofError';
+  override name = BlockProofError.#name;
+
+  constructor(
+    message: string,
+    public readonly txHashes: TxHash[],
+  ) {
+    super(message);
+  }
+
+  static isBlockProofError(err: any): err is BlockProofError {
+    return err && typeof err === 'object' && err.name === BlockProofError.#name;
+  }
+}

package/src/interfaces/prover-node.ts

@@ -0,0 +1,68 @@
+import { createSafeJsonRpcClient, defaultFetch } from '@aztec-labs/foundation/json-rpc/client';
+import { z } from 'zod';
+
+import { type ApiSchemaFor, schemas } from '../schemas/index.js';
+import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
+
+const EpochProvingJobState = [
+  'initialized',
+  'awaiting-checkpoints',
+  'awaiting-root',
+  'awaiting-predecessor',
+  'publishing-proof',
+  'completed',
+  'superseded',
+  'failed',
+  'stopped',
+  'cancelled',
+  'timed-out',
+] as const;
+
+export type EpochProvingJobState = (typeof EpochProvingJobState)[number];
+
+export const EpochProvingJobTerminalState: EpochProvingJobState[] = [
+  'completed',
+  'superseded',
+  'failed',
+  'stopped',
+  'cancelled',
+  'timed-out',
+] as const;
+
+export type EpochProvingJobTerminalState = (typeof EpochProvingJobTerminalState)[number];
+
+/** JSON RPC admin interface to a prover node. */
+export interface ProverNodeApi {
+  getJobs(): Promise<{ uuid: string; status: EpochProvingJobState; epochNumber: number }[]>;
+
+  /**
+   * Schedules proving for the given epoch and returns the job id immediately, without waiting for
+   * the proof to complete (proving can take far longer than an HTTP request). Poll `getJobs()` to
+   * track the returned job's progress.
+   */
+  startProof(epochNumber: number): Promise<string>;
+}
+
+/** Schemas for prover node API functions. */
+export const ProverNodeApiSchema: ApiSchemaFor<ProverNodeApi> = {
+  getJobs: z.function({
+    input: z.tuple([]),
+    output: z.array(z.object({ uuid: z.string(), status: z.enum(EpochProvingJobState), epochNumber: z.number() })),
+  }),
+
+  startProof: z.function({ input: z.tuple([schemas.Integer]), output: z.string() }),
+};
+
+export function createProverNodeAdminClient(
+  url: string,
+  versions: Partial<ComponentsVersions> = {},
+  fetch = defaultFetch,
+  apiKey?: string,
+): ProverNodeApi {
+  return createSafeJsonRpcClient<ProverNodeApi>(url, ProverNodeApiSchema, {
+    namespaceMethods: 'prover',
+    fetch,
+    onResponse: getVersioningResponseHandler(versions),
+    ...(apiKey ? { extraHeaders: { 'x-api-key': apiKey } } : {}),
+  });
+}