@aztec-labs/stdlib 6.0.0-nightly.20260829

package/src/tx/global_variable_builder.ts

@@ -0,0 +1,19 @@
+import type { SimulationOverridesPlan } from '@aztec-labs/ethereum/contracts';
+import type { EthAddress } from '@aztec-labs/foundation/eth-address';
+import type { SlotNumber } from '@aztec-labs/foundation/schemas';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+import type { CheckpointGlobalVariables } from './global_variables.js';
+
+/**
+ * Interface for building global variables for Aztec blocks.
+ */
+export interface GlobalVariableBuilder {
+  /** Builds global variables that are constant throughout a checkpoint. */
+  buildCheckpointGlobalVariables(
+    coinbase: EthAddress,
+    feeRecipient: AztecAddress,
+    slotNumber: SlotNumber,
+    simulationOverridesPlan?: SimulationOverridesPlan,
+  ): Promise<CheckpointGlobalVariables>;
+}

package/src/tx/global_variables.ts

@@ -0,0 +1,265 @@
+import { GLOBAL_VARIABLES_LENGTH } from '@aztec-labs/constants';
+import { BlockNumber, BlockNumberSchema, SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { randomInt } from '@aztec-labs/foundation/crypto/random';
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { EthAddress } from '@aztec-labs/foundation/eth-address';
+import { jsonStringify } from '@aztec-labs/foundation/json-rpc';
+import {
+  BufferReader,
+  BufferSink,
+  FieldReader,
+  serializeToFields,
+  serializeToSink,
+} from '@aztec-labs/foundation/serialize';
+import type { FieldsOf } from '@aztec-labs/foundation/types';
+import { inspect } from 'util';
+import { z } from 'zod';
+
+import { AztecAddress } from '../aztec-address/index.js';
+import { GasFees } from '../gas/gas_fees.js';
+import { schemas } from '../schemas/index.js';
+import type { UInt64 } from '../types/index.js';
+
+/**
+ * Global variables that are constant across the entire checkpoint (slot).
+ * Excludes blockNumber since that varies per block within a checkpoint.
+ */
+export type CheckpointGlobalVariables = Omit<FieldsOf<GlobalVariables>, 'blockNumber'>;
+
+/**
+ * Global variables of the L2 block.
+ */
+export class GlobalVariables {
+  constructor(
+    /** ChainId for the L2 block. */
+    public chainId: Fr,
+    /** Version for the L2 block. */
+    public version: Fr,
+    /** Block number of the L2 block. */
+    public blockNumber: BlockNumber,
+    /** Slot number of the L2 block */
+    public slotNumber: SlotNumber,
+    /** Timestamp of the L2 block. */
+    public timestamp: UInt64,
+    /** Recipient of block reward. */
+    public coinbase: EthAddress,
+    /** Address to receive fees. */
+    public feeRecipient: AztecAddress,
+    /** Global gas prices for this block. */
+    public gasFees: GasFees,
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        chainId: schemas.Fr,
+        version: schemas.Fr,
+        blockNumber: BlockNumberSchema,
+        slotNumber: schemas.SlotNumber,
+        timestamp: schemas.BigInt,
+        coinbase: schemas.EthAddress,
+        feeRecipient: schemas.AztecAddress,
+        gasFees: GasFees.schema,
+      })
+      .transform(GlobalVariables.from);
+  }
+
+  getSize(): number {
+    return this.toBuffer().length;
+  }
+
+  static from(fields: FieldsOf<GlobalVariables>): GlobalVariables {
+    return new GlobalVariables(...GlobalVariables.getFields(fields));
+  }
+
+  /**
+   * Creates a GlobalVariables 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 GlobalVariables fields
+   * @returns A GlobalVariables instance
+   */
+  static fromPlainObject(obj: any): GlobalVariables {
+    return new GlobalVariables(
+      Fr.fromPlainObject(obj.chainId),
+      Fr.fromPlainObject(obj.version),
+      obj.blockNumber,
+      SlotNumber(Fr.fromPlainObject(obj.slotNumber).toNumber()),
+      typeof obj.timestamp === 'bigint' ? obj.timestamp : BigInt(obj.timestamp),
+      EthAddress.fromPlainObject(obj.coinbase),
+      AztecAddress.fromPlainObject(obj.feeRecipient),
+      GasFees.fromPlainObject(obj.gasFees),
+    );
+  }
+
+  static empty(fields: Partial<FieldsOf<GlobalVariables>> = {}): GlobalVariables {
+    return GlobalVariables.from({
+      blockNumber: BlockNumber.ZERO,
+      slotNumber: SlotNumber.ZERO,
+      timestamp: 0n,
+      chainId: Fr.ZERO,
+      version: Fr.ZERO,
+      coinbase: EthAddress.ZERO,
+      feeRecipient: AztecAddress.ZERO,
+      gasFees: GasFees.empty(),
+      ...fields,
+    });
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): GlobalVariables {
+    const reader = BufferReader.asReader(buffer);
+    return new GlobalVariables(
+      Fr.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+      BlockNumber(reader.readNumber()),
+      SlotNumber(reader.readNumber()),
+      reader.readUInt64(),
+      reader.readObject(EthAddress),
+      reader.readObject(AztecAddress),
+      reader.readObject(GasFees),
+    );
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): GlobalVariables {
+    const reader = FieldReader.asReader(fields);
+
+    return new GlobalVariables(
+      reader.readField(),
+      reader.readField(),
+      BlockNumber(reader.readU32()),
+      SlotNumber(reader.readU32()),
+      reader.readField().toBigInt(),
+      EthAddress.fromField(reader.readField()),
+      AztecAddress.fromFieldUnsafe(reader.readField()),
+      GasFees.fromFields(reader),
+    );
+  }
+
+  static getFields(fields: FieldsOf<GlobalVariables>) {
+    return [
+      fields.chainId,
+      fields.version,
+      fields.blockNumber,
+      fields.slotNumber,
+      fields.timestamp,
+      fields.coinbase,
+      fields.feeRecipient,
+      fields.gasFees,
+    ] as const;
+  }
+
+  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() {
+    const fields = serializeToFields(...GlobalVariables.getFields(this));
+    if (fields.length !== GLOBAL_VARIABLES_LENGTH) {
+      throw new Error(
+        `Invalid number of fields for GlobalVariables. Expected ${GLOBAL_VARIABLES_LENGTH}, got ${fields.length}`,
+      );
+    }
+    return fields;
+  }
+
+  /**
+   * A trimmed version of the JSON representation of the global variables,
+   * tailored for human consumption.
+   */
+  toFriendlyJSON() {
+    return {
+      blockNumber: this.blockNumber,
+      slotNumber: this.slotNumber,
+      timestamp: this.timestamp.toString(),
+      coinbase: this.coinbase.toString(),
+      gasFees: jsonStringify(this.gasFees),
+    };
+  }
+
+  /**
+   * Converts GlobalVariables to a plain object suitable for MessagePack serialization.
+   * This method ensures that slotNumber is serialized as a Fr (Field element) to match
+   * the C++ struct definition which expects slot_number as FF.
+   */
+  toJSON() {
+    return {
+      chainId: this.chainId,
+      version: this.version,
+      blockNumber: this.blockNumber,
+      slotNumber: new Fr(this.slotNumber), // Convert to Fr for C++ compatibility
+      timestamp: this.timestamp,
+      coinbase: this.coinbase,
+      feeRecipient: this.feeRecipient,
+      gasFees: this.gasFees,
+    };
+  }
+
+  clone(): GlobalVariables {
+    return GlobalVariables.fromBuffer(this.toBuffer());
+  }
+
+  isEmpty(): boolean {
+    return (
+      this.chainId.isZero() &&
+      this.version.isZero() &&
+      this.blockNumber === 0 &&
+      this.slotNumber === 0 &&
+      this.timestamp === 0n &&
+      this.coinbase.isZero() &&
+      this.feeRecipient.isZero() &&
+      this.gasFees.isEmpty()
+    );
+  }
+
+  static random(overrides: Partial<FieldsOf<GlobalVariables>> = {}): GlobalVariables {
+    return GlobalVariables.from({
+      chainId: new Fr(randomInt(100_000)),
+      version: new Fr(randomInt(100_000)),
+      blockNumber: BlockNumber(randomInt(100_000)),
+      slotNumber: SlotNumber(randomInt(100_000)),
+      coinbase: EthAddress.random(),
+      feeRecipient: AztecAddress.fromFieldUnsafe(Fr.random()),
+      gasFees: GasFees.random(),
+      timestamp: BigInt(randomInt(100_000_000)),
+      ...overrides,
+    });
+  }
+
+  toInspect() {
+    return {
+      chainId: this.chainId.toNumber(),
+      version: this.version.toNumber(),
+      blockNumber: this.blockNumber,
+      slotNumber: this.slotNumber,
+      timestamp: this.timestamp,
+      coinbase: this.coinbase.toString(),
+      feeRecipient: this.feeRecipient.toString(),
+      feePerDaGas: Number(this.gasFees.feePerDaGas),
+      feePerL2Gas: Number(this.gasFees.feePerL2Gas),
+    };
+  }
+
+  [inspect.custom]() {
+    return `GlobalVariables ${inspect(this.toInspect())}`;
+  }
+
+  public equals(other: this): boolean {
+    return (
+      this.chainId.equals(other.chainId) &&
+      this.version.equals(other.version) &&
+      this.blockNumber === other.blockNumber &&
+      this.slotNumber === other.slotNumber &&
+      this.timestamp === other.timestamp &&
+      this.coinbase.equals(other.coinbase) &&
+      this.feeRecipient.equals(other.feeRecipient) &&
+      this.gasFees.equals(other.gasFees)
+    );
+  }
+}

