@aztec/stdlib 3.0.0-nightly.20251221 → 3.0.0-nightly.20251223

package/src/checkpoint/checkpoint.ts

@@ -1,5 +1,6 @@
 import { encodeCheckpointBlobDataFromBlocks } from '@aztec/blob-lib/encoding';
 import { BlockNumber, CheckpointNumber, CheckpointNumberSchema } from '@aztec/foundation/branded-types';
+import { sum } from '@aztec/foundation/collection';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
@@ -9,6 +10,7 @@ import { z } from 'zod';
 import { L2BlockNew } from '../block/l2_block_new.js';
 import { CheckpointHeader } from '../rollup/checkpoint_header.js';
 import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import type { CheckpointInfo } from './checkpoint_info.js';
 
 export class Checkpoint {
   constructor(
@@ -68,6 +70,36 @@ export class Checkpoint {
     return this.blocks.at(-1)!.header.state;
   }
 
+  public toCheckpointInfo(): CheckpointInfo {
+    return {
+      archive: this.archive.root,
+      slotNumber: this.header.slotNumber,
+      checkpointNumber: this.number,
+      timestamp: this.header.timestamp,
+    };
+  }
+
+  /** Returns stats used for logging */
+  public getStats() {
+    const txEffects = this.blocks.flatMap(block => block.body.txEffects);
+
+    const logsStats = {
+      privateLogCount: sum(txEffects.map(tx => tx.privateLogs.length)),
+      publicLogCount: sum(txEffects.map(tx => tx.publicLogs.length)),
+      contractClassLogCount: sum(txEffects.map(tx => tx.contractClassLogs.length)),
+      contractClassLogSize: sum(txEffects.map(tx => sum(tx.contractClassLogs.map(log => log.emittedLength)))),
+    };
+
+    return {
+      txCount: txEffects.length,
+      blockCount: this.blocks.length,
+      slotNumber: this.header.slotNumber,
+      checkpointNumber: this.number,
+      timestamp: this.header.timestamp,
+      ...logsStats,
+    };
+  }
+
   static async random(
     checkpointNumber = CheckpointNumber(1),
     {

package/src/checkpoint/checkpoint_info.ts

@@ -0,0 +1,9 @@
+import type { CheckpointNumber } from '@aztec/foundation/branded-types';
+import type { Fr, SlotNumber } from '@aztec/foundation/schemas';
+
+export type CheckpointInfo = {
+  archive: Fr;
+  slotNumber: SlotNumber;
+  checkpointNumber: CheckpointNumber;
+  timestamp: bigint;
+};

package/src/interfaces/block-builder.ts

@@ -60,7 +60,17 @@ export interface BuildBlockResult {
 
 export type FullNodeBlockBuilderConfig = Pick<L1RollupConstants, 'l1GenesisTime' | 'slotDuration'> &
   Pick<ChainConfig, 'l1ChainId' | 'rollupVersion'> &
-  Pick<SequencerConfig, 'txPublicSetupAllowList' | 'fakeProcessingDelayPerTxMs'>;
+  Pick<SequencerConfig, 'txPublicSetupAllowList' | 'fakeProcessingDelayPerTxMs' | 'fakeThrowAfterProcessingTxCount'>;
+
+export const FullNodeBlockBuilderConfigKeys: (keyof FullNodeBlockBuilderConfig)[] = [
+  'l1GenesisTime',
+  'slotDuration',
+  'l1ChainId',
+  'rollupVersion',
+  'txPublicSetupAllowList',
+  'fakeProcessingDelayPerTxMs',
+  'fakeThrowAfterProcessingTxCount',
+] as const;
 
 export interface IFullNodeBlockBuilder {
   getConfig(): FullNodeBlockBuilderConfig;

package/src/interfaces/configs.ts

@@ -1,4 +1,5 @@
 import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Prettify } from '@aztec/foundation/types';
 
 import { z } from 'zod';
 
@@ -6,16 +7,16 @@ import type { AztecAddress } from '../aztec-address/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) */
@@ -60,12 +63,17 @@ export interface SequencerConfig {
   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 = zodFor<SequencerConfig>()(
   z.object({
-    transactionPollingIntervalMS: z.number().optional(),
+    sequencerPollingIntervalMS: z.number().optional(),
     maxTxsPerBlock: z.number().optional(),
+    minValidTxsPerBlock: z.number().optional(),
     minTxsPerBlock: z.number().optional(),
     maxL2BlockGas: z.number().optional(),
     publishTxsWithProposals: z.boolean().optional(),
@@ -77,9 +85,10 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     txPublicSetupAllowList: z.array(AllowedElementSchema).optional(),
     maxBlockSizeInBytes: z.number().optional(),
     governanceProposerPayload: schemas.EthAddress.optional(),
-    maxL1TxInclusionTimeIntoSlot: z.number().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(),
@@ -89,5 +98,24 @@ export const SequencerConfigSchema = zodFor<SequencerConfig>()(
     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/merkle_tree_operations.ts

@@ -251,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/world_state.ts

@@ -42,8 +42,13 @@ export interface WorldStateSynchronizerStatus {
 
 /** Provides writeable forks of the world state at a given block number. */
 export interface ForkMerkleTreeOperations {
-  /** Forks the world state at the given block number, defaulting to the latest one. */
-  fork(block?: BlockNumber): Promise<MerkleTreeWriteOperations>;
+  /**
+   * Forks the world state at the given block number, defaulting to the latest one.
+   * @param block - The block number to fork at.
+   * @param opts - Optional parameters:
+   *  - closeDelayMs: number of milliseconds to wait before closing the fork on dispose.
+   */
+  fork(block?: BlockNumber, opts?: { closeDelayMs?: number }): Promise<MerkleTreeWriteOperations>;
 
   /** Gets a handle that allows reading the state as it was at the given block number. */
   getSnapshot(blockNumber: BlockNumber): MerkleTreeReadOperations;

package/src/logs/tx_scoped_l2_log.ts

@@ -1,10 +1,12 @@
 import { BlockNumber, BlockNumberSchema } from '@aztec/foundation/branded-types';
-import { BufferReader, boolToBuffer, numToUInt32BE } from '@aztec/foundation/serialize';
+import { BufferReader, bigintToUInt64BE, boolToBuffer, numToUInt32BE } from '@aztec/foundation/serialize';
 
 import { z } from 'zod';
 
 import { L2BlockHash } from '../block/block_hash.js';
+import { schemas } from '../schemas/schemas.js';
 import { TxHash } from '../tx/tx_hash.js';
+import type { UInt64 } from '../types/shared.js';
 import { PrivateLog } from './private_log.js';
 import { PublicLog } from './public_log.js';
 
@@ -33,6 +35,10 @@ export class TxScopedL2Log {
      * The block this log is included in
      */
     public blockHash: L2BlockHash,
+    /*
+     * The timestamp of the block this log is included in
+     */
+    public blockTimestamp: UInt64,
     /*
      * The log data as either a PrivateLog or PublicLog
      */
@@ -51,11 +57,12 @@ export class TxScopedL2Log {
         logIndexInTx: z.number(),
         blockNumber: BlockNumberSchema,
         blockHash: L2BlockHash.schema,
+        blockTimestamp: schemas.UInt64,
         log: z.union([PrivateLog.schema, PublicLog.schema]),
       })
       .transform(
-        ({ txHash, dataStartIndexForTx, logIndexInTx, blockNumber, blockHash, log }) =>
-          new TxScopedL2Log(txHash, dataStartIndexForTx, logIndexInTx, blockNumber, blockHash, log),
+        ({ txHash, dataStartIndexForTx, logIndexInTx, blockNumber, blockHash, blockTimestamp, log }) =>
+          new TxScopedL2Log(txHash, dataStartIndexForTx, logIndexInTx, blockNumber, blockHash, blockTimestamp, log),
       );
   }
 
@@ -66,6 +73,7 @@ export class TxScopedL2Log {
       numToUInt32BE(this.logIndexInTx),
       numToUInt32BE(this.blockNumber),
       this.blockHash.toBuffer(),
+      bigintToUInt64BE(this.blockTimestamp),
       boolToBuffer(this.isFromPublic),
       this.log.toBuffer(),
     ]);
@@ -78,15 +86,16 @@ export class TxScopedL2Log {
     const logIndexInTx = reader.readNumber();
     const blockNumber = BlockNumber(reader.readNumber());
     const blockHash = reader.readObject(L2BlockHash);
+    const blockTimestamp = reader.readUInt64();
     const isFromPublic = reader.readBoolean();
     const log = isFromPublic ? PublicLog.fromBuffer(reader) : PrivateLog.fromBuffer(reader);
 
-    return new TxScopedL2Log(txHash, dataStartIndexForTx, logIndexInTx, blockNumber, blockHash, log);
+    return new TxScopedL2Log(txHash, dataStartIndexForTx, logIndexInTx, blockNumber, blockHash, blockTimestamp, log);
   }
 
   static async random(isFromPublic = Math.random() < 0.5) {
     const log = isFromPublic ? await PublicLog.random() : PrivateLog.random();
-    return new TxScopedL2Log(TxHash.random(), 1, 1, BlockNumber(1), L2BlockHash.random(), log);
+    return new TxScopedL2Log(TxHash.random(), 1, 1, BlockNumber(1), L2BlockHash.random(), BigInt(1), log);
   }
 
   equals(other: TxScopedL2Log) {
@@ -96,6 +105,7 @@ export class TxScopedL2Log {
       this.logIndexInTx === other.logIndexInTx &&
       this.blockNumber === other.blockNumber &&
       this.blockHash.equals(other.blockHash) &&
+      this.blockTimestamp === other.blockTimestamp &&
       ((this.log instanceof PublicLog && other.log instanceof PublicLog) ||
         (this.log instanceof PrivateLog && other.log instanceof PrivateLog)) &&
       this.log.equals(other.log as any)

package/src/messaging/l1_to_l2_message.ts

@@ -84,6 +84,7 @@ export async function getNonNullifiedL1ToL2MessageWitness(
   if (!response) {
     throw new Error(`No L1 to L2 message found for message hash ${messageHash.toString()}`);
   }
+
   const [messageIndex, siblingPath] = response;
 
   const messageNullifier = await computeL1ToL2MessageNullifier(contractAddress, messageHash, secret);

package/src/rollup/checkpoint_constant_data.ts

@@ -11,6 +11,7 @@ import { GasFees } from '../gas/gas_fees.js';
 
 /**
  * Constants that are the same for the entire checkpoint.
+ * Used in circuits during rollup proving.
  */
 export class CheckpointConstantData {
   constructor(

package/src/rollup/checkpoint_header.ts

@@ -17,6 +17,10 @@ import { schemas } from '../schemas/index.js';
 import { ContentCommitment } from '../tx/content_commitment.js';
 import type { UInt64 } from '../types/shared.js';
 
+/**
+ * Header of a checkpoint. A checkpoint is a collection of blocks submitted to L1 all within the same slot.
+ * TODO(palla/mbps): Should this include chainId and version as well? Is this used just in circuits?
+ */
 export class CheckpointHeader {
   constructor(
     /** Root of the archive tree before this block is added. */

package/src/schemas/schemas.ts

@@ -40,6 +40,9 @@ export const schemas = {
   /** Coerces input to UInt32. */
   UInt32: foundationSchemas.UInt32,
 
+  /** Coerces input to UInt64. */
+  UInt64: foundationSchemas.UInt64,
+
   /** Accepts a hex string as a Buffer32 type. */
   Buffer32: foundationSchemas.Buffer32 as ZodFor<Buffer32>,
 

package/src/stats/stats.ts

@@ -20,6 +20,13 @@ export type L2BlockStats = {
   publicLogCount?: number;
 };
 
+export type CheckpointStats = {
+  /** Number of transactions in the checkpoint */
+  txCount: number;
+  /** Number of blocks in the checkpoint */
+  blockCount: number;
+};
+
 /** Stats logged for each L1 publish tx.*/
 export type L1PublishStats = {
   /** Address of the sender. */
@@ -45,11 +52,11 @@ export type L1PublishStats = {
 };
 
 /** Stats logged for each L1 rollup publish tx.*/
-export type L1PublishBlockStats = {
+export type L1PublishCheckpointStats = {
   /** Name of the event for metrics purposes */
   eventName: 'rollup-published-to-l1';
 } & L1PublishStats &
-  L2BlockStats;
+  CheckpointStats;
 
 /** Stats logged for each L1 rollup publish tx.*/
 export type L1PublishProofStats = {
@@ -189,8 +196,6 @@ export type CircuitVerificationStats = {
 
 /** Stats for an L2 block built by a sequencer. */
 export type L2BlockBuiltStats = {
-  /** The creator of the block */
-  creator: string;
   /** Name of the event. */
   eventName: 'l2-block-built';
   /** Total duration in ms. */
@@ -272,7 +277,7 @@ export type Stats =
   | CircuitSimulationStats
   | CircuitWitnessGenerationStats
   | PublicDBAccessStats
-  | L1PublishBlockStats
+  | L1PublishCheckpointStats
   | L1PublishProofStats
   | L2BlockBuiltStats
   | L2BlockHandledStats

package/src/tx/global_variable_builder.ts

@@ -4,7 +4,7 @@ import type { SlotNumber } from '@aztec/foundation/schemas';
 import type { AztecAddress } from '../aztec-address/index.js';
 import type { GasFees } from '../gas/gas_fees.js';
 import type { UInt32 } from '../types/index.js';
-import type { GlobalVariables } from './global_variables.js';
+import type { CheckpointGlobalVariables, GlobalVariables } from './global_variables.js';
 
 /**
  * Interface for building global variables for Aztec blocks.
@@ -26,4 +26,11 @@ export interface GlobalVariableBuilder {
     feeRecipient: AztecAddress,
     slotNumber?: SlotNumber,
   ): Promise<GlobalVariables>;
+
+  /** Builds global variables that are constant throughout a checkpoint. */
+  buildCheckpointGlobalVariables(
+    coinbase: EthAddress,
+    feeRecipient: AztecAddress,
+    slotNumber: SlotNumber,
+  ): Promise<CheckpointGlobalVariables>;
 }

package/src/tx/global_variables.ts

@@ -21,6 +21,12 @@ import { GasFees } from '../gas/gas_fees.js';
 import { schemas } from '../schemas/index.js';
 import type { UInt64 } from '../types/index.js';
 
+/**
+ * Global variables that are constant across the entire slot.
+ * TODO(palla/mbps): Should timestamp be included here as well?
+ */
+export type CheckpointGlobalVariables = Omit<FieldsOf<GlobalVariables>, 'blockNumber' | 'timestamp'>;
+
 /**
  * Global variables of the L2 block.
  */