@aztec/stdlib 4.0.0-nightly.20250907 → 4.0.0-nightly.20260108

package/src/interfaces/configs.ts

@@ -1,21 +1,22 @@
 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 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. */
@@ -38,10 +39,12 @@ export interface SequencerConfig {
   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) */
@@ -52,27 +55,67 @@ export interface SequencerConfig {
   skipCollectingAttestations?: boolean;
   /** Do not invalidate the previous block if invalid when we are the proposer (for testing only) */
   skipInvalidateBlockAsProposer?: boolean;
+  /** Broadcast invalid block proposals with corrupted state (for testing only) */
+  broadcastInvalidBlockProposal?: boolean;
+  /** Inject a fake attestation (for testing only) */
+  injectFakeAttestation?: 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;
+  /** Have sequencer build and publish an empty checkpoint if there are no txs */
+  buildCheckpointIfEmpty?: boolean;
 }
 
-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(),
-}) satisfies ZodFor<SequencerConfig>;
+export const SequencerConfigSchema = zodFor<SequencerConfig>()(
+  z.object({
+    sequencerPollingIntervalMS: z.number().optional(),
+    maxTxsPerBlock: z.number().optional(),
+    minValidTxsPerBlock: 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(),
+    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(),
+    fishermanMode: z.boolean().optional(),
+    shuffleAttestationOrdering: z.boolean().optional(),
+    blockDurationMs: z.number().positive().optional(),
+    buildCheckpointIfEmpty: z.boolean().optional(),
+  }),
+);
+
+type SequencerConfigOptionalKeys =
+  | 'governanceProposerPayload'
+  | 'blockDurationMs'
+  | 'coinbase'
+  | 'feeRecipient'
+  | 'acvmWorkingDirectory'
+  | 'acvmBinaryPath'
+  | 'fakeProcessingDelayPerTxMs'
+  | 'fakeThrowAfterProcessingTxCount'
+  | 'l1PublishingTime'
+  | 'txPublicSetupAllowList'
+  | 'minValidTxsPerBlock';
+
+export type ResolvedSequencerConfig = Prettify<
+  Required<Omit<SequencerConfig, SequencerConfigOptionalKeys>> & Pick<SequencerConfig, SequencerConfigOptionalKeys>
+>;

package/src/interfaces/epoch-prover.ts

@@ -1,36 +1,62 @@
-import type { BatchedBlob, FinalBlobBatchingChallenges } from '@aztec/blob-lib';
+import type { BatchedBlob, FinalBlobBatchingChallenges } from '@aztec/blob-lib/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 { L2Block } from '../block/l2_block.js';
 import type { Proof } from '../proofs/proof.js';
-import type { RootRollupPublicInputs } from '../rollup/root_rollup.js';
+import type { CheckpointConstantData } from '../rollup/checkpoint_constant_data.js';
+import type { RootRollupPublicInputs } from '../rollup/root_rollup_public_inputs.js';
 import type { BlockHeader } from '../tx/block_header.js';
 import type { Tx } from '../tx/tx.js';
+import type { UInt64 } from '../types/index.js';
 import type { IBlockFactory } from './block-builder.js';
 
 /** Coordinates the proving of an entire epoch. */