package/src/tx/hashed_values.ts

@@ -0,0 +1,78 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader, BufferSink, serializeToSink } from '@aztec-labs/foundation/serialize';
+import type { FieldsOf } from '@aztec-labs/foundation/types';
+import { z } from 'zod';
+
+import { computeCalldataHash, computeVarArgsHash } from '../hash/index.js';
+import { type ZodFor, schemas } from '../schemas/schemas.js';
+import { Vector } from '../types/index.js';
+
+/**
+ * A container for storing a list of values and their hash.
+ */
+export class HashedValues {
+  constructor(
+    /**
+     *  Raw values.
+     */
+    public readonly values: Fr[],
+    /**
+     * The hash of the raw values
+     */
+    public readonly hash: Fr,
+  ) {}
+
+  getSize() {
+    return this.values.length + 1 /* hash */;
+  }
+
+  static get schema(): ZodFor<HashedValues> {
+    return HashedValues.schemaFor();
+  }
+
+  /**
+   * Returns a schema that additionally rejects more than `maxValues` values. The bound belongs to the caller
+   * rather than to this class: the same container carries public calldata, private call arguments and authwit
+   * arguments, and those have different limits.
+   */
+  static schemaFor(maxValues?: number): ZodFor<HashedValues> {
+    const values = maxValues === undefined ? z.array(schemas.Fr) : z.array(schemas.Fr).max(maxValues);
+    return z.object({ values, hash: schemas.Fr }).transform(HashedValues.from);
+  }
+
+  static from(fields: FieldsOf<HashedValues>): HashedValues {
+    return new HashedValues(...HashedValues.getFields(fields));
+  }
+
+  static getFields(fields: FieldsOf<HashedValues>) {
+    return [fields.values, fields.hash] as const;
+  }
+
+  static random() {
+    return new HashedValues([Fr.random(), Fr.random()], Fr.random());
+  }
+
+  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 {
+    const reader = BufferReader.asReader(buffer);
+    return new HashedValues(reader.readVector(Fr), Fr.fromBuffer(reader));
+  }
+
+  // Computes the hash of input arguments or return values for private functions, or for authwit creation.
+  static async fromArgs(args: Fr[]) {
+    return new HashedValues(args, await computeVarArgsHash(args));
+  }
+
+  // Computes the hash of calldata for public functions.
+  static async fromCalldata(calldata: Fr[]) {
+    return new HashedValues(calldata, await computeCalldataHash(calldata));
+  }
+}

