@aztec/stdlib 5.0.0-private.20260318 → 5.0.0-rc.1

package/src/interfaces/p2p.ts

@@ -1,19 +1,23 @@
-import type { SlotNumber } from '@aztec/foundation/branded-types';
+import type { CheckpointProposalHash, SlotNumber } from '@aztec/foundation/branded-types';
+import { bufferSchemaFor } from '@aztec/foundation/schemas';
 
 import { z } from 'zod';
 
+import { BlockProposal } from '../p2p/block_proposal.js';
 import { CheckpointAttestation } from '../p2p/checkpoint_attestation.js';
+import { CheckpointProposal, type CheckpointProposalCore } from '../p2p/checkpoint_proposal.js';
 import { type ApiSchemaFor, optional, schemas } from '../schemas/index.js';
 import { Tx } from '../tx/tx.js';
 import { TxHash } from '../tx/tx_hash.js';
 import { MAX_RPC_TXS_LEN } from './api_limit.js';
+import { type GetTxByHashOptions, GetTxByHashOptionsSchema } from './get_tx_by_hash_options.js';
 
 export type PeerInfo =
   | { status: 'connected'; score: number; id: string }
   | { status: 'dialing'; dialStatus: string; id: string; addresses: string[] }
   | { status: 'cached'; id: string; addresses: string[]; enr: string; dialAttempts: number };
 
