@aztec/stdlib 0.0.1-commit.b655e406 → 0.0.1-commit.b9865e97

package/src/timetable/index.ts

@@ -0,0 +1,304 @@
+/**
+ * Timetable constants used for sequencer timing calculations.
+ * These define the time budgets for various phases of block production.
+ *
+ * The sequencer slot is divided into phases:
+ * 1. Checkpoint initialization (sync + proposer check)
+ * 2. Block building (execution)
+ * 3. Checkpoint assembly
+ * 4. P2P propagation for proposal and attestations (round-trip)
+ * 5. L1 publishing
+ */
+
+/** Time budget for checkpoint initialization (sync + proposer check) in seconds */
+export const CHECKPOINT_INITIALIZATION_TIME = 1;
+
+/** Time budget for assembling a checkpoint after building the last block in seconds */
+export const CHECKPOINT_ASSEMBLE_TIME = 1;
+
+/** Default one-way P2P propagation time for proposals and attestations in seconds */
+export const DEFAULT_P2P_PROPAGATION_TIME = 2;
+
+/** Default L1 publishing time (matches Ethereum slot duration on mainnet) in seconds */
+export const DEFAULT_L1_PUBLISHING_TIME = 12;
+
+/** Minimum execution time for building a block in seconds */
+export const MIN_EXECUTION_TIME = 2;
+
+export type CheckpointTimingConfig = {
+  aztecSlotDuration: number;
+  ethereumSlotDuration?: number;
+  blockDuration?: number;
+  checkpointAssembleTime?: number;
+  checkpointInitializationTime?: number;
+  l1PublishingTime?: number;
+  minExecutionTime?: number;
+  p2pPropagationTime?: number;
+};
+
+export interface CheckpointTiming {
+  readonly aztecSlotDuration: number;
+  readonly blockDuration: number | undefined;
+  readonly checkpointAssembleTime: number;
+  readonly checkpointInitializationTime: number;
+  readonly l1PublishingTime: number;
+  readonly minExecutionTime: number;
+  readonly p2pPropagationTime: number;
+  readonly checkpointFinalizationTime: number;
+  readonly pipeliningAttestationGracePeriod: number;
+  readonly timeReservedAtEnd: number;
+  readonly minimumBuildSlotWork: number;
+  readonly initializeDeadline: number;
+  readonly checkpointAssemblyDeadline: number;
+  readonly checkpointAttestationStartDeadline: number;
+  readonly checkpointAttestationDeadline: number;
+  readonly checkpointPublishingDeadline: number;
+
+  calculateMaxBlocksPerSlot(): number;
+}
+
+export interface PipelinedCheckpointTiming extends CheckpointTiming {
+  readonly proposalWindowIntoTargetSlot: number;
+  readonly attestationWindowIntoTargetSlot: number;
+}
+
+/**
+ * Checkpoint timing model for proposer pipelining.
+ *
+ * The build work starts at the wall-clock slot boundary and the checkpoint
+ * proposal is broadcast early enough that attestations complete by the end of
+ * the build slot. L1 submission can then be sent at the boundary of the target
+ * slot. The target-slot window getters are intended for consumers such as P2P
+ * validators that need to validate pipelined messages against wallclock time.
+ */
+class CheckpointTimingModel implements PipelinedCheckpointTiming {
+  public readonly aztecSlotDuration: number;
+  public readonly blockDuration: number | undefined;
+  public readonly checkpointAssembleTime: number;
+  public readonly checkpointInitializationTime: number;
+  public readonly l1PublishingTime: number;
+  public readonly minExecutionTime: number;
+  public readonly p2pPropagationTime: number;
+  private readonly ethereumSlotDuration: number;
+
+  constructor(opts: CheckpointTimingConfig) {
+    this.aztecSlotDuration = opts.aztecSlotDuration;
+    this.blockDuration = opts.blockDuration;
+
+    this.checkpointAssembleTime = opts.checkpointAssembleTime ?? CHECKPOINT_ASSEMBLE_TIME;
+    this.checkpointInitializationTime = opts.checkpointInitializationTime ?? CHECKPOINT_INITIALIZATION_TIME;
+    this.l1PublishingTime = opts.l1PublishingTime ?? DEFAULT_L1_PUBLISHING_TIME;
+    this.minExecutionTime = opts.minExecutionTime ?? MIN_EXECUTION_TIME;
+    this.p2pPropagationTime = opts.p2pPropagationTime ?? DEFAULT_P2P_PROPAGATION_TIME;
+    this.ethereumSlotDuration = opts.ethereumSlotDuration ?? this.l1PublishingTime;
+  }
+
+  public get checkpointFinalizationTime(): number {
+    // Allow enough time to
+    // - build the checkpoint
+    // - Round-trip over p2p
+    // - Publish to L1
+    return this.checkpointAssembleTime + this.p2pPropagationTime * 2 + this.l1PublishingTime;
+  }
+
+  public get proposalWindowIntoTargetSlot(): number {
+    // Proposals no longer spill into the target slot: they are broadcast early
+    // enough in the build slot that attestations complete before the boundary.
+    // Any residual tolerance into the target slot is covered by clock disparity.
+    return 0;
+  }
+
+  public get attestationWindowIntoTargetSlot(): number {
+    // Span from the target-slot start to the L1 publish deadline (12s before the last L1 block of
+    // the target slot). The p2p layer accepts slot-N attestations until right before the publish
+    // deadline so the proposer can keep collecting useful attestations up to the latest moment the
+    // checkpoint can still land on L1 in the target slot.
+    return Math.max(0, this.aztecSlotDuration - 2 * this.ethereumSlotDuration);
+  }
+
+  public get pipeliningAttestationGracePeriod(): number {
+    // Under the early-pipelining regime attestations complete inside the build slot itself. Local
+    // networks can publish much faster than the Ethereum slot geometry, so they may use the target
+    // slot attestation window without moving the L1 publish cutoff.
+    return this.l1PublishingTime < this.ethereumSlotDuration ? this.attestationWindowIntoTargetSlot : 0;
+  }
+
+  public get timeReservedAtEnd(): number {
+    // Reserve enough time at the end of the build slot for:
+    // - assembling and broadcasting the checkpoint proposal
+    // - round-trip p2p propagation (proposal out, attestations back)
+    // - validators re-executing the last block
+    return this.checkpointAssembleTime + 2 * this.p2pPropagationTime + (this.blockDuration ?? 0);
+  }
+
+  public get minimumBuildSlotWork(): number {
+    return this.checkpointInitializationTime + this.minExecutionTime * 2;
+  }
+
+  public get initializeDeadline(): number {
+    return this.aztecSlotDuration - this.minimumBuildSlotWork;
+  }
+
+  public get checkpointAssemblyDeadline(): number {
+    // Allow enough time to build all blocks and receive attestations. With
+    // `pipeliningAttestationGracePeriod = 0` this equals `aztecSlotDuration`.
+    return this.aztecSlotDuration + this.pipeliningAttestationGracePeriod;
+  }
+
+  public get checkpointAttestationStartDeadline(): number {
+    return this.checkpointAssemblyDeadline;
+  }
+
+  public get checkpointAttestationDeadline(): number {
+    // L1 publish deadline — 12s (one Ethereum slot) before the last L1 block of the target L2 slot;
+    // the latest the checkpoint can be submitted and still land on L1 in the target slot. This is an
+    // L1-geometry bound (ethereumSlotDuration), matching the publisher's send lead in sendRequestsAt
+    // (which also targets one Ethereum slot before the target slot start).
+    return this.aztecSlotDuration * 2 - this.ethereumSlotDuration;
+  }
+
+  public get checkpointPublishingDeadline(): number {
+    // L1 publish deadline — 12s (one Ethereum slot) before the last L1 block of the target L2 slot;
+    // the latest the checkpoint can be submitted and still land on L1 in the target slot.
+    return this.aztecSlotDuration * 2 - this.ethereumSlotDuration;
+  }
+
+  public calculateMaxBlocksPerSlot(): number {
+    if (!this.blockDuration) {
+      return 1;
+    }
+
+    const timeAvailableForBlocks = this.aztecSlotDuration - this.checkpointInitializationTime - this.timeReservedAtEnd;
+    return Math.floor(timeAvailableForBlocks / this.blockDuration);
+  }
+}
+
+/**
+ * Creates a checkpoint timing model.
+ *
+ * Most callers should use this factory and depend only on the shared
+ * `CheckpointTiming` interface.
+ */
+export function createCheckpointTimingModel(opts: CheckpointTimingConfig): CheckpointTiming {
+  return createPipelinedCheckpointTimingModel(opts);
+}
+
+/**
+ * Creates a checkpoint timing model exposing the target-slot window accessors.
+ *
+ * Use this when the caller specifically needs the pipelined timing surface, such
+ * as proposal or attestation acceptance windows into the target slot.
+ */
+export function createPipelinedCheckpointTimingModel(opts: CheckpointTimingConfig): PipelinedCheckpointTiming {
+  validateCheckpointTimingConfig(opts);
+  const normalizedOpts = normalizeCheckpointTimingConfig(opts);
+
+  const timing = new CheckpointTimingModel(normalizedOpts);
+  validateCheckpointTimingModel(timing);
+  return timing;
+}
+
+/**
+ * Calculates the maximum number of blocks that can be built in a slot.
+ * Used by both the sequencer timetable and p2p gossipsub scoring.
+ *
+ * @param aztecSlotDurationSec - Aztec slot duration in seconds
+ * @param blockDurationSec - Duration per block in seconds (undefined = single block mode)
+ * @param opts - Optional overrides for timing constants
+ * @returns Maximum number of blocks per slot
+ */
+export function calculateMaxBlocksPerSlot(
+  aztecSlotDurationSec: number,
+  blockDurationSec: number | undefined,
+  opts: {
+    checkpointInitializationTime?: number;
+    checkpointAssembleTime?: number;
+    p2pPropagationTime?: number;
+    l1PublishingTime?: number;
+  } = {},
+): number {
+  return createCheckpointTimingModel({
+    aztecSlotDuration: aztecSlotDurationSec,
+    blockDuration: blockDurationSec,
+    checkpointAssembleTime: opts.checkpointAssembleTime,
+    checkpointInitializationTime: opts.checkpointInitializationTime,
+    l1PublishingTime: opts.l1PublishingTime,
+    p2pPropagationTime: opts.p2pPropagationTime,
+  }).calculateMaxBlocksPerSlot();
+}
+
+function assertNonNegative(name: string, value: number): void {
+  if (value < 0) {
+    throw new Error(`${name} must be non-negative (got ${value})`);
+  }
+}
+
+function validateCheckpointTimingConfig(opts: CheckpointTimingConfig): void {
+  if (opts.aztecSlotDuration <= 0) {
+    throw new Error(`aztecSlotDuration must be positive (got ${opts.aztecSlotDuration})`);
+  }
+
+  if (opts.ethereumSlotDuration !== undefined && opts.ethereumSlotDuration <= 0) {
+    throw new Error(`ethereumSlotDuration must be positive when provided (got ${opts.ethereumSlotDuration})`);
+  }
+
+  if (opts.blockDuration !== undefined && opts.blockDuration <= 0) {
+    throw new Error(`blockDuration must be positive when provided (got ${opts.blockDuration})`);
+  }
+
+  if (opts.minExecutionTime !== undefined && opts.minExecutionTime <= 0) {
+    throw new Error(`minExecutionTime must be positive when provided (got ${opts.minExecutionTime})`);
+  }
+
+  if (opts.checkpointAssembleTime !== undefined) {
+    assertNonNegative('checkpointAssembleTime', opts.checkpointAssembleTime);
+  }
+  if (opts.checkpointInitializationTime !== undefined) {
+    assertNonNegative('checkpointInitializationTime', opts.checkpointInitializationTime);
+  }
+  if (opts.l1PublishingTime !== undefined) {
+    assertNonNegative('l1PublishingTime', opts.l1PublishingTime);
+  }
+  if (opts.p2pPropagationTime !== undefined) {
+    assertNonNegative('p2pPropagationTime', opts.p2pPropagationTime);
+  }
+}
+
+function normalizeCheckpointTimingConfig(opts: CheckpointTimingConfig): CheckpointTimingConfig {
+  let checkpointAssembleTime = opts.checkpointAssembleTime ?? CHECKPOINT_ASSEMBLE_TIME;
+  let checkpointInitializationTime = opts.checkpointInitializationTime ?? CHECKPOINT_INITIALIZATION_TIME;
+  let minExecutionTime = opts.minExecutionTime ?? MIN_EXECUTION_TIME;
+  let p2pPropagationTime = opts.p2pPropagationTime ?? DEFAULT_P2P_PROPAGATION_TIME;
+
+  if (opts.ethereumSlotDuration !== undefined && opts.ethereumSlotDuration < 8) {
+    p2pPropagationTime = 0;
+    checkpointAssembleTime = 0.5;
+    checkpointInitializationTime = 0.5;
+    minExecutionTime = 1;
+  }
+
+  if (opts.blockDuration !== undefined && minExecutionTime > opts.blockDuration) {
+    minExecutionTime = opts.blockDuration;
+  }
+
+  return {
+    ...opts,
+    checkpointAssembleTime,
+    checkpointInitializationTime,
+    minExecutionTime,
+    p2pPropagationTime,
+  };
+}
+
+function validateCheckpointTimingModel(model: CheckpointTiming): void {
+  if (model.blockDuration === undefined) {
+    return;
+  }
+
+  const timeAvailableForBlocks = model.aztecSlotDuration - model.checkpointInitializationTime - model.timeReservedAtEnd;
+  if (timeAvailableForBlocks < model.blockDuration) {
+    throw new Error(
+      `Invalid timing configuration: only ${timeAvailableForBlocks}s available for block building, which is less than one blockDuration (${model.blockDuration}s).`,
+    );
+  }
+}