package/src/tx/in_tx.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+import { type InBlock, inBlockSchema, randomInBlock } from '../block/in_block.js';
+import { TxHash } from './tx_hash.js';
+
+export type InTx = InBlock & {
+  txHash: TxHash;
+};
+
+export function randomInTx(): InTx {
+  return {
+    ...randomInBlock(),
+    txHash: TxHash.random(),
+  };
+}
+
+export function inTxSchema() {
+  return z.intersection(
+    inBlockSchema(),
+    z.object({
+      txHash: TxHash.schema,
+    }),
+  );
+}

package/src/tx/index.ts

@@ -0,0 +1,34 @@
+export * from './block_header.js';
+export * from './call_context.js';
+export * from './global_variables.js';
+export * from './state_reference.js';
+export * from './partial_state_reference.js';
+export * from './function_data.js';
+export * from './tree_snapshots.js';
+export * from './private_tx_constant_data.js';
+export * from './tx_constant_data.js';
+export * from './tx_context.js';
+export * from './tx_request.js';
+export * from './private_execution_result.js';
+export * from './public_call_request_with_calldata.js';
+export * from './tx_hash.js';
+export * from './tx_receipt.js';
+export * from './tx.js';
+export * from './processed_tx.js';
+export * from './proven_tx.js';
+export * from './simulated_tx.js';
+export * from './tx_effect.js';
+export * from './public_simulation_output.js';
+export * from './tx_execution_request.js';
+export * from './validator/tx_validator.js';
+export * from './validator/error_texts.js';
+export * from './capsule.js';
+export * from './fee_provider.js';
+export * from './global_variable_builder.js';
+export * from './hashed_values.js';
+export * from './indexed_tx_effect.js';
+export * from './offchain_effect.js';
+export * from './profiling.js';
+export * from './protocol_contracts.js';
+export * from './execution_payload.js';
+export * from './in_tx.js';

