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

package/src/tests/mocks.ts

@@ -1,63 +1,86 @@
-import { MAX_ENQUEUED_CALLS_PER_TX, MAX_INCLUDE_BY_TIMESTAMP_DURATION } from '@aztec/constants';
+import {
+  FIXED_DA_GAS,
+  FIXED_L2_GAS,
+  MAX_ENQUEUED_CALLS_PER_TX,
+  MAX_INCLUDE_BY_TIMESTAMP_DURATION,
+  MAX_NULLIFIERS_PER_TX,
+  MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
+} from '@aztec/constants';
+import { makeTuple } from '@aztec/foundation/array';
 import { Buffer32 } from '@aztec/foundation/buffer';
-import { times } from '@aztec/foundation/collection';
+import { padArrayEnd, times } from '@aztec/foundation/collection';
 import { Secp256k1Signer, randomBytes } from '@aztec/foundation/crypto';
 import { Fr } from '@aztec/foundation/fields';
 
 import type { ContractArtifact } from '../abi/abi.js';
+import { AvmCircuitPublicInputs } from '../avm/avm_circuit_public_inputs.js';
+import { PublicDataWrite } from '../avm/public_data_write.js';
+import { RevertCode } from '../avm/revert_code.js';
 import { AztecAddress } from '../aztec-address/index.js';
-import { CommitteeAttestation, L1PublishedData, L2BlockHeader } from '../block/index.js';
+import { CommitteeAttestation, L2BlockHeader } from '../block/index.js';
 import { L2Block } from '../block/l2_block.js';
 import type { CommitteeAttestationsAndSigners } from '../block/proposal/attestations_and_signers.js';
 import { PublishedL2Block } from '../block/published_l2_block.js';
+import type { Checkpoint } from '../checkpoint/checkpoint.js';
+import { L1PublishedData } from '../checkpoint/published_checkpoint.js';
 import { computeContractAddressFromInstance } from '../contract/contract_address.js';
 import { getContractClassFromArtifact } from '../contract/contract_class.js';
 import { SerializableContractInstance } from '../contract/contract_instance.js';
 import type { ContractInstanceWithAddress } from '../contract/index.js';
+import { computeEffectiveGasFees } from '../fees/transaction_fee.js';
 import { Gas } from '../gas/gas.js';
 import { GasFees } from '../gas/gas_fees.js';
 import { GasSettings } from '../gas/gas_settings.js';
+import type { GasUsed } from '../gas/gas_used.js';
+import type { MerkleTreeReadOperations } from '../interfaces/merkle_tree_operations.js';
 import { Nullifier } from '../kernel/nullifier.js';
 import { PrivateCircuitPublicInputs } from '../kernel/private_circuit_public_inputs.js';
 import {
   PartialPrivateTailPublicInputsForPublic,
   PrivateKernelTailCircuitPublicInputs,
 } from '../kernel/private_kernel_tail_circuit_public_inputs.js';
+import { PrivateToAvmAccumulatedData } from '../kernel/private_to_avm_accumulated_data.js';
 import { PrivateToPublicAccumulatedDataBuilder } from '../kernel/private_to_public_accumulated_data_builder.js';
-import { Note } from '../note/note.js';
-import { UniqueNote } from '../note/unique_note.js';
+import { PublicCallRequestArrayLengths } from '../kernel/public_call_request.js';
 import { BlockAttestation } from '../p2p/block_attestation.js';
 import { BlockProposal } from '../p2p/block_proposal.js';
 import { ConsensusPayload } from '../p2p/consensus_payload.js';
 import { SignatureDomainSeparator, getHashedSignaturePayloadEthSignedMessage } from '../p2p/signature_utils.js';
 import { ChonkProof } from '../proofs/chonk_proof.js';
