@aztec/foundation 0.23.0 → 0.26.1

package/src/abi/decoder.ts

@@ -0,0 +1,176 @@
+import { AztecAddress } from '../aztec-address/index.js';
+import { Fr } from '../fields/index.js';
+import { ABIParameter, type ABIType, ABIVariable, FunctionArtifact } from './abi.js';
+import { isAztecAddressStruct } from './utils.js';
+
+/**
+ * The type of our decoded ABI.
+ */
+export type DecodedReturn = bigint | boolean | AztecAddress | DecodedReturn[] | { [key: string]: DecodedReturn };
+
+/**
+ * Decodes return values from a function call.
+ * Missing support for integer and string.
+ */
+class ReturnValuesDecoder {
+  constructor(private artifact: FunctionArtifact, private flattened: Fr[]) {}
+
+  /**
+   * Decodes a single return value from field to the given type.
+   * @param abiType - The type of the return value.
+   * @returns The decoded return value.
+   */
+  private decodeReturn(abiType: ABIType): DecodedReturn {
+    switch (abiType.kind) {
+      case 'field':
+        return this.getNextField().toBigInt();
+      case 'integer':
+        if (abiType.sign === 'signed') {
+          throw new Error('Unsupported type: signed integer');
+        }
+        return this.getNextField().toBigInt();
+      case 'boolean':
+        return !this.getNextField().isZero();
+      case 'array': {
+        const array = [];
+        for (let i = 0; i < abiType.length; i += 1) {
+          array.push(this.decodeReturn(abiType.type));
+        }
+        return array;
+      }
+      case 'struct': {
+        const struct: { [key: string]: DecodedReturn } = {};
+        if (isAztecAddressStruct(abiType)) {
+          return new AztecAddress(this.getNextField().toBuffer());
+        }
+
+        for (const field of abiType.fields) {
+          struct[field.name] = this.decodeReturn(field.type);
+        }
+        return struct;
+      }
+      case 'string': {
+        const array = [];
+        for (let i = 0; i < abiType.length; i += 1) {
+          array.push(this.getNextField().toBigInt());
+        }
+        return array;
+      }
+      default:
+        throw new Error(`Unsupported type: ${abiType}`);
+    }
+  }
+
+  /**
+   * Gets the next field in the flattened return values.
+   * @returns The next field in the flattened return values.
+   */
+  private getNextField(): Fr {
+    const field = this.flattened.shift();
+    if (!field) {
+      throw new Error('Not enough return values');
+    }
+    return field;
+  }
+
+  /**
+   * Decodes all the return values for the given function ABI.
+   * Aztec.nr support only single return value
+   * The return value can however be simple types, structs or arrays
+   * @returns The decoded return values.
+   */
+  public decode(): DecodedReturn {
+    if (this.artifact.returnTypes.length > 1) {
+      throw new Error('Multiple return values not supported');
+    }
+    if (this.artifact.returnTypes.length === 0) {
+      return [];
+    }
+    return this.decodeReturn(this.artifact.returnTypes[0]);
+  }
+}
+
+/**
+ * Decodes return values from a function call.
+ * @param abi - The ABI entry of the function.
+ * @param returnValues - The decoded return values.
+ * @returns
+ */
+export function decodeReturnValues(abi: FunctionArtifact, returnValues: Fr[]) {
+  return new ReturnValuesDecoder(abi, returnValues.slice()).decode();
+}
+
+/**
+ * Decodes the signature of a function from the name and parameters.
+ */
+export class FunctionSignatureDecoder {
+  private separator: string;
+  constructor(private name: string, private parameters: ABIParameter[], private includeNames = false) {
+    this.separator = includeNames ? ', ' : ',';
+  }
+
+  /**
+   * Decodes a single function parameter type for the function signature.
+   * @param param - The parameter type to decode.
+   * @returns A string representing the parameter type.
+   */
+  private getParameterType(param: ABIType): string {
+    switch (param.kind) {
+      case 'field':
+        return 'Field';
+      case 'integer':
+        if (param.sign === 'signed') {
+          throw new Error('Unsupported type: signed integer');
+        }
+        return `u${param.width}`;
+      case 'boolean':
+        return 'bool';
+      case 'array':
+        return `[${this.getParameterType(param.type)};${param.length}]`;
+      case 'string':
+        return `str<${param.length}>`;
+      case 'struct':
+        return `(${param.fields.map(field => `${this.decodeParameter(field)}`).join(this.separator)})`;
+      default:
+        throw new Error(`Unsupported type: ${param}`);
+    }
+  }
+
+  /**
+   * Decodes a single function parameter for the function signature.
+   * @param param - The parameter to decode.
+   * @returns A string representing the parameter type and optionally its name.
+   */
+  private decodeParameter(param: ABIVariable): string {
+    const type = this.getParameterType(param.type);
+    return this.includeNames ? `${param.name}: ${type}` : type;
+  }
+
+  /**
+   * Decodes all the parameters and build the function signature
+   * @returns The function signature.
+   */
+  public decode(): string {
+    return `${this.name}(${this.parameters.map(param => this.decodeParameter(param)).join(this.separator)})`;
+  }
+}
+
+/**
+ * Decodes a function signature from the name and parameters.
+ * @param name - The name of the function.
+ * @param parameters - The parameters of the function.
+ * @returns - The function signature.
+ */
+export function decodeFunctionSignature(name: string, parameters: ABIParameter[]) {
+  return new FunctionSignatureDecoder(name, parameters).decode();
+}
+
+/**
+ * Decodes a function signature from the name and parameters including parameter names.
+ * @param name - The name of the function.
+ * @param parameters - The parameters of the function.
+ * @returns - The user-friendly function signature.
+ */
+export function decodeFunctionSignatureWithParameterNames(name: string, parameters: ABIParameter[]) {
+  return new FunctionSignatureDecoder(name, parameters, true).decode();
+}