-export interface EpochProver extends Omit<IBlockFactory, 'setBlockCompleted'> {
+export interface EpochProver extends Omit<IBlockFactory, 'setBlockCompleted' | 'startNewBlock'> {
   /**
    * Starts a new epoch. Must be the first method to be called.
    * @param epochNumber - The epoch number.
-   * @param firstBlockNumber - The block number of the first block in the epoch.
-   * @param totalNumBlocks - The total number of blocks expected in the epoch (must be at least one).
+   * @param totalNumCheckpoints - The total number of checkpoints expected in the epoch (must be at least one).
+   * @param finalBlobBatchingChallenges - The final blob batching challenges for the epoch.
    **/
   startNewEpoch(
-    epochNumber: number,
-    firstBlockNumber: number,
-    totalNumBlocks: number,
+    epochNumber: EpochNumber,
+    totalNumCheckpoints: number,
     finalBlobBatchingChallenges: FinalBlobBatchingChallenges,
   ): void;
 
   /**
-   * Kickstarts tube circuits for the specified txs. These will be used during epoch proving.
-   * Note that if the tube circuits are not started this way, they will be started nontheless after processing.
+   * Starts a new checkpoint.
+   * @param checkpointIndex - The index of the checkpoint in the epoch.
+   * @param constants - The constants for this checkpoint.
+   * @param l1ToL2Messages - The set of L1 to L2 messages to be included in this checkpoint.
+   * @param totalNumBlocks - The total number of blocks expected in the checkpoint (must be at least one).
+   * @param headerOfLastBlockInPreviousCheckpoint - The header of the last block in the previous checkpoint.
+   */
+  startNewCheckpoint(
+    checkpointIndex: number,
+    constants: CheckpointConstantData,
+    l1ToL2Messages: Fr[],
+    totalNumBlocks: number,
+    headerOfLastBlockInPreviousCheckpoint: BlockHeader,
+  ): Promise<void>;
+
+  /**
+   * Starts a new block.
+   * @param blockNumber - The block number.
+   * @param timestamp - The timestamp of the block.
+   * @param totalNumTxs - The total number of txs in the block.
    */
-  startTubeCircuits(txs: Tx[]): 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.
+   * Note that if the chonk verifier circuits are not started this way, they will be started nonetheless after processing.
+   */
+  startChonkVerifierCircuits(txs: Tx[]): Promise<void>;
 
   /** Returns the block. */
-  setBlockCompleted(blockNumber: number, expectedBlockHeader?: BlockHeader): Promise<L2Block>;
+  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 }>;
@@ -41,9 +67,6 @@ export interface EpochProver extends Omit<IBlockFactory, 'setBlockCompleted'> {
   /** Returns an identifier for the prover or zero if not set. */
   getProverId(): EthAddress;
 
-  /** Returns the block assembled at a given index (zero-based) within the epoch. */
-  getBlock(index: number): L2Block;
-
   /** Called when no longer required, cleans up internal resources */
   stop(): Promise<void>;
 }

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,16 @@ 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 all 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.
    */
-  getPrivateLogs(from: number, limit: number): Promise<PrivateLog[]>;
+  getPrivateLogsByTags(tags: SiloedTag[]): 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 all 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.
    */
-  getLogsByTags(tags: Fr[], logsPerTag?: number): Promise<TxScopedL2Log[][]>;
+  getPublicLogsByTagsFromContract(contractAddress: AztecAddress, tags: Tag[]): Promise<TxScopedL2Log[][]>;
 
   /**
    * Gets public logs based on the provided filter.
@@ -44,5 +41,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';
 
@@ -7,6 +8,7 @@ import type { NullifierLeaf } from '../trees/nullifier_leaf.js';
 import type { PublicDataTreeLeaf } from '../trees/public_data_leaf.js';
 import type { BlockHeader } from '../tx/block_header.js';
 import type { StateReference } from '../tx/state_reference.js';
+import type { WorldStateRevision, WorldStateRevisionWithHandle } from '../world-state/world_state_revision.js';
 
 /**
  * Type alias for the nullifier tree ID.
@@ -132,6 +134,11 @@ export interface MerkleTreeReadOperations {
    */
   getInitialHeader(): BlockHeader;
 
+  /**
+   * Gets the current revision.
+   */
+  getRevision(): WorldStateRevision | WorldStateRevisionWithHandle;
+
   /**
    * Gets sibling path for a leaf.
    * @param treeId - The tree to be queried for a sibling path.
@@ -214,7 +221,7 @@ export interface MerkleTreeReadOperations {
   getBlockNumbersForLeafIndices<ID extends MerkleTreeId>(
     treeId: ID,
     leafIndices: bigint[],
-  ): Promise<(bigint | undefined)[]>;
+  ): Promise<(BlockNumber | undefined)[]>;
 }
 
 export interface MerkleTreeCheckpointOperations {
@@ -244,7 +251,10 @@ export interface MerkleTreeCheckpointOperations {
   revertAllCheckpoints(): Promise<void>;
 }
 
-export interface MerkleTreeWriteOperations extends MerkleTreeReadOperations, MerkleTreeCheckpointOperations {
+export interface MerkleTreeWriteOperations
+  extends MerkleTreeReadOperations,
+    MerkleTreeCheckpointOperations,
+    Disposable {
   /**
    * Appends leaves to a given tree.
    * @param treeId - The tree to be updated.

package/src/interfaces/p2p.ts

@@ -1,3 +1,5 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+
 import { z } from 'zod';
 
 import { BlockAttestation } from '../p2p/block_attestation.js';
@@ -56,7 +58,10 @@ export interface P2PApiWithAttestations extends P2PApiWithoutAttestations {
    * @param proposalId - the proposal id to query, or undefined to query all proposals for the slot
    * @returns BlockAttestations
    */
-  getAttestationsForSlot(slot: bigint, proposalId?: string): Promise<BlockAttestation[]>;
+  getAttestationsForSlot(slot: SlotNumber, proposalId?: string): Promise<BlockAttestation[]>;
+
+  /** Deletes a given attestation manually from the p2p client attestation pool. */
+  deleteAttestation(attestation: BlockAttestation): Promise<void>;
 }
 
 export interface P2PClient extends P2PApiWithAttestations {
@@ -75,7 +80,7 @@ export type P2PApiFull<T extends P2PClientType = P2PClientType.Full> = T extends
 export const P2PApiSchema: ApiSchemaFor<P2PApi> = {
   getAttestationsForSlot: z
     .function()
-    .args(schemas.BigInt, optional(z.string()))
+    .args(schemas.SlotNumber, optional(z.string()))
     .returns(z.array(BlockAttestation.schema)),
   getPendingTxs: z
     .function()
@@ -85,4 +90,5 @@ 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/private_kernel_prover.ts

@@ -10,7 +10,7 @@ import type {
   PrivateKernelTailCircuitPrivateInputs,
   PrivateKernelTailCircuitPublicInputs,
 } from '../kernel/index.js';
-import type { ClientIvcProof } from '../proofs/client_ivc_proof.js';
+import type { ChonkProofWithPublicInputs } from '../proofs/chonk_proof.js';
 
 /**
  * PrivateKernelProver provides functionality to simulate and validate circuits, and retrieve
@@ -110,7 +110,7 @@ export interface PrivateKernelProver {
    * @param acirs The program bytecode.
    * @param witnessStack The witnessses for each program bytecode.
    */
-  createClientIvcProof(executionSteps: PrivateExecutionStep[]): Promise<ClientIvcProof>;
+  createChonkProof(executionSteps: PrivateExecutionStep[]): Promise<ChonkProofWithPublicInputs>;
 
   /**
    * Compute the gate count for a given circuit.

package/src/interfaces/prover-client.ts

@@ -3,7 +3,7 @@ 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';
@@ -33,15 +33,18 @@ export type ProverConfig = ActualProverConfig & {
   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(),
+    failedProofStore: z.string().optional(),
+  }),
+);
 
 export const proverConfigMappings: ConfigMappingsType<ProverConfig> = {
   nodeUrl: {