@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/abi/event_selector.ts

@@ -0,0 +1,93 @@
+import { fromHex, toBigIntBE } from '@aztec/foundation/bigint-buffer';
+import { poseidon2HashBytes, randomBytes } from '@aztec/foundation/crypto';
+import type { Fr } from '@aztec/foundation/fields';
+import { hexSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader } from '@aztec/foundation/serialize';
+
+import { Selector } from './selector.js';
+
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+
+/** Event selector branding */
+export interface EventSelector {
+  /** Brand. */
+  _branding: 'EventSelector';
+}
+
+/** An event selector is the first 4 bytes of the hash of an event signature. */
+export class EventSelector extends Selector {
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer  or BufferReader to read from.
+   * @returns The Selector.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    const value = Number(toBigIntBE(reader.readBytes(Selector.SIZE)));
+    return new EventSelector(value);
+  }
+
+  /**
+   * Converts a field to selector.
+   * @param fr - The field to convert.
+   * @returns The selector.
+   */
+  static fromField(fr: Fr) {
+    return new EventSelector(Number(fr.toBigInt()));
+  }
+
+  /**
+   * Creates a selector from a signature.
+   * @param signature - Signature to generate the selector for (e.g. "transfer(field,field)").
+   * @returns selector.
+   */
+  static async fromSignature(signature: string) {
+    // throw if signature contains whitespace
+    if (/\s/.test(signature)) {
+      throw new Error('Signature cannot contain whitespace');
+    }
+    const hash = await poseidon2HashBytes(Buffer.from(signature));
+    // We take the last Selector.SIZE big endian bytes
+    const bytes = hash.toBuffer().slice(-Selector.SIZE);
+    return EventSelector.fromBuffer(bytes);
+  }
+
+  /**
+   * Create a Selector instance from a hex-encoded string.
+   *
+   * @param selector - The hex-encoded string representing the Selector.
+   * @returns An Selector instance.
+   * @throws If the selector length is invalid.
+   */
+  static fromString(selector: string) {
+    const buf = fromHex(selector);
+    if (buf.length !== Selector.SIZE) {
+      throw new Error(`Invalid EventSelector length ${buf.length} (expected ${Selector.SIZE}).`);
+    }
+    return EventSelector.fromBuffer(buf);
+  }
+
+  /**
+   * Creates an empty selector.
+   * @returns An empty selector.
+   */
+  static empty() {
+    return new EventSelector(0);
+  }
+
+  /**
+   * Creates a random selector.
+   * @returns A random selector.
+   */
+  static random() {
+    return EventSelector.fromBuffer(randomBytes(Selector.SIZE));
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static get schema() {
+    return hexSchemaFor(EventSelector);
+  }
+}

package/src/abi/function_call.ts

@@ -0,0 +1,58 @@
+import type { Fr } from '@aztec/foundation/fields';
+import type { FieldsOf } from '@aztec/foundation/types';
+
+import { AztecAddress } from '../aztec-address/index.js';
+import { type AbiType, FunctionType } from './abi.js';
+import { FunctionSelector } from './function_selector.js';
+
+/** A request to call a function on a contract from a given address. */
+export class FunctionCall {
+  constructor(
+    /** The name of the function to call */
+    public name: string,
+    /** The recipient contract */
+    public to: AztecAddress,
+    /** The function being called */
+    public selector: FunctionSelector,
+    /** Type of the function */
+    public type: FunctionType,
+    /** Whether this call can make modifications to state or not */
+    public isStatic: boolean,
+    /** The encoded args */
+    public args: Fr[],
+    /** The return type for decoding */
+    public returnTypes: AbiType[],
+  ) {}
+
+  static getFields(fields: FieldsOf<FunctionCall>) {
+    return [
+      fields.name,
+      fields.to,
+      fields.selector,
+      fields.type,
+      fields.isStatic,
+      fields.args,
+      fields.returnTypes,
+    ] as const;
+  }
+
+  static from(fields: FieldsOf<FunctionCall>): FunctionCall {
+    return new FunctionCall(...FunctionCall.getFields(fields));
+  }
+
+  /**
+   * Creates an empty function call.
+   * @returns an empty function call.
+   */
+  public static empty() {
+    return {
+      name: '',
+      to: AztecAddress.ZERO,
+      selector: FunctionSelector.empty(),
+      type: FunctionType.PUBLIC,
+      isStatic: false,
+      args: [],
+      returnTypes: [],
+    };
+  }
+}