package/src/abi/encoder.ts

@@ -0,0 +1,143 @@
+import { Fr } from '../fields/index.js';
+import { ABIType, FunctionAbi } from './abi.js';
+import { isAddressStruct, isFunctionSelectorStruct, isWrappedFieldStruct } from './utils.js';
+
+/**
+ * Encodes arguments for a function call.
+ * Missing support for integer and string.
+ */
+class ArgumentEncoder {
+  private flattened: Fr[] = [];
+
+  constructor(private abi: FunctionAbi, private args: any[]) {}
+
+  static typeSize(abiType: ABIType): number {
+    switch (abiType.kind) {
+      case 'field':
+      case 'boolean':
+      case 'integer':
+        return 1;
+      case 'string':
+        return abiType.length;
+      case 'array':
+        return abiType.length * ArgumentEncoder.typeSize(abiType.type);
+      case 'struct':
+        return abiType.fields.reduce((acc, field) => acc + ArgumentEncoder.typeSize(field.type), 0);
+      default: {
+        const exhaustiveCheck: never = abiType;
+        throw new Error(`Unhandled abi type: ${exhaustiveCheck}`);
+      }
+    }
+  }
+
+  /**
+   * Encodes a single argument from the given type to field.
+   * @param abiType - The abi type of the argument.
+   * @param arg - The value to encode.
+   * @param name - Name.
+   */
+  private encodeArgument(abiType: ABIType, arg: any, name?: string) {
+    if (arg === undefined || arg == null) {
+      throw new Error(`Undefined argument ${name ?? 'unnamed'} of type ${abiType.kind}`);
+    }
+    switch (abiType.kind) {
+      case 'field':
+        if (typeof arg === 'number') {
+          this.flattened.push(new Fr(BigInt(arg)));
+        } else if (typeof arg === 'bigint') {
+          this.flattened.push(new Fr(arg));
+        } else if (typeof arg === 'boolean') {
+          this.flattened.push(new Fr(arg ? 1n : 0n));
+        } else if (typeof arg === 'object') {
+          if (Buffer.isBuffer(arg)) {
+            this.flattened.push(Fr.fromBuffer(arg));
+          } else if (typeof arg.toField === 'function') {
+            this.flattened.push(arg.toField());
+          } else {
+            throw new Error(`Argument for ${name} cannot be serialized to a field`);
+          }
+        } else {
+          throw new Error(`Invalid argument "${arg}" of type ${abiType.kind}`);
+        }
+        break;
+      case 'boolean':
+        this.flattened.push(new Fr(arg ? 1n : 0n));
+        break;
+      case 'array':
+        for (let i = 0; i < abiType.length; i += 1) {
+          this.encodeArgument(abiType.type, arg[i], `${name}[${i}]`);
+        }
+        break;
+      case 'string':
+        for (let i = 0; i < abiType.length; i += 1) {
+          // If the string is shorter than the defined length, pad it with 0s.
+          const toInsert = i < arg.length ? BigInt((arg as string).charCodeAt(i)) : 0n;
+          this.flattened.push(new Fr(toInsert));
+        }
+        break;
+      case 'struct': {
+        // If the abi expects a struct like { address: Field } and the supplied arg does not have
+        // an address field in it, we try to encode it as if it were a field directly.
+        const isAddress = isAddressStruct(abiType);
+        if (isAddress && typeof arg.address === 'undefined' && typeof arg.inner === 'undefined') {
+          this.encodeArgument({ kind: 'field' }, arg, `${name}.inner`);
+          break;
+        }
+        // Or if the supplied argument does have an address field in it, like a CompleteAddress,
+        // we encode it directly as a field.
+        if (isAddress && typeof arg.address !== 'undefined') {
+          this.encodeArgument({ kind: 'field' }, arg.address, `${name}.address`);
+          break;
+        }
+        if (isFunctionSelectorStruct(abiType)) {
+          this.encodeArgument({ kind: 'integer', sign: 'unsigned', width: 32 }, arg.value ?? arg, `${name}.inner`);
+          break;
+        }
+        if (isWrappedFieldStruct(abiType)) {
+          this.encodeArgument({ kind: 'field' }, arg.inner ?? arg, `${name}.inner`);
+          break;
+        }
+        for (const field of abiType.fields) {
+          this.encodeArgument(field.type, arg[field.name], `${name}.${field.name}`);
+        }
+        break;
+      }
+      case 'integer':
+        this.flattened.push(new Fr(arg));
+        break;
+      default:
+        throw new Error(`Unsupported type: ${abiType}`);
+    }
+  }
+
+  /**
+   * Encodes all the arguments for the given function ABI.
+   * @returns The encoded arguments.
+   */
+  public encode() {
+    for (let i = 0; i < this.abi.parameters.length; i += 1) {
+      const parameterAbi = this.abi.parameters[i];
+      this.encodeArgument(parameterAbi.type, this.args[i], parameterAbi.name);
+    }
+    return this.flattened;
+  }
+}
+
+/**
+ * Encodes all the arguments for a function call.
+ * @param abi - The function ABI entry.
+ * @param args - The arguments to encode.
+ * @returns The encoded arguments.
+ */
+export function encodeArguments(abi: FunctionAbi, args: any[]) {
+  return new ArgumentEncoder(abi, args).encode();
+}
+
+/**
+ * Returns the size of the arguments for a function ABI.
+ * @param abi - The function ABI entry.
+ * @returns The size of the arguments.
+ */
+export function countArgumentsSize(abi: FunctionAbi) {
+  return abi.parameters.reduce((acc, parameter) => acc + ArgumentEncoder.typeSize(parameter.type), 0);
+}