package/src/trees/append_only_tree_snapshot.ts

@@ -1,7 +1,6 @@
-import type { ViemAppendOnlyTreeSnapshot } from '@aztec/ethereum';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
-import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToSink } from '@aztec/foundation/serialize';
 import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
 
 import { inspect } from 'util';
@@ -45,8 +44,13 @@ export class AppendOnlyTreeSnapshot {
     return this.root.size + 4;
   }
 
-  toBuffer() {
-    return serializeToBuffer(this.root, this.nextAvailableLeafIndex);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.root, this.nextAvailableLeafIndex);
   }
 
   toFields(): Fr[] {
@@ -72,17 +76,6 @@ export class AppendOnlyTreeSnapshot {
     return new AppendOnlyTreeSnapshot(reader.readField(), Number(reader.readField().toBigInt()));
   }
 
-  static fromViem(snapshot: ViemAppendOnlyTreeSnapshot) {
-    return new AppendOnlyTreeSnapshot(Fr.fromString(snapshot.root), snapshot.nextAvailableLeafIndex);
-  }
-
-  toViem(): ViemAppendOnlyTreeSnapshot {
-    return {
-      root: this.root.toString(),
-      nextAvailableLeafIndex: this.nextAvailableLeafIndex,
-    };
-  }
-
   toAbi(): [`0x${string}`, number] {
     return [this.root.toString(), this.nextAvailableLeafIndex];
   }
@@ -91,6 +84,17 @@ export class AppendOnlyTreeSnapshot {
     return new AppendOnlyTreeSnapshot(Fr.ZERO, 0);
   }
 
+  /**
+   * Creates an AppendOnlyTreeSnapshot instance from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing AppendOnlyTreeSnapshot fields
+   * @returns An AppendOnlyTreeSnapshot instance
+   */
+  static fromPlainObject(obj: any): AppendOnlyTreeSnapshot {
+    return new AppendOnlyTreeSnapshot(Fr.fromPlainObject(obj.root), obj.nextAvailableLeafIndex);
+  }
+
   isEmpty(): boolean {
     return this.root.isZero() && this.nextAvailableLeafIndex === 0;
   }

package/src/trees/database_public_state_source.ts

@@ -1,4 +1,4 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 
 import type { AztecAddress } from '../aztec-address/index.js';
 import { computePublicDataTreeLeafSlot } from '../hash/hash.js';

package/src/trees/nullifier_leaf.ts

@@ -1,5 +1,5 @@
 import { toBigIntBE, toBufferBE } from '@aztec/foundation/bigint-buffer';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
 import { BufferReader } from '@aztec/foundation/serialize';
 import type { IndexedTreeLeaf, IndexedTreeLeafPreimage } from '@aztec/foundation/trees';
@@ -36,6 +36,24 @@ export class NullifierLeafPreimage implements IndexedTreeLeafPreimage {
       .transform(({ leaf, nextKey, nextIndex }) => new NullifierLeafPreimage(leaf, nextKey, nextIndex));
   }
 
+  /**
+   * Creates a NullifierLeafPreimage from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing NullifierLeafPreimage fields
+   * @returns A NullifierLeafPreimage instance
+   */
+  static fromPlainObject(obj: any): NullifierLeafPreimage {
+    if (obj instanceof NullifierLeafPreimage) {
+      return obj;
+    }
+    return new NullifierLeafPreimage(
+      NullifierLeaf.fromPlainObject(obj.leaf),
+      Fr.fromPlainObject(obj.nextKey),
+      typeof obj.nextIndex === 'bigint' ? obj.nextIndex : BigInt(obj.nextIndex),
+    );
+  }
+
   static get leafSchema() {
     return NullifierLeaf.schema;
   }
@@ -68,6 +86,10 @@ export class NullifierLeafPreimage implements IndexedTreeLeafPreimage {
     ];
   }
 
