@aztec/stdlib 3.0.3 → 3.9.9-nightly.20260312

package/src/block/validate_block_result.ts

@@ -5,57 +5,62 @@ import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 
 import { z } from 'zod';
 
-import { BlockInfoSchema, type L2BlockInfo, deserializeBlockInfo, serializeBlockInfo } from './l2_block_info.js';
+import {
+  type CheckpointInfo,
+  CheckpointInfoSchema,
+  deserializeCheckpointInfo,
+  serializeCheckpointInfo,
+} from '../checkpoint/checkpoint_info.js';
+import { MAX_COMMITTEE_SIZE } from '../deserialization/index.js';
 import { CommitteeAttestation } from './proposal/committee_attestation.js';
 
-/** Subtype for invalid block validation results */
-export type ValidateBlockNegativeResult =
+/** Subtype for invalid checkpoint validation results */
+export type ValidateCheckpointNegativeResult =
   | {
       valid: false;
-      /** Identifiers from the invalid block */
-      block: L2BlockInfo;
-      /** Committee members at the epoch this block was proposed */
+      /** Identifiers from the invalid checkpoint */
+      checkpoint: CheckpointInfo;
+      /** Committee members at the epoch this checkpoint was proposed */
       committee: EthAddress[];
-      /** Epoch in which this block was proposed */
+      /** Epoch in which this checkpoint was proposed */
       epoch: EpochNumber;
       /** Proposer selection seed for the epoch */
       seed: bigint;
-      /** List of committee members who signed this block proposal */
+      /** List of committee members who signed this checkpoint proposal */
       attestors: EthAddress[];
-      /** Committee attestations for this block as they were posted to L1 */
+      /** Committee attestations for this checkpoint as they were posted to L1 */
       attestations: CommitteeAttestation[];
-      /** Reason for the block being invalid: not enough attestations were posted */
+      /** Reason for the checkpoint being invalid: not enough attestations were posted */
       reason: 'insufficient-attestations';
     }
   | {
       valid: false;
-      /** Identifiers from the invalid block */
-      block: L2BlockInfo;
-      /** Committee members at the epoch this block was proposed */
+      /** Identifiers from the invalid checkpoint */
+      checkpoint: CheckpointInfo;
+      /** Committee members at the epoch this checkpoint was proposed */
       committee: EthAddress[];
-      /** Epoch in which this block was proposed */
+      /** Epoch in which this checkpoint was proposed */
       epoch: EpochNumber;
       /** Proposer selection seed for the epoch */
       seed: bigint;
-      /** List of committee members who signed this block proposal */
+      /** List of committee members who signed this checkpoint proposal */
       attestors: EthAddress[];
-      /** Committee attestations for this block as they were posted to L1 */
+      /** Committee attestations for this checkpoint as they were posted to L1 */
       attestations: CommitteeAttestation[];
-      /** Reason for the block being invalid: an invalid attestation was posted */
+      /** Reason for the checkpoint being invalid: an invalid attestation was posted */
       reason: 'invalid-attestation';
       /** Index in the attestations array of the invalid attestation posted */
       invalidIndex: number;
     };
 
-// TODO: Rename to ValidateAttestationsResult
-/** Result type for validating a block attestations */
-export type ValidateBlockResult = { valid: true } | ValidateBlockNegativeResult;
+/** Result type for validating checkpoint attestations */
+export type ValidateCheckpointResult = { valid: true } | ValidateCheckpointNegativeResult;
 
