@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/tx/call_context.ts

@@ -0,0 +1,138 @@
+import { CALL_CONTEXT_LENGTH } from '@aztec/constants';
+import type { Fr } from '@aztec/foundation/fields';
+import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { inspect } from 'util';
+import { z } from 'zod';
+
+import { FunctionSelector } from '../abi/index.js';
+import { AztecAddress } from '../aztec-address/index.js';
+import { schemas } from '../schemas/index.js';
+
+/**
+ * Call context.
+ */
+export class CallContext {
+  constructor(
+    /**
+     * Address of the account which represents the entity who invoked the call.
+     */
+    public msgSender: AztecAddress,
+    /**
+     * The contract address being called.
+     */
+    public contractAddress: AztecAddress,
+    /**
+     * Function selector of the function being called.
+     */
+    public functionSelector: FunctionSelector,
+    /**
+     * Determines whether the call is modifying state.
+     */
+    public isStaticCall: boolean,
+  ) {}
+
+  /**
+   * Returns a new instance of CallContext with zero msg sender, storage contract address.
+   * @returns A new instance of CallContext with zero msg sender, storage contract address.
+   */
+  public static empty(): CallContext {
+    return new CallContext(AztecAddress.ZERO, AztecAddress.ZERO, FunctionSelector.empty(), false);
+  }
+
+  static async random() {
+    return new CallContext(
+      await AztecAddress.random(),
+      await AztecAddress.random(),
+      FunctionSelector.random(),
+      Math.random() > 0.5,
+    );
+  }
+
+  static get schema() {
+    return z
+      .object({
+        msgSender: schemas.AztecAddress,
+        contractAddress: schemas.AztecAddress,
+        functionSelector: schemas.FunctionSelector,
+        isStaticCall: z.boolean(),
+      })
+      .transform(CallContext.from);
+  }
+
+  isEmpty() {
+    return (
+      this.msgSender.isZero() && this.contractAddress.isZero() && this.functionSelector.isEmpty() && !this.isStaticCall
+    );
+  }
+
+  static from(fields: FieldsOf<CallContext>): CallContext {
+    return new CallContext(...CallContext.getFields(fields));
+  }
+
+  static getFields(fields: FieldsOf<CallContext>) {
+    return [fields.msgSender, fields.contractAddress, fields.functionSelector, fields.isStaticCall] as const;
+  }
+
+  /**
+   * Serialize this as a buffer.
+   * @returns The buffer.
+   */
+  toBuffer() {
+    return serializeToBuffer(...CallContext.getFields(this));
+  }
+
+  toFields(): Fr[] {
+    const fields = serializeToFields(...CallContext.getFields(this));
+    if (fields.length !== CALL_CONTEXT_LENGTH) {
+      throw new Error(
+        `Invalid number of fields for CallContext. Expected ${CALL_CONTEXT_LENGTH}, got ${fields.length}`,
+      );
+    }
+    return fields;
+  }
+
+  /**
+   * Deserialize this from a buffer.
+   * @param buffer - The bufferable type from which to deserialize.
+   * @returns The deserialized instance of CallContext.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new CallContext(
+      reader.readObject(AztecAddress),
+      reader.readObject(AztecAddress),
+      reader.readObject(FunctionSelector),
+      reader.readBoolean(),
+    );
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): CallContext {
+    const reader = FieldReader.asReader(fields);
+    return new CallContext(
+      reader.readObject(AztecAddress),
+      reader.readObject(AztecAddress),
+      reader.readObject(FunctionSelector),
+      reader.readBoolean(),
+    );
+  }
+
+  equals(callContext: CallContext) {
+    return (
+      callContext.msgSender.equals(this.msgSender) &&
+      callContext.contractAddress.equals(this.contractAddress) &&
+      callContext.functionSelector.equals(this.functionSelector) &&
+      callContext.isStaticCall === this.isStaticCall
+    );
+  }
+
+  [inspect.custom]() {
+    return `CallContext {
+      msgSender: ${this.msgSender}
+      contractAddress: ${this.contractAddress}
+      functionSelector: ${this.functionSelector}
+      isStaticCall: ${this.isStaticCall}
+    }`;
+  }
+}

package/src/tx/capsule.ts

@@ -0,0 +1,46 @@
+import { Fr } from '@aztec/foundation/fields';
+import { hexSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+
+import { AztecAddress } from '../aztec-address/index.js';
+import { Vector } from '../types/shared.js';
+
+/**
+ * Read-only data that is passed to the contract through an oracle during a transaction execution.
+ */
+export class Capsule {
+  constructor(
+    /** The address of the contract the capsule is for */
+    public readonly contractAddress: AztecAddress,
+    /** The storage slot of the capsule */
+    public readonly storageSlot: Fr,
+    /** Data passed to the contract  */
+    public readonly data: Fr[],
+  ) {}
+
+  static get schema() {
+    return hexSchemaFor(Capsule);
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  toBuffer() {
+    return serializeToBuffer(this.contractAddress, this.storageSlot, new Vector(this.data));
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): Capsule {
+    const reader = BufferReader.asReader(buffer);
+    return new Capsule(AztecAddress.fromBuffer(reader), Fr.fromBuffer(reader), reader.readVector(Fr));
+  }
+
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  static fromString(str: string) {
+    return Capsule.fromBuffer(hexToBuffer(str));
+  }
+}

package/src/tx/content_commitment.ts

@@ -0,0 +1,133 @@
+import { CONTENT_COMMITMENT_LENGTH } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/fields';
+import { schemas } from '@aztec/foundation/schemas';
+import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { bufferToHex } from '@aztec/foundation/string';
+
+import { z } from 'zod';
+
+export const NUM_BYTES_PER_SHA256 = 32;
+
+export class ContentCommitment {
+  constructor(public numTxs: Fr, public blobsHash: Buffer, public inHash: Buffer, public outHash: Buffer) {
+    // NB: we do not calculate blobHash in the circuit, but we still truncate it so it fits in a field
+    if (blobsHash.length !== NUM_BYTES_PER_SHA256) {
+      throw new Error(`blobsHash buffer must be ${NUM_BYTES_PER_SHA256} bytes`);
+    }
+    if (blobsHash[0] !== 0) {
+      throw new Error(`blobsHash buffer should be truncated and left padded`);
+    }
+    if (inHash.length !== NUM_BYTES_PER_SHA256) {
+      throw new Error(`inHash buffer must be ${NUM_BYTES_PER_SHA256} bytes`);
+    }
+    if (inHash[0] !== 0) {
+      throw new Error(`inHash buffer should be truncated and left padded`);
+    }
+    if (outHash.length !== NUM_BYTES_PER_SHA256) {
+      throw new Error(`outHash buffer must be ${NUM_BYTES_PER_SHA256} bytes`);
+    }
+    if (outHash[0] !== 0) {
+      throw new Error(`outHash buffer should be truncated and left padded`);
+    }
+  }
+
+  static get schema() {
+    return z
+      .object({
+        numTxs: schemas.Fr,
+        blobsHash: schemas.Buffer,
+        inHash: schemas.Buffer,
+        outHash: schemas.Buffer,
+      })
+      .transform(({ numTxs, blobsHash, inHash, outHash }) => new ContentCommitment(numTxs, blobsHash, inHash, outHash));
+  }
+
+  getSize() {
+    return this.toBuffer().length;
+  }
+
+  toBuffer() {
+    return serializeToBuffer(this.numTxs, this.blobsHash, this.inHash, this.outHash);
+  }
+
+  toInspect() {
+    return {
+      numTxs: this.numTxs.toNumber(),
+      blobsHash: bufferToHex(this.blobsHash),
+      inHash: bufferToHex(this.inHash),
+      outHash: bufferToHex(this.outHash),
+    };
+  }
+
+  toFields(): Fr[] {
+    const serialized = [
+      this.numTxs,
+      Fr.fromBuffer(this.blobsHash),
+      Fr.fromBuffer(this.inHash),
+      Fr.fromBuffer(this.outHash),
+    ];
+    if (serialized.length !== CONTENT_COMMITMENT_LENGTH) {
+      throw new Error(
+        `Expected content commitment to have ${CONTENT_COMMITMENT_LENGTH} fields, but it has ${serialized.length} fields`,
+      );
+    }
+    return serialized;
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): ContentCommitment {
+    const reader = BufferReader.asReader(buffer);
+
+    return new ContentCommitment(
+      reader.readObject(Fr),
+      reader.readBytes(NUM_BYTES_PER_SHA256),
+      reader.readBytes(NUM_BYTES_PER_SHA256),
+      reader.readBytes(NUM_BYTES_PER_SHA256),
+    );
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): ContentCommitment {
+    const reader = FieldReader.asReader(fields);
+    return new ContentCommitment(
+      reader.readField(),
+      reader.readField().toBuffer(),
+      reader.readField().toBuffer(),
+      reader.readField().toBuffer(),
+    );
+  }
+
+  static empty(): ContentCommitment {
+    return new ContentCommitment(
+      Fr.zero(),
+      Buffer.alloc(NUM_BYTES_PER_SHA256),
+      Buffer.alloc(NUM_BYTES_PER_SHA256),
+      Buffer.alloc(NUM_BYTES_PER_SHA256),
+    );
+  }
+
+  isEmpty(): boolean {
+    return (
+      this.numTxs.isZero() &&
+      this.blobsHash.equals(Buffer.alloc(NUM_BYTES_PER_SHA256)) &&
+      this.inHash.equals(Buffer.alloc(NUM_BYTES_PER_SHA256)) &&
+      this.outHash.equals(Buffer.alloc(NUM_BYTES_PER_SHA256))
+    );
+  }
+
+  public toString(): string {
+    return bufferToHex(this.toBuffer());
+  }
+
+  static fromString(str: string): ContentCommitment {
+    const buffer = Buffer.from(str.replace(/^0x/i, ''), 'hex');
+    return ContentCommitment.fromBuffer(buffer);
+  }
+
+  public equals(other: this): boolean {
+    return (
+      this.inHash.equals(other.inHash) &&
+      this.outHash.equals(other.outHash) &&
+      this.numTxs.equals(other.numTxs) &&
+      this.blobsHash.equals(other.blobsHash)
+    );
+  }
+}

package/src/tx/function_data.ts

@@ -0,0 +1,102 @@
+import { FUNCTION_DATA_LENGTH } from '@aztec/constants';
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import { z } from 'zod';
+
+import { type FunctionAbi, FunctionSelector, FunctionType } from '../abi/index.js';
+import type { ContractFunctionDao } from '../contract/contract_function_dao.js';
+
+/** Function description for circuit. */
+export class FunctionData {
+  constructor(
+    /** Function selector of the function being called. */
+    public selector: FunctionSelector,
+    /** Indicates whether the function is private or public. */
+    public isPrivate: boolean,
+  ) {}
+
+  static async fromAbi(abi: FunctionAbi | ContractFunctionDao): Promise<FunctionData> {
+    return new FunctionData(
+      await FunctionSelector.fromNameAndParameters(abi.name, abi.parameters),
+      abi.functionType === FunctionType.PRIVATE,
+    );
+  }
+
+  static get schema() {
+    return z
+      .object({
+        selector: FunctionSelector.schema,
+        isPrivate: z.boolean(),
+      })
+      .transform(({ selector, isPrivate }) => new FunctionData(selector, isPrivate));
+  }
+
+  /**
+   * Serialize this as a buffer.
+   * @returns The buffer.
+   */
+  toBuffer(): Buffer {
+    return serializeToBuffer(this.selector, this.isPrivate);
+  }
+
+  toFields(): Fr[] {
+    const fields = [this.selector.toField(), new Fr(this.isPrivate)];
+    if (fields.length !== FUNCTION_DATA_LENGTH) {
+      throw new Error(
+        `Invalid number of fields for FunctionData. Expected ${FUNCTION_DATA_LENGTH}, got ${fields.length}`,
+      );
+    }
+    return fields;
+  }
+
+  /**
+   * Returns whether this instance is empty.
+   * @returns True if the function selector is zero.
+   */
+  isEmpty() {
+    return this.selector.isEmpty();
+  }
+
+  /**
+   * Returns whether this instance is equal to another.
+   * @param other
+   * @returns
+   */
+  equals(other: FunctionData): boolean {
+    return this.selector.equals(other.selector) && this.isPrivate === other.isPrivate;
+  }
+
+  /**
+   * Returns a new instance of FunctionData with zero function selector.
+   * @param args - Arguments to pass to the constructor.
+   * @returns A new instance of FunctionData with zero function selector.
+   */
+  public static empty(args?: {
+    /** Indicates whether the function is private or public. */
+    isPrivate?: boolean;
+    /** Indicates whether the function can alter state or not. */
+    isStatic?: boolean;
+  }): FunctionData {
+    return new FunctionData(FunctionSelector.empty(), args?.isPrivate ?? false);
+  }
+
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer or reader to read from.
+   * @returns A new instance of FunctionData.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader): FunctionData {
+    const reader = BufferReader.asReader(buffer);
+    return new FunctionData(reader.readObject(FunctionSelector), /*isPrivate=*/ reader.readBoolean());
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): FunctionData {
+    const reader = FieldReader.asReader(fields);
+
+    const selector = FunctionSelector.fromFields(reader);
+    const isPrivate = reader.readBoolean();
+
+    return new FunctionData(selector, isPrivate);
+  }
+}

package/src/tx/global_variable_builder.ts

@@ -0,0 +1,28 @@
+import type { EthAddress } from '@aztec/foundation/eth-address';
+import type { Fr } from '@aztec/foundation/fields';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+import type { GasFees } from '../gas/gas_fees.js';
+import type { GlobalVariables } from './global_variables.js';
+
+/**
+ * Interface for building global variables for Aztec blocks.
+ */
+export interface GlobalVariableBuilder {
+  getCurrentBaseFees(): Promise<GasFees>;
+
+  /**
+   * Builds global variables for a given block.
+   * @param blockNumber - The block number to build global variables for.
+   * @param coinbase - The address to receive block reward.
+   * @param feeRecipient - The address to receive fees.
+   * @param slotNumber - Optional. The slot number to use for the global variables. If undefined, it will be calculated.
+   * @returns A promise that resolves to the GlobalVariables for the given block number.
+   */
+  buildGlobalVariables(
+    blockNumber: Fr,
+    coinbase: EthAddress,
+    feeRecipient: AztecAddress,
+    slotNumber?: bigint,
+  ): Promise<GlobalVariables>;
+}

package/src/tx/global_variables.ts

@@ -0,0 +1,193 @@
+import { GLOBAL_VARIABLES_LENGTH } from '@aztec/constants';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Fr } from '@aztec/foundation/fields';
+import { jsonStringify } from '@aztec/foundation/json-rpc';
+import { BufferReader, FieldReader, serializeToBuffer, serializeToFields } from '@aztec/foundation/serialize';
+import type { FieldsOf } from '@aztec/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';
+
+/**
+ * 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: Fr,
+    /** Slot number of the L2 block */
+    public slotNumber: Fr,
+    /** Timestamp of the L2 block. */
+    public timestamp: Fr,
+    /** 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: schemas.Fr,
+        slotNumber: schemas.Fr,
+        timestamp: schemas.Fr,
+        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));
+  }
+
+  static empty(fields: Partial<FieldsOf<GlobalVariables>> = {}): GlobalVariables {
+    return GlobalVariables.from({
+      blockNumber: Fr.ZERO,
+      slotNumber: Fr.ZERO,
+      timestamp: Fr.ZERO,
+      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),
+      Fr.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+      Fr.fromBuffer(reader),
+      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(),
+      reader.readField(),
+      reader.readField(),
+      reader.readField(),
+      EthAddress.fromField(reader.readField()),
+      AztecAddress.fromField(reader.readField()),
+      GasFees.fromFields(reader),
+    );
+  }
+
+  static getFields(fields: FieldsOf<GlobalVariables>) {
+    // Note: The order here must match the order in the HeaderLib solidity library.
+    return [
+      fields.chainId,
+      fields.version,
+      fields.blockNumber,
+      fields.slotNumber,
+      fields.timestamp,
+      fields.coinbase,
+      fields.feeRecipient,
+      fields.gasFees,
+    ] as const;
+  }
+
+  toBuffer() {
+    return serializeToBuffer(...GlobalVariables.getFields(this));
+  }
+
+  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.toNumber(),
+      slotNumber: this.slotNumber.toNumber(),
+      timestamp: this.timestamp.toString(),
+      coinbase: this.coinbase.toString(),
+      gasFees: jsonStringify(this.gasFees),
+    };
+  }
+
+  clone(): GlobalVariables {
+    return GlobalVariables.fromBuffer(this.toBuffer());
+  }
+
+  isEmpty(): boolean {
+    return (
+      this.chainId.isZero() &&
+      this.version.isZero() &&
+      this.blockNumber.isZero() &&
+      this.slotNumber.isZero() &&
+      this.timestamp.isZero() &&
+      this.coinbase.isZero() &&
+      this.feeRecipient.isZero() &&
+      this.gasFees.isEmpty()
+    );
+  }
+
+  toInspect() {
+    return {
+      chainId: this.chainId.toNumber(),
+      version: this.version.toNumber(),
+      blockNumber: this.blockNumber.toNumber(),
+      slotNumber: this.slotNumber.toNumber(),
+      timestamp: this.timestamp.toNumber(),
+      coinbase: this.coinbase.toString(),
+      feeRecipient: this.feeRecipient.toString(),
+      feePerDaGas: this.gasFees.feePerDaGas.toNumber(),
+      feePerL2Gas: this.gasFees.feePerL2Gas.toNumber(),
+    };
+  }
+
+  [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.equals(other.blockNumber) &&
+      this.slotNumber.equals(other.slotNumber) &&
+      this.timestamp.equals(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,49 @@
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import { z } from 'zod';
+
+import { 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 {
+  private constructor(
+    /**
+     *  Raw values.
+     */
+    public readonly values: Fr[],
+    /**
+     * The hash of the raw values
+     */
+    public readonly hash: Fr,
+  ) {}
+
+  static get schema(): ZodFor<HashedValues> {
+    return z.array(schemas.Fr).transform(HashedValues.fromValues);
+  }
+
+  toJSON() {
+    return this.values;
+  }
+
+  static random() {
+    return HashedValues.fromValues([Fr.random(), Fr.random()]);
+  }
+
+  static async fromValues(values: Fr[]) {
+    return new HashedValues(values, await computeVarArgsHash(values));
+  }
+
+  toBuffer() {
+    return serializeToBuffer(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));
+  }
+}