+  isEmpty(): boolean {
+    return this.leaf.isEmpty() && this.nextKey.isZero() && this.nextIndex === 0n;
+  }
+
   toFields(): Fr[] {
     return this.toHashInputs().map(buf => Fr.fromBuffer(buf));
   }
@@ -157,4 +179,18 @@ export class NullifierLeaf implements IndexedTreeLeaf {
   static get schema() {
     return z.object({ nullifier: schemas.Fr }).transform(({ nullifier }) => new NullifierLeaf(nullifier));
   }
+
+  /**
+   * Creates a NullifierLeaf from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing NullifierLeaf fields
+   * @returns A NullifierLeaf instance
+   */
+  static fromPlainObject(obj: any): NullifierLeaf {
+    if (obj instanceof NullifierLeaf) {
+      return obj;
+    }
+    return new NullifierLeaf(Fr.fromPlainObject(obj.nullifier));
+  }
 }

package/src/trees/nullifier_membership_witness.ts

@@ -1,5 +1,5 @@
 import { NULLIFIER_TREE_HEIGHT } from '@aztec/constants';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { MembershipWitness, SiblingPath } from '@aztec/foundation/trees';
 
 import { z } from 'zod';
@@ -53,22 +53,12 @@ export class NullifierMembershipWitness {
     return new MembershipWitness(NULLIFIER_TREE_HEIGHT, this.index, this.siblingPath.toTuple());
   }
 
