@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/avm/public_data_read.ts

@@ -0,0 +1,48 @@
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+/**
+ * Read operations from the public state tree.
+ */
+export class PublicDataRead {
+  constructor(
+    /**
+     * Index of the leaf in the public data tree.
+     */
+    public readonly leafSlot: Fr,
+    /**
+     * Returned value from the public data tree.
+     */
+    public readonly value: Fr,
+    /**
+     * Side effect counter tracking position of this event in tx execution.
+     */
+    public readonly counter: number,
+  ) {}
+
+  toBuffer() {
+    return serializeToBuffer(this.leafSlot, this.value, this.counter);
+  }
+
+  isEmpty() {
+    return this.leafSlot.isZero() && this.value.isZero() && !this.counter;
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return new PublicDataRead(reader.readField(), reader.readField(), reader.readU32());
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new PublicDataRead(Fr.fromBuffer(reader), Fr.fromBuffer(reader), reader.readNumber());
+  }
+
+  static empty() {
+    return new PublicDataRead(Fr.ZERO, Fr.ZERO, 0);
+  }
+
+  equals(other: PublicDataRead) {
+    return this.leafSlot.equals(other.leafSlot) && this.value.equals(other.value) && this.counter == other.counter;
+  }
+}

package/src/avm/public_data_update_request.ts

@@ -0,0 +1,106 @@
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+
+import { inspect } from 'util';
+
+import type { AztecAddress } from '../aztec-address/index.js';
+import { computePublicDataTreeLeafSlot } from '../hash/hash.js';
+import type { ContractStorageUpdateRequest } from './contract_storage_update_request.js';
+
+// TO BE REMOVED.
+/**
+ * Write operations on the public data tree including the previous value.
+ */
+export class PublicDataUpdateRequest {
+  constructor(
+    /**
+     * Index of the leaf in the public data tree which is to be updated.
+     */
+    public readonly leafSlot: Fr,
+    /**
+     * New value of the leaf.
+     */
+    public readonly newValue: Fr,
+    /**
+     * Side effect counter tracking position of this event in tx execution.
+     */
+    public readonly sideEffectCounter: number,
+  ) {}
+
+  static from(args: {
+    /**
+     * Index of the leaf in the public data tree which is to be updated.
+     */
+    leafIndex: Fr;
+    /**
+     * New value of the leaf.
+     */
+    newValue: Fr;
+
+    /**
+     * Side effect counter tracking position of this event in tx execution.
+     */
+    sideEffectCounter: number;
+  }) {
+    return new PublicDataUpdateRequest(args.leafIndex, args.newValue, args.sideEffectCounter);
+  }
+
+  get counter() {
+    return this.sideEffectCounter;
+  }
+
+  get position() {
+    return this.leafSlot;
+  }
+
+  toBuffer() {
+    return serializeToBuffer(this.leafSlot, this.newValue, this.sideEffectCounter);
+  }
+
+  isEmpty() {
+    return this.leafSlot.isZero() && this.newValue.isZero();
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return new PublicDataUpdateRequest(reader.readField(), reader.readField(), reader.readU32());
+  }
+
+  static isEmpty(x: PublicDataUpdateRequest) {
+    return x.isEmpty();
+  }
+
+  equals(other: PublicDataUpdateRequest) {
+    return this.leafSlot.equals(other.leafSlot) && this.newValue.equals(other.newValue);
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new PublicDataUpdateRequest(Fr.fromBuffer(reader), Fr.fromBuffer(reader), reader.readNumber());
+  }
+
+  static async fromContractStorageUpdateRequest(
+    contractAddress: AztecAddress,
+    updateRequest: ContractStorageUpdateRequest,
+  ) {
+    const leafSlot = await computePublicDataTreeLeafSlot(contractAddress, updateRequest.storageSlot);
+
+    return new PublicDataUpdateRequest(leafSlot, updateRequest.newValue, updateRequest.counter);
+  }
+
+  static empty() {
+    return new PublicDataUpdateRequest(Fr.ZERO, Fr.ZERO, 0);
+  }
+
+  toFriendlyJSON() {
+    return `Leaf=${this.leafSlot.toFriendlyJSON()}: ${this.newValue.toFriendlyJSON()}, SideEffectCounter=${
+      this.sideEffectCounter
+    }`;
+  }
+
+  [inspect.custom]() {
+    return `PublicDataUpdateRequest { leafSlot: ${this.leafSlot.toFriendlyJSON()}, newValue: ${this.newValue.toFriendlyJSON()}, sideEffectCounter: ${
+      this.sideEffectCounter
+    } }`;
+  }
+}

