@aztec/stdlib 0.77.0-testnet-ignition.17

package/src/abi/contract_artifact.ts

@@ -0,0 +1,294 @@
+import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
+
+import {
+  type ABIParameter,
+  type ABIParameterVisibility,
+  type AbiType,
+  type BasicValue,
+  type ContractArtifact,
+  ContractArtifactSchema,
+  type ContractNote,
+  type FieldLayout,
+  type FunctionArtifact,
+  FunctionType,
+  type IntegerValue,
+  type StructValue,
+  type TypedStructFieldValue,
+} from '../abi/index.js';
+import {
+  AZTEC_INITIALIZER_ATTRIBUTE,
+  AZTEC_INTERNAL_ATTRIBUTE,
+  AZTEC_PRIVATE_ATTRIBUTE,
+  AZTEC_PUBLIC_ATTRIBUTE,
+  AZTEC_VIEW_ATTRIBUTE,
+  type NoirCompiledContract,
+} from '../noir/index.js';
+
+/**
+ * Serializes a contract artifact to a buffer for storage.
+ * @param artifact - Artifact to serialize.
+ * @returns A buffer.
+ */
+export function contractArtifactToBuffer(artifact: ContractArtifact): Buffer {
+  return Buffer.from(jsonStringify(artifact), 'utf-8');
+}
+
+/**
+ * Deserializes a contract artifact from storage.
+ * @param buffer - Buffer to deserialize.
+ * @returns Deserialized artifact.
+ */
+export function contractArtifactFromBuffer(buffer: Buffer): Promise<ContractArtifact> {
+  return jsonParseWithSchema(buffer.toString('utf-8'), ContractArtifactSchema);
+}
+
+/**
+ * Gets nargo build output and returns a valid contract artifact instance.
+ * @param input - Input object as generated by nargo compile.
+ * @returns A valid contract artifact instance.
+ */
+export function loadContractArtifact(input: NoirCompiledContract): ContractArtifact {
+  if (isContractArtifact(input)) {
+    return input;
+  }
+  return generateContractArtifact(input);
+}
+
+/**
+ * Checks if the given input looks like a valid ContractArtifact. The check is not exhaustive,
+ * and it's just meant to differentiate between nargo raw build artifacts and the ones
+ * produced by this compiler.
+ * @param input - Input object.
+ * @returns True if it looks like a ContractArtifact.
+ */
+function isContractArtifact(input: any): input is ContractArtifact {
+  if (typeof input !== 'object') {
+    return false;
+  }
+  const maybeContractArtifact = input as ContractArtifact;
+  if (typeof maybeContractArtifact.name !== 'string') {
+    return false;
+  }
+  if (!Array.isArray(maybeContractArtifact.functions)) {
+    return false;
+  }
+  for (const fn of maybeContractArtifact.functions) {
+    if (typeof fn.name !== 'string') {
+      return false;
+    }
+    if (typeof fn.functionType !== 'string') {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Parameter in a function from a noir contract compilation artifact */
+type NoirCompiledContractFunctionParameter = NoirCompiledContractFunction['abi']['parameters'][number];
+
+/**
+ * Generates a function parameter out of one generated by a nargo build.
+ * @param param - Noir parameter.
+ * @returns A function parameter.
+ */
+function generateFunctionParameter(param: NoirCompiledContractFunctionParameter): ABIParameter {
+  const { visibility } = param;
+  if ((visibility as string) === 'databus') {
+    throw new Error(`Unsupported visibility ${param.visibility} for noir contract function parameter ${param.name}.`);
+  }
+  return { ...param, visibility: visibility as ABIParameterVisibility };
+}
+
+/** Function from a noir contract compilation artifact */
+type NoirCompiledContractFunction = NoirCompiledContract['functions'][number];
+
+/**
+ * Generates a function build artifact.
+ * @param fn - Noir function entry.
+ * @param contract - Parent contract.
+ * @returns Function artifact.
+ */
+function generateFunctionArtifact(
+  fn: NoirCompiledContractFunction,
+  contract: NoirCompiledContract,
+): Omit<FunctionArtifact, 'bytecode'> & { bytecode: string } {
+  if (fn.custom_attributes === undefined) {
+    throw new Error(
+      `No custom attributes found for contract function ${fn.name}. Try rebuilding the contract with the latest nargo version.`,
+    );
+  }
+  const functionType = getFunctionType(fn);
+  const isInternal = fn.custom_attributes.includes(AZTEC_INTERNAL_ATTRIBUTE);
+  const isStatic = fn.custom_attributes.includes(AZTEC_VIEW_ATTRIBUTE);
+
+  // If the function is not unconstrained, the first item is inputs or CallContext which we should omit
+  let parameters = fn.abi.parameters.map(generateFunctionParameter);
+  if (hasKernelFunctionInputs(parameters)) {
+    parameters = parameters.slice(1);
+  }
+
+  let returnTypes: AbiType[] = [];
+  if (functionType === FunctionType.UNCONSTRAINED) {
+    returnTypes = fn.abi.return_type ? [fn.abi.return_type.abi_type] : returnTypes;
+  } else {
+    const pathToFind = `${contract.name}::${fn.name}_abi`;
+    const abiStructs: AbiType[] = contract.outputs.structs['functions'];
+
+    const returnStruct = abiStructs.find(a => a.kind === 'struct' && a.path === pathToFind);
+
+    if (returnStruct) {
+      if (returnStruct.kind !== 'struct') {
+        throw new Error('Could not generate contract function artifact');
+      }
+
+      const returnTypeField = returnStruct.fields.find(field => field.name === 'return_type');
+      if (returnTypeField) {
+        returnTypes = [returnTypeField.type];
+      }
+    }
+  }
+
+  return {
+    name: fn.name,
+    functionType,
+    isInternal,
+    isStatic,
+    isInitializer: fn.custom_attributes.includes(AZTEC_INITIALIZER_ATTRIBUTE),
+    parameters,
+    returnTypes,
+    bytecode: fn.bytecode,
+    debugSymbols: fn.debug_symbols,
+    errorTypes: fn.abi.error_types,
+    ...(fn.assert_messages ? { assertMessages: fn.assert_messages } : undefined),
+    ...(fn.verification_key ? { verificationKey: fn.verification_key } : undefined),
+  };
+}
+
+function getFunctionType(fn: NoirCompiledContractFunction): FunctionType {
+  if (fn.custom_attributes.includes(AZTEC_PRIVATE_ATTRIBUTE)) {
+    return FunctionType.PRIVATE;
+  } else if (fn.custom_attributes.includes(AZTEC_PUBLIC_ATTRIBUTE)) {
+    return FunctionType.PUBLIC;
+  } else if (fn.is_unconstrained) {
+    return FunctionType.UNCONSTRAINED;
+  } else {
+    // Default to a private function (see simple_macro_example_expanded for an example of this behavior)
+    return FunctionType.PRIVATE;
+  }
+}
+
+/**
+ * Returns true if the first parameter is kernel function inputs.
+ *
+ * Noir macros #[aztec(private|public)] inject the following code
+ * fn <name>(inputs: <Public|Private>ContextInputs, ...otherparams) {}
+ *
+ * Return true if this injected parameter is found
+ */
+function hasKernelFunctionInputs(params: ABIParameter[]): boolean {
+  const firstParam = params[0];
+  return firstParam?.type.kind === 'struct' && firstParam.type.path.includes('ContextInputs');
+}
+
+/**
+ * Generates a storage layout for the contract artifact.
+ * @param input - The compiled noir contract to get storage layout for
+ * @returns A storage layout for the contract.
+ */
+function getStorageLayout(input: NoirCompiledContract) {
+  // If another contract is imported by the main contract, its storage layout its going to also show up here.
+  // The layout export includes the contract name, so here we can find the one that belongs to the current one and
+  // ignore the rest.
+  const storageExports = input.outputs.globals.storage ? (input.outputs.globals.storage as StructValue[]) : [];
+  const storageForContract = storageExports.find(storageExport => {
+    const contractNameField = storageExport.fields.find(field => field.name === 'contract_name')?.value as BasicValue<
+      'string',
+      string
+    >;
+    return contractNameField.value === input.name;
+  });
+  const storageFields = storageForContract
+    ? ((storageForContract.fields.find(field => field.name == 'fields') as TypedStructFieldValue<StructValue>).value
+        .fields as TypedStructFieldValue<StructValue>[])
+    : [];
+
+  if (storageFields.length === 0) {
+    return {};
+  }
+
+  return storageFields.reduce((acc: Record<string, Omit<FieldLayout, 'slot'> & { slot: string }>, field) => {
+    const name = field.name;
+    const slot = field.value.fields[0].value as IntegerValue;
+    acc[name] = {
+      slot: `0x${slot.value}`,
+    };
+    return acc;
+  }, {});
+}
+
+/**
+ * Generates records of the notes with note type ids of the artifact.
+ * @param input - The compiled noir contract to get note types for
+ * @return A record of the note types and their ids
+ */
+function getNoteTypes(input: NoirCompiledContract) {
+  // The type is useless here as it does not give us any guarantee (e.g. `AbiValue` can be one of many different
+  // types) so we nuke it and later we manually check the values are as we expect.
+  const notes = input.outputs.globals.notes as any[];
+
+  if (!notes) {
+    return {};
+  }
+
+  return notes.reduce((acc: Record<string, Omit<ContractNote, 'id'> & { id: string }>, note) => {
+    const noteFields = note.fields;
+
+    // We find note type id by looking for respective kinds as each of them is unique
+    const rawNoteTypeId = noteFields.find((field: any) => field.kind === 'integer');
+    const rawName = noteFields.find((field: any) => field.kind === 'string');
+    const rawNoteFields = noteFields.find((field: any) => field.kind === 'struct');
+
+    if (!rawNoteTypeId || !rawName || !rawNoteFields) {
+      throw new Error(`Could not find note type id, name or fields for note ${note}`);
+    }
+
+    const noteTypeId = rawNoteTypeId.value as string;
+    const name = rawName.value as string;
+
+    // Note type id is encoded as a hex string
+    const fields = rawNoteFields.fields.map((field: any) => {
+      return {
+        name: field.name,
+        index: parseInt(field.value.fields[0].value.value, 16),
+        nullable: field.value.fields[1].value.value,
+      };
+    });
+    acc[name] = {
+      id: noteTypeId,
+      typ: name,
+      fields,
+    };
+    return acc;
+  }, {});
+}
+
+/**
+ * Given a Nargo output generates an Aztec-compatible contract artifact.
+ * @param compiled - Noir build output.
+ * @returns Aztec contract build artifact.
+ */
+function generateContractArtifact(contract: NoirCompiledContract, aztecNrVersion?: string): ContractArtifact {
+  try {
+    return ContractArtifactSchema.parse({
+      name: contract.name,
+      functions: contract.functions.map(f => generateFunctionArtifact(f, contract)),
+      outputs: contract.outputs,
+      storageLayout: getStorageLayout(contract),
+      notes: getNoteTypes(contract),
+      fileMap: contract.file_map,
+      ...(aztecNrVersion ? { aztecNrVersion } : {}),
+    });
+  } catch (err) {
+    throw new Error(`Could not generate contract artifact for ${contract.name}: ${err}`);
+  }
+}

package/src/abi/decoder.ts

@@ -0,0 +1,187 @@
+import { Fr } from '@aztec/foundation/fields';
+
+import { AztecAddress } from '../aztec-address/index.js';
+import type { ABIParameter, ABIVariable, AbiType } from './abi.js';
+import { isAztecAddressStruct, parseSignedInt } from './utils.js';
+
+/**
+ * The type of our decoded ABI.
+ */
+export type AbiDecoded = bigint | boolean | AztecAddress | AbiDecoded[] | { [key: string]: AbiDecoded };
+
+/**
+ * Decodes values using a provided ABI.
+ */
+class AbiDecoder {
+  constructor(private types: AbiType[], 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 decodeNext(abiType: AbiType): AbiDecoded {
+    switch (abiType.kind) {
+      case 'field':
+        return this.getNextField().toBigInt();
+      case 'integer': {
+        const nextField = this.getNextField();
+
+        if (abiType.sign === 'signed') {
+          // We parse the buffer using 2's complement
+          return parseSignedInt(nextField.toBuffer(), abiType.width);
+        }
+
+        return nextField.toBigInt();
+      }
+      case 'boolean':
+        return !this.getNextField().isZero();
+      case 'array': {
+        const array = [];
+        for (let i = 0; i < abiType.length; i += 1) {
+          array.push(this.decodeNext(abiType.type));
+        }
+        return array;
+      }
+      case 'struct': {
+        const struct: { [key: string]: AbiDecoded } = {};
+        if (isAztecAddressStruct(abiType)) {
+          return new AztecAddress(this.getNextField().toBuffer());
+        }
+
+        for (const field of abiType.fields) {
+          struct[field.name] = this.decodeNext(field.type);
+        }
+        return struct;
+      }
+      case 'string': {
+        const array = [];
+        for (let i = 0; i < abiType.length; i += 1) {
+          array.push(this.getNextField().toBigInt());
+        }
+        return array;
+      }
+      case 'tuple': {
+        const array = [];
+        for (const tupleAbiType of abiType.fields) {
+          array.push(this.decodeNext(tupleAbiType));
+        }
+        return array;
+      }
+      default:
+        throw new Error(`Unsupported type: ${abiType}`);
+    }
+  }
+
+  /**
+   * Gets the next field in the flattened buffer.
+   * @returns The next field in the flattened buffer.
+   */
+  private getNextField(): Fr {
+    const field = this.flattened.shift();
+    if (!field) {
+      throw new Error('Not enough return values');
+    }
+    return field;
+  }
+
+  /**
+   * Decodes all the values for the given ABI.
+   * The decided value can be simple types, structs or arrays
+   * @returns The decoded return values.
+   */
+  public decode(): AbiDecoded {
+    if (this.types.length > 1) {
+      throw new Error('Multiple types not supported');
+    }
+    if (this.types.length === 0) {
+      return [];
+    }
+    return this.decodeNext(this.types[0]);
+  }
+}
+
+/**
+ * Decodes values in a flattened Field array using a provided ABI.
+ * @param abi - The ABI to use as reference.
+ * @param buffer - The flattened Field array to decode.
+ * @returns
+ */
+export function decodeFromAbi(typ: AbiType[], buffer: Fr[]) {
+  return new AbiDecoder(typ, buffer.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,161 @@
+import { Fr } from '@aztec/foundation/fields';
+
+import type { 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);
+      case 'tuple':
+        return abiType.fields.reduce((acc, field) => acc + ArgumentEncoder.typeSize(field), 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 === 'string') {
+          this.flattened.push(Fr.fromString(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 if (typeof arg.value === 'string') {
+            this.flattened.push(Fr.fromHexString(arg.value));
+          } 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 type defines the encoding to noir, we use it
+        if (arg.encodeToNoir !== undefined) {
+          this.flattened.push(...arg.encodeToNoir());
+          break;
+        }
+
+        // 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':
+        if (typeof arg === 'string') {
+          const value = BigInt(arg);
+          this.flattened.push(new Fr(value));
+        } else {
+          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);
+}