-  /**
-   * Returns a field array representation of a nullifier witness.
-   * @returns A field array representation of a nullifier witness.
-   */
-  public toFields(): Fr[] {
-    return [new Fr(this.index), ...this.leafPreimage.toFields(), ...this.siblingPath.toFields()];
-  }
-
-  /**
-   * Returns a representation of the nullifier membership witness as expected by intrinsic Noir deserialization.
-   */
+  /** Serializes as `(NullifierLeafPreimage, MembershipWitness)` to match the Noir oracle return type. */
   public toNoirRepresentation(): (string | string[])[] {
     // TODO(#12874): remove the stupid as string conversion by modifying ForeignCallOutput type in acvm.js
     return [
-      new Fr(this.index).toString() as string,
       ...(this.leafPreimage.toFields().map(fr => fr.toString()) as string[]),
+      new Fr(this.index).toString() as string,
       this.siblingPath.toFields().map(fr => fr.toString()) as string[],
     ];
   }

package/src/trees/public_data_leaf.ts

@@ -1,5 +1,6 @@
 import { toBigIntBE, toBufferBE } from '@aztec/foundation/bigint-buffer';
-import { Fr } from '@aztec/foundation/fields';
+import { poseidon2Hash } from '@aztec/foundation/crypto/poseidon';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { schemas } from '@aztec/foundation/schemas';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 import type { IndexedTreeLeaf, IndexedTreeLeafPreimage } from '@aztec/foundation/trees';
@@ -36,6 +37,24 @@ export class PublicDataTreeLeafPreimage implements IndexedTreeLeafPreimage {
       .transform(({ leaf, nextKey, nextIndex }) => new PublicDataTreeLeafPreimage(leaf, nextKey, nextIndex));
   }
 