package/src/tx/indexed_tx_effect.ts

@@ -0,0 +1,53 @@
+import { BlockNumber, SlotNumber } from '@aztec-labs/foundation/branded-types';
+import { schemas } from '@aztec-labs/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec-labs/foundation/serialize';
+
+import { BlockHash } from '../block/block_hash.js';
+import { type DataInBlock, dataInBlockSchemaFor, randomDataInBlock } from '../block/in_block.js';
+import { TxEffect } from './tx_effect.js';
+
+/** 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,
+    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.slotNumber,
+    effect.data,
+  );
+}
+
+export function deserializeIndexedTxEffect(buffer: Buffer): IndexedTxEffect {
+  const reader = BufferReader.asReader(buffer);
+
+  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/offchain_effect.ts

@@ -0,0 +1,20 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+
+// The following identifier was copied over from `noir-projects/aztec-nr/aztec/src/messages/offchain_messages.nr`.
+// poseidon2hash("aztecnr_offchain_message")
+export const OFFCHAIN_MESSAGE_IDENTIFIER: Fr = new Fr(
+  6023466688192654631553769360478808766602235351827869819420284624004071427516n,
+);
+
+/**
+ * Represents an offchain effect emitted via the `emit_offchain_effect` oracle (see the oracle documentation for
+ * more details).
+ */
+export type OffchainEffect = {
+  /** The emitted data */
+  data: Fr[];
+  /** The contract that emitted the data */
+  contractAddress: AztecAddress;
+};

package/src/tx/partial_state_reference.ts

