@aztec/stdlib 0.0.1-commit.d3ec352c → 0.0.1-commit.d58ff9d0

package/src/interfaces/prover-client.ts

@@ -3,9 +3,8 @@ import { EthAddress } from '@aztec/foundation/eth-address';
 
 import { z } from 'zod';
 
-import { type ZodFor, schemas } from '../schemas/index.js';
+import { schemas, zodFor } 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 = {
@@ -17,6 +16,14 @@ export type ActualProverConfig = {
   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;
 };
 
 /**
@@ -29,19 +36,27 @@ export type ProverConfig = ActualProverConfig & {
   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 = 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(),
-}) satisfies ZodFor<ProverConfig>;
+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: {
@@ -55,7 +70,7 @@ export const proverConfigMappings: ConfigMappingsType<ProverConfig> = {
   },
   proverId: {
     env: 'PROVER_ID',
-    parseEnv: (val?: string) => parseProverId(val),
+    parseEnv: (val: string) => parseProverId(val),
     description: 'Hex value that identifies the prover. Defaults to the address used for submitting proofs if not set.',
   },
   proverTestDelayType: {
@@ -77,27 +92,40 @@ export const proverConfigMappings: ConfigMappingsType<ProverConfig> = {
     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) {
-  if (!str) {
-    return undefined;
-  }
+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 {
-  createEpochProver(): EpochProver;
-
   start(): Promise<void>;
 
   stop(): Promise<void>;

package/src/interfaces/prover-node.ts

@@ -1,54 +1,69 @@
+import { createSafeJsonRpcClient, defaultFetch } from '@aztec/foundation/json-rpc/client';
+
 import { z } from 'zod';
 
-import { type L2Tips, L2TipsSchema } from '../block/l2_block_source.js';
 import { type ApiSchemaFor, schemas } from '../schemas/index.js';
-import { type WorldStateSyncStatus, WorldStateSyncStatusSchema } from './world_state.js';
+import { type ComponentsVersions, getVersioningResponseHandler } from '../versioning/index.js';
 
 const EpochProvingJobState = [
   'initialized',
-  'processing',
-  'awaiting-prover',
+  'awaiting-checkpoints',
+  'awaiting-root',
+  'awaiting-predecessor',
   'publishing-proof',
   'completed',
+  'superseded',
   'failed',
   'stopped',
+  'cancelled',
   'timed-out',
-  'reorg',
 ] as const;
 
 export type EpochProvingJobState = (typeof EpochProvingJobState)[number];
 
 export const EpochProvingJobTerminalState: EpochProvingJobState[] = [
   'completed',
+  'superseded',
   'failed',
   'stopped',
+  'cancelled',
   'timed-out',
-  'reorg',
 ] as const;
 
 export type EpochProvingJobTerminalState = (typeof EpochProvingJobTerminalState)[number];
 
-/** JSON RPC public interface to a prover node. */
+/** JSON RPC admin interface to a prover node. */
 export interface ProverNodeApi {
   getJobs(): Promise<{ uuid: string; status: EpochProvingJobState; epochNumber: number }[]>;
 
-  startProof(epochNumber: number): Promise<void>;
-
-  getL2Tips(): Promise<L2Tips>;
-
-  getWorldStateSyncStatus(): Promise<WorldStateSyncStatus>;
+  /**
+   * 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()
-    .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()),
+  getJobs: z.function({
+    input: z.tuple([]),
+    output: z.array(z.object({ uuid: z.string(), status: z.enum(EpochProvingJobState), epochNumber: z.number() })),
+  }),
 
-  getL2Tips: z.function().args().returns(L2TipsSchema),
-
-  getWorldStateSyncStatus: z.function().args().returns(WorldStateSyncStatusSchema),
+  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 } } : {}),
+  });
+}

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

@@ -33,8 +33,8 @@ export interface ProvingJobSource {
 }
 
 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()),
+  getProvingJob: z.function({ input: z.tuple([]), output: ProvingJob.optional() }),
+  heartbeat: z.function({ input: z.tuple([ProvingJobId]), output: z.void() }),
+  resolveProvingJob: z.function({ input: z.tuple([ProvingJobId, ProvingJobResult]), output: z.void() }),
+  rejectProvingJob: z.function({ input: z.tuple([ProvingJobId, z.string()]), output: z.void() }),
 };

package/src/interfaces/proving-job.ts

@@ -1,5 +1,5 @@
 import {
-  AVM_V2_PROOF_LENGTH_IN_FIELDS_PADDED,
+  AVM_V2_PROOF_LENGTH_IN_FIELDS,
   NESTED_RECURSIVE_PROOF_LENGTH,
   NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH,
   RECURSIVE_PROOF_LENGTH,
@@ -47,15 +47,6 @@ export type ProofAndVerificationKey<N extends number> = {
   verificationKey: VerificationKeyData;
 };
 
-function schemaForRecursiveProofAndVerificationKey<N extends number>(
-  proofLength: N,
-): ZodFor<ProofAndVerificationKey<N>> {
-  return z.object({
-    proof: RecursiveProof.schemaFor(proofLength),
-    verificationKey: VerificationKeyData.schema,
-  });
-}
-
 export function makeProofAndVerificationKey<N extends number>(
   proof: RecursiveProof<N>,
   verificationKey: VerificationKeyData,
@@ -213,7 +204,7 @@ export type ProvingJobInputsMap = {
 export const ProvingJobResult = z.discriminatedUnion('type', [
   z.object({
     type: z.literal(ProvingRequestType.PUBLIC_VM),
-    result: schemaForRecursiveProofAndVerificationKey(AVM_V2_PROOF_LENGTH_IN_FIELDS_PADDED),
+    result: RecursiveProof.schemaFor(AVM_V2_PROOF_LENGTH_IN_FIELDS),
   }),
   z.object({
     type: z.literal(ProvingRequestType.PUBLIC_CHONK_VERIFIER),
@@ -328,7 +319,7 @@ export const ProvingJobResult = z.discriminatedUnion('type', [
 ]);
 export type ProvingJobResult = z.infer<typeof ProvingJobResult>;
 export type ProvingJobResultsMap = {
-  [ProvingRequestType.PUBLIC_VM]: ProofAndVerificationKey<typeof AVM_V2_PROOF_LENGTH_IN_FIELDS_PADDED>;
+  [ProvingRequestType.PUBLIC_VM]: RecursiveProof<typeof AVM_V2_PROOF_LENGTH_IN_FIELDS>;
   [ProvingRequestType.PUBLIC_CHONK_VERIFIER]: PublicInputsAndRecursiveProof<
     PublicChonkVerifierPublicInputs,
     typeof NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH
@@ -397,8 +388,8 @@ export type ProvingRequestResultFor<T extends ProvingRequestType> = { type: T; r
 
 export const ProvingJobId = z.string();
 
-export const ProofUri = z.string().brand('ProvingJobUri');
-export type ProofUri = z.infer<typeof ProofUri>;
+export type ProofUri = string & z.$brand<'ProvingJobUri'>;
+export const ProofUri: ZodFor<ProofUri> = z.string().transform(value => value as ProofUri);
 
 export type ProvingJobId = z.infer<typeof ProvingJobId>;
 
@@ -409,7 +400,7 @@ type ProvingJobShape = {
   inputsUri: ProofUri;
 };
 
-export const ProvingJob: z.ZodType<ProvingJobShape, z.ZodTypeDef, any> = z.object({
+export const ProvingJob: z.ZodType<ProvingJobShape, any> = z.object({
   id: ProvingJobId,
   type: z.nativeEnum(ProvingRequestType),
   epochNumber: EpochNumberSchema,

package/src/interfaces/public_state_source.ts

@@ -1,4 +1,4 @@
-import type { Fr } from '@aztec/foundation/fields';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 
 import type { AztecAddress } from '../aztec-address/index.js';
 

package/src/interfaces/public_storage_override.ts

@@ -0,0 +1,26 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
+
+import { z } from 'zod';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+import { schemas } from '../schemas/schemas.js';
+
+/**
+ * A single public-storage override to inject before simulation. Identifies a slot in
+ * (contract, raw slot) space, not by leafSlot — the simulator computes the leafSlot internally
+ * via `computePublicDataTreeLeafSlot`.
+ */
+export type PublicStorageOverride = {
+  /** Contract that owns the storage slot. */
+  contract: AztecAddress;
+  /** Raw storage slot within the contract (not yet hashed into a tree key). */
+  slot: Fr;
+  /** Value to place at that slot for the duration of the simulation. */
+  value: Fr;
+};
+
+export const PublicStorageOverrideSchema = z.object({
+  contract: schemas.AztecAddress,
+  slot: schemas.Fr,
+  value: schemas.Fr,
+});

package/src/interfaces/server.ts

@@ -2,9 +2,13 @@ export * from './allowed_element.js';
 export * from './api_limit.js';
 export * from './archiver.js';
 export * from './aztec-node.js';
+export * from './block_response.js';
+export * from './chain_tips.js';
+export * from './checkpoint_parameter.js';
+export * from './checkpoint_response.js';
+export * from './l1_publish_info.js';
 export * from './block-builder.js';
 export * from './configs.js';
-export * from './epoch-prover.js';
 export * from './l2_logs_source.js';
 export * from './merkle_tree_operations.js';
 export * from './p2p-bootstrap.js';
@@ -13,7 +17,6 @@ export * from './processed-tx-handler.js';
 export * from './prover-agent.js';
 export * from './prover-broker.js';
 export * from './prover-client.js';
-export * from './prover-coordination.js';
 export * from './prover-node.js';
 export * from './proving-job-source.js';
 export * from './proving-job.js';

package/src/interfaces/server_circuit_prover.ts

@@ -1,5 +1,5 @@
 import type {
-  AVM_V2_PROOF_LENGTH_IN_FIELDS_PADDED,
+  AVM_V2_PROOF_LENGTH_IN_FIELDS,
   NESTED_RECURSIVE_PROOF_LENGTH,
   NESTED_RECURSIVE_ROLLUP_HONK_PROOF_LENGTH,
   RECURSIVE_PROOF_LENGTH,
@@ -9,6 +9,7 @@ import type { AvmCircuitInputs } from '../avm/avm.js';
 import type { ParityBasePrivateInputs } from '../parity/parity_base_private_inputs.js';
 import type { ParityPublicInputs } from '../parity/parity_public_inputs.js';
 import type { ParityRootPrivateInputs } from '../parity/parity_root_private_inputs.js';
+import type { RecursiveProof } from '../proofs/recursive_proof.js';
 import type { BlockMergeRollupPrivateInputs } from '../rollup/block_merge_rollup_private_inputs.js';
 import type { BlockRollupPublicInputs } from '../rollup/block_rollup_public_inputs.js';
 import type {
@@ -34,7 +35,7 @@ import type { RootRollupPublicInputs } from '../rollup/root_rollup_public_inputs
 import type { TxMergeRollupPrivateInputs } from '../rollup/tx_merge_rollup_private_inputs.js';
 import type { TxRollupPublicInputs } from '../rollup/tx_rollup_public_inputs.js';
 import type { Tx } from '../tx/tx.js';
-import type { ProofAndVerificationKey, PublicInputsAndRecursiveProof } from './proving-job.js';
+import type { PublicInputsAndRecursiveProof } from './proving-job.js';
 
 /**
  * Generates proofs for parity and rollup circuits.
@@ -186,10 +187,9 @@ export interface ServerCircuitProver {
    */
   getAvmProof(
     inputs: AvmCircuitInputs,
-    skipPublicInputsValidation?: boolean, // TODO(#14234)[Unconditional PIs validation]: Remove.
     signal?: AbortSignal,
     epochNumber?: number,
-  ): Promise<ProofAndVerificationKey<typeof AVM_V2_PROOF_LENGTH_IN_FIELDS_PADDED>>;
+  ): Promise<RecursiveProof<typeof AVM_V2_PROOF_LENGTH_IN_FIELDS>>;
 }
 
 export type IVCProofVerificationResult = {

package/src/interfaces/slasher.ts

@@ -1,25 +1,30 @@
 import type { EthAddress } from '@aztec/foundation/eth-address';
-import { type ZodFor, schemas } from '@aztec/foundation/schemas';
+import { schemas, zodFor } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
 
-export type SlasherClientType = 'empire' | 'tally';
-
 export interface SlasherConfig {
   slashOverridePayload?: EthAddress;
-  slashMinPenaltyPercentage: number;
-  slashMaxPenaltyPercentage: number;
   slashSelfAllowed?: boolean; // Whether to allow slashes to own validators
   slashValidatorsAlways: EthAddress[]; // Array of validator addresses
   slashValidatorsNever: EthAddress[]; // Array of validator addresses
   slashInactivityTargetPercentage: number; // 0-1, 0.9 means 90%. Must be greater than 0
   slashInactivityConsecutiveEpochThreshold: number; // Number of consecutive epochs a validator must be inactive before slashing
-  slashPrunePenalty: bigint;
   slashDataWithholdingPenalty: bigint;
+  /**
+   * Number of full L2 slots that must elapse after a checkpoint's slot before declaring its
+   * txs missing and slashing the checkpoint's attesters for data withholding. With tolerance
+   * = N and checkpoint slot S, the check fires at the start of slot `S + N + 1`.
+   */
+  slashDataWithholdingToleranceSlots: number;
   slashInactivityPenalty: bigint;
   slashBroadcastedInvalidBlockPenalty: bigint;
+  slashBroadcastedInvalidCheckpointProposalPenalty: bigint;
+  slashDuplicateProposalPenalty: bigint;
+  slashDuplicateAttestationPenalty: bigint;
   slashProposeInvalidAttestationsPenalty: bigint;
-  slashAttestDescendantOfInvalidPenalty: bigint;
+  slashProposeDescendantOfCheckpointWithInvalidAttestationsPenalty: bigint;
+  slashAttestInvalidCheckpointProposalPenalty: bigint;
   slashUnknownPenalty: bigint;
   slashOffenseExpirationRounds: number; // Number of rounds after which pending offenses expire
   slashMaxPayloadSize: number; // Maximum number of offenses to include in a single slash payload
@@ -27,24 +32,32 @@ export interface SlasherConfig {
   slashExecuteRoundsLookBack: number; // How many rounds to look back when searching for a round to execute
 }
 
-export const SlasherConfigSchema = z.object({
-  slashOverridePayload: schemas.EthAddress.optional(),
-  slashMinPenaltyPercentage: z.number(),
-  slashMaxPenaltyPercentage: z.number(),
-  slashValidatorsAlways: z.array(schemas.EthAddress),
-  slashValidatorsNever: z.array(schemas.EthAddress),
-  slashPrunePenalty: schemas.BigInt,
-  slashDataWithholdingPenalty: schemas.BigInt,
-  slashInactivityTargetPercentage: z.number(),
-  slashInactivityConsecutiveEpochThreshold: z.number(),
-  slashInactivityPenalty: schemas.BigInt,
-  slashProposeInvalidAttestationsPenalty: schemas.BigInt,
-  slashAttestDescendantOfInvalidPenalty: schemas.BigInt,
-  slashUnknownPenalty: schemas.BigInt,
-  slashOffenseExpirationRounds: z.number(),
-  slashMaxPayloadSize: z.number(),
-  slashGracePeriodL2Slots: z.number(),
-  slashBroadcastedInvalidBlockPenalty: schemas.BigInt,
-  slashExecuteRoundsLookBack: z.number(),
-  slashSelfAllowed: z.boolean().optional(),
-}) satisfies ZodFor<SlasherConfig>;
+export const SlasherConfigSchema = zodFor<SlasherConfig>()(
+  z.object({
+    slashOverridePayload: schemas.EthAddress.optional(),
+    slashValidatorsAlways: z.array(schemas.EthAddress),
+    slashValidatorsNever: z.array(schemas.EthAddress),
+    slashDataWithholdingPenalty: schemas.BigInt,
+    // Tolerated as undefined to allow validating responses from older node images that
+    // predate the per-slot data-withholding watcher (PR #23116).
+    slashDataWithholdingToleranceSlots: z.number().default(3),
+    slashInactivityTargetPercentage: z.number(),
+    slashInactivityConsecutiveEpochThreshold: z.number(),
+    slashInactivityPenalty: schemas.BigInt,
+    slashProposeInvalidAttestationsPenalty: schemas.BigInt,
+    // Tolerated as undefined to allow validating responses from older node images that
+    // predate this slasher penalty being added.
+    slashBroadcastedInvalidCheckpointProposalPenalty: schemas.BigInt.default(0n),
+    slashDuplicateProposalPenalty: schemas.BigInt,
+    slashDuplicateAttestationPenalty: schemas.BigInt,
+    slashProposeDescendantOfCheckpointWithInvalidAttestationsPenalty: schemas.BigInt,
+    slashAttestInvalidCheckpointProposalPenalty: schemas.BigInt,
+    slashUnknownPenalty: schemas.BigInt,
+    slashOffenseExpirationRounds: z.number(),
+    slashMaxPayloadSize: z.number(),
+    slashGracePeriodL2Slots: z.number(),
+    slashBroadcastedInvalidBlockPenalty: schemas.BigInt,
+    slashExecuteRoundsLookBack: z.number(),
+    slashSelfAllowed: z.boolean().optional(),
+  }),
+);

package/src/interfaces/tx_provider.ts

@@ -1,4 +1,4 @@
-import type { L2BlockNew } from '@aztec/stdlib/block';
+import type { L2Block } from '@aztec/stdlib/block';
 import type { BlockProposal } from '@aztec/stdlib/p2p';
 import { type Tx, TxHash } from '@aztec/stdlib/tx';
 
@@ -7,11 +7,17 @@ import type { PeerId } from '@libp2p/interface';
 export interface ITxProvider {
   getAvailableTxs(txHashes: TxHash[]): Promise<{ txs: Tx[]; missingTxs: TxHash[] }>;
 
+  /**
+   * Checks whether each tx hash is currently held by the local tx pool. Returns a parallel
+   * boolean array (one entry per input hash). Does not fetch from the network.
+   */
+  hasTxs(txHashes: TxHash[]): Promise<boolean[]>;
+
   getTxsForBlockProposal(
     blockProposal: BlockProposal,
     blockNumber: number,
     opts: { pinnedPeer: PeerId | undefined; deadline: Date },
   ): Promise<{ txs: Tx[]; missingTxs: TxHash[] }>;
 
-  getTxsForBlock(block: L2BlockNew, opts: { deadline: Date }): Promise<{ txs: Tx[]; missingTxs: TxHash[] }>;
+  getTxsForBlock(block: L2Block, opts: { deadline: Date }): Promise<{ txs: Tx[]; missingTxs: TxHash[] }>;
 }