-import { HashedValues, PrivateCallExecutionResult, PrivateExecutionResult, StateReference, Tx } from '../tx/index.js';
-import { PublicSimulationOutput } from '../tx/public_simulation_output.js';
-import { TxSimulationResult, accumulatePrivateReturnValues } from '../tx/simulated_tx.js';
+import { ProvingRequestType } from '../proofs/proving_request_type.js';
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+import {
+  BlockHeader,
+  GlobalVariables,
+  HashedValues,
+  PrivateCallExecutionResult,
+  PrivateExecutionResult,
+  ProtocolContracts,
+  Tx,
+  TxConstantData,
+  makeProcessedTxFromPrivateOnlyTx,
+  makeProcessedTxFromTxWithPublicCalls,
+} from '../tx/index.js';
+import { NestedProcessReturnValues, PublicSimulationOutput } from '../tx/public_simulation_output.js';
+import { TxSimulationResult } from '../tx/simulated_tx.js';
 import { TxEffect } from '../tx/tx_effect.js';
 import { TxHash } from '../tx/tx_hash.js';
-import { makeGas, makeGlobalVariables, makeL2BlockHeader, makePublicCallRequest } from './factories.js';
+import {
+  makeAvmCircuitInputs,
+  makeAztecAddress,
+  makeBlockHeader,
+  makeGas,
+  makeGlobalVariables,
+  makeL2BlockHeader,
+  makePrivateToPublicAccumulatedData,
+  makePrivateToRollupAccumulatedData,
+  makeProtocolContracts,
+  makePublicCallRequest,
+  makePublicDataWrite,
+} from './factories.js';
 
 export const randomTxHash = (): TxHash => TxHash.random();
 