package/src/abi/function_selector.ts

@@ -0,0 +1,123 @@
+import { fromHex, toBigIntBE } from '@aztec/foundation/bigint-buffer';
+import { poseidon2HashBytes, randomBytes } from '@aztec/foundation/crypto';
+import type { Fr } from '@aztec/foundation/fields';
+import { type ZodFor, hexSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader, FieldReader, TypeRegistry } from '@aztec/foundation/serialize';
+
+import type { ABIParameter } from './abi.js';
+import { decodeFunctionSignature } from './decoder.js';
+import { Selector } from './selector.js';
+
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+
+/** Function selector branding */
+export interface FunctionSelector {
+  /** Brand. */
+  _branding: 'FunctionSelector';
+}
+
+/** A function selector is the first 4 bytes of the hash of a function signature. */
+export class FunctionSelector extends Selector {
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer  or BufferReader to read from.
+   * @returns The Selector.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    const value = Number(toBigIntBE(reader.readBytes(Selector.SIZE)));
+    return new FunctionSelector(value);
+  }
+
+  /**
+   * Converts a field to selector.
+   * @param fr - The field to convert.
+   * @returns The selector.
+   */
+  static fromField(fr: Fr) {
+    return new FunctionSelector(Number(fr.toBigInt()));
+  }
+
+  static fromFields(fields: Fr[] | FieldReader) {
+    const reader = FieldReader.asReader(fields);
+    return FunctionSelector.fromField(reader.readField());
+  }
+
+  /**
+   * Creates a selector from a signature.
+   * @param signature - Signature to generate the selector for (e.g. "transfer(field,field)").
+   * @returns selector.
+   */
+  static async fromSignature(signature: string) {
+    // throw if signature contains whitespace
+    if (/\s/.test(signature)) {
+      throw new Error('Signature cannot contain whitespace');
+    }
+    const hash = await poseidon2HashBytes(Buffer.from(signature));
+    // We take the last Selector.SIZE big endian bytes
+    const bytes = hash.toBuffer().slice(-Selector.SIZE);
+    return FunctionSelector.fromBuffer(bytes);
+  }
+
+  /**
+   * Create a Selector instance from a hex-encoded string.
+   *
+   * @param selector - The hex-encoded string representing the Selector.
+   * @returns An Selector instance.
+   * @throws If the selector length is invalid.
+   */
+  static fromString(selector: string) {
+    const buf = fromHex(selector);
+    if (buf.length !== Selector.SIZE) {
+      throw new Error(`Invalid FunctionSelector length ${buf.length} (expected ${Selector.SIZE}).`);
+    }
+    return FunctionSelector.fromBuffer(buf);
+  }
+
+  /**
+   * Creates an empty selector.
+   * @returns An empty selector.
+   */
+  static empty() {
+    return new FunctionSelector(0);
+  }
+
+  /**
+   * Creates a function selector for a given function name and parameters.
+   * @param name - The name of the function.
+   * @param parameters - An array of ABIParameter objects, each containing the type information of a function parameter.
+   * @returns A Buffer containing the 4-byte selector.
+   */
+  static fromNameAndParameters(args: { name: string; parameters: ABIParameter[] }): Promise<FunctionSelector>;
+  static fromNameAndParameters(name: string, parameters: ABIParameter[]): Promise<FunctionSelector>;
+  static async fromNameAndParameters(
+    nameOrArgs: string | { name: string; parameters: ABIParameter[] },
+    maybeParameters?: ABIParameter[],
+  ): Promise<FunctionSelector> {
+    const { name, parameters } =
+      typeof nameOrArgs === 'string' ? { name: nameOrArgs, parameters: maybeParameters! } : nameOrArgs;
+    const signature = decodeFunctionSignature(name, parameters);
+    const selector = await this.fromSignature(signature);
+    // If using the debug logger here it kill the typing in the `server_world_state_synchronizer` and jest tests.
+    // console.log(`selector for ${signature} is ${selector}`);
+    return selector;
+  }
+
+  /**
+   * Creates a random instance.
+   */
+  static random() {
+    return FunctionSelector.fromBuffer(randomBytes(Selector.SIZE));
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static get schema(): ZodFor<FunctionSelector> {
+    return hexSchemaFor(FunctionSelector);
+  }
+}
+
+// For deserializing JSON.
+TypeRegistry.register('FunctionSelector', FunctionSelector);