+  /**
+   * Creates a PublicDataTreeLeafPreimage from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing PublicDataTreeLeafPreimage fields
+   * @returns A PublicDataTreeLeafPreimage instance
+   */
+  static fromPlainObject(obj: any): PublicDataTreeLeafPreimage {
+    if (obj instanceof PublicDataTreeLeafPreimage) {
+      return obj;
+    }
+    return new PublicDataTreeLeafPreimage(
+      PublicDataTreeLeaf.fromPlainObject(obj.leaf),
+      Fr.fromPlainObject(obj.nextKey),
+      typeof obj.nextIndex === 'bigint' ? obj.nextIndex : BigInt(obj.nextIndex),
+    );
+  }
+
   static get leafSchema() {
     return PublicDataTreeLeaf.schema;
   }
@@ -63,11 +82,15 @@ export class PublicDataTreeLeafPreimage implements IndexedTreeLeafPreimage {
   toHashInputs(): Buffer[] {
     return [
       ...this.leaf.toHashInputs(),
-      Buffer.from(toBufferBE(this.nextIndex, 32)),
       Buffer.from(this.nextKey.toBuffer()),
+      Buffer.from(toBufferBE(this.nextIndex, 32)),
     ];
   }
 
+  hash(): Promise<Fr> {
+    return poseidon2Hash(this.toHashInputs());
+  }
+
   clone(): PublicDataTreeLeafPreimage {
     return new PublicDataTreeLeafPreimage(this.leaf.clone(), this.nextKey, this.nextIndex);
   }
@@ -86,10 +109,11 @@ export class PublicDataTreeLeafPreimage implements IndexedTreeLeafPreimage {
 
   static fromBuffer(buffer: Buffer | BufferReader): PublicDataTreeLeafPreimage {
     const reader = BufferReader.asReader(buffer);
-    const value = PublicDataTreeLeaf.fromBuffer(reader);
-    const nextIndex = toBigIntBE(reader.readBytes(32));
-    const nextSlot = Fr.fromBuffer(reader);
-    return new PublicDataTreeLeafPreimage(value, nextSlot, nextIndex);
+    return new PublicDataTreeLeafPreimage(
+      PublicDataTreeLeaf.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+      toBigIntBE(reader.readBytes(32)),
+    );
   }
 
   static fromLeaf(leaf: PublicDataTreeLeaf, nextKey: bigint, nextIndex: bigint): PublicDataTreeLeafPreimage {
@@ -172,4 +196,18 @@ export class PublicDataTreeLeaf implements IndexedTreeLeaf {
       })
       .transform(({ slot, value }) => new PublicDataTreeLeaf(slot, value));
   }
+
+  /**
+   * Creates a PublicDataTreeLeaf from a plain object without Zod validation.
+   * This method is optimized for performance and skips validation, making it suitable
+   * for deserializing trusted data (e.g., from C++ via MessagePack).
+   * @param obj - Plain object containing PublicDataTreeLeaf fields
+   * @returns A PublicDataTreeLeaf instance
+   */
+  static fromPlainObject(obj: any): PublicDataTreeLeaf {
+    if (obj instanceof PublicDataTreeLeaf) {
+      return obj;
+    }
+    return new PublicDataTreeLeaf(Fr.fromPlainObject(obj.slot), Fr.fromPlainObject(obj.value));
+  }
 }

