@aztec/stdlib 0.77.0-testnet-ignition.17

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,20 @@
+import { z } from 'zod';
+
+import type { ApiSchemaFor } from '../schemas/index.js';
+
+export interface ProverAgentApi {
+  setMaxConcurrency(maxConcurrency: number): Promise<void>;
+
+  isRunning(): Promise<boolean>;
+
+  getCurrentJobs(): Promise<{ id: string; type: string }[]>;
+}
+
+export const ProverAgentApiSchema: ApiSchemaFor<ProverAgentApi> = {
+  setMaxConcurrency: z.function().args(z.number().min(1).int()).returns(z.void()),
+  isRunning: z.function().args().returns(z.boolean()),
+  getCurrentJobs: z
+    .function()
+    .args()
+    .returns(z.array(z.object({ id: z.string(), type: z.string() }))),
+};

package/src/interfaces/prover-broker.ts

@@ -0,0 +1,90 @@
+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 {}

package/src/interfaces/prover-client.ts

@@ -0,0 +1,121 @@
+import { type ConfigMappingsType, booleanConfigHelper, numberConfigHelper } from '@aztec/foundation/config';
+import { Fr } from '@aztec/foundation/fields';
+
+import { z } from 'zod';
+
+import { type ZodFor, schemas } from '../schemas/index.js';
+import type { TxHash } from '../tx/tx_hash.js';
+import type { EpochProver } from './epoch-prover.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;
+};
+
+/**
+ * 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: Fr;
+  /** Number of proving agents to start within the prover. */
+  proverAgentCount: number;
+  /** Store for failed proof inputs. */
+  failedProofStore?: string;
+};
+
+export const ProverConfigSchema = z.object({
+  nodeUrl: z.string().optional(),
+  realProofs: z.boolean(),
+  proverId: schemas.Fr,
+  proverTestDelayType: z.enum(['fixed', 'realistic']),
+  proverTestDelayMs: z.number(),
+  proverTestDelayFactor: z.number(),
+  proverAgentCount: z.number(),
+}) satisfies ZodFor<ProverConfig>;
+
+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(),
+  },
+  proverId: {
+    env: 'PROVER_ID',
+    parseEnv: (val: string) => parseProverId(val),
+    description: 'Identifier of the prover',
+    defaultValue: Fr.ZERO,
+  },
+  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),
+  },
+  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.',
+  },
+};
+
+function parseProverId(str: string) {
+  return Fr.fromHexString(str.startsWith('0x') ? str : Buffer.from(str, 'utf8').toString('hex'));
+}
+
+/**
+ * The interface to the prover client.
+ * Provides the ability to generate proofs and build rollups.
+ */
+export interface EpochProverManager {
+  createEpochProver(): EpochProver;
+
+  start(): Promise<void>;
+
+  stop(): Promise<void>;
+
+  getProvingJobSource(): ProvingJobConsumer;
+
+  getProverId(): Fr;
+
+  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-coordination.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+
+import type { ApiSchemaFor } from '../schemas/index.js';
+import { Tx } from '../tx/tx.js';
+import { TxHash } from '../tx/tx_hash.js';
+
+/** Provides basic operations for ProverNodes to interact with other nodes in the network. */
+export interface ProverCoordination {
+  /**
+   * Returns a transaction given its hash if available.
+   * @param txHash - The hash of the transaction, used as an ID.
+   * @returns The transaction, if found, 'undefined' otherwise.
+   */
+  getTxByHash(txHash: TxHash): Promise<Tx | undefined>;
+
+  /**
+   * Returns a set of transactions given their hashes if available.
+   * @param txHashes - The hashes of the transactions, used as an ID.
+   * @returns The transactions, if found, 'undefined' otherwise.
+   */
+  getTxsByHash(txHashes: TxHash[]): Promise<Tx[]>;
+}
+
+export const ProverCoordinationApiSchema: ApiSchemaFor<ProverCoordination> = {
+  getTxByHash: z.function().args(TxHash.schema).returns(Tx.schema.optional()),
+  getTxsByHash: z.function().args(z.array(TxHash.schema)).returns(z.array(Tx.schema)),
+};

package/src/interfaces/prover-node.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+import { type ApiSchemaFor, schemas } from '../schemas/index.js';
+
+const EpochProvingJobState = [
+  'initialized',
+  'processing',
+  'awaiting-prover',
+  'publishing-proof',
+  'completed',
+  'failed',
+  'stopped',
+  'timed-out',
+] as const;
+
+export type EpochProvingJobState = (typeof EpochProvingJobState)[number];
+
+export const EpochProvingJobTerminalState: EpochProvingJobState[] = [
+  'completed',
+  'failed',
+  'stopped',
+  'timed-out',
+] as const;
+
+export type EpochProvingJobTerminalState = (typeof EpochProvingJobTerminalState)[number];
+
+/** JSON RPC public interface to a prover node. */
+export interface ProverNodeApi {
+  getJobs(): Promise<{ uuid: string; status: EpochProvingJobState; epochNumber: number }[]>;
+
+  startProof(epochNumber: number): Promise<void>;
+
+  prove(epochNumber: number): Promise<void>;
+}
+
+/** Schemas for prover node API functions. */
+export const ProverNodeApiSchema: ApiSchemaFor<ProverNodeApi> = {
+  getJobs: z
+    .function()
+    .args()
+    .returns(z.array(z.object({ uuid: z.string(), status: z.enum(EpochProvingJobState), epochNumber: z.number() }))),
+
+  startProof: z.function().args(schemas.Integer).returns(z.void()),
+
+  prove: z.function().args(schemas.Integer).returns(z.void()),
+};

package/src/interfaces/proving-job-source.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+
+import type { ApiSchemaFor } from '../schemas/index.js';
+import { ProvingJob, ProvingJobId, ProvingJobResult } from './proving-job.js';
+
+export interface ProvingJobSource {
+  /**
+   * Gets the next proving job. `heartbeat` must be called periodically to keep the job alive.
+   * @returns The proving job, or undefined if there are no jobs available.
+   */
+  getProvingJob(): Promise<ProvingJob | undefined>;
+
+  /**
+   * Keeps the job alive. If this isn't called regularly then the job will be
+   * considered abandoned and re-queued for another consumer to pick up
+   * @param jobId The ID of the job to heartbeat.
+   */
+  heartbeat(jobId: string): Promise<void>;
+
+  /**
+   * Resolves a proving job.
+   * @param jobId - The ID of the job to resolve.
+   * @param result - The result of the proving job.
+   */
+  resolveProvingJob(jobId: string, result: ProvingJobResult): Promise<void>;
+
+  /**
+   * Rejects a proving job.
+   * @param jobId - The ID of the job to reject.
+   * @param reason - The reason for rejecting the job.
+   */
+  rejectProvingJob(jobId: string, reason: string): Promise<void>;
+}
+
+export const ProvingJobSourceSchema: ApiSchemaFor<ProvingJobSource> = {
+  getProvingJob: z.function().args().returns(ProvingJob.optional()),
+  heartbeat: z.function().args(ProvingJobId).returns(z.void()),
+  resolveProvingJob: z.function().args(ProvingJobId, ProvingJobResult).returns(z.void()),
+  rejectProvingJob: z.function().args(ProvingJobId, z.string()).returns(z.void()),
+};