package/src/abi/index.ts

@@ -0,0 +1,10 @@
+export * from './abi.js';
+export * from './buffer.js';
+export * from './decoder.js';
+export * from './encoder.js';
+export * from './event_selector.js';
+export * from './function_selector.js';
+export * from './note_selector.js';
+export * from './utils.js';
+export * from './contract_artifact.js';
+export * from './function_call.js';

package/src/abi/mocked_keys.ts

@@ -0,0 +1,2 @@
+export const mockVerificationKey =
+  '0000000200000800000000740000000f00000003515f3109623eb3c25aa5b16a1a79fd558bac7a7ce62c4560a8c537c77ce80dd339128d1d37b6582ee9e6df9567efb64313471dfa18f520f9ce53161b50dbf7731bc5f900000003515f322bc4cce83a486a92c92fd59bd84e0f92595baa639fc2ed86b00ffa0dfded2a092a669a3bdb7a273a015eda494457cc7ed5236f26cee330c290d45a33b9daa94800000003515f332729426c008c085a81bd34d8ef12dd31e80130339ef99d50013a89e4558eee6d0fa4ffe2ee7b7b62eb92608b2251ac31396a718f9b34978888789042b790a30100000003515f342be6b6824a913eb7a57b03cb1ee7bfb4de02f2f65fe8a4e97baa7766ddb353a82a8a25c49dc63778cd9fe96173f12a2bc77f3682f4c4448f98f1df82c75234a100000003515f351f85760d6ab567465aadc2f180af9eae3800e6958fec96aef53fd8a7b195d7c000c6267a0dd5cfc22b3fe804f53e266069c0e36f51885baec1e7e67650c62e170000000c515f41524954484d455449430d9d0f8ece2aa12012fa21e6e5c859e97bd5704e5c122064a66051294bc5e04213f61f54a0ebdf6fee4d4a6ecf693478191de0c2899bcd8e86a636c8d3eff43400000003515f43224a99d02c86336737c8dd5b746c40d2be6aead8393889a76a18d664029096e90f7fe81adcc92a74350eada9622ac453f49ebac24a066a1f83b394df54dfa0130000000c515f46495845445f42415345060e8a013ed289c2f9fd7473b04f6594b138ddb4b4cf6b901622a14088f04b8d2c83ff74fce56e3d5573b99c7b26d85d5046ce0c6559506acb7a675e7713eb3a00000007515f4c4f4749430721a91cb8da4b917e054f72147e1760cfe0ef3d45090ac0f4961d84ec1996961a25e787b26bd8b50b1a99450f77a424a83513c2b33af268cd253b0587ff50c700000003515f4d05dbd8623b8652511e1eb38d38887a69eceb082f807514f09e127237c5213b401b9325b48c6c225968002318095f89d0ef9cf629b2b7f0172e03bc39aacf6ed800000007515f52414e474504b57a3805e41df328f5ca9aefa40fad5917391543b7b65c6476e60b8f72e9ad07c92f3b3e11c8feae96dedc4b14a6226ef3201244f37cfc1ee5b96781f48d2b000000075349474d415f3125001d1954a18571eaa007144c5a567bb0d2be4def08a8be918b8c05e3b27d312c59ed41e09e144eab5de77ca89a2fd783be702a47c951d3112e3de02ce6e47c000000075349474d415f3223994e6a23618e60fa01c449a7ab88378709197e186d48d604bfb6931ffb15ad11c5ec7a0700570f80088fd5198ab5d5c227f2ad2a455a6edeec024156bb7beb000000075349474d415f3300cda5845f23468a13275d18bddae27c6bb189cf9aa95b6a03a0cb6688c7e8d829639b45cf8607c525cc400b55ebf90205f2f378626dc3406cc59b2d1b474fba000000075349474d415f342d299e7928496ea2d37f10b43afd6a80c90a33b483090d18069ffa275eedb2fc2f82121e8de43dc036d99b478b6227ceef34248939987a19011f065d8b5cef5c0000000010000000000000000100000002000000030000000400000005000000060000000700000008000000090000000a0000000b0000000c0000000d0000000e0000000f';

package/src/abi/note_selector.ts