package/src/abi/event_selector.ts

@@ -0,0 +1,73 @@
+import { fromHex, toBigIntBE } from '../bigint-buffer/index.js';
+import { keccak } from '../crypto/index.js';
+import { Fr } from '../fields/fields.js';
+import { BufferReader } from '../serialize/buffer_reader.js';
+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 fromSignature(signature: string) {
+    // throw if signature contains whitespace
+    if (/\s/.test(signature)) {
+      throw new Error('Signature cannot contain whitespace');
+    }
+    return EventSelector.fromBuffer(keccak(Buffer.from(signature)).subarray(0, Selector.SIZE));
+  }
+
+  /**
+   * Create a Selector instance from a hex-encoded string.
+   * The input 'address' should be prefixed with '0x' or not, and have exactly 64 hex characters.
+   * Throws an error if the input length is invalid or address value is out of range.
+   *
+   * @param selector - The hex-encoded string representing the Selector.
+   * @returns An Selector instance.
+   */
+  static fromString(selector: string) {
+    const buf = fromHex(selector);
+    if (buf.length !== Selector.SIZE) {
+      throw new Error(`Invalid Selector length ${buf.length} (expected ${Selector.SIZE}).`);
+    }
+    return EventSelector.fromBuffer(buf);
+  }
+
+  /**
+   * Creates an empty selector.
+   * @returns An empty selector.
+   */
+  static empty() {
+    return new EventSelector(0);
+  }
+}