package/src/trees/public_data_witness.ts

@@ -1,6 +1,6 @@
 import { PUBLIC_DATA_TREE_HEIGHT } from '@aztec/constants';
 import { toBigIntBE } from '@aztec/foundation/bigint-buffer';
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
 import { MembershipWitness, SiblingPath } from '@aztec/foundation/trees';

package/src/tx/block_header.ts

@@ -1,36 +1,41 @@
-import { BLOCK_HEADER_LENGTH, GeneratorIndex } from '@aztec/constants';
-import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto';
-import { Fr } from '@aztec/foundation/fields';
+import { BLOCK_HEADER_LENGTH, DomainSeparator } from '@aztec/constants';
+import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto/poseidon';
+import { randomInt } from '@aztec/foundation/crypto/random';
+import { Fr } from '@aztec/foundation/curves/bn254';
 import { type ZodFor, schemas } from '@aztec/foundation/schemas';
-import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToFields, serializeToSink } from '@aztec/foundation/serialize';
 import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { inspect } from 'util';
 import { z } from 'zod';
 
+import { BlockHash } from '../block/block_hash.js';
 import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
 import { GlobalVariables } from './global_variables.js';
 import { StateReference } from './state_reference.js';
 
 /** A header of an L2 block. */
 export class BlockHeader {
+  private _cachedHash?: Promise<BlockHash>;
+
   constructor(
     /** Snapshot of archive before the block is applied. */
-    public lastArchive: AppendOnlyTreeSnapshot,
+    public readonly lastArchive: AppendOnlyTreeSnapshot,
     /** State reference. */
-    public state: StateReference,
+    public readonly state: StateReference,
     /**
      * Hash of the sponge blob after the tx effects of this block has been applied.
      * May contain tx effects from the previous blocks in the same checkpoint.
      */
-    public spongeBlobHash: Fr,
+    public readonly spongeBlobHash: Fr,
     /** Global variables of an L2 block. */
-    public globalVariables: GlobalVariables,
+    public readonly globalVariables: GlobalVariables,
     /** Total fees in the block, computed by the root rollup circuit */
-    public totalFees: Fr,
+    public readonly totalFees: Fr,
     /** Total mana used in the block, computed by the root rollup circuit */
-    public totalManaUsed: Fr,
+    public readonly totalManaUsed: Fr,
   ) {}
 
   static get schema(): ZodFor<BlockHeader> {
@@ -61,11 +66,11 @@ export class BlockHeader {
     return new BlockHeader(...BlockHeader.getFields(fields));
   }
 
-  getSlot() {
-    return this.globalVariables.slotNumber.toBigInt();
+  getSlot(): SlotNumber {
+    return this.globalVariables.slotNumber;
   }
 
-  getBlockNumber() {
+  getBlockNumber(): BlockNumber {
     return this.globalVariables.blockNumber;
   }
 
@@ -80,8 +85,13 @@ export class BlockHeader {
     );
   }
 
-  toBuffer() {
-    return serializeToBuffer(...BlockHeader.getFields(this));
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, ...BlockHeader.getFields(this));
   }
 
   toFields(): Fr[] {
@@ -157,8 +167,36 @@ export class BlockHeader {
     return BlockHeader.fromBuffer(hexToBuffer(str));
   }
 
-  hash(): Promise<Fr> {
-    return poseidon2HashWithSeparator(this.toFields(), GeneratorIndex.BLOCK_HASH);
+  hash(): Promise<BlockHash> {
+    if (!this._cachedHash) {
+      this._cachedHash = poseidon2HashWithSeparator(this.toFields(), DomainSeparator.BLOCK_HEADER_HASH).then(
+        fr => new BlockHash(fr),
+      );
+    }
+    return this._cachedHash;
+  }
+
+  /** Manually set the hash for this block header if already computed */
+  setHash(hashed: BlockHash) {
+    this._cachedHash = Promise.resolve(hashed);
+  }
+
+  /** Recomputes the cached hash. Used for testing when header fields are mutated via unfreeze. */
+  recomputeHash(): Promise<BlockHash> {
+    this._cachedHash = undefined;
+    return this.hash();
+  }
+
+  static random(overrides: Partial<FieldsOf<BlockHeader>> & Partial<FieldsOf<GlobalVariables>> = {}): BlockHeader {
+    return BlockHeader.from({
+      lastArchive: AppendOnlyTreeSnapshot.random(),
+      state: StateReference.random(),
+      spongeBlobHash: Fr.random(),
+      globalVariables: GlobalVariables.random(overrides),
+      totalFees: new Fr(randomInt(100_000)),
+      totalManaUsed: new Fr(randomInt(100_000_000)),
+      ...overrides,
+    });
   }
 
   toInspect() {