package/src/avm/public_data_write.ts

@@ -0,0 +1,80 @@
+import { Fr } from '@aztec/foundation/fields';
+import { schemas } from '@aztec/foundation/schemas';
+import { BufferReader, FieldReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { z } from 'zod';
+
+/**
+ * Write operations on the public state tree.
+ */
+export class PublicDataWrite {
+  static SIZE_IN_BYTES = Fr.SIZE_IN_BYTES * 2;
+
+  constructor(
+    /**
+     * The updated leaf.
+     */
+    public readonly leafSlot: Fr,
+    /**
+     * New value of the leaf.
+     */
+    public readonly value: Fr,
+  ) {}
+
+  static get schema() {
+    return z
+      .object({
+        leafSlot: schemas.Fr,
+        value: schemas.Fr,
+      })
+      .transform(PublicDataWrite.from);
+  }
+
+  static from(fields: FieldsOf<PublicDataWrite>) {
+    return new PublicDataWrite(...PublicDataWrite.getFields(fields));
+  }
+
+  static getFields(fields: FieldsOf<PublicDataWrite>) {
+    return [fields.leafSlot, fields.value] as const;
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): PublicDataWrite {
+    const reader = FieldReader.asReader(fields);
+    return new PublicDataWrite(reader.readField(), reader.readField());
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new PublicDataWrite(Fr.fromBuffer(reader), Fr.fromBuffer(reader));
+  }
+
+  toBuffer() {
+    return serializeToBuffer(...PublicDataWrite.getFields(this));
+  }
+
+  static fromString(str: string) {
+    return PublicDataWrite.fromBuffer(hexToBuffer(str));
+  }
+
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  static empty() {
+    return new PublicDataWrite(Fr.ZERO, Fr.ZERO);
+  }
+
+  static random() {
+    return new PublicDataWrite(Fr.random(), Fr.random());
+  }
+
+  static isEmpty(data: PublicDataWrite): boolean {
+    return data.isEmpty();
+  }
+
+  isEmpty() {
+    return this.leafSlot.isZero() && this.value.isZero();
+  }
+}

package/src/avm/public_inner_call_request.ts

@@ -0,0 +1,85 @@
+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 { PublicCallStackItemCompressed } from './public_call_stack_item_compressed.js';
+
+// TO BE REMOVED
+/**
+ * Represents a request to call a public function.
+ */
+export class PublicInnerCallRequest {
+  constructor(
+    public item: PublicCallStackItemCompressed,
+    /**
+     * The counter for this call request.
+     */
+    public counter: number,
+  ) {}
+
+  getSize() {
+    return this.isEmpty() ? 0 : this.toBuffer().length;
+  }
+
+  /**
+   * Serialize this as a buffer.
+   * @returns The buffer.
+   */
+  toBuffer() {
+    return serializeToBuffer(this.item, this.counter);
+  }
+
+  /**
+   * Deserialize this from a buffer.
+   * @param buffer - The bufferable type from which to deserialize.
+   * @returns The deserialized instance of PublicInnerCallRequest.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    return new PublicInnerCallRequest(PublicCallStackItemCompressed.fromBuffer(reader), reader.readNumber());
+  }
+
+  /**
+   * Create PublicInnerCallRequest from a fields dictionary.
+   * @param fields - The dictionary.
+   * @returns A PublicInnerCallRequest object.
+   */
+  static from(fields: FieldsOf<PublicInnerCallRequest>): PublicInnerCallRequest {
+    return new PublicInnerCallRequest(...PublicInnerCallRequest.getFields(fields));
+  }
+
+  /**
+   * Serialize into a field array. Low-level utility.
+   * @param fields - Object with fields.
+   * @returns The array.
+   */
+  static getFields(fields: FieldsOf<PublicInnerCallRequest>) {
+    return [fields.item, fields.counter] as const;
+  }
+
+  toFields(): Fr[] {
+    return serializeToFields([this.item, this.counter]);
+  }
+
+  static fromFields(fields: Fr[] | FieldReader): PublicInnerCallRequest {
+    const reader = FieldReader.asReader(fields);
+    return new PublicInnerCallRequest(PublicCallStackItemCompressed.fromFields(reader), reader.readU32());
+  }
+
+  static empty() {
+    return new PublicInnerCallRequest(PublicCallStackItemCompressed.empty(), 0);
+  }
+
+  isEmpty(): boolean {
+    return this.item.isEmpty() && this.counter == 0;
+  }
+
+  [inspect.custom]() {
+    return `PublicInnerCallRequest {
+      item: ${this.item}
+      counter: ${this.counter}
+    }`;
+  }
+}

package/src/avm/revert_code.ts

@@ -0,0 +1,128 @@
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, FieldReader } from '@aztec/foundation/serialize';
+
+import { inspect } from 'util';
+import { z } from 'zod';
+
+export enum RevertCodeEnum {
+  OK = 0,
+  APP_LOGIC_REVERTED = 1,
+  TEARDOWN_REVERTED = 2,
+  BOTH_REVERTED = 3,
+}
+
+function isRevertCodeEnum(value: number): value is RevertCodeEnum {
+  return (
+    value === RevertCodeEnum.OK ||
+    value === RevertCodeEnum.APP_LOGIC_REVERTED ||
+    value === RevertCodeEnum.TEARDOWN_REVERTED ||
+    value === RevertCodeEnum.BOTH_REVERTED
+  );
+}
+
+/**
+ * Wrapper class over a field to safely represent a revert code.
+ */
+export class RevertCode {
+  private code: number;
+  private constructor(e: RevertCodeEnum) {
+    this.code = e.valueOf();
+  }
+  static readonly OK: RevertCode = new RevertCode(RevertCodeEnum.OK);
+  static readonly APP_LOGIC_REVERTED: RevertCode = new RevertCode(RevertCodeEnum.APP_LOGIC_REVERTED);
+  static readonly TEARDOWN_REVERTED: RevertCode = new RevertCode(RevertCodeEnum.TEARDOWN_REVERTED);
+  static readonly BOTH_REVERTED: RevertCode = new RevertCode(RevertCodeEnum.BOTH_REVERTED);
+
+  public getCode(): RevertCodeEnum {
+    return this.code;
+  }
+
+  public equals(other: RevertCode): boolean {
+    return this.code === other.code;
+  }
+
+  public isOK(): boolean {
+    return this.equals(RevertCode.OK);
+  }
+
+  public getDescription() {
+    switch (this.code) {
+      case RevertCodeEnum.OK:
+        return 'OK';
+      case RevertCodeEnum.APP_LOGIC_REVERTED:
+        return 'Application logic reverted';
+      case RevertCodeEnum.TEARDOWN_REVERTED:
+        return 'Teardown reverted';
+      case RevertCodeEnum.BOTH_REVERTED:
+        return 'Both reverted';
+      default:
+        return `Unknown RevertCode: ${this.code}`;
+    }
+  }
+
+  public toJSON() {
+    return this.code;
+  }
+
+  static get schema() {
+    return z.nativeEnum(RevertCodeEnum).transform(value => new RevertCode(value));
+  }
+
+  /**
+   * Having different serialization methods allows for
+   * decoupling the serialization for producing the content commitment hash
+   * (where we use fields)
+   * from serialization for transmitting the data.
+   */
+
+  private static readonly PREIMAGE_SIZE_IN_BYTES = 32;
+  public toHashPreimage(): Buffer {
+    const padding = Buffer.alloc(RevertCode.PREIMAGE_SIZE_IN_BYTES - RevertCode.PACKED_SIZE_IN_BYTES);
+    return Buffer.concat([padding, this.toBuffer()]);
+  }
+
+  private static readonly PACKED_SIZE_IN_BYTES = 1;
+  public toBuffer(): Buffer {
+    const b = Buffer.alloc(RevertCode.PACKED_SIZE_IN_BYTES);
+    b.writeUInt8(this.code, 0);
+    return b;
+  }
+
+  public toField(): Fr {
+    return new Fr(this.toBuffer());
+  }
+
+  public getSerializedLength(): number {
+    return this.toBuffer().length;
+  }
+
+  public static fromField(fr: Fr): RevertCode {
+    if (!isRevertCodeEnum(fr.toNumber())) {
+      throw new Error(`Invalid RevertCode: ${fr.toNumber()}`);
+    }
+    return new RevertCode(fr.toNumber());
+  }
+
+  public static fromFields(fields: Fr[] | FieldReader): RevertCode {
+    const reader = FieldReader.asReader(fields);
+    return RevertCode.fromField(reader.readField());
+  }
+
+  public static fromBuffer(buffer: Buffer | BufferReader): RevertCode {
+    const reader = BufferReader.asReader(buffer);
+    const code = reader.readBytes(RevertCode.PACKED_SIZE_IN_BYTES).readUInt8(0);
+    if (!isRevertCodeEnum(code)) {
+      throw new Error(`Invalid RevertCode: ${code}`);
+    }
+    return new RevertCode(code);
+  }
+
+  private static readonly NUM_OPTIONS = 4;
+  static random(): RevertCode {
+    return new RevertCode(Math.floor(Math.random() * RevertCode.NUM_OPTIONS));
+  }
+
+  [inspect.custom]() {
+    return `RevertCode<${this.code.toString()}>`;
+  }
+}