package/src/abi/function_selector.ts

@@ -0,0 +1,122 @@
+import { fromHex, toBigIntBE } from '../bigint-buffer/index.js';
+import { keccak, randomBytes } from '../crypto/index.js';
+import { Fr } from '../fields/fields.js';
+import { BufferReader } from '../serialize/buffer_reader.js';
+import { FieldReader } from '../serialize/field_reader.js';
+import { 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 {
+  /**
+   * Checks if this function selector is equal to another.
+   * @returns True if the function selectors are equal.
+   */
+  equals(otherName: string, otherParams: ABIParameter[]): boolean;
+  equals(other: FunctionSelector): boolean;
+  equals(other: FunctionSelector | string, otherParams?: ABIParameter[]): boolean {
+    if (typeof other === 'string') {
+      return this.equals(FunctionSelector.fromNameAndParameters(other, otherParams!));
+    }
+    return this.value === other.value;
+  }
+
+  /**
+   * 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 fromSignature(signature: string) {
+    // throw if signature contains whitespace
+    if (/\s/.test(signature)) {
+      throw new Error('Signature cannot contain whitespace');
+    }
+    return FunctionSelector.fromBuffer(keccak(Buffer.from(signature)).subarray(0, Selector.SIZE));
+  }
+
+  /**
+   * Create a Selector instance from a hex-encoded string.
+   * The input 'address' should be prefixed with '0x' or not, and have exactly 64 hex characters.
+   * Throws an error if the input length is invalid or address value is out of range.
+   *
+   * @param selector - The hex-encoded string representing the Selector.
+   * @returns An Selector instance.
+   */
+  static fromString(selector: string) {
+    const buf = fromHex(selector);
+    if (buf.length !== Selector.SIZE) {
+      throw new Error(`Invalid Selector 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[] }): FunctionSelector;
+  static fromNameAndParameters(name: string, parameters: ABIParameter[]): FunctionSelector;
+  static fromNameAndParameters(
+    nameOrArgs: string | { name: string; parameters: ABIParameter[] },
+    maybeParameters?: ABIParameter[],
+  ): FunctionSelector {
+    const { name, parameters } =
+      typeof nameOrArgs === 'string' ? { name: nameOrArgs, parameters: maybeParameters! } : nameOrArgs;
+    const signature = decodeFunctionSignature(name, parameters);
+    const selector = 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));
+  }
+}

package/src/abi/index.ts

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

package/src/abi/selector.ts

@@ -0,0 +1,63 @@
+import { inspect } from 'util';
+
+import { toBufferBE } from '../bigint-buffer/index.js';
+import { Fr } from '../fields/index.js';
+
+/** 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 '0x' + this.toBuffer().toString('hex');
+  }
+
+  [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,50 @@
+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'
+  );
+}