-const PeerInfoSchema = z.discriminatedUnion('status', [
+export const PeerInfoSchema = z.discriminatedUnion('status', [
   z.object({ status: z.literal('connected'), score: z.number(), id: z.string() }),
   z.object({ status: z.literal('dialing'), dialStatus: z.string(), id: z.string(), addresses: z.array(z.string()) }),
   z.object({
@@ -28,12 +32,14 @@ const PeerInfoSchema = z.discriminatedUnion('status', [
 /** Exposed API to the P2P module. */
 export interface P2PApi {
   /**
-   * Returns all pending transactions in the transaction pool.
+   * Returns all pending transactions in the transaction pool. The txs' proofs are stripped unless
+   * `includeProof` is set.
    * @param limit - The number of items to returns
    * @param after - The last known pending tx. Used for pagination
+   * @param options - Options for the returned txs (eg whether to include their proofs).
    * @returns An array of Txs.
    */
-  getPendingTxs(limit?: number, after?: TxHash): Promise<Tx[]>;
+  getPendingTxs(limit?: number, after?: TxHash, options?: GetTxByHashOptions): Promise<Tx[]>;
 
   /** Returns the number of pending txs in the p2p tx pool. */
   getPendingTxCount(): Promise<number>;
@@ -49,31 +55,65 @@ export interface P2PApi {
   getPeers(includePending?: boolean): Promise<PeerInfo[]>;
 
   /**
-   * Queries the Attestation pool for checkpoint attestations for the given slot
+   * Queries the Attestation pool for checkpoint attestations for the given slot.
    *
    * @param slot - the slot to query
-   * @param proposalId - the proposal id to query, or undefined to query all proposals for the slot
+   * @param proposalPayloadHash - hex-encoded keccak256 of the target proposal's signed
+   *        payload (`CheckpointProposal.getPayloadHash()`). When provided, only
+   *        attestations whose own signed payload hashes to the same value are returned.
+   *        When omitted, all attestations for the slot are returned.
    * @returns CheckpointAttestations
    */
-  getCheckpointAttestationsForSlot(slot: SlotNumber, proposalId?: string): Promise<CheckpointAttestation[]>;
+  getCheckpointAttestationsForSlot(
+    slot: SlotNumber,
+    proposalPayloadHash?: CheckpointProposalHash,
+  ): Promise<CheckpointAttestation[]>;
 }
 
+export type ProposalsForSlot = {
+  blockProposals: BlockProposal[];
+  checkpointProposals: CheckpointProposalCore[];
+};
+
 export interface P2PClient extends P2PApi {
   /** Manually adds checkpoint attestations to the p2p client attestation pool. */
   addOwnCheckpointAttestations(attestations: CheckpointAttestation[]): Promise<void>;
+
+  /** Returns retained signed proposals for a slot. */
+  getProposalsForSlot(slot: SlotNumber): Promise<ProposalsForSlot>;
+
+  /** Returns whether a checkpoint proposal was retained for a slot. */
+  hasCheckpointProposalForSlot(slot: SlotNumber): Promise<boolean>;
 }
 
+const MAX_PROPOSALS_FOR_SLOT_RPC_LEN = 256;
+
+export const BlockProposalSchema = bufferSchemaFor(BlockProposal);
+export const CheckpointProposalSchema = bufferSchemaFor(CheckpointProposal);
+
+export const ProposalsForSlotSchema = z.object({
+  blockProposals: z.array(BlockProposalSchema).max(MAX_PROPOSALS_FOR_SLOT_RPC_LEN),
+  checkpointProposals: z.array(CheckpointProposalSchema).max(MAX_PROPOSALS_FOR_SLOT_RPC_LEN),
+});
+
 export const P2PApiSchema: ApiSchemaFor<P2PApi> = {
-  getCheckpointAttestationsForSlot: z
-    .function()
-    .args(schemas.SlotNumber, optional(z.string()))
-    .returns(z.array(CheckpointAttestation.schema)),
-  getPendingTxs: z
-    .function()
-    .args(optional(z.number().gte(1).lte(MAX_RPC_TXS_LEN).default(MAX_RPC_TXS_LEN)), optional(TxHash.schema))
-    .returns(z.array(Tx.schema)),
-
-  getPendingTxCount: z.function().returns(schemas.Integer),
-  getEncodedEnr: z.function().returns(z.string().optional()),
-  getPeers: z.function().args(optional(z.boolean())).returns(z.array(PeerInfoSchema)),
+  getCheckpointAttestationsForSlot: z.function({
+    input: z.tuple([
+      schemas.SlotNumber,
+      optional(z.string().regex(/^0x[0-9a-fA-F]+$/) as unknown as z.ZodType<CheckpointProposalHash>),
+    ]),
+    output: z.array(CheckpointAttestation.schema),
+  }),
+  getPendingTxs: z.function({
+    input: z.tuple([
+      optional(z.number().gte(1).lte(MAX_RPC_TXS_LEN).default(MAX_RPC_TXS_LEN)),
+      optional(TxHash.schema),
+      optional(GetTxByHashOptionsSchema),
+    ]),
+    output: z.array(Tx.schema),
+  }),
+
+  getPendingTxCount: z.function({ input: z.tuple([]), output: schemas.Integer }),
+  getEncodedEnr: z.function({ input: z.tuple([]), output: z.string().optional() }),
+  getPeers: z.function({ input: z.tuple([optional(z.boolean())]), output: z.array(PeerInfoSchema) }),
 };

package/src/interfaces/private_kernel_prover.ts

@@ -3,7 +3,11 @@ import type {
   HidingKernelToRollupPrivateInputs,
   PrivateExecutionStep,
   PrivateKernelCircuitPublicInputs,
+  PrivateKernelInit2CircuitPrivateInputs,
+  PrivateKernelInit3CircuitPrivateInputs,
   PrivateKernelInitCircuitPrivateInputs,
+  PrivateKernelInner2CircuitPrivateInputs,
+  PrivateKernelInner3CircuitPrivateInputs,
   PrivateKernelInnerCircuitPrivateInputs,
   PrivateKernelResetCircuitPrivateInputs,
   PrivateKernelSimulateOutput,
@@ -37,6 +41,48 @@ export interface PrivateKernelProver {
     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 given previous kernel data and private call data for an inner iteration.
    *
@@ -57,6 +103,48 @@ export interface PrivateKernelProver {
     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 by resetting the arrays using the reset circuit.
    *

package/src/interfaces/prover-agent.ts

@@ -15,5 +15,5 @@ export interface ProverAgentApi {
 }
 
 export const ProverAgentApiSchema: ApiSchemaFor<ProverAgentApi> = {
-  getStatus: z.function().args().returns(ProverAgentStatusSchema),
+  getStatus: z.function({ input: z.tuple([]), output: ProverAgentStatusSchema }),
 };

package/src/interfaces/prover-client.ts

@@ -5,7 +5,6 @@ import { z } from 'zod';
 
 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 = {
@@ -71,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: {
@@ -117,20 +116,16 @@ export const proverConfigMappings: ConfigMappingsType<ProverConfig> = {
   },
 };
 
-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

@@ -6,24 +6,26 @@ import { type WorldStateSyncStatus, WorldStateSyncStatusSchema } from './world_s
 
 const EpochProvingJobState = [
   'initialized',
-  'processing',
-  'awaiting-prover',
+  'awaiting-checkpoints',
+  '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];
@@ -32,7 +34,12 @@ export type EpochProvingJobTerminalState = (typeof EpochProvingJobTerminalState)
 export interface ProverNodeApi {
   getJobs(): Promise<{ uuid: string; status: EpochProvingJobState; epochNumber: number }[]>;
 
-  startProof(epochNumber: number): Promise<void>;
+  /**
+   * 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>;
 
   getL2Tips(): Promise<L2Tips>;
 
@@ -41,14 +48,14 @@ export interface ProverNodeApi {
 
 /** 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() }))),
+  getJobs: z.function({
+    input: z.tuple([]),
+    output: z.array(z.object({ uuid: z.string(), status: z.enum(EpochProvingJobState), epochNumber: z.number() })),
+  }),
 
-  startProof: z.function().args(schemas.Integer).returns(z.void()),
+  startProof: z.function({ input: z.tuple([schemas.Integer]), output: z.string() }),
 
-  getL2Tips: z.function().args().returns(L2TipsSchema),
+  getL2Tips: z.function({ input: z.tuple([]), output: L2TipsSchema }),
 
-  getWorldStateSyncStatus: z.function().args().returns(WorldStateSyncStatusSchema),
+  getWorldStateSyncStatus: z.function({ input: z.tuple([]), output: WorldStateSyncStatusSchema }),
 };

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

@@ -388,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>;
 
@@ -400,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_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';

package/src/interfaces/slasher.ts

@@ -3,25 +3,28 @@ 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
@@ -32,19 +35,23 @@ export interface SlasherConfig {
 export const SlasherConfigSchema = zodFor<SlasherConfig>()(
   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,
+    // 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,
-    slashAttestDescendantOfInvalidPenalty: schemas.BigInt,
+    slashProposeDescendantOfCheckpointWithInvalidAttestationsPenalty: schemas.BigInt,
+    slashAttestInvalidCheckpointProposalPenalty: schemas.BigInt,
     slashUnknownPenalty: schemas.BigInt,
     slashOffenseExpirationRounds: z.number(),
     slashMaxPayloadSize: z.number(),

package/src/interfaces/tx_provider.ts

@@ -7,6 +7,12 @@ 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,