@aztec/stdlib 0.0.1-commit.b2a5d0dd1 → 0.0.1-commit.b3d3157a

package/src/timetable/index.ts

@@ -34,7 +34,6 @@ export type CheckpointTimingConfig = {
   l1PublishingTime?: number;
   minExecutionTime?: number;
   p2pPropagationTime?: number;
-  pipelining?: boolean;
 };
 
 export interface CheckpointTiming {
@@ -64,13 +63,15 @@ export interface PipelinedCheckpointTiming extends CheckpointTiming {
 }
 
 /**
- * Shared base for checkpoint timing implementations.
+ * Checkpoint timing model for proposer pipelining.
  *
- * This class owns the common inputs and formulas used by both pipelined and
- * non-pipelined scheduling. Variant-specific deadline math is delegated to the
- * concrete subclasses below.
+ * 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.
  */
-abstract class BaseCheckpointTiming implements CheckpointTiming {
+class CheckpointTimingModel implements PipelinedCheckpointTiming {
   public readonly aztecSlotDuration: number;
   public readonly blockDuration: number | undefined;
   public readonly checkpointAssembleTime: number;
@@ -78,6 +79,7 @@ abstract class BaseCheckpointTiming implements CheckpointTiming {
   public readonly l1PublishingTime: number;
   public readonly minExecutionTime: number;
   public readonly p2pPropagationTime: number;
+  private readonly ethereumSlotDuration: number;
 
   constructor(opts: CheckpointTimingConfig) {
     this.aztecSlotDuration = opts.aztecSlotDuration;
@@ -88,6 +90,7 @@ abstract class BaseCheckpointTiming implements CheckpointTiming {
     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 {
@@ -98,142 +101,99 @@ abstract class BaseCheckpointTiming implements CheckpointTiming {
     return this.checkpointAssembleTime + this.p2pPropagationTime * 2 + this.l1PublishingTime;
   }
 
-  public get pipeliningAttestationGracePeriod(): number {
-    // Allow enough time to
-    // - build the block
-    // - pass it back over p2p
-    return (this.blockDuration ?? 0) + this.p2pPropagationTime;
-  }
-
-  public abstract get timeReservedAtEnd(): number;
-  public abstract get minimumBuildSlotWork(): number;
-
-  public get initializeDeadline(): number {
-    return this.aztecSlotDuration - this.minimumBuildSlotWork;
+  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 abstract get checkpointAssemblyDeadline(): number;
-
-  public get checkpointAttestationStartDeadline(): number {
-    return this.checkpointAssemblyDeadline;
+  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 abstract get checkpointAttestationDeadline(): number;
-  public abstract get checkpointPublishingDeadline(): number;
-
-  public calculateMaxBlocksPerSlot(): number {
-    if (!this.blockDuration) {
-      return 1;
-    }
-
-    const timeAvailableForBlocks = this.aztecSlotDuration - this.checkpointInitializationTime - this.timeReservedAtEnd;
-    return Math.floor(timeAvailableForBlocks / this.blockDuration);
+  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;
   }
-}
 
-/**
- * Checkpoint timing model for the non-pipelined sequencer flow.
- *
- * In this mode, checkpoint assembly, attestation collection, and L1 publishing
- * must all complete within the current Aztec slot.
- */
-class StandardCheckpointTimingModel extends BaseCheckpointTiming {
   public get timeReservedAtEnd(): number {
-    return (this.blockDuration ?? 0) + this.checkpointFinalizationTime;
+    // 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 + this.checkpointFinalizationTime;
-  }
-
-  public get checkpointAssemblyDeadline(): number {
-    return this.aztecSlotDuration - this.l1PublishingTime - 2 * this.p2pPropagationTime;
-  }
-
-  public get checkpointAttestationDeadline(): number {
-    return this.aztecSlotDuration - this.l1PublishingTime;
+    return this.checkpointInitializationTime + this.minExecutionTime * 2;
   }
 
-  public get checkpointPublishingDeadline(): number {
-    return this.aztecSlotDuration - this.l1PublishingTime;
-  }
-}
-
-/**
- * Checkpoint timing model for proposer pipelining.
- *
- * In this mode, the build work still starts in the current slot, but checkpoint
- * assembly and attestation collection can extend into the target slot. The extra
- * target-slot window getters are intended for consumers such as P2P validators
- * that need to validate pipelined messages against wallclock time.
- */
-class PipelinedCheckpointTimingModel extends BaseCheckpointTiming implements PipelinedCheckpointTiming {
-  public get proposalWindowIntoTargetSlot(): number {
-    // Allow the p2p propagation time to receive a checkpoint proposal from leader
-    return this.p2pPropagationTime;
+  public get initializeDeadline(): number {
+    return this.aztecSlotDuration - this.minimumBuildSlotWork;
   }
 
-  public get attestationWindowIntoTargetSlot(): number {
-    return this.aztecSlotDuration - this.l1PublishingTime;
+  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 timeReservedAtEnd(): number {
-    return this.checkpointAssembleTime + this.p2pPropagationTime;
+  public get checkpointAttestationStartDeadline(): number {
+    return this.checkpointAssemblyDeadline;
   }
 
-  public get minimumBuildSlotWork(): number {
-    return this.checkpointInitializationTime + this.minExecutionTime * 2;
+  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 checkpointAssemblyDeadline(): number {
-    // Allow enough time to
-    // - build all blocks
-    // - receive attestations
-    return this.aztecSlotDuration + this.pipeliningAttestationGracePeriod;
+  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 get checkpointAttestationDeadline(): number {
-    // Allowed to be into the next wallclock slot minus the allocated l1 publishing time
-    return this.aztecSlotDuration * 2 - this.l1PublishingTime;
-  }
+  public calculateMaxBlocksPerSlot(): number {
+    if (!this.blockDuration) {
+      return 1;
+    }
 
-  public get checkpointPublishingDeadline(): number {
-    // Allowed to be into the next wallclock slot minus the allocated l1 Publishing time
-    return this.aztecSlotDuration * 2 - this.l1PublishingTime;
+    const timeAvailableForBlocks = this.aztecSlotDuration - this.checkpointInitializationTime - this.timeReservedAtEnd;
+    return Math.floor(timeAvailableForBlocks / this.blockDuration);
   }
 }
 
 /**
- * Creates a checkpoint timing model for the requested scheduling mode.
+ * Creates a checkpoint timing model.
  *
  * Most callers should use this factory and depend only on the shared
- * `CheckpointTiming` interface. The returned implementation is selected from
- * `opts.pipelining`.
+ * `CheckpointTiming` interface.
  */
 export function createCheckpointTimingModel(opts: CheckpointTimingConfig): CheckpointTiming {
-  validateCheckpointTimingConfig(opts);
-  const normalizedOpts = normalizeCheckpointTimingConfig(opts);
-
-  const timing = normalizedOpts.pipelining
-    ? new PipelinedCheckpointTimingModel(normalizedOpts)
-    : new StandardCheckpointTimingModel(normalizedOpts);
-  validateCheckpointTimingModel(timing);
-  return timing;
+  return createPipelinedCheckpointTimingModel(opts);
 }
 
 /**
- * Creates a pipelined checkpoint timing model with target-slot window accessors.
+ * Creates a checkpoint timing model exposing the target-slot window accessors.
  *
- * Use this when the caller specifically needs the pipelined-only timing surface,
- * such as proposal or attestation acceptance windows into the target slot.
+ * 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: Omit<CheckpointTimingConfig, 'pipelining'>,
-): PipelinedCheckpointTiming {
+export function createPipelinedCheckpointTimingModel(opts: CheckpointTimingConfig): PipelinedCheckpointTiming {
   validateCheckpointTimingConfig(opts);
   const normalizedOpts = normalizeCheckpointTimingConfig(opts);
 
-  const timing = new PipelinedCheckpointTimingModel(normalizedOpts);
+  const timing = new CheckpointTimingModel(normalizedOpts);
   validateCheckpointTimingModel(timing);
   return timing;
 }
@@ -255,7 +215,6 @@ export function calculateMaxBlocksPerSlot(
     checkpointAssembleTime?: number;
     p2pPropagationTime?: number;
     l1PublishingTime?: number;
-    pipelining?: boolean;
   } = {},
 ): number {
   return createCheckpointTimingModel({
@@ -265,7 +224,6 @@ export function calculateMaxBlocksPerSlot(
     checkpointInitializationTime: opts.checkpointInitializationTime,
     l1PublishingTime: opts.l1PublishingTime,
     p2pPropagationTime: opts.p2pPropagationTime,
-    pipelining: opts.pipelining,
   }).calculateMaxBlocksPerSlot();
 }
 

package/src/trees/append_only_tree_snapshot.ts

@@ -1,6 +1,6 @@
 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';
@@ -44,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[] {

package/src/trees/nullifier_membership_witness.ts

@@ -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/tx/block_header.ts

@@ -4,7 +4,7 @@ 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';
 
@@ -85,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[] {

package/src/tx/global_variables.ts

@@ -4,13 +4,7 @@ import { randomInt } from '@aztec/foundation/crypto/random';
 import { Fr } from '@aztec/foundation/curves/bn254';
 import { EthAddress } from '@aztec/foundation/eth-address';
 import { jsonStringify } from '@aztec/foundation/json-rpc';
-import {
-  BufferReader,
-  FieldReader,
-  bigintToUInt64BE,
-  serializeToBuffer,
-  serializeToFields,
-} from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToFields, serializeToSink } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { inspect } from 'util';
@@ -149,17 +143,15 @@ export class GlobalVariables {
     ] as const;
   }
 
-  toBuffer() {
-    return serializeToBuffer([
-      this.chainId,
-      this.version,
-      this.blockNumber,
-      this.slotNumber,
-      bigintToUInt64BE(this.timestamp),
-      this.coinbase,
-      this.feeRecipient,
-      this.gasFees,
-    ]);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.chainId, this.version, this.blockNumber, this.slotNumber);
+    sink.writeUInt64(this.timestamp);
+    serializeToSink(sink, this.coinbase, this.feeRecipient, this.gasFees);
   }
 
   toFields() {

package/src/tx/hashed_values.ts

@@ -1,5 +1,5 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, serializeToSink } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { z } from 'zod';
@@ -48,8 +48,13 @@ export class HashedValues {
     return new HashedValues([Fr.random(), Fr.random()], Fr.random());
   }
 
-  toBuffer() {
-    return serializeToBuffer(new Vector(this.values), this.hash);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, new Vector(this.values), this.hash);
   }
 
   static fromBuffer(buffer: Buffer | BufferReader): HashedValues {

package/src/tx/indexed_tx_effect.ts

@@ -1,4 +1,4 @@
-import { BlockNumber } from '@aztec/foundation/branded-types';
+import { BlockNumber, SlotNumber } from '@aztec/foundation/branded-types';
 import { schemas } from '@aztec/foundation/schemas';
 import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
 
@@ -6,21 +6,32 @@ import { BlockHash } from '../block/block_hash.js';
 import { type DataInBlock, dataInBlockSchemaFor, randomDataInBlock } from '../block/in_block.js';
 import { TxEffect } from './tx_effect.js';
 
-export type IndexedTxEffect = DataInBlock<TxEffect> & { txIndexInBlock: number };
+/** A tx effect together with its position in the block (`txIndexInBlock`) and the slot the block was built in. */
+export type IndexedTxEffect = DataInBlock<TxEffect> & { txIndexInBlock: number; slotNumber: SlotNumber };
 
 export function indexedTxSchema() {
-  return dataInBlockSchemaFor(TxEffect.schema).extend({ txIndexInBlock: schemas.Integer });
+  return dataInBlockSchemaFor(TxEffect.schema).extend({
+    txIndexInBlock: schemas.Integer,
+    slotNumber: schemas.SlotNumber,
+  });
 }
 
 export async function randomIndexedTxEffect(): Promise<IndexedTxEffect> {
   return {
     ...randomDataInBlock(await TxEffect.random({ numNullifiers: 1 + Math.floor(Math.random() * 64) })),
     txIndexInBlock: Math.floor(Math.random() * 1000),
+    slotNumber: SlotNumber(Math.floor(Math.random() * 1000)),
   };
 }
 
 export function serializeIndexedTxEffect(effect: IndexedTxEffect): Buffer {
-  return serializeToBuffer(effect.l2BlockHash, effect.l2BlockNumber, effect.txIndexInBlock, effect.data);
+  return serializeToBuffer(
+    effect.l2BlockHash,
+    effect.l2BlockNumber,
+    effect.txIndexInBlock,
+    effect.slotNumber,
+    effect.data,
+  );
 }
 
 export function deserializeIndexedTxEffect(buffer: Buffer): IndexedTxEffect {
@@ -29,12 +40,14 @@ export function deserializeIndexedTxEffect(buffer: Buffer): IndexedTxEffect {
   const l2BlockHash = BlockHash.fromBuffer(reader);
   const l2BlockNumber = BlockNumber(reader.readNumber());
   const txIndexInBlock = reader.readNumber();
+  const slotNumber = SlotNumber(reader.readNumber());
   const data = reader.readObject(TxEffect);
 
   return {
     l2BlockHash,
     l2BlockNumber,
     txIndexInBlock,
+    slotNumber,
     data,
   };
 }

package/src/tx/partial_state_reference.ts

@@ -1,6 +1,6 @@
 import { PARTIAL_STATE_REFERENCE_LENGTH } from '@aztec/constants';
 import type { Fr } from '@aztec/foundation/curves/bn254';
-import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToSink } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { z } from 'zod';
@@ -88,8 +88,13 @@ export class PartialStateReference {
     );
   }
 
-  toBuffer() {
-    return serializeToBuffer(this.noteHashTree, this.nullifierTree, this.publicDataTree);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.noteHashTree, this.nullifierTree, this.publicDataTree);
   }
 
   toFields() {

package/src/tx/profiling.ts

@@ -133,12 +133,12 @@ export class TxProfileResult {
       ],
       {
         nodeRPCCalls: {
-          perMethod: { getBlockHeader: { times: [1] } },
+          perMethod: { getBlock: { times: [1] } },
           roundTrips: {
             roundTrips: 1,
             totalBlockingTime: 1,
             roundTripDurations: [1],
-            roundTripMethods: [['getBlockHeader']],
+            roundTripMethods: [['getBlock']],
           },
         },
         timings: {
@@ -184,12 +184,12 @@ export class UtilityExecutionResult {
   static random(): UtilityExecutionResult {
     return new UtilityExecutionResult([Fr.random()], [], 0n, {
       nodeRPCCalls: {
-        perMethod: { getBlockHeader: { times: [1] } },
+        perMethod: { getBlock: { times: [1] } },
         roundTrips: {
           roundTrips: 1,
           totalBlockingTime: 1,
           roundTripDurations: [1],
-          roundTripMethods: [['getBlockHeader']],
+          roundTripMethods: [['getBlock']],
         },
       },
       timings: {

package/src/tx/proven_tx.ts

@@ -13,6 +13,7 @@ import {
 } from './private_execution_result.js';
 import { type ProvingStats, ProvingTimingsSchema } from './profiling.js';
 import { Tx } from './tx.js';
+import type { TxHash } from './tx_hash.js';
 
 export class TxProvingResult {
   constructor(
@@ -22,6 +23,11 @@ export class TxProvingResult {
     public stats?: ProvingStats,
   ) {}
 
+  getTxHash(): Promise<TxHash> {
+    // Equivalent to `(await this.toTx()).txHash` but skips walking the execution result tree to collect logs.
+    return Tx.computeTxHash({ data: this.publicInputs });
+  }
+
   async toTx(): Promise<Tx> {
     const contractClassLogs = collectSortedContractClassLogs(this.privateExecutionResult);
 

package/src/tx/public_call_request_with_calldata.ts

@@ -1,5 +1,5 @@
 import { Fr } from '@aztec/foundation/curves/bn254';
-import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, serializeToSink } from '@aztec/foundation/serialize';
 
 import { inspect } from 'util';
 import { z } from 'zod';
@@ -63,8 +63,13 @@ export class PublicCallRequestWithCalldata {
     );
   }
 
-  toBuffer() {
-    return serializeToBuffer(this.request, new Vector(this.calldata));
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.request, new Vector(this.calldata));
   }
 
   static fromBuffer(buffer: Buffer | BufferReader) {

package/src/tx/simulated_tx.ts

@@ -3,13 +3,13 @@ import type { FieldsOf } from '@aztec/foundation/types';
 
 import { z } from 'zod';
 
-import { type ContractArtifact, ContractArtifactSchema } from '../abi/abi.js';
 import {
   type ContractInstanceWithAddress,
   ContractInstanceWithAddressSchema,
 } from '../contract/interfaces/contract_instance.js';
 import { Gas } from '../gas/gas.js';
 import type { GasUsed } from '../gas/gas_used.js';
+import { type PublicStorageOverride, PublicStorageOverrideSchema } from '../interfaces/public_storage_override.js';
 import { PrivateKernelTailCircuitPublicInputs } from '../kernel/private_kernel_tail_circuit_public_inputs.js';
 import { ChonkProof } from '../proofs/chonk_proof.js';
 import type { OffchainEffect } from './offchain_effect.js';
@@ -24,39 +24,36 @@ import { NestedProcessReturnValues, PublicSimulationOutput } from './public_simu
 import { Tx } from './tx.js';
 
 /*
- * If passed during the execution of a user circuit, the contract function simulator will replace the instance and class
- * of the contract with the one provided in the overrides for that address. An example use case
- * would be overriding your own account contract so that valid signatures don't have to be provided while simulating.
+ * If passed during the execution of a user circuit, the contract function simulator will replace
+ * the contract instance at that address with the one provided. An example use case would be
+ * overriding your own account contract so that valid signatures don't have to be provided while
+ * simulating. The override's `currentContractClassId` resolves through PXE's locally registered
+ * classes, so pre-register the target artifact via `pxe.registerContractClass(...)`.
  */
-export type ContractOverrides = Record<
-  string /* AztecAddress as string */,
-  { instance: ContractInstanceWithAddress; artifact: ContractArtifact }
->;
+export type ContractOverrides = Record<string /* AztecAddress as string */, { instance: ContractInstanceWithAddress }>;
 
 /*
- * Optional values that can be overridden during simulation. In order to simulate a transaction with these
- * set, it *must* be run without the kernel circuits, or validations will fail
+ * Optional values that can be overridden during simulation. `publicStorage` writes to the public-data
+ * tree fork. `contracts` overrides contract instances in the contract DB.
+ * In order to simulate a transaction with these set, it *must* be run without the kernel circuits,
+ * or validations will fail.
  */
 export class SimulationOverrides {
+  public publicStorage?: PublicStorageOverride[];
   public contracts?: ContractOverrides;
 
-  constructor(contracts: ContractOverrides = {}) {
-    this.contracts = Object.keys(contracts).length > 0 ? contracts : undefined;
+  constructor(args: { publicStorage?: PublicStorageOverride[]; contracts?: ContractOverrides } = {}) {
+    this.publicStorage = args.publicStorage?.length ? args.publicStorage : undefined;
+    this.contracts = args.contracts && Object.keys(args.contracts).length > 0 ? args.contracts : undefined;
   }
 
   static get schema() {
     return z
       .object({
-        contracts: optional(
-          z.record(
-            z.string(),
-            z.object({ instance: ContractInstanceWithAddressSchema, artifact: ContractArtifactSchema }),
-          ),
-        ),
+        publicStorage: optional(z.array(PublicStorageOverrideSchema)),
+        contracts: optional(z.record(z.string(), z.object({ instance: ContractInstanceWithAddressSchema }))),
       })
-      .transform(({ contracts }) => {
-        return new SimulationOverrides(contracts);
-      });
+      .transform(args => new SimulationOverrides(args));
   }
 }
 

package/src/tx/state_reference.ts

@@ -5,7 +5,7 @@ import {
   STATE_REFERENCE_LENGTH,
 } from '@aztec/constants';
 import type { Fr } from '@aztec/foundation/curves/bn254';
-import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferReader, BufferSink, FieldReader, serializeToSink } from '@aztec/foundation/serialize';
 import type { FieldsOf } from '@aztec/foundation/types';
 
 import { inspect } from 'util';
@@ -46,9 +46,14 @@ export class StateReference {
     return new StateReference(...StateReference.getFields(fields));
   }
 
-  toBuffer() {
-    // Note: The order here must match the order in the ProposedHeaderLib solidity library.
-    return serializeToBuffer(this.l1ToL2MessageTree, this.partial);
+  // Note: The order here must match the order in the ProposedHeaderLib solidity library.
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.l1ToL2MessageTree, this.partial);
   }
 
   toFields(): Fr[] {