@aztec-labs/prover-client 6.0.0-nightly.20260829

package/src/proving_broker/proving_job_controller.ts

@@ -0,0 +1,199 @@
+import { EpochNumber } from '@aztec-labs/foundation/branded-types';
+import { randomBytes } from '@aztec-labs/foundation/crypto/random';
+import { AbortError } from '@aztec-labs/foundation/error';
+import { type Logger, type LoggerBindings, createLogger } from '@aztec-labs/foundation/log';
+import type {
+  ProvingJobId,
+  ProvingJobInputs,
+  ProvingJobResultsMap,
+  ServerCircuitProver,
+} from '@aztec-labs/stdlib/interfaces/server';
+import { ProvingRequestType } from '@aztec-labs/stdlib/proofs';
+
+export enum ProvingJobControllerStatus {
+  IDLE = 'idle',
+  RUNNING = 'running',
+  DONE = 'done',
+}
+
+export class ProvingJobController {
+  private status: ProvingJobControllerStatus = ProvingJobControllerStatus.IDLE;
+  private promise?: Promise<void>;
+  private abortController = new AbortController();
+  private result?: ProvingJobResultsMap[ProvingRequestType] | Error;
+  private log: Logger;
+
+  constructor(
+    private jobId: ProvingJobId,
+    private inputs: ProvingJobInputs,
+    private epochNumber: EpochNumber,
+    private startedAt: number,
+    private circuitProver: ServerCircuitProver,
+    private onComplete: () => void,
+    bindings?: LoggerBindings,
+  ) {
+    this.log = createLogger('prover-client:proving-agent:job-controller', {
+      instanceId: randomBytes(4).toString('hex'),
+      ...bindings,
+    });
+  }
+
+  public start(): void {
+    if (this.status !== ProvingJobControllerStatus.IDLE) {
+      this.log.warn(
+        `Job controller for jobId=${this.jobId} not starting because it is not idle currentStatus=${this.status}`,
+        {
+          currentStatus: this.status,
+          jobId: this.jobId,
+        },
+      );
+      return;
+    }
+
+    this.promise = this.run();
+
+    this.log.info(`Job controller started jobId=${this.jobId}`, {
+      jobId: this.jobId,
+    });
+  }
+
+  public getStatus(): ProvingJobControllerStatus {
+    return this.status;
+  }
+
+  public getResult(): ProvingJobResultsMap[ProvingRequestType] | Error | undefined {
+    return this.result;
+  }
+
+  public abort(): void {
+    if (this.status !== ProvingJobControllerStatus.RUNNING) {
+      this.log.warn(`Tried to abort job controller for jobId=${this.jobId} but it is not running`, {
+        currentStatus: this.status,
+        jobId: this.jobId,
+      });
+      return;
+    }
+
+    this.abortController.abort();
+    this.log.warn(`Aborted job controller for jobId=${this.jobId}`, {
+      jobId: this.jobId,
+    });
+  }
+
+  public getJobId(): ProvingJobId {
+    return this.jobId;
+  }
+
+  public getProofType(): ProvingRequestType {
+    return this.inputs.type;
+  }
+
+  public getStartedAt(): number {
+    return this.startedAt;
+  }
+
+  public getProofTypeName(): string {
+    return ProvingRequestType[this.inputs.type];
+  }
+
+  private run = async () => {
+    this.status = ProvingJobControllerStatus.RUNNING;
+    let result: ProvingJobResultsMap[ProvingRequestType] | Error;
+    try {
+      result = await this.generateProof();
+    } catch (err) {
+      if (err && err instanceof Error) {
+        result = err;
+      } else {
+        result = new Error('Unknown proving error: ' + String(err), { cause: err });
+      }
+    }
+
+    if (this.abortController.signal.aborted) {
+      this.log.warn(`Job controller for jobId=${this.jobId} completed but job was aborted`, {
+        currentStatus: this.status,
+        jobId: this.jobId,
+      });
+      result = new AbortError('Proof was aborted');
+    }
+
+    this.result = result;
+    this.status = ProvingJobControllerStatus.DONE;
+    try {
+      this.onComplete();
+    } catch (err) {
+      this.log.warn(`On complete handler error: ${err}`, { jobId: this.jobId });
+    }
+  };
+
+  private async generateProof(): Promise<ProvingJobResultsMap[ProvingRequestType]> {
+    const { type, inputs } = this.inputs;
+    const signal = this.abortController.signal;
+    switch (type) {
+      case ProvingRequestType.PUBLIC_VM: {
+        return await this.circuitProver.getAvmProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.PUBLIC_CHONK_VERIFIER: {
+        return await this.circuitProver.getPublicChonkVerifierProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.PRIVATE_TX_BASE_ROLLUP: {
+        return await this.circuitProver.getPrivateTxBaseRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.PUBLIC_TX_BASE_ROLLUP: {
+        return await this.circuitProver.getPublicTxBaseRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.TX_MERGE_ROLLUP: {
+        return await this.circuitProver.getTxMergeRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.BLOCK_ROOT_NO_TXS_ROLLUP: {
+        return await this.circuitProver.getBlockRootNoTxsRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.BLOCK_ROOT_ROLLUP: {
+        return await this.circuitProver.getBlockRootRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.BLOCK_ROOT_SINGLE_TX_ROLLUP: {
+        return await this.circuitProver.getBlockRootSingleTxRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.BLOCK_MERGE_ROLLUP: {
+        return await this.circuitProver.getBlockMergeRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.CHECKPOINT_ROOT_ROLLUP: {
+        return await this.circuitProver.getCheckpointRootRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.CHECKPOINT_ROOT_SINGLE_BLOCK_ROLLUP: {
+        return await this.circuitProver.getCheckpointRootSingleBlockRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.CHECKPOINT_PADDING_ROLLUP: {
+        return await this.circuitProver.getCheckpointPaddingRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.CHECKPOINT_MERGE_ROLLUP: {
+        return await this.circuitProver.getCheckpointMergeRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.ROOT_ROLLUP: {
+        return await this.circuitProver.getRootRollupProof(inputs, signal, this.epochNumber);
+      }
+
+      case ProvingRequestType.INBOX_PARITY: {
+        return await this.circuitProver.getInboxParityProof(inputs, signal, this.epochNumber);
+      }
+
+      default: {
+        const _exhaustive: never = type;
+        return Promise.reject(new Error(`Invalid proof request type: ${type}`));
+      }
+    }
+  }
+}

package/src/proving_broker/rpc.ts

@@ -0,0 +1,131 @@
+import { EpochNumberSchema } from '@aztec-labs/foundation/branded-types';
+import { createSafeJsonRpcClient } from '@aztec-labs/foundation/json-rpc/client';
+import {
+  type GetProvingJobResponse,
+  ProofUri,
+  ProvingJob,
+  type ProvingJobBroker,
+  type ProvingJobBrokerDebug,
+  type ProvingJobConsumer,
+  ProvingJobId,
+  type ProvingJobProducer,
+  ProvingJobStatus,
+} from '@aztec-labs/stdlib/interfaces/server';
+import { ProvingRequestType } from '@aztec-labs/stdlib/proofs';
+import { type ApiSchemaFor, optional } from '@aztec-labs/stdlib/schemas';
+import { type ComponentsVersions, getVersioningResponseHandler } from '@aztec-labs/stdlib/versioning';
+import { makeTracedFetch } from '@aztec-labs/telemetry-client';
+import { z } from 'zod';
+
+/**
+ * Max JSON-RPC request body the broker clients will send.
+ *
+ * Job inputs and proof results travel inline as `data:` URIs on this path, so a single call is routinely larger than
+ * the 1 mb the generic JSON-RPC client allows — that default sizes batches of small node requests against the node
+ * server's own default. An AVM (`PUBLIC_VM`) result is around 1.3 mb today. This value must stay at or below the
+ * broker server's `RPC_MAX_BODY_SIZE`, which deployments set to 50mb.
+ */
+export const PROVER_BROKER_MAX_REQUEST_BODY_SIZE = 50 * 1024 * 1024;
+
+/** Indefinite backoff for broker communication: 1, 1, 1, 2, 4, 4, 4, ... seconds. */
+export function* proverBrokerBackoff() {
+  const v = [1, 1, 1, 2, 4];
+  let i = 0;
+  while (true) {
+    yield v[Math.min(i++, v.length - 1)];
+  }
+}
+
+const ProvingJobFilterSchema = z.object({
+  allowList: z.array(z.nativeEnum(ProvingRequestType)),
+});
+
+const GetProvingJobResponse = z.object({
+  job: ProvingJob,
+  time: z.number(),
+});
+
+export const ProvingJobProducerSchema: ApiSchemaFor<ProvingJobProducer> = {
+  enqueueProvingJob: z.function({ input: z.tuple([ProvingJob]), output: ProvingJobStatus }),
+  getProvingJobStatus: z.function({ input: z.tuple([ProvingJobId]), output: ProvingJobStatus }),
+  cancelProvingJob: z.function({ input: z.tuple([ProvingJobId]), output: z.void() }),
+  getCompletedJobs: z.function({ input: z.tuple([z.array(ProvingJobId)]), output: z.array(ProvingJobId) }),
+};
+
+export const ProvingJobConsumerSchema: ApiSchemaFor<ProvingJobConsumer> = {
+  getProvingJob: z.function({
+    input: z.tuple([optional(ProvingJobFilterSchema)]),
+    output: GetProvingJobResponse.optional(),
+  }),
+  reportProvingJobError: z.function({
+    input: z.tuple([ProvingJobId, z.string(), optional(z.boolean()), optional(ProvingJobFilterSchema)]),
+    output: GetProvingJobResponse.optional(),
+  }),
+  reportProvingJobProgress: z.function({
+    input: z.tuple([ProvingJobId, z.number(), optional(ProvingJobFilterSchema)]),
+    output: GetProvingJobResponse.optional(),
+  }),
+  reportProvingJobSuccess: z.function({
+    input: z.tuple([ProvingJobId, ProofUri, optional(ProvingJobFilterSchema)]),
+    output: GetProvingJobResponse.optional(),
+  }),
+};
+
+export const ProvingJobBrokerSchema: ApiSchemaFor<ProvingJobBroker> = {
+  ...ProvingJobConsumerSchema,
+  ...ProvingJobProducerSchema,
+};
+
+export const ProvingJobBrokerDebugSchema: ApiSchemaFor<ProvingJobBrokerDebug> = {
+  replayProvingJob: z.function({
+    input: z.tuple([ProvingJobId, z.nativeEnum(ProvingRequestType), EpochNumberSchema, ProofUri]),
+    output: ProvingJobStatus,
+  }),
+};
+
+export const ProvingJobBrokerSchemaWithDebug: ApiSchemaFor<ProvingJobBroker & ProvingJobBrokerDebug> = {
+  ...ProvingJobBrokerSchema,
+  ...ProvingJobBrokerDebugSchema,
+};
+
+export function createProvingJobBrokerClient(
+  url: string,
+  versions: Partial<ComponentsVersions>,
+  fetch = makeTracedFetch(proverBrokerBackoff, false),
+  maxRequestBodySize = PROVER_BROKER_MAX_REQUEST_BODY_SIZE,
+): ProvingJobBroker {
+  return createSafeJsonRpcClient(url, ProvingJobBrokerSchema, {
+    namespaceMethods: 'proverBroker',
+    fetch,
+    maxRequestBodySize,
+    onResponse: getVersioningResponseHandler(versions),
+  });
+}
+
+export function createProvingJobProducerClient(
+  url: string,
+  versions: Partial<ComponentsVersions>,
+  fetch = makeTracedFetch(proverBrokerBackoff, false),
+  maxRequestBodySize = PROVER_BROKER_MAX_REQUEST_BODY_SIZE,
+): ProvingJobProducer {
+  return createSafeJsonRpcClient(url, ProvingJobProducerSchema, {
+    namespaceMethods: 'provingJobProducer',
+    fetch,
+    maxRequestBodySize,
+    onResponse: getVersioningResponseHandler(versions),
+  });
+}
+
+export function createProvingJobConsumerClient(
+  url: string,
+  versions: Partial<ComponentsVersions>,
+  fetch = makeTracedFetch(proverBrokerBackoff, false),
+  maxRequestBodySize = PROVER_BROKER_MAX_REQUEST_BODY_SIZE,
+): ProvingJobConsumer {
+  return createSafeJsonRpcClient(url, ProvingJobConsumerSchema, {
+    namespaceMethods: 'provingJobConsumer',
+    fetch,
+    maxRequestBodySize,
+    onResponse: getVersioningResponseHandler(versions),
+  });
+}

package/src/test/epoch_settlement.ts

@@ -0,0 +1,82 @@
+import type { RollupCheatCodes } from '@aztec-labs/ethereum/test';
+import type { CheckpointNumber, EpochNumber, SlotNumber } from '@aztec-labs/foundation/branded-types';
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { Logger } from '@aztec-labs/foundation/log';
+import type { L2BlockSource } from '@aztec-labs/stdlib/block';
+import { computeEpochOutHash } from '@aztec-labs/stdlib/messaging';
+
+/** Arguments for {@link settleEpochOutbox}. */
+export type SettleEpochOutboxArgs = {
+  /** Cheat codes used to write the computed out hash directly into the L1 Outbox storage. */
+  rollupCheatCodes: RollupCheatCodes;
+  /** Source of checkpointed L2 blocks for the epoch being settled. */
+  l2BlockSource: L2BlockSource;
+  /** Epoch to settle. */
+  epoch: EpochNumber;
+  /**
+   * When set, only checkpoints up to and including this number are covered. Used to settle a partial
+   * epoch (the AZIP-14 Outbox keeps one root per `numCheckpointsInEpoch`, so a prefix of an epoch can
+   * be settled and consumed before the epoch completes). When omitted, every checkpointed block in the
+   * epoch is covered.
+   */
+  maxCheckpoint?: CheckpointNumber;
+  log: Logger;
+};
+
+/**
+ * Computes the epoch out hash over the checkpointed blocks of an epoch (optionally only up to
+ * `maxCheckpoint`) and writes it into the L1 Outbox via cheat codes. This is the synthetic,
+ * no-prover equivalent of an epoch root proof landing on L1: it makes the L2-to-L1 messages in the
+ * covered checkpoints consumable. It does NOT advance the rollup's proven tip — callers
+ * `markAsProven` separately so a single prove call can settle multiple epochs before marking proven.
+ *
+ * Used by the test-only proving drivers: the `AutomineSequencer`'s auto-settle loop and the standalone
+ * `EpochTestSettler`. Lives here (rather than in either consumer) so both share one implementation.
+ *
+ * @returns The last checkpoint number covered by the settled range, or `undefined` if the epoch has
+ * no checkpointed blocks (within the `maxCheckpoint` bound).
+ */
+export async function settleEpochOutbox({
+  rollupCheatCodes,
+  l2BlockSource,
+  epoch,
+  maxCheckpoint,
+  log,
+}: SettleEpochOutboxArgs): Promise<CheckpointNumber | undefined> {
+  let blocks = await l2BlockSource.getBlocks({ epoch, onlyCheckpointed: true });
+  if (maxCheckpoint !== undefined) {
+    blocks = blocks.filter(block => block.checkpointNumber <= maxCheckpoint);
+  }
+  if (blocks.length === 0) {
+    return undefined;
+  }
+
+  log.info(
+    `Settling epoch ${epoch}${maxCheckpoint !== undefined ? ` up to checkpoint ${maxCheckpoint}` : ''} with blocks ${blocks[0]?.header.getBlockNumber()} to ${blocks.at(-1)?.header.getBlockNumber()}`,
+    { epoch, maxCheckpoint, blocks: blocks.map(block => block.toBlockInfo()) },
+  );
+
+  const messagesInEpoch: Fr[][][][] = [];
+  // Undefined (not SlotNumber.ZERO) so a first checkpointed block at slot 0 still opens checkpoint 0.
+  let previousSlotNumber: SlotNumber | undefined;
+  let checkpointIndex = -1;
+
+  for (const block of blocks) {
+    const slotNumber = block.header.globalVariables.slotNumber;
+    if (slotNumber !== previousSlotNumber) {
+      checkpointIndex++;
+      messagesInEpoch[checkpointIndex] = [];
+      previousSlotNumber = slotNumber;
+    }
+    messagesInEpoch[checkpointIndex].push(block.body.txEffects.map(txEffect => txEffect.l2ToL1Msgs));
+  }
+
+  const outHash = computeEpochOutHash(messagesInEpoch);
+  if (!outHash.isZero()) {
+    await rollupCheatCodes.insertOutbox(epoch, messagesInEpoch.length, outHash.toBigInt());
+  } else {
+    log.info(`No L2 to L1 messages in epoch ${epoch}`, { epoch });
+  }
+
+  return blocks.at(-1)?.checkpointNumber;
+}

package/src/test/index.ts

@@ -0,0 +1 @@
+export { settleEpochOutbox, type SettleEpochOutboxArgs } from './epoch_settlement.js';

package/src/test/mock_proof_store.ts

@@ -0,0 +1,14 @@
+import type { ProvingJobId } from '@aztec-labs/stdlib/interfaces/server';
+import { ProvingRequestType } from '@aztec-labs/stdlib/proofs';
+
+// Mock ProofStore for faster benchmarks with realistic Cloud Storage URIs
+export class MockProofStore {
+  private mockCounter = 0;
+  private readonly bucketName = 'aztec-proving-benchmarks';
+  private readonly basePath = 'proving-jobs';
+
+  saveProofInput(jobId: ProvingJobId, type: ProvingRequestType): Promise<string> {
+    const uri = `gs://${this.bucketName}/${this.basePath}/inputs/${type}/${jobId}`;
+    return Promise.resolve(uri as any);
+  }
+}