@@ -0,0 +1,124 @@
+import { PARTIAL_STATE_REFERENCE_LENGTH } from '@aztec-labs/constants';
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import { BufferReader, BufferSink, FieldReader, serializeToSink } from '@aztec-labs/foundation/serialize';
+import type { FieldsOf } from '@aztec-labs/foundation/types';
+import { z } from 'zod';
+
+import { AppendOnlyTreeSnapshot } from '../trees/append_only_tree_snapshot.js';
+
+/**
+ * Stores snapshots of trees which are commonly needed by base or merge rollup circuits.
+ */
+export class PartialStateReference {
+  constructor(
+    /** Snapshot of the note hash tree. */
+    public readonly noteHashTree: AppendOnlyTreeSnapshot,
+    /** Snapshot of the nullifier tree. */
+    public readonly nullifierTree: AppendOnlyTreeSnapshot,
+    /** Snapshot of the public data tree. */
+    public readonly publicDataTree: AppendOnlyTreeSnapshot,
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        noteHashTree: AppendOnlyTreeSnapshot.schema,
+        nullifierTree: AppendOnlyTreeSnapshot.schema,
+        publicDataTree: AppendOnlyTreeSnapshot.schema,
+      })
+      .transform(
+        ({ noteHashTree, nullifierTree, publicDataTree }) =>
+          new PartialStateReference(noteHashTree, nullifierTree, publicDataTree),
+      );
+  }
+
+  getSize() {
+    return this.noteHashTree.getSize() + this.nullifierTree.getSize() + this.publicDataTree.getSize();
+  }
+
+  static getFields(fields: FieldsOf<PartialStateReference>) {
+    return [fields.noteHashTree, fields.nullifierTree, fields.publicDataTree] as const;
+  }
+
+  static from(fields: FieldsOf<PartialStateReference>) {
+    return new PartialStateReference(...PartialStateReference.getFields(fields));
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): PartialStateReference {
+    const reader = BufferReader.asReader(buffer);
+    return new PartialStateReference(
+      reader.readObject(AppendOnlyTreeSnapshot),
+      reader.readObject(AppendOnlyTreeSnapshot),
+      reader.readObject(AppendOnlyTreeSnapshot),
+    );
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): PartialStateReference {
+    const reader = FieldReader.asReader(fields);
+
+    const noteHashTree = AppendOnlyTreeSnapshot.fromFields(reader);
+    const nullifierTree = AppendOnlyTreeSnapshot.fromFields(reader);
+    const publicDataTree = AppendOnlyTreeSnapshot.fromFields(reader);
+
+    return new PartialStateReference(noteHashTree, nullifierTree, publicDataTree);
+  }
+
+  static random(): PartialStateReference {
+    return new PartialStateReference(
+      AppendOnlyTreeSnapshot.random(),
+      AppendOnlyTreeSnapshot.random(),
+      AppendOnlyTreeSnapshot.random(),
+    );
+  }
+
+  toAbi(): [
+    ReturnType<AppendOnlyTreeSnapshot['toAbi']>,
+    ReturnType<AppendOnlyTreeSnapshot['toAbi']>,
+    ReturnType<AppendOnlyTreeSnapshot['toAbi']>,
+  ] {
+    return [this.noteHashTree.toAbi(), this.nullifierTree.toAbi(), this.publicDataTree.toAbi()];
+  }
+
+  static empty(): PartialStateReference {
+    return new PartialStateReference(
+      AppendOnlyTreeSnapshot.empty(),
+      AppendOnlyTreeSnapshot.empty(),
+      AppendOnlyTreeSnapshot.empty(),
+    );
+  }
+
+  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() {
+    const fields = [
+      ...this.noteHashTree.toFields(),
+      ...this.nullifierTree.toFields(),
+      ...this.publicDataTree.toFields(),
+    ];
+    if (fields.length !== PARTIAL_STATE_REFERENCE_LENGTH) {
+      throw new Error(
+        `Invalid number of fields for PartialStateReference. Expected ${PARTIAL_STATE_REFERENCE_LENGTH}, got ${fields.length}`,
+      );
+    }
+    return fields;
+  }
+
+  isEmpty(): boolean {
+    return this.noteHashTree.isEmpty() && this.nullifierTree.isEmpty() && this.publicDataTree.isEmpty();
+  }
+
+  public equals(other: this): boolean {
+    return (
+      this.noteHashTree.equals(other.noteHashTree) &&
+      this.nullifierTree.equals(other.nullifierTree) &&
+      this.publicDataTree.equals(other.publicDataTree)
+    );
+  }
+}