-export const ValidateBlockResultSchema: ZodFor<ValidateBlockResult> = z.union([
+export const ValidateCheckpointResultSchema: ZodFor<ValidateCheckpointResult> = z.union([
   z.object({ valid: z.literal(true) }),
   z.object({
     valid: z.literal(false),
-    block: BlockInfoSchema,
+    checkpoint: CheckpointInfoSchema,
     committee: z.array(schemas.EthAddress),
     epoch: EpochNumberSchema,
     seed: schemas.BigInt,
@@ -65,7 +70,7 @@ export const ValidateBlockResultSchema: ZodFor<ValidateBlockResult> = z.union([
   }),
   z.object({
     valid: z.literal(false),
-    block: BlockInfoSchema,
+    checkpoint: CheckpointInfoSchema,
     committee: z.array(schemas.EthAddress),
     epoch: EpochNumberSchema,
     seed: schemas.BigInt,
@@ -76,17 +81,17 @@ export const ValidateBlockResultSchema: ZodFor<ValidateBlockResult> = z.union([
   }),
 ]);
 
-export function serializeValidateBlockResult(result: ValidateBlockResult): Buffer {
+export function serializeValidateCheckpointResult(result: ValidateCheckpointResult): Buffer {
   if (result.valid) {
     return serializeToBuffer(true);
   }
 
-  const l2Block = serializeBlockInfo(result.block);
+  const checkpointBuffer = serializeCheckpointInfo(result.checkpoint);
   return serializeToBuffer(
     result.valid,
     result.reason,
-    l2Block.length,
-    l2Block,
+    checkpointBuffer.length,
+    checkpointBuffer,
     result.committee.length,
     result.committee,
     result.epoch,
@@ -99,24 +104,24 @@ export function serializeValidateBlockResult(result: ValidateBlockResult): Buffe
   );
 }
 
-export function deserializeValidateBlockResult(bufferOrReader: Buffer | BufferReader): ValidateBlockResult {
+export function deserializeValidateCheckpointResult(bufferOrReader: Buffer | BufferReader): ValidateCheckpointResult {
   const reader = BufferReader.asReader(bufferOrReader);
   const valid = reader.readBoolean();
   if (valid) {
     return { valid };
   }
-  const reason = reader.readString() as 'insufficient-attestations' | 'invalid-attestation';
-  const block = deserializeBlockInfo(reader.readBuffer());
-  const committee = reader.readVector(EthAddress);
+  const reason = reader.readString(64) as 'insufficient-attestations' | 'invalid-attestation';
+  const checkpoint = deserializeCheckpointInfo(reader.readBuffer());
+  const committee = reader.readVector(EthAddress, MAX_COMMITTEE_SIZE);
   const epoch = EpochNumber(reader.readNumber());
   const seed = reader.readBigInt();
-  const attestors = reader.readVector(EthAddress);
-  const attestations = reader.readVector(CommitteeAttestation);
+  const attestors = reader.readVector(EthAddress, MAX_COMMITTEE_SIZE);
+  const attestations = reader.readVector(CommitteeAttestation, MAX_COMMITTEE_SIZE);
   const invalidIndex = reader.readNumber();
   if (reason === 'insufficient-attestations') {
-    return { valid, reason, block, committee, epoch, seed, attestors, attestations: attestations };
+    return { valid, reason, checkpoint, committee, epoch, seed, attestors, attestations };
   } else if (reason === 'invalid-attestation') {
-    return { valid, reason, block, committee, epoch, seed, attestors, invalidIndex, attestations: attestations };
+    return { valid, reason, checkpoint, committee, epoch, seed, attestors, invalidIndex, attestations };
   } else {
     const _: never = reason;
     throw new Error(`Unknown reason: ${reason}`);

package/src/checkpoint/checkpoint.ts

@@ -1,14 +1,27 @@
 import { encodeCheckpointBlobDataFromBlocks } from '@aztec/blob-lib/encoding';
-import { BlockNumber, CheckpointNumber, CheckpointNumberSchema } from '@aztec/foundation/branded-types';
+import {
+  BlockNumber,
+  CheckpointNumber,
+  CheckpointNumberSchema,
+  IndexWithinCheckpoint,
+  SlotNumber,
+} from '@aztec/foundation/branded-types';
+import { pick, sum } from '@aztec/foundation/collection';
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferReader, serializeSignedBigInt, serializeToBuffer } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { z } from 'zod';
 
-import { L2BlockNew } from '../block/l2_block_new.js';
+import { L2Block } from '../block/l2_block.js';
+import { MAX_BLOCKS_PER_CHECKPOINT } from '../deserialization/index.js';
+import { computeCheckpointOutHash } from '../messaging/out_hash.js';
 import { CheckpointHeader } from '../rollup/checkpoint_header.js';
+import { schemas } from '../schemas/schemas.js';
 import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import type { CheckpointInfo } from './checkpoint_info.js';
+
+type FieldsOfCheckpoint = Omit<FieldsOf<Checkpoint>, 'slot'>;
 
 export class Checkpoint {
   constructor(
@@ -17,42 +30,59 @@ export class Checkpoint {
     /** Header of the checkpoint. */
     public header: CheckpointHeader,
     /** L2 blocks in the checkpoint. */
-    public blocks: L2BlockNew[],
+    public blocks: L2Block[],
     /** Number of the checkpoint. */
     public number: CheckpointNumber,
+    /** Fee asset price modifier in basis points (from oracle). Defaults to 0 (no change). */
+    public feeAssetPriceModifier: bigint = 0n,
   ) {}
 
+  get slot(): SlotNumber {
+    return this.header.slotNumber;
+  }
+
   static get schema() {
     return z
       .object({
         archive: AppendOnlyTreeSnapshot.schema,
         header: CheckpointHeader.schema,
-        blocks: z.array(L2BlockNew.schema),
+        blocks: z.array(L2Block.schema),
         number: CheckpointNumberSchema,
+        feeAssetPriceModifier: schemas.BigInt,
       })
-      .transform(({ archive, header, blocks, number }) => new Checkpoint(archive, header, blocks, number));
+      .transform(
+        ({ archive, header, blocks, number, feeAssetPriceModifier }) =>
+          new Checkpoint(archive, header, blocks, number, feeAssetPriceModifier),
+      );
   }
 
-  static from(fields: FieldsOf<Checkpoint>) {
+  static from(fields: FieldsOfCheckpoint) {
     return new Checkpoint(...Checkpoint.getFields(fields));
   }
 
-  static getFields(fields: FieldsOf<Checkpoint>) {
-    return [fields.archive, fields.header, fields.blocks, fields.number] as const;
+  static getFields(fields: FieldsOfCheckpoint) {
+    return [fields.archive, fields.header, fields.blocks, fields.number, fields.feeAssetPriceModifier] as const;
   }
 
   static fromBuffer(buf: Buffer | BufferReader) {
     const reader = BufferReader.asReader(buf);
-    return new Checkpoint(
-      reader.readObject(AppendOnlyTreeSnapshot),
-      reader.readObject(CheckpointHeader),
-      reader.readVector(L2BlockNew),
-      CheckpointNumber(reader.readNumber()),
-    );
+    const archive = reader.readObject(AppendOnlyTreeSnapshot);
+    const header = reader.readObject(CheckpointHeader);
+    const blocks = reader.readVector(L2Block, MAX_BLOCKS_PER_CHECKPOINT);
+    const number = CheckpointNumber(reader.readNumber());
+    const feeAssetPriceModifier = reader.readInt256();
+    return new Checkpoint(archive, header, blocks, number, feeAssetPriceModifier);
   }
 
   public toBuffer() {
-    return serializeToBuffer(this.archive, this.header, this.blocks.length, this.blocks, this.number);
+    return serializeToBuffer(
+      this.archive,
+      this.header,
+      this.blocks.length,
+      this.blocks,
+      this.number,
+      serializeSignedBigInt(this.feeAssetPriceModifier),
+    );
   }
 
   public toBlobFields(): Fr[] {
@@ -64,25 +94,92 @@ export class Checkpoint {
     return this.header.hash();
   }
 
+  /**
+   * Returns the out hash computed from all l2-to-l1 messages in this checkpoint.
+   * Note: This value is different from the out hash in the header, which is the **accumulated** out hash over all
+   * checkpoints up to and including this one in the epoch.
+   */
+  public getCheckpointOutHash(): Fr {
+    const msgs = this.blocks.map(block => block.body.txEffects.map(txEffect => txEffect.l2ToL1Msgs));
+    return computeCheckpointOutHash(msgs);
+  }
+
   public getState() {
     return this.blocks.at(-1)!.header.state;
   }
 
+  public toCheckpointInfo(): CheckpointInfo {
+    return {
+      archive: this.archive.root,
+      lastArchive: this.header.lastArchiveRoot,
+      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),
     {
       numBlocks = 1,
       startBlockNumber = 1,
+      previousArchive,
+      feeAssetPriceModifier = 0n,
       ...options
-    }: { numBlocks?: number; startBlockNumber?: number } & Partial<Parameters<typeof CheckpointHeader.random>[0]> &
-      Partial<Parameters<typeof L2BlockNew.random>[1]> = {},
+    }: {
+      numBlocks?: number;
+      startBlockNumber?: number;
+      previousArchive?: AppendOnlyTreeSnapshot;
+      feeAssetPriceModifier?: bigint;
+      archive?: AppendOnlyTreeSnapshot;
+    } & Partial<Parameters<typeof CheckpointHeader.random>[0]> &
+      Partial<Parameters<typeof L2Block.random>[1]> = {},
   ) {
-    const header = CheckpointHeader.random(options);
+    const headerOptions = previousArchive ? { lastArchiveRoot: previousArchive.root, ...options } : options;
+    const header = CheckpointHeader.random(headerOptions);
 
-    const blocks = await Promise.all(
-      Array.from({ length: numBlocks }, (_, i) => L2BlockNew.random(BlockNumber(startBlockNumber + i), options)),
-    );
+    // Create blocks sequentially to chain archive roots properly.
+    // Each block's header.lastArchive must equal the previous block's archive.
+    const blocks: L2Block[] = [];
+    let lastArchive = previousArchive;
+    for (let i = 0; i < numBlocks; i++) {
+      const block = await L2Block.random(BlockNumber(startBlockNumber + i), {
+        indexWithinCheckpoint: IndexWithinCheckpoint(i),
+        ...options,
+        ...(lastArchive ? { lastArchive } : {}),
+        ...pick(header, 'slotNumber', 'timestamp', 'coinbase', 'feeRecipient', 'gasFees'),
+      });
+      lastArchive = block.archive;
+      blocks.push(block);
+    }
 
-    return new Checkpoint(AppendOnlyTreeSnapshot.random(), header, blocks, checkpointNumber);
+    return new Checkpoint(
+      options.archive ?? AppendOnlyTreeSnapshot.random(),
+      header,
+      blocks,
+      checkpointNumber,
+      feeAssetPriceModifier,
+    );
   }
 }

package/src/checkpoint/checkpoint_data.ts

@@ -0,0 +1,51 @@
+import {
+  BlockNumber,
+  BlockNumberSchema,
+  CheckpointNumber,
+  CheckpointNumberSchema,
+} from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { schemas } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import { CommitteeAttestation } from '../block/proposal/committee_attestation.js';
+import { CheckpointHeader } from '../rollup/checkpoint_header.js';
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import { L1PublishedData } from './published_checkpoint.js';
+
+/** Lightweight checkpoint metadata without full block data. */
+export type CheckpointData = {
+  checkpointNumber: CheckpointNumber;
+  header: CheckpointHeader;
+  archive: AppendOnlyTreeSnapshot;
+  checkpointOutHash: Fr;
+  startBlock: BlockNumber;
+  blockCount: number;
+  attestations: CommitteeAttestation[];
+  l1: L1PublishedData;
+};
+
+export const CheckpointDataSchema = z
+  .object({
+    checkpointNumber: CheckpointNumberSchema,
+    header: CheckpointHeader.schema,
+    archive: AppendOnlyTreeSnapshot.schema,
+    checkpointOutHash: schemas.Fr,
+    startBlock: BlockNumberSchema,
+    blockCount: schemas.Integer,
+    attestations: z.array(CommitteeAttestation.schema),
+    l1: L1PublishedData.schema,
+  })
+  .transform(
+    (obj): CheckpointData => ({
+      checkpointNumber: obj.checkpointNumber,
+      header: obj.header,
+      archive: obj.archive,
+      checkpointOutHash: obj.checkpointOutHash,
+      startBlock: obj.startBlock,
+      blockCount: obj.blockCount,
+      attestations: obj.attestations,
+      l1: obj.l1,
+    }),
+  );

package/src/checkpoint/checkpoint_info.ts

@@ -0,0 +1,52 @@
+import {
+  CheckpointNumber,
+  CheckpointNumberSchema,
+  SlotNumber,
+  SlotNumberSchema,
+} from '@aztec/foundation/branded-types';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { schemas } from '@aztec/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import { z } from 'zod';
+
+export type CheckpointInfo = {
+  archive: Fr;
+  lastArchive: Fr;
+  slotNumber: SlotNumber;
+  checkpointNumber: CheckpointNumber;
+  timestamp: bigint;
+};
+
+export function randomCheckpointInfo(checkpointNumber?: CheckpointNumber | number): CheckpointInfo {
+  return {
+    archive: Fr.random(),
+    lastArchive: Fr.random(),
+    slotNumber: SlotNumber(Math.floor(Math.random() * 100000) + 1),
+    checkpointNumber: CheckpointNumber(checkpointNumber ?? Math.floor(Math.random() * 100000) + 1),
+    timestamp: BigInt(Math.floor(Date.now() / 1000)),
+  };
+}
+
+export const CheckpointInfoSchema = z.object({
+  archive: schemas.Fr,
+  lastArchive: schemas.Fr,
+  slotNumber: SlotNumberSchema,
+  checkpointNumber: CheckpointNumberSchema,
+  timestamp: schemas.BigInt,
+});
+
+export function serializeCheckpointInfo(info: CheckpointInfo): Buffer {
+  return serializeToBuffer(info.archive, info.lastArchive, info.slotNumber, info.checkpointNumber, info.timestamp);
+}
+
+export function deserializeCheckpointInfo(buffer: Buffer | BufferReader): CheckpointInfo {
+  const reader = BufferReader.asReader(buffer);
+  return {
+    archive: reader.readObject(Fr),
+    lastArchive: reader.readObject(Fr),
+    slotNumber: SlotNumber(reader.readNumber()),
+    checkpointNumber: CheckpointNumber(reader.readNumber()),
+    timestamp: reader.readBigInt(),
+  };
+}

package/src/checkpoint/index.ts

@@ -1,2 +1,5 @@
 export * from './checkpoint.js';
+export * from './checkpoint_data.js';
+export * from './checkpoint_info.js';
 export * from './published_checkpoint.js';
+export * from './validate.js';

package/src/checkpoint/published_checkpoint.ts

@@ -8,6 +8,7 @@ import type { FieldsOf } from '@aztec/foundation/types';
 import { z } from 'zod';
 
 import { CommitteeAttestation } from '../block/proposal/committee_attestation.js';
+import { MAX_BLOCK_HASH_STRING_LENGTH, MAX_COMMITTEE_SIZE } from '../deserialization/index.js';
 import { Checkpoint } from './checkpoint.js';
 
 export class L1PublishedData {
@@ -18,11 +19,13 @@ export class L1PublishedData {
   ) {}
 
   static get schema() {
-    return z.object({
-      blockNumber: schemas.BigInt,
-      timestamp: schemas.BigInt,
-      blockHash: z.string(),
-    });
+    return z
+      .object({
+        blockNumber: schemas.BigInt,
+        timestamp: schemas.BigInt,
+        blockHash: z.string(),
+      })
+      .transform(obj => L1PublishedData.fromFields(obj));
   }
 
   static random() {
@@ -36,13 +39,27 @@ export class L1PublishedData {
   static fromFields(fields: FieldsOf<L1PublishedData>) {
     return new L1PublishedData(fields.blockNumber, fields.timestamp, fields.blockHash);
   }
+
+  static fromBuffer(bufferOrReader: Buffer | BufferReader): L1PublishedData {
+    const reader = BufferReader.asReader(bufferOrReader);
+    const l1BlockNumber = reader.readBigInt();
+    const l1BlockHash = reader.readString(MAX_BLOCK_HASH_STRING_LENGTH);
+    const l1Timestamp = reader.readBigInt();
+    return new L1PublishedData(l1BlockNumber, l1Timestamp, l1BlockHash);
+  }
+
+  public toBuffer(): Buffer {
+    return serializeToBuffer(this.blockNumber, this.blockHash, this.timestamp);
+  }
 }
 
 export class PublishedCheckpoint {
   constructor(
+    /** The checkpoint itself. */
     public checkpoint: Checkpoint,
+    /** Info on when this checkpoint was published on L1. */
     public l1: L1PublishedData,
-    // The attestations for the last block in the checkpoint.
+    /** The attestations for the last block in the checkpoint. */
     public attestations: CommitteeAttestation[],
   ) {}
 
@@ -68,9 +85,9 @@ export class PublishedCheckpoint {
     const reader = BufferReader.asReader(bufferOrReader);
     const checkpoint = reader.readObject(Checkpoint);
     const l1BlockNumber = reader.readBigInt();
-    const l1BlockHash = reader.readString();
+    const l1BlockHash = reader.readString(MAX_BLOCK_HASH_STRING_LENGTH);
     const l1Timestamp = reader.readBigInt();
-    const attestations = reader.readVector(CommitteeAttestation);
+    const attestations = reader.readVector(CommitteeAttestation, MAX_COMMITTEE_SIZE);
     return new PublishedCheckpoint(
       checkpoint,
       new L1PublishedData(l1BlockNumber, l1Timestamp, l1BlockHash),