package/src/aztec-address/index.ts

@@ -0,0 +1,145 @@
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+import { Fr, Point, fromBuffer } from '@aztec/foundation/fields';
+import { type ZodFor, hexSchemaFor } from '@aztec/foundation/schemas';
+import { type BufferReader, FieldReader, TypeRegistry } from '@aztec/foundation/serialize';
+import { hexToBuffer } from '@aztec/foundation/string';
+
+import { inspect } from 'util';
+
+/** Branding to ensure fields are not interchangeable types. */
+export interface AztecAddress {
+  /** Brand. */
+  _branding: 'AztecAddress';
+}
+/**
+ * AztecAddress represents a 32-byte address in the Aztec Protocol. It provides methods to create, manipulate, and
+ * compare addresses, as well as conversion to and from strings, buffers, and other formats.
+ * Addresses are the x coordinate of a point in the Grumpkin curve, and therefore their maximum is determined by the
+ * field modulus. An address with a value that is not the x coordinate of a point in the curve is a called an 'invalid
+ * address'. These addresses have a greatly reduced feature set, as they cannot own secrets nor have messages encrypted
+ * to them, making them quite useless. We need to be able to represent them however as they can be encountered in the
+ * wild.
+ */
+export class AztecAddress {
+  private xCoord: Fr;
+
+  constructor(buffer: Buffer | Fr) {
+    if ('length' in buffer && buffer.length !== 32) {
+      throw new Error(`Invalid AztecAddress length ${buffer.length}.`);
+    }
+    this.xCoord = new Fr(buffer);
+  }
+
+  [inspect.custom]() {
+    return `AztecAddress<${this.toString()}>`;
+  }
+
+  static isAddress(str: string) {
+    return /^(0x)?[a-fA-F0-9]{64}$/.test(str);
+  }
+
+  static SIZE_IN_BYTES = Fr.SIZE_IN_BYTES;
+
+  static ZERO = new AztecAddress(Buffer.alloc(32, 0));
+
+  static zero(): AztecAddress {
+    return AztecAddress.ZERO;
+  }
+
+  static fromField(fr: Fr) {
+    return new AztecAddress(fr);
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    return new AztecAddress(fromBuffer(buffer, Fr));
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return new AztecAddress(reader.readField());
+  }
+
+  static fromBigInt(value: bigint) {
+    return new AztecAddress(new Fr(value));
+  }
+
+  static fromNumber(value: number) {
+    return new AztecAddress(new Fr(value));
+  }
+
+  static fromString(buf: string) {
+    return new AztecAddress(hexToBuffer(buf));
+  }
+
+  /**
+   * @returns a random valid address (i.e. one that can be encrypted to).
+   */
+  static async random() {
+    // About half of random field elements result in invalid addresses, so we loop until we get a valid one.
+    while (true) {
+      const candidate = new AztecAddress(Fr.random());
+      if (await candidate.isValid()) {
+        return candidate;
+      }
+    }
+  }
+
+  get size() {
+    return this.xCoord.size;
+  }
+
+  equals(other: AztecAddress) {
+    return this.xCoord.equals(other.xCoord);
+  }
+
+  isZero() {
+    return this.xCoord.isZero();
+  }
+
+  /**
+   * @returns true if the address is valid. Invalid addresses cannot receive encrypted messages.
+   */
+  async isValid() {
+    // An address is a field value (Fr), which for some purposes is assumed to be the x coordinate of a point in the
+    // Grumpkin curve (notably in order to encrypt to it). An address that is not the x coordinate of such a point is
+    // called an 'invalid' address.
+    //
+    // For Grumpkin, y^2 = x^3 − 17 . There exist values x ∈ Fr for which no y satisfies this equation. This means that
+    // given such an x and t = x^3 − 17, then sqrt(t) does not exist in Fr.
+    return (await Point.YFromX(this.xCoord)) !== null;
+  }
+
+  /**
+   * @returns the Point from which the address is derived. Throws if the address is invalid.
+   */
+  toAddressPoint(): Promise<Point> {
+    return Point.fromXAndSign(this.xCoord, true);
+  }
+
+  toBuffer() {
+    return this.xCoord.toBuffer();
+  }
+
+  toBigInt() {
+    return this.xCoord.toBigInt();
+  }
+
+  toField() {
+    return this.xCoord;
+  }
+
+  toString() {
+    return this.xCoord.toString();
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static get schema(): ZodFor<AztecAddress> {
+    return hexSchemaFor(AztecAddress, AztecAddress.isAddress);
+  }
+}
+
+// For deserializing JSON.
+TypeRegistry.register('AztecAddress', AztecAddress);

package/src/block/block_hash.ts

@@ -0,0 +1,30 @@
+import { Buffer32 } from '@aztec/foundation/buffer';
+import { Fr } from '@aztec/foundation/fields';
+
+import { schemas } from '../schemas/schemas.js';
+
+/** Hash of an L2 block. */
+export class L2BlockHash extends Buffer32 {
+  constructor(
+    /** The buffer containing the hash. */
+    hash: Buffer,
+  ) {
+    super(hash);
+  }
+
+  static override random() {
+    return new L2BlockHash(Fr.random().toBuffer());
+  }
+
+  static get schema() {
+    return schemas.BufferHex.transform(value => new L2BlockHash(value));
+  }
+
+  static zero() {
+    return new L2BlockHash(Buffer32.ZERO.toBuffer());
+  }
+
+  static override fromField(hash: Fr) {
+    return new L2BlockHash(hash.toBuffer());
+  }
+}