-export const randomUniqueNote = async ({
-  note = Note.random(),
-  recipient = undefined,
-  contractAddress = undefined,
-  txHash = randomTxHash(),
-  storageSlot = Fr.random(),
-  noteNonce = Fr.random(),
-}: Partial<UniqueNote> = {}) => {
-  return new UniqueNote(
-    note,
-    recipient ?? (await AztecAddress.random()),
-    contractAddress ?? (await AztecAddress.random()),
-    storageSlot,
-    txHash,
-    noteNonce,
-  );
-};
-
 export const mockTx = async (
   seed = 1,
   {
@@ -159,6 +182,156 @@ export const mockTx = async (
 export const mockTxForRollup = (seed = 1, opts: Parameters<typeof mockTx>[1] = {}) =>
   mockTx(seed, { ...opts, numberOfNonRevertiblePublicCallRequests: 0, numberOfRevertiblePublicCallRequests: 0 });
 
+/** Mock a processed tx for testing purposes. */
+export async function mockProcessedTx({
+  seed = 1,
+  anchorBlockHeader,
+  db,
+  chainId = Fr.ZERO,
+  version = Fr.ZERO,
+  gasSettings = GasSettings.default({ maxFeesPerGas: new GasFees(10, 10) }),
+  vkTreeRoot = Fr.ZERO,
+  protocolContracts = makeProtocolContracts(seed + 0x100),
+  globalVariables = GlobalVariables.empty(),
+  newL1ToL2Snapshot = AppendOnlyTreeSnapshot.empty(),
+  feePayer,
+  feePaymentPublicDataWrite,
+  // The default gasUsed is the tx overhead.
+  gasUsed = Gas.from({ daGas: FIXED_DA_GAS, l2Gas: FIXED_L2_GAS }),
+  privateOnly = false,
+  ...mockTxOpts
+}: {
+  seed?: number;
+  anchorBlockHeader?: BlockHeader;
+  db?: MerkleTreeReadOperations;
+  gasSettings?: GasSettings;
+  globalVariables?: GlobalVariables;
+  newL1ToL2Snapshot?: AppendOnlyTreeSnapshot;
+  protocolContracts?: ProtocolContracts;
+  feePaymentPublicDataWrite?: PublicDataWrite;
+  privateOnly?: boolean;
+} & Parameters<typeof mockTx>[1] = {}) {
+  seed *= 0x1000; // Avoid clashing with the previous mock values if seed only increases by 1.
+  anchorBlockHeader ??= db?.getInitialHeader() ?? makeBlockHeader(seed);
+  feePayer ??= makeAztecAddress(seed + 0x100);
+  feePaymentPublicDataWrite ??= makePublicDataWrite(seed + 0x200);
+
+  const txConstantData = TxConstantData.empty();
+  txConstantData.anchorBlockHeader = anchorBlockHeader;
+  txConstantData.txContext.chainId = chainId;
+  txConstantData.txContext.version = version;
+  txConstantData.txContext.gasSettings = gasSettings;
+  txConstantData.vkTreeRoot = vkTreeRoot;
+  txConstantData.protocolContractsHash = await protocolContracts.hash();
+
+  const tx = !privateOnly
+    ? await mockTx(seed, { feePayer, gasUsed, ...mockTxOpts })
+    : await mockTx(seed, {
+        numberOfNonRevertiblePublicCallRequests: 0,
+        numberOfRevertiblePublicCallRequests: 0,
+        feePayer,
+        gasUsed,
+        ...mockTxOpts,
+      });
+  tx.data.constants = txConstantData;
+
+  const transactionFee = tx.data.gasUsed.computeFee(globalVariables.gasFees);
+
+  if (privateOnly) {
+    const data = makePrivateToRollupAccumulatedData(seed + 0x1000, { numContractClassLogs: 0 });
+
+    tx.data.forRollup!.end = data;
+
+    await tx.recomputeHash();
+    return makeProcessedTxFromPrivateOnlyTx(tx, transactionFee, feePaymentPublicDataWrite, globalVariables);
+  } else {
+    const dataFromPrivate = tx.data.forPublic!;
+
+    const nonRevertibleData = dataFromPrivate.nonRevertibleAccumulatedData;
+
+    // Create revertible data.
+    const revertibleData = makePrivateToPublicAccumulatedData(seed + 0x1000, { numContractClassLogs: 0 });
+    revertibleData.nullifiers[MAX_NULLIFIERS_PER_TX - 1] = Fr.ZERO; // Leave one space for the tx hash nullifier in nonRevertibleAccumulatedData.
+    dataFromPrivate.revertibleAccumulatedData = revertibleData;
+
+    // Create avm output.
+    const avmOutput = AvmCircuitPublicInputs.empty();
+    // Assign data from hints.
+    avmOutput.protocolContracts = protocolContracts;
+    avmOutput.startTreeSnapshots.l1ToL2MessageTree = newL1ToL2Snapshot;
+    avmOutput.endTreeSnapshots.l1ToL2MessageTree = newL1ToL2Snapshot;
+    avmOutput.effectiveGasFees = computeEffectiveGasFees(globalVariables.gasFees, gasSettings);
+    // Assign data from private.
+    avmOutput.globalVariables = globalVariables;
+    avmOutput.startGasUsed = tx.data.gasUsed;
+    avmOutput.gasSettings = gasSettings;
+    avmOutput.feePayer = feePayer;
+    avmOutput.publicCallRequestArrayLengths = new PublicCallRequestArrayLengths(
+      tx.data.numberOfNonRevertiblePublicCallRequests(),
+      tx.data.numberOfRevertiblePublicCallRequests(),
+      tx.data.hasTeardownPublicCallRequest(),
+    );
+    avmOutput.publicSetupCallRequests = dataFromPrivate.nonRevertibleAccumulatedData.publicCallRequests;
+    avmOutput.publicAppLogicCallRequests = dataFromPrivate.revertibleAccumulatedData.publicCallRequests;
+    avmOutput.publicTeardownCallRequest = dataFromPrivate.publicTeardownCallRequest;
+    avmOutput.previousNonRevertibleAccumulatedData = new PrivateToAvmAccumulatedData(
+      dataFromPrivate.nonRevertibleAccumulatedData.noteHashes,
+      dataFromPrivate.nonRevertibleAccumulatedData.nullifiers,
+      dataFromPrivate.nonRevertibleAccumulatedData.l2ToL1Msgs,
+    );
+    avmOutput.previousNonRevertibleAccumulatedDataArrayLengths =
+      avmOutput.previousNonRevertibleAccumulatedData.getArrayLengths();
+    avmOutput.previousRevertibleAccumulatedData = new PrivateToAvmAccumulatedData(
+      dataFromPrivate.revertibleAccumulatedData.noteHashes,
+      dataFromPrivate.revertibleAccumulatedData.nullifiers,
+      dataFromPrivate.revertibleAccumulatedData.l2ToL1Msgs,
+    );
+    avmOutput.previousRevertibleAccumulatedDataArrayLengths =
+      avmOutput.previousRevertibleAccumulatedData.getArrayLengths();
+    // Assign final data emitted from avm.
+    avmOutput.accumulatedData.noteHashes = revertibleData.noteHashes;
+    avmOutput.accumulatedData.nullifiers = padArrayEnd(
+      nonRevertibleData.nullifiers.concat(revertibleData.nullifiers).filter(n => !n.isEmpty()),
+      Fr.ZERO,
+      MAX_NULLIFIERS_PER_TX,
+    );
+    avmOutput.accumulatedData.l2ToL1Msgs = revertibleData.l2ToL1Msgs;
+    avmOutput.accumulatedData.publicDataWrites = makeTuple(
+      MAX_TOTAL_PUBLIC_DATA_UPDATE_REQUESTS_PER_TX,
+      i => new PublicDataWrite(new Fr(i), new Fr(i + 10)),
+      seed + 0x2000,
+    );
+    avmOutput.accumulatedData.publicDataWrites[0] = feePaymentPublicDataWrite;
+    avmOutput.accumulatedDataArrayLengths = avmOutput.accumulatedData.getArrayLengths();
+    avmOutput.gasSettings = gasSettings;
+    // Note: The fee is computed from the tx's gas used, which only includes the gas used in private. But this shouldn't
+    // be a problem for the tests.
+    avmOutput.transactionFee = transactionFee;
+
+    const avmCircuitInputs = await makeAvmCircuitInputs(seed + 0x3000, { publicInputs: avmOutput });
+    avmCircuitInputs.hints.startingTreeRoots.l1ToL2MessageTree = newL1ToL2Snapshot;
+
+    const gasUsed = {
+      totalGas: Gas.empty(),
+      teardownGas: Gas.empty(),
+      publicGas: Gas.empty(),
+      billedGas: Gas.empty(),
+    } satisfies GasUsed;
+
+    await tx.recomputeHash();
+    return makeProcessedTxFromTxWithPublicCalls(
+      tx,
+      {
+        type: ProvingRequestType.PUBLIC_VM,
+        inputs: avmCircuitInputs,
+      },
+      gasUsed,
+      RevertCode.OK,
+      undefined /* revertReason */,
+    );
+  }
+}
+
 const emptyPrivateCallExecutionResult = () =>
   new PrivateCallExecutionResult(
     Buffer.from(''),
@@ -184,7 +357,7 @@ export const mockSimulatedTx = async (seed = 1) => {
     undefined,
     makeGlobalVariables(),
     await TxEffect.random(),
-    [accumulatePrivateReturnValues(privateExecutionResult)],
+    times(2, () => NestedProcessReturnValues.random(2)),
     {
       totalGas: makeGas(),
       teardownGas: makeGas(),
@@ -234,7 +407,6 @@ export interface MakeConsensusPayloadOptions {
   proposerSigner?: Secp256k1Signer;
   header?: L2BlockHeader;
   archive?: Fr;
-  stateReference?: StateReference;
   txHashes?: TxHash[];
   txs?: Tx[];
 }
@@ -244,12 +416,11 @@ const makeAndSignConsensusPayload = (
   options?: MakeConsensusPayloadOptions,
 ) => {
   const header = options?.header ?? makeL2BlockHeader(1);
-  const { signer = Secp256k1Signer.random(), archive = Fr.random(), stateReference = header.state } = options ?? {};
+  const { signer = Secp256k1Signer.random(), archive = Fr.random() } = options ?? {};
 
   const payload = ConsensusPayload.fromFields({
     header: header.toCheckpointHeader(),
     archive,
-    stateReference,
   });
 
   const hash = getHashedSignaturePayloadEthSignedMessage(payload, domainSeparator);
@@ -276,31 +447,32 @@ export const makeBlockProposal = (options?: MakeConsensusPayloadOptions): BlockP
 };
 
 // TODO(https://github.com/AztecProtocol/aztec-packages/issues/8028)
-export const makeBlockAttestation = (options?: MakeConsensusPayloadOptions): BlockAttestation => {
-  const header = options?.header ?? makeL2BlockHeader(1);
-  const {
-    signer,
-    attesterSigner = signer ?? Secp256k1Signer.random(),
-    proposerSigner = signer ?? Secp256k1Signer.random(),
-    archive = Fr.random(),
-    stateReference = header.state,
-  } = options ?? {};
+export const makeBlockAttestation = (options: MakeConsensusPayloadOptions = {}): BlockAttestation => {
+  const header = options.header ?? makeL2BlockHeader(1);
+  const { signer, attesterSigner = signer, proposerSigner = signer, archive = Fr.random() } = options;
 
   const payload = ConsensusPayload.fromFields({
     header: header.toCheckpointHeader(),
     archive,
-    stateReference,
   });
 
-  // Sign as attester
-  const attestationHash = getHashedSignaturePayloadEthSignedMessage(payload, SignatureDomainSeparator.blockAttestation);
-  const attestationSignature = attesterSigner.sign(attestationHash);
+  return makeBlockAttestationFromPayload(payload, attesterSigner, proposerSigner);
+};
 
-  // Sign as proposer
-  const proposalHash = getHashedSignaturePayloadEthSignedMessage(payload, SignatureDomainSeparator.blockProposal);
-  const proposerSignature = proposerSigner.sign(proposalHash);
+export const makeAttestationFromCheckpoint = (
+  checkpoint: Checkpoint,
+  attesterSigner?: Secp256k1Signer,
+  proposerSigner?: Secp256k1Signer,
+): BlockAttestation => {
+  const header = checkpoint.header;
+  const archive = checkpoint.archive.root;
 
-  return new BlockAttestation(payload, attestationSignature, proposerSignature);
+  const payload = ConsensusPayload.fromFields({
+    header,
+    archive,
+  });
+
+  return makeBlockAttestationFromPayload(payload, attesterSigner, proposerSigner);
 };
 
 export const makeBlockAttestationFromBlock = (
@@ -310,14 +482,20 @@ export const makeBlockAttestationFromBlock = (
 ): BlockAttestation => {
   const header = block.header;
   const archive = block.archive.root;
-  const stateReference = block.header.state;
 
   const payload = ConsensusPayload.fromFields({
     header: header.toCheckpointHeader(),
     archive,
-    stateReference,
   });
 
+  return makeBlockAttestationFromPayload(payload, attesterSigner, proposerSigner);
+};
+
+export const makeBlockAttestationFromPayload = (
+  payload: ConsensusPayload,
+  attesterSigner?: Secp256k1Signer,
+  proposerSigner?: Secp256k1Signer,
+): BlockAttestation => {
   // Sign as attester
   const attestationHash = getHashedSignaturePayloadEthSignedMessage(payload, SignatureDomainSeparator.blockAttestation);
   const attestationSigner = attesterSigner ?? Secp256k1Signer.random();

package/src/trees/append_only_tree_snapshot.ts

@@ -1,4 +1,3 @@
-import type { ViemAppendOnlyTreeSnapshot } from '@aztec/ethereum';
 import { Fr } from '@aztec/foundation/fields';
 import { schemas } from '@aztec/foundation/schemas';
 import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
@@ -72,17 +71,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 +79,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/nullifier_leaf.ts

@@ -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;
   }
@@ -157,4 +175,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/public_data_leaf.ts

@@ -36,6 +36,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;
   }
@@ -172,4 +190,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/tx/block_header.ts

@@ -1,5 +1,6 @@
 import { BLOCK_HEADER_LENGTH, GeneratorIndex } from '@aztec/constants';
-import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto';
+import { SlotNumber } from '@aztec/foundation/branded-types';
+import { poseidon2HashWithSeparator, randomInt } from '@aztec/foundation/crypto';
 import { Fr } from '@aztec/foundation/fields';
 import { type ZodFor, schemas } from '@aztec/foundation/schemas';
 import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
@@ -61,8 +62,8 @@ export class BlockHeader {
     return new BlockHeader(...BlockHeader.getFields(fields));
   }
 
-  getSlot() {
-    return this.globalVariables.slotNumber.toBigInt();
+  getSlot(): SlotNumber {
+    return this.globalVariables.slotNumber;
   }
 
   getBlockNumber() {
@@ -161,6 +162,18 @@ export class BlockHeader {
     return poseidon2HashWithSeparator(this.toFields(), GeneratorIndex.BLOCK_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() {
     return {
       lastArchive: this.lastArchive.root.toString(),

package/src/tx/execution_payload.ts

@@ -0,0 +1,60 @@
+import type { FunctionCall } from '../abi/function_call.js';
+import type { AuthWitness } from '../auth_witness/auth_witness.js';
+import { AztecAddress } from '../aztec-address/index.js';
+import type { Capsule } from './capsule.js';
+import type { HashedValues } from './hashed_values.js';
+
+/**
+ * Represents data necessary to perform an action in the network successfully.
+ * This class can be considered Aztec's "minimal execution unit".
+ * */
+export class ExecutionPayload {
+  public constructor(
+    /** The function calls to be executed. */
+    public calls: FunctionCall[],
+    /** Any transient auth witnesses needed for this execution */
+    public authWitnesses: AuthWitness[],
+    /** Data passed through an oracle for this execution. */
+    public capsules: Capsule[],
+    /** Extra hashed values to be injected in the execution cache */
+    public extraHashedArgs: HashedValues[] = [],
+    /**
+     * The address that is paying for the fee in this execution payload (if any).
+     * If undefined, the wallet software executing the payload will have to add a fee payment method
+     */
+    public feePayer?: AztecAddress,
+  ) {}
+
+  static empty() {
+    return new ExecutionPayload([], [], [], [], undefined);
+  }
+}
+
+/**
+ * Merges an array ExecutionPayloads combining their calls, authWitnesses, capsules and extraArgHashes.
+ * @throws Error if multiple payloads have different fee payers set
+ */
+export function mergeExecutionPayloads(requests: ExecutionPayload[]): ExecutionPayload {
+  const calls = requests.map(r => r.calls).flat();
+  const combinedAuthWitnesses = requests.map(r => r.authWitnesses ?? []).flat();
+  const combinedCapsules = requests.map(r => r.capsules ?? []).flat();
+  const combinedExtraHashedArgs = requests.map(r => r.extraHashedArgs ?? []).flat();
+
+  // Collect unique fee payers
+  const uniqueFeePayers = new Set(
+    requests
+      .map(r => r.feePayer)
+      .filter((fp): fp is AztecAddress => fp !== undefined)
+      .map(fp => fp.toString()),
+  );
+
+  if (uniqueFeePayers.size > 1) {
+    throw new Error(
+      `Cannot merge execution payloads with different fee payers. Found: ${Array.from(uniqueFeePayers).join(', ')}`,
+    );
+  }
+
+  const feePayer = uniqueFeePayers.size === 1 ? AztecAddress.fromString(Array.from(uniqueFeePayers)[0]) : undefined;
+
+  return new ExecutionPayload(calls, combinedAuthWitnesses, combinedCapsules, combinedExtraHashedArgs, feePayer);
+}

package/src/tx/global_variable_builder.ts

@@ -1,4 +1,5 @@
 import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { SlotNumber } from '@aztec/foundation/schemas';
 
 import type { AztecAddress } from '../aztec-address/index.js';
 import type { GasFees } from '../gas/gas_fees.js';
@@ -23,6 +24,6 @@ export interface GlobalVariableBuilder {
     blockNumber: UInt32,
     coinbase: EthAddress,
     feeRecipient: AztecAddress,
-    slotNumber?: bigint,
+    slotNumber?: SlotNumber,
   ): Promise<GlobalVariables>;
 }