@@ -0,0 +1,78 @@
+import { toBigIntBE } from '@aztec/foundation/bigint-buffer';
+import { randomInt } from '@aztec/foundation/crypto';
+import { Fr } from '@aztec/foundation/fields';
+import { hexSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader, TypeRegistry } from '@aztec/foundation/serialize';
+
+import { Selector } from './selector.js';
+
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+
+/** Note selector branding */
+export interface NoteSelector {
+  /** Brand. */
+  _branding: 'NoteSelector';
+}
+
+/**
+ * A note selector is a 7 bit long value that identifies a note type within a contract.
+ * TODO(#10952): Encoding of note type id can be reduced to 7 bits.
+ */
+export class NoteSelector extends Selector {
+  /**
+   * Deserializes from a buffer or reader, corresponding to a write in cpp.
+   * @param buffer - Buffer  or BufferReader to read from.
+   * @returns The Selector.
+   */
+  static fromBuffer(buffer: Buffer | BufferReader) {
+    const reader = BufferReader.asReader(buffer);
+    const value = Number(toBigIntBE(reader.readBytes(Selector.SIZE)));
+    if (value >= 1 << 7) {
+      throw new Error(`Invalid note selector: ${value}`);
+    }
+    return new NoteSelector(value);
+  }
+
+  static fromString(buf: string) {
+    const withoutPrefix = buf.replace(/^0x/i, '').slice(-8);
+    const buffer = Buffer.from(withoutPrefix, 'hex');
+    return NoteSelector.fromBuffer(buffer);
+  }
+
+  /**
+   * Converts a field to selector.
+   * @param fr - The field to convert.
+   * @returns The selector.
+   */
+  static fromField(fr: Fr) {
+    return new NoteSelector(Number(fr.toBigInt()));
+  }
+
+  /**
+   * Creates an empty selector.
+   * @returns An empty selector.
+   */
+  static empty() {
+    return new NoteSelector(0);
+  }
+
+  /**
+   * Creates a random selector.
+   * @returns A random selector.
+   */
+  static random() {
+    const value = randomInt(1 << 7);
+    return NoteSelector.fromField(new Fr(value));
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static get schema() {
+    return hexSchemaFor(NoteSelector);
+  }
+}
+
+// For deserializing JSON.
+TypeRegistry.register('NoteSelector', NoteSelector);

package/src/abi/selector.ts

@@ -0,0 +1,64 @@
+import { toBufferBE } from '@aztec/foundation/bigint-buffer';
+import { Fr } from '@aztec/foundation/fields';
+import { bufferToHex } from '@aztec/foundation/string';
+
+import { inspect } from 'util';
+
+/** A selector is the first 4 bytes of the hash of a signature. */
+export abstract class Selector {
+  /** The size of the selector in bytes. */
+  public static SIZE = 4;
+
+  constructor(/** Value of the selector */ public value: number) {
+    if (value > 2 ** (Selector.SIZE * 8) - 1) {
+      throw new Error(`Selector must fit in ${Selector.SIZE} bytes (got value ${value}).`);
+    }
+  }
+
+  /**
+   * Checks if the selector is empty (all bytes are 0).
+   * @returns True if the selector is empty (all bytes are 0).
+   */
+  public isEmpty(): boolean {
+    return this.value === 0;
+  }
+
+  /**
+   * Serialize as a buffer.
+   * @param bufferSize - The buffer size.
+   * @returns The buffer.
+   */
+  toBuffer(bufferSize = Selector.SIZE): Buffer {
+    return toBufferBE(BigInt(this.value), bufferSize);
+  }
+
+  /**
+   * Serialize as a hex string.
+   * @returns The string.
+   */
+  toString(): string {
+    return bufferToHex(this.toBuffer());
+  }
+
+  [inspect.custom]() {
+    return `Selector<${this.toString()}>`;
+  }
+
+  /**
+   * Checks if this selector is equal to another.
+   * @param other - The other selector.
+   * @returns True if the selectors are equal.
+   */
+  equals(other: Selector): boolean {
+    return this.value === other.value;
+  }
+
+  /**
+   * Returns a new field with the same contents as this EthAddress.
+   *
+   * @returns An Fr instance.
+   */
+  public toField() {
+    return new Fr(BigInt(this.value));
+  }
+}

package/src/abi/utils.ts

@@ -0,0 +1,78 @@
+import type { AbiType } from './abi.js';
+
+/**
+ * Returns whether the ABI type is an Aztec or Ethereum Address defined in Aztec.nr.
+ * @param abiType - Type to check.
+ * @returns Boolean.
+ */
+export function isAddressStruct(abiType: AbiType) {
+  return isEthAddressStruct(abiType) || isAztecAddressStruct(abiType);
+}
+
+/**
+ * Returns whether the ABI type is an Ethereum Address defined in Aztec.nr.
+ * @param abiType - Type to check.
+ * @returns Boolean.
+ */
+export function isEthAddressStruct(abiType: AbiType) {
+  return abiType.kind === 'struct' && abiType.path.endsWith('address::EthAddress');
+}
+
+/**
+ * Returns whether the ABI type is an Aztec Address defined in Aztec.nr.
+ * @param abiType - Type to check.
+ * @returns Boolean.
+ */
+export function isAztecAddressStruct(abiType: AbiType) {
+  return abiType.kind === 'struct' && abiType.path.endsWith('address::AztecAddress');
+}
+
+/**
+ * Returns whether the ABI type is an Function Selector defined in Aztec.nr.
+ * @param abiType - Type to check.
+ * @returns Boolean.
+ */
+export function isFunctionSelectorStruct(abiType: AbiType) {
+  return abiType.kind === 'struct' && abiType.path.endsWith('types::abis::function_selector::FunctionSelector');
+}
+
+/**
+ * Returns whether the ABI type is a struct with a single `inner` field.
+ * @param abiType - Type to check.
+ */
+export function isWrappedFieldStruct(abiType: AbiType) {
+  return (
+    abiType.kind === 'struct' &&
+    abiType.fields.length === 1 &&
+    abiType.fields[0].name === 'inner' &&
+    abiType.fields[0].type.kind === 'field'
+  );
+}
+
+/**
+ * Returns a bigint by parsing a serialized 2's complement signed int.
+ * @param b - The signed int as a buffer
+ * @returns - a deserialized bigint
+ */
+export function parseSignedInt(b: Buffer, width?: number) {
+  const buf = Buffer.from(b);
+
+  // We get the last (width / 8) bytes where width = bits of type (i64, i32 etc)
+  const slicedBuf = width !== undefined ? buf.subarray(-(width / 8)) : buf;
+
+  // Then manually deserialize with 2's complement, with the process as follows:
+
+  // If our most significant bit is high...
+  if (0x80 & slicedBuf.subarray(0, 1).readUInt8()) {
+    // We flip the bits
+    for (let i = 0; i < slicedBuf.length; i++) {
+      slicedBuf[i] = ~slicedBuf[i];
+    }
+
+    // Add one, then negate it
+    return -(BigInt(`0x${slicedBuf.toString('hex')}`) + 1n);
+  }
+
+  // ...otherwise we just return our positive int
+  return BigInt(`0x${slicedBuf.toString('hex')}`);
+}

package/src/auth_witness/auth_witness.ts

@@ -0,0 +1,52 @@
+import { Fr } from '@aztec/foundation/fields';
+import { BufferReader, serializeToBuffer } from '@aztec/foundation/serialize';
+import { bufferToHex, hexToBuffer } from '@aztec/foundation/string';
+
+import { hexSchemaFor } from '../schemas/schemas.js';
+import { Vector } from '../types/shared.js';
+
+/**
+ * An authentication witness. Used to authorize an action by a user.
+ */
+export class AuthWitness {
+  /** Authentication witness for the hash  */
+  public readonly witness: Fr[];
+
+  constructor(
+    /** Hash of the request to authorize */
+    public readonly requestHash: Fr,
+    /** Authentication witness for the hash  */
+    witness: (Fr | number)[],
+  ) {
+    this.witness = witness.map(x => new Fr(x));
+  }
+
+  static get schema() {
+    return hexSchemaFor(AuthWitness);
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  toBuffer() {
+    return serializeToBuffer(this.requestHash, new Vector(this.witness));
+  }
+
+  static fromBuffer(buffer: Buffer | BufferReader): AuthWitness {
+    const reader = BufferReader.asReader(buffer);
+    return new AuthWitness(Fr.fromBuffer(reader), reader.readVector(Fr));
+  }
+
+  toString() {
+    return bufferToHex(this.toBuffer());
+  }
+
+  static fromString(str: string) {
+    return AuthWitness.fromBuffer(hexToBuffer(str));
+  }
+
+  static random() {
+    return new AuthWitness(Fr.random(), [Fr.random(), Fr.random(), Fr.random()]);
+  }
+}

package/src/auth_witness/index.ts

@@ -0,0 +1 @@
+export * from './auth_witness.js';