@aztec/stdlib 0.0.1-commit.9b94fc1 → 0.0.1-commit.9ee6fcc6

package/src/interfaces/block-builder.ts

@@ -1,16 +1,17 @@
-import type { Fr } from '@aztec/foundation/fields';
-import type { Timer } from '@aztec/foundation/timer';
+import type { BlockNumber, CheckpointNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { LoggerBindings } from '@aztec/foundation/log';
 
 import type { L2Block } from '../block/l2_block.js';
 import type { ChainConfig, SequencerConfig } from '../config/chain-config.js';
 import type { L1RollupConstants } from '../epoch-helpers/index.js';
 import type { Gas } from '../gas/gas.js';
-import type { MerkleTreeWriteOperations } from '../trees/index.js';
 import type { BlockHeader } from '../tx/block_header.js';
-import type { GlobalVariables } from '../tx/global_variables.js';
+import type { CheckpointGlobalVariables, GlobalVariables } from '../tx/global_variables.js';
 import type { FailedTx, ProcessedTx } from '../tx/processed_tx.js';
 import { Tx } from '../tx/tx.js';
 import type { TxValidator } from '../tx/validator/tx_validator.js';
+import type { MerkleTreeWriteOperations } from './merkle_tree_operations.js';
 import type { ProcessedTxHandler } from './processed-tx-handler.js';
 
 /** The interface to a block builder. Generates an L2 block out of a set of processed txs. */
@@ -34,45 +35,119 @@ export interface IBlockFactory extends ProcessedTxHandler {
   setBlockCompleted(expectedBlockHeader?: BlockHeader): Promise<L2Block>;
 }
 
-export interface PublicProcessorLimits {
+/** Limits passed to the public processor for tx processing within a block. */
+export type PublicProcessorLimits = {
+  /** Maximum number of txs to process. */
   maxTransactions?: number;
-  maxBlockSize?: number;
+  /** L2 and DA gas limits. */
   maxBlockGas?: Gas;
+  /** Maximum number of blob fields allowed. */
   maxBlobFields?: number;
+  /** Deadline for processing the txs. Processor will stop as soon as it hits this time. */
   deadline?: Date;
-}
+  /** Whether this processor is building a proposal (as opposed to re-executing one). Skipping txs due to gas or blob limits is only done during proposal building. */
+  isBuildingProposal?: boolean;
+};
+
+/** Base fields shared by both proposer and validator block builder options. */
+type BlockBuilderOptionsBase = PublicProcessorLimits & {
+  /** Minimum number of successfully processed txs required. Block is rejected if fewer succeed. */
+  minValidTxs: number;
+};
+
+/** Proposer mode: redistribution params are required. */
+type ProposerBlockBuilderOptions = BlockBuilderOptionsBase & {
+  isBuildingProposal: true;
+  /** Maximum number of blocks per checkpoint, derived from the timetable. */
+  maxBlocksPerCheckpoint: number;
+  /** Per-block gas budget multiplier. Budget = (remaining / remainingBlocks) * multiplier. */
+  perBlockAllocationMultiplier: number;
+};
+
+/** Validator mode: no redistribution params needed. */
+type ValidatorBlockBuilderOptions = BlockBuilderOptionsBase & {
+  isBuildingProposal: false;
+};
+
+/** Options for building a block within a checkpoint. When proposing, redistribution params are required. */
+export type BlockBuilderOptions = ProposerBlockBuilderOptions | ValidatorBlockBuilderOptions;
 
 export interface PublicProcessorValidator {
   preprocessValidator?: TxValidator<Tx>;
   nullifierCache?: { addNullifiers: (nullifiers: Buffer[]) => void };
 }
-export interface BuildBlockResult {
+
+export type FullNodeBlockBuilderConfig = Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration' | 'rollupManaLimit'> &
+  Pick<ChainConfig, 'l1ChainId' | 'rollupVersion'> &
+  Pick<
+    SequencerConfig,
+    | 'txPublicSetupAllowListExtend'
+    | 'fakeProcessingDelayPerTxMs'
+    | 'fakeThrowAfterProcessingTxCount'
+    | 'maxTxsPerBlock'
+    | 'maxTxsPerCheckpoint'
+    | 'maxL2BlockGas'
+    | 'maxDABlockGas'
+  >;
+
+export const FullNodeBlockBuilderConfigKeys: (keyof FullNodeBlockBuilderConfig)[] = [
+  'l1GenesisTime',
+  'slotDuration',
+  'l1ChainId',
+  'rollupVersion',
+  'txPublicSetupAllowListExtend',
+  'fakeProcessingDelayPerTxMs',
+  'fakeThrowAfterProcessingTxCount',
+  'maxTxsPerBlock',
+  'maxTxsPerCheckpoint',
+  'maxL2BlockGas',
+  'maxDABlockGas',
+  'rollupManaLimit',
+] as const;
+
+/** Thrown when the number of successfully processed transactions is below the required minimum. */
+export class InsufficientValidTxsError extends Error {
+  constructor(
+    public readonly processedCount: number,
+    public readonly minRequired: number,
+    public readonly failedTxs: FailedTx[],
+  ) {
+    super(`Insufficient valid txs: got ${processedCount} but need ${minRequired}`);
+    this.name = 'InsufficientValidTxsError';
+  }
+}
+
+/** Result of building a block within a checkpoint. */
+export type BuildBlockInCheckpointResult = {
   block: L2Block;
-  publicGas: Gas;
   publicProcessorDuration: number;
-  numMsgs: number;
   numTxs: number;
   failedTxs: FailedTx[];
-  blockBuildingTimer: Timer;
   usedTxs: Tx[];
-}
-
-export type FullNodeBlockBuilderConfig = Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'> &
-  Pick<ChainConfig, 'l1ChainId' | 'rollupVersion'> &
-  Pick<SequencerConfig, 'txPublicSetupAllowList' | 'fakeProcessingDelayPerTxMs'>;
+};
 
-export interface IFullNodeBlockBuilder {
-  getConfig(): FullNodeBlockBuilderConfig;
+/** Interface for building blocks within a checkpoint context. */
+export interface ICheckpointBlockBuilder {
+  /** Builds a single block within this checkpoint. Throws InsufficientValidTxsError if fewer than minValidTxs succeed. */
+  buildBlock(
+    pendingTxs: Iterable<Tx> | AsyncIterable<Tx>,
+    blockNumber: BlockNumber,
+    timestamp: bigint,
+    opts: BlockBuilderOptions,
+  ): Promise<BuildBlockInCheckpointResult>;
+}
 
-  updateConfig(config: Partial<FullNodeBlockBuilderConfig>): void;
+/** Interface for creating checkpoint builders. */
+export interface ICheckpointsBuilder {
+  getFork(blockNumber: BlockNumber): Promise<MerkleTreeWriteOperations>;
 
-  buildBlock(
-    txs: Iterable<Tx> | AsyncIterable<Tx>,
+  startCheckpoint(
+    checkpointNumber: CheckpointNumber,
+    constants: CheckpointGlobalVariables,
+    feeAssetPriceModifier: bigint,
     l1ToL2Messages: Fr[],
-    globalVariables: GlobalVariables,
-    options: PublicProcessorLimits,
-    fork?: MerkleTreeWriteOperations,
-  ): Promise<BuildBlockResult>;
-
-  getFork(blockNumber: number): Promise<MerkleTreeWriteOperations>;
+    previousCheckpointOutHashes: Fr[],
+    fork: MerkleTreeWriteOperations,
+    bindings?: LoggerBindings,
+  ): Promise<ICheckpointBlockBuilder>;
 }

package/src/interfaces/configs.ts

@@ -1,27 +1,34 @@
 import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Prettify } from '@aztec/foundation/types';
 
 import { z } from 'zod';
 
 import type { AztecAddress } from '../aztec-address/index.js';
-import { type ZodFor, schemas } from '../schemas/index.js';
+import { schemas, zodFor } from '../schemas/index.js';
 import { type AllowedElement, AllowedElementSchema } from './allowed_element.js';
 
-/**
- * The sequencer configuration.
- */
+/** Sequencer configuration */
 export interface SequencerConfig {
   /** The number of ms to wait between polling for pending txs. */
-  transactionPollingIntervalMS?: number;
+  sequencerPollingIntervalMS?: number;
   /** The maximum number of txs to include in a block. */
   maxTxsPerBlock?: number;
+  /** The maximum number of txs across all blocks in a checkpoint. */
+  maxTxsPerCheckpoint?: number;
   /** The minimum number of txs to include in a block. */
   minTxsPerBlock?: number;
+  /** The minimum number of valid txs (after execution) to include in a block. If not set, falls back to minTxsPerBlock. */
+  minValidTxsPerBlock?: number;
   /** Whether to publish txs with the block proposals */
   publishTxsWithProposals?: boolean;
   /** The maximum L2 block gas. */
   maxL2BlockGas?: number;
   /** The maximum DA block gas. */
   maxDABlockGas?: number;
+  /** Per-block gas budget multiplier for both L2 and DA gas. Budget = (checkpointLimit / maxBlocks) * multiplier. */
+  perBlockAllocationMultiplier?: number;
+  /** Redistribute remaining checkpoint budget evenly across remaining blocks instead of allowing a single block to consume the entire remaining budget. */
+  redistributeCheckpointBudget?: boolean;
   /** Recipient of block reward. */
   coinbase?: EthAddress;
   /** Address to receive fees. */
@@ -30,18 +37,18 @@ export interface SequencerConfig {
   acvmWorkingDirectory?: string;
   /** The path to the ACVM binary */
   acvmBinaryPath?: string;
-  /** The list of functions calls allowed to run in setup */
-  txPublicSetupAllowList?: AllowedElement[];
-  /** Max block size */
-  maxBlockSizeInBytes?: number;
+  /** Additional entries to extend the default setup allow list. */
+  txPublicSetupAllowListExtend?: AllowedElement[];
   /** Payload address to vote for */
   governanceProposerPayload?: EthAddress;
   /** Whether to enforce the time table when building blocks */
   enforceTimeTable?: boolean;
-  /** How many seconds into an L1 slot we can still send a tx and get it mined. */
-  maxL1TxInclusionTimeIntoSlot?: number;
+  /** How much time (in seconds) we allow in the slot for publishing the L1 tx. */
+  l1PublishingTime?: number;
   /** Used for testing to introduce a fake delay after processing each tx */
   fakeProcessingDelayPerTxMs?: number;
+  /** Used for testing to throw an error after processing N txs */
+  fakeThrowAfterProcessingTxCount?: number;
   /** How many seconds it takes for proposals and attestations to travel across the p2p layer (one-way) */
   attestationPropagationTime?: number;
   /** How many seconds before invalidating a block as a committee member (zero to never invalidate) */
@@ -56,35 +63,90 @@ export interface SequencerConfig {
   broadcastInvalidBlockProposal?: boolean;
   /** Inject a fake attestation (for testing only) */
   injectFakeAttestation?: boolean;
+  /** Inject a malleable attestation with a high-s value (for testing only) */
+  injectHighSValueAttestation?: boolean;
+  /** Inject an attestation with an unrecoverable signature (for testing only) */
+  injectUnrecoverableSignatureAttestation?: boolean;
   /** Whether to run in fisherman mode: builds blocks on every slot for validation without publishing */
   fishermanMode?: boolean;
   /** Shuffle attestation ordering to create invalid ordering (for testing only) */
   shuffleAttestationOrdering?: boolean;
+  /** Duration per block in milliseconds when building multiple blocks per slot (default: undefined = single block per slot) */
+  blockDurationMs?: number;
+  /** Expected number of block proposals per slot for P2P peer scoring. 0 disables scoring, undefined falls back to blocksPerSlot - 1. */
+  expectedBlockProposalsPerSlot?: number;
+  /** Have sequencer build and publish an empty checkpoint if there are no txs */
+  buildCheckpointIfEmpty?: boolean;
+  /** Skip pushing proposed blocks to archiver (default: false) */
+  skipPushProposedBlocksToArchiver?: boolean;
+  /** Minimum number of blocks required for a checkpoint proposal (test only, defaults to undefined = no minimum) */
+  minBlocksForCheckpoint?: number;
+  /** Skip publishing checkpoint proposals probability (for testing checkpoint prunes only) */
+  skipPublishingCheckpointsPercent?: number;
 }
 
-export const SequencerConfigSchema = z.object({
-  transactionPollingIntervalMS: z.number().optional(),
-  maxTxsPerBlock: z.number().optional(),
-  minTxsPerBlock: z.number().optional(),
-  maxL2BlockGas: z.number().optional(),
-  publishTxsWithProposals: z.boolean().optional(),
-  maxDABlockGas: z.number().optional(),
-  coinbase: schemas.EthAddress.optional(),
-  feeRecipient: schemas.AztecAddress.optional(),
-  acvmWorkingDirectory: z.string().optional(),
-  acvmBinaryPath: z.string().optional(),
-  txPublicSetupAllowList: z.array(AllowedElementSchema).optional(),
-  maxBlockSizeInBytes: z.number().optional(),
-  governanceProposerPayload: schemas.EthAddress.optional(),
-  maxL1TxInclusionTimeIntoSlot: z.number().optional(),
-  enforceTimeTable: z.boolean().optional(),
-  fakeProcessingDelayPerTxMs: z.number().optional(),
-  attestationPropagationTime: z.number().optional(),
-  skipCollectingAttestations: z.boolean().optional(),
-  secondsBeforeInvalidatingBlockAsCommitteeMember: z.number(),
-  secondsBeforeInvalidatingBlockAsNonCommitteeMember: z.number(),
-  broadcastInvalidBlockProposal: z.boolean().optional(),
-  injectFakeAttestation: z.boolean().optional(),
-  fishermanMode: z.boolean().optional(),
-  shuffleAttestationOrdering: z.boolean().optional(),
-}) satisfies ZodFor<SequencerConfig>;
+export const SequencerConfigSchema = zodFor<SequencerConfig>()(
+  z.object({
+    sequencerPollingIntervalMS: z.number().optional(),
+    maxTxsPerBlock: z.number().optional(),
+    maxTxsPerCheckpoint: z.number().optional(),
+    minValidTxsPerBlock: z.number().optional(),
+    minTxsPerBlock: z.number().optional(),
+    maxL2BlockGas: z.number().optional(),
+    publishTxsWithProposals: z.boolean().optional(),
+    maxDABlockGas: z.number().optional(),
+    perBlockAllocationMultiplier: z.number().optional(),
+    redistributeCheckpointBudget: z.boolean().optional(),
+    coinbase: schemas.EthAddress.optional(),
+    feeRecipient: schemas.AztecAddress.optional(),
+    acvmWorkingDirectory: z.string().optional(),
+    acvmBinaryPath: z.string().optional(),
+    txPublicSetupAllowListExtend: z.array(AllowedElementSchema).optional(),
+    governanceProposerPayload: schemas.EthAddress.optional(),
+    l1PublishingTime: z.number().optional(),
+    enforceTimeTable: z.boolean().optional(),
+    fakeProcessingDelayPerTxMs: z.number().optional(),
+    fakeThrowAfterProcessingTxCount: z.number().optional(),
+    attestationPropagationTime: z.number().optional(),
+    skipCollectingAttestations: z.boolean().optional(),
+    skipInvalidateBlockAsProposer: z.boolean().optional(),
+    secondsBeforeInvalidatingBlockAsCommitteeMember: z.number(),
+    secondsBeforeInvalidatingBlockAsNonCommitteeMember: z.number(),
+    broadcastInvalidBlockProposal: z.boolean().optional(),
+    injectFakeAttestation: z.boolean().optional(),
+    injectHighSValueAttestation: z.boolean().optional(),
+    injectUnrecoverableSignatureAttestation: z.boolean().optional(),
+    fishermanMode: z.boolean().optional(),
+    shuffleAttestationOrdering: z.boolean().optional(),
+    blockDurationMs: z.number().positive().optional(),
+    expectedBlockProposalsPerSlot: z.number().nonnegative().optional(),
+    buildCheckpointIfEmpty: z.boolean().optional(),
+    skipPushProposedBlocksToArchiver: z.boolean().optional(),
+    minBlocksForCheckpoint: z.number().positive().optional(),
+    skipPublishingCheckpointsPercent: z.number().gte(0).lte(100).optional(),
+  }),
+);
+
+type SequencerConfigOptionalKeys =
+  | 'governanceProposerPayload'
+  | 'blockDurationMs'
+  | 'expectedBlockProposalsPerSlot'
+  | 'coinbase'
+  | 'feeRecipient'
+  | 'acvmWorkingDirectory'
+  | 'acvmBinaryPath'
+  | 'fakeProcessingDelayPerTxMs'
+  | 'fakeThrowAfterProcessingTxCount'
+  | 'l1PublishingTime'
+  | 'txPublicSetupAllowListExtend'
+  | 'minValidTxsPerBlock'
+  | 'minBlocksForCheckpoint'
+  | 'maxTxsPerBlock'
+  | 'maxTxsPerCheckpoint'
+  | 'maxL2BlockGas'
+  | 'maxDABlockGas'
+  | 'redistributeCheckpointBudget';
+
+export type ResolvedSequencerConfig = Prettify<
+  Required<Omit<SequencerConfig, SequencerConfigOptionalKeys>> & Pick<SequencerConfig, SequencerConfigOptionalKeys>
+>;

package/src/interfaces/epoch-prover.ts

@@ -1,7 +1,7 @@
 import type { BatchedBlob, FinalBlobBatchingChallenges } from '@aztec/blob-lib/types';
-import type { EpochNumber } from '@aztec/foundation/branded-types';
+import type { BlockNumber, EpochNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { EthAddress } from '@aztec/foundation/eth-address';
-import type { Fr } from '@aztec/foundation/fields';
 
 import type { Proof } from '../proofs/proof.js';
 import type { CheckpointConstantData } from '../rollup/checkpoint_constant_data.js';
@@ -47,7 +47,7 @@ export interface EpochProver extends Omit<IBlockFactory, 'setBlockCompleted' | '
    * @param timestamp - The timestamp of the block.
    * @param totalNumTxs - The total number of txs in the block.
    */
-  startNewBlock(blockNumber: number, timestamp: UInt64, totalNumTxs: number): Promise<void>;
+  startNewBlock(blockNumber: BlockNumber, timestamp: UInt64, totalNumTxs: number): Promise<void>;
 
   /**
    * Kickstarts chonk verifier circuits for the specified txs. These will be used during epoch proving.
@@ -56,7 +56,7 @@ export interface EpochProver extends Omit<IBlockFactory, 'setBlockCompleted' | '
   startChonkVerifierCircuits(txs: Tx[]): Promise<void>;
 
   /** Returns the block. */
-  setBlockCompleted(blockNumber: number, expectedBlockHeader?: BlockHeader): Promise<BlockHeader>;
+  setBlockCompleted(blockNumber: BlockNumber, expectedBlockHeader?: BlockHeader): Promise<BlockHeader>;
 
   /** Pads the epoch with empty block roots if needed and blocks until proven. Throws if proving has failed. */
   finalizeEpoch(): Promise<{ publicInputs: RootRollupPublicInputs; proof: Proof; batchedBlobInputs: BatchedBlob }>;

package/src/interfaces/get_logs_response.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 import { ExtendedContractClassLog } from '../logs/extended_contract_class_log.js';
 import { ExtendedPublicLog } from '../logs/extended_public_log.js';
-import type { ZodFor } from '../schemas/index.js';
+import { zodFor } from '../schemas/index.js';
 
 /** Response for the getContractClassLogs archiver call. */
 export type GetContractClassLogsResponse = {
@@ -12,10 +12,12 @@ export type GetContractClassLogsResponse = {
   maxLogsHit: boolean;
 };
 
-export const GetContractClassLogsResponseSchema: ZodFor<GetContractClassLogsResponse> = z.object({
-  logs: z.array(ExtendedContractClassLog.schema),
-  maxLogsHit: z.boolean(),
-});
+export const GetContractClassLogsResponseSchema = zodFor<GetContractClassLogsResponse>()(
+  z.object({
+    logs: z.array(ExtendedContractClassLog.schema),
+    maxLogsHit: z.boolean(),
+  }),
+);
 
 /** Response for the getPublicLogs archiver call. */
 export type GetPublicLogsResponse = {
@@ -25,7 +27,9 @@ export type GetPublicLogsResponse = {
   maxLogsHit: boolean;
 };
 
-export const GetPublicLogsResponseSchema = z.object({
-  logs: z.array(ExtendedPublicLog.schema),
-  maxLogsHit: z.boolean(),
-}) satisfies ZodFor<GetPublicLogsResponse>;
+export const GetPublicLogsResponseSchema = zodFor<GetPublicLogsResponse>()(
+  z.object({
+    logs: z.array(ExtendedPublicLog.schema),
+    maxLogsHit: z.boolean(),
+  }),
+);

package/src/interfaces/l2_logs_source.ts

@@ -1,7 +1,9 @@
-import type { Fr } from '@aztec/foundation/fields';
+import type { BlockNumber } from '@aztec/foundation/branded-types';
 
+import type { AztecAddress } from '../aztec-address/index.js';
 import type { LogFilter } from '../logs/log_filter.js';
-import type { PrivateLog } from '../logs/private_log.js';
+import type { SiloedTag } from '../logs/siloed_tag.js';
+import type { Tag } from '../logs/tag.js';
 import type { TxScopedL2Log } from '../logs/tx_scoped_l2_log.js';
 import type { GetContractClassLogsResponse, GetPublicLogsResponse } from './get_logs_response.js';
 
@@ -10,21 +12,32 @@ import type { GetContractClassLogsResponse, GetPublicLogsResponse } from './get_
  */
 export interface L2LogsSource {
   /**
-   * Retrieves all private logs from up to `limit` blocks, starting from the block number `from`.
-   * @param from - The block number from which to begin retrieving logs.
-   * @param limit - The maximum number of blocks to retrieve logs from.
-   * @returns An array of private logs from the specified range of blocks.
+   * Gets private logs that match any of the `tags`. For each tag, an array of matching logs is returned. An empty
+   * array implies no logs match that tag.
+   * @param tags - The tags to search for.
+   * @param page - The page number (0-indexed) for pagination.
+   * @param upToBlockNumber - If set, only return logs from blocks up to and including this block number.
+   * @returns An array of log arrays, one per tag. Returns at most 10 logs per tag per page. If 10 logs are returned
+   * for a tag, the caller should fetch the next page to check for more logs.
    */
-  getPrivateLogs(from: number, limit: number): Promise<PrivateLog[]>;
+  getPrivateLogsByTags(tags: SiloedTag[], page?: number, upToBlockNumber?: BlockNumber): Promise<TxScopedL2Log[][]>;
 
   /**
-   * Gets all logs that match any of the received tags (i.e. logs with their first field equal to a tag).
-   * @param tags - The tags to filter the logs by.
-   * @param logsPerTag - The maximum number of logs to return for each tag. Default returns everything
-   * @returns For each received tag, an array of matching logs is returned. An empty array implies no logs match
-   * that tag.
+   * Gets public logs that match any of the `tags` from the specified contract. For each tag, an array of matching
+   * logs is returned. An empty array implies no logs match that tag.
+   * @param contractAddress - The contract address to search logs for.
+   * @param tags - The tags to search for.
+   * @param page - The page number (0-indexed) for pagination.
+   * @param upToBlockNumber - If set, only return logs from blocks up to and including this block number.
+   * @returns An array of log arrays, one per tag. Returns at most 10 logs per tag per page. If 10 logs are returned
+   * for a tag, the caller should fetch the next page to check for more logs.
    */
-  getLogsByTags(tags: Fr[], logsPerTag?: number): Promise<TxScopedL2Log[][]>;
+  getPublicLogsByTagsFromContract(
+    contractAddress: AztecAddress,
+    tags: Tag[],
+    page?: number,
+    upToBlockNumber?: BlockNumber,
+  ): Promise<TxScopedL2Log[][]>;
 
   /**
    * Gets public logs based on the provided filter.
@@ -44,5 +57,5 @@ export interface L2LogsSource {
    * Gets the number of the latest L2 block processed by the implementation.
    * @returns The number of the latest L2 block processed by the implementation.
    */
-  getBlockNumber(): Promise<number>;
+  getBlockNumber(): Promise<BlockNumber>;
 }

package/src/interfaces/merkle_tree_operations.ts

@@ -1,4 +1,5 @@
-import type { Fr } from '@aztec/foundation/fields';
+import type { BlockNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
 import { type IndexedTreeLeafPreimage, SiblingPath } from '@aztec/foundation/trees';
 
@@ -220,37 +221,30 @@ export interface MerkleTreeReadOperations {
   getBlockNumbersForLeafIndices<ID extends MerkleTreeId>(
     treeId: ID,
     leafIndices: bigint[],
-  ): Promise<(bigint | undefined)[]>;
+  ): Promise<(BlockNumber | undefined)[]>;
 }
 
 export interface MerkleTreeCheckpointOperations {
-  /**
-   * Checkpoints the current fork state
-   */
-  createCheckpoint(): Promise<void>;
+  /** Checkpoints the current fork state. Returns the depth of the new checkpoint. */
+  createCheckpoint(): Promise<number>;
 
-  /**
-   * Commits the current checkpoint
-   */
+  /** Commits the current checkpoint. */
   commitCheckpoint(): Promise<void>;
 
-  /**
-   * Reverts the current checkpoint
-   */
+  /** Reverts the current checkpoint. */
   revertCheckpoint(): Promise<void>;
 
-  /**
-   * Commits all checkpoints
-   */
-  commitAllCheckpoints(): Promise<void>;
+  /** Commits all checkpoints above the given depth, leaving checkpoint depth at the given value. */
+  commitAllCheckpointsTo(depth: number): Promise<void>;
 
-  /**
-   * Reverts all checkpoints
-   */
-  revertAllCheckpoints(): Promise<void>;
+  /** Reverts all checkpoints above the given depth, leaving checkpoint depth at the given value. */
+  revertAllCheckpointsTo(depth: number): Promise<void>;
 }
 
-export interface MerkleTreeWriteOperations extends MerkleTreeReadOperations, MerkleTreeCheckpointOperations {
+export interface MerkleTreeWriteOperations
+  extends MerkleTreeReadOperations,
+    MerkleTreeCheckpointOperations,
+    AsyncDisposable {
   /**
    * Appends leaves to a given tree.
    * @param treeId - The tree to be updated.

package/src/interfaces/p2p.ts

@@ -2,8 +2,7 @@ import type { SlotNumber } from '@aztec/foundation/branded-types';
 
 import { z } from 'zod';
 
-import { BlockAttestation } from '../p2p/block_attestation.js';
-import type { P2PClientType } from '../p2p/client_type.js';
+import { CheckpointAttestation } from '../p2p/checkpoint_attestation.js';
 import { type ApiSchemaFor, optional, schemas } from '../schemas/index.js';
 import { Tx } from '../tx/tx.js';
 import { TxHash } from '../tx/tx_hash.js';
@@ -27,7 +26,7 @@ const PeerInfoSchema = z.discriminatedUnion('status', [
 ]);
 
 /** Exposed API to the P2P module. */
-export interface P2PApiWithoutAttestations {
+export interface P2PApi {
   /**
    * Returns all pending transactions in the transaction pool.
    * @param limit - The number of items to returns
@@ -48,40 +47,27 @@ export interface P2PApiWithoutAttestations {
    * Returns info for all connected, dialing, and cached peers.
    */
   getPeers(includePending?: boolean): Promise<PeerInfo[]>;
-}
 
-export interface P2PApiWithAttestations extends P2PApiWithoutAttestations {
   /**
-   * Queries the Attestation pool for 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
-   * @returns BlockAttestations
+   * @returns CheckpointAttestations
    */
-  getAttestationsForSlot(slot: SlotNumber, proposalId?: string): Promise<BlockAttestation[]>;
-
-  /** Deletes a given attestation manually from the p2p client attestation pool. */
-  deleteAttestation(attestation: BlockAttestation): Promise<void>;
+  getCheckpointAttestationsForSlot(slot: SlotNumber, proposalId?: string): Promise<CheckpointAttestation[]>;
 }
 
-export interface P2PClient extends P2PApiWithAttestations {
-  /** Manually adds an attestation to the p2p client attestation pool. */
-  addAttestations(attestations: BlockAttestation[]): Promise<void>;
+export interface P2PClient extends P2PApi {
+  /** Manually adds checkpoint attestations to the p2p client attestation pool. */
+  addOwnCheckpointAttestations(attestations: CheckpointAttestation[]): Promise<void>;
 }
 
-export type P2PApi<T extends P2PClientType = P2PClientType.Full> = T extends P2PClientType.Full
-  ? P2PApiWithAttestations
-  : P2PApiWithoutAttestations;
-
-export type P2PApiFull<T extends P2PClientType = P2PClientType.Full> = T extends P2PClientType.Full
-  ? P2PApiWithAttestations & P2PClient
-  : P2PApiWithoutAttestations;
-
 export const P2PApiSchema: ApiSchemaFor<P2PApi> = {
-  getAttestationsForSlot: z
+  getCheckpointAttestationsForSlot: z
     .function()
     .args(schemas.SlotNumber, optional(z.string()))
-    .returns(z.array(BlockAttestation.schema)),
+    .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))
@@ -90,5 +76,4 @@ export const P2PApiSchema: ApiSchemaFor<P2PApi> = {
   getPendingTxCount: z.function().returns(schemas.Integer),
   getEncodedEnr: z.function().returns(z.string().optional()),
   getPeers: z.function().args(optional(z.boolean())).returns(z.array(PeerInfoSchema)),
-  deleteAttestation: z.function().args(BlockAttestation.schema).returns(z.void()),
 };

package/src/interfaces/prover-broker.ts

@@ -1,3 +1,5 @@
+import type { EpochNumber } from '@aztec/foundation/branded-types';
+
 import type { ProvingRequestType } from '../proofs/proving_request_type.js';
 import type { ProofUri, ProvingJob, ProvingJobId, ProvingJobStatus } from './proving-job.js';
 
@@ -88,3 +90,23 @@ export interface ProvingJobConsumer {
 }
 
 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>;
+}