@aztec/foundation 0.61.0 → 0.63.0

package/src/abi/abi.ts

@@ -1,23 +1,21 @@
+/* eslint-disable camelcase */
 import { inflate } from 'pako';
+import { z } from 'zod';
 
 import { type Fr } from '../fields/fields.js';
+import { schemas } from '../schemas/schemas.js';
+import { type ZodFor } from '../schemas/types.js';
 import { type FunctionSelector } from './function_selector.js';
 import { type NoteSelector } from './note_selector.js';
 
-/**
- * A basic value.
- */
+/** A basic value. */
 export interface BasicValue<T extends string, V> {
-  /**
-   * The kind of the value.
-   */
+  /** The kind of the value. */
   kind: T;
   value: V;
 }
 
-/**
- * An exported value.
- */
+/** An exported value. */
 export type AbiValue =
   | BasicValue<'boolean', boolean>
   | BasicValue<'string', string>
@@ -26,6 +24,18 @@ export type AbiValue =
   | IntegerValue
   | StructValue;
 
+export const AbiValueSchema: z.ZodType<AbiValue> = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('boolean'), value: z.boolean() }),
+  z.object({ kind: z.literal('string'), value: z.string() }),
+  z.object({ kind: z.literal('array'), value: z.array(z.lazy(() => AbiValueSchema)) }),
+  z.object({ kind: z.literal('tuple'), fields: z.array(z.lazy(() => AbiValueSchema)) }),
+  z.object({ kind: z.literal('integer'), value: z.string(), sign: z.boolean() }),
+  z.object({
+    kind: z.literal('struct'),
+    fields: z.array(z.object({ name: z.string(), value: z.lazy(() => AbiValueSchema) })),
+  }),
+]);
+
 export type TypedStructFieldValue<T> = { name: string; value: T };
 
 export interface StructValue {
@@ -42,48 +52,23 @@ export interface IntegerValue extends BasicValue<'integer', string> {
   sign: boolean;
 }
 
-/**
- * A named type.
- */
-export interface ABIVariable {
-  /**
-   * The name of the variable.
-   */
-  name: string;
-  /**
-   * The type of the variable.
-   */
-  type: AbiType;
-}
+/** Indicates whether a parameter is public or secret/private. */
+export const ABIParameterVisibility = ['public', 'private', 'databus'] as const;
 
-/**
- * Indicates whether a parameter is public or secret/private.
- */
-export type ABIParameterVisibility = 'public' | 'private' | 'databus';
+/** Indicates whether a parameter is public or secret/private. */
+export type ABIParameterVisibility = (typeof ABIParameterVisibility)[number];
 
-/**
- * A function parameter.
- */
-export interface ABIParameter extends ABIVariable {
-  /**
-   * Indicates whether a parameter is public or secret/private.
-   */
-  visibility: ABIParameterVisibility;
-}
-
-/**
- * A basic type.
- */
+/** A basic type. */
 export interface BasicType<T extends string> {
-  /**
-   * The kind of the type.
-   */
+  /** The kind of the type. */
   kind: T;
 }
 
-/**
- * A variable type.
- */
+/** Sign for numeric types. */
+const Sign = ['unsigned', 'signed'] as const;
+type Sign = (typeof Sign)[number];
+
+/** A variable type. */
 export type AbiType =
   | BasicType<'field'>
   | BasicType<'boolean'>
@@ -93,156 +78,178 @@ export type AbiType =
   | StructType
   | TupleType;
 
-type Sign = 'unsigned' | 'signed';
-
-/**
- * An integer type.
- */
+export const AbiTypeSchema: z.ZodType<AbiType> = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('field') }),
+  z.object({ kind: z.literal('boolean') }),
+  z.object({ kind: z.literal('integer'), sign: z.enum(Sign), width: z.number() }),
+  z.object({ kind: z.literal('array'), length: z.number(), type: z.lazy(() => AbiTypeSchema) }),
+  z.object({ kind: z.literal('string'), length: z.number() }),
+  z.object({ kind: z.literal('struct'), fields: z.array(z.lazy(() => ABIVariableSchema)), path: z.string() }),
+  z.object({ kind: z.literal('tuple'), fields: z.array(z.lazy(() => AbiTypeSchema)) }),
+]);
+
+/** A named type. */
+export const ABIVariableSchema = z.object({
+  /** The name of the variable. */
+  name: z.string(),
+  /** The type of the variable. */
+  type: AbiTypeSchema,
+});
+
+/** A named type. */
+export type ABIVariable = z.infer<typeof ABIVariableSchema>;
+
+/** A function parameter. */
+export const ABIParameterSchema = ABIVariableSchema.and(
+  z.object({
+    /** Visibility of the parameter in the function. */
+    visibility: z.enum(ABIParameterVisibility),
+  }),
+);
+
+/** A function parameter. */
+export type ABIParameter = z.infer<typeof ABIParameterSchema>;
+
+/** An integer type. */
 export interface IntegerType extends BasicType<'integer'> {
-  /**
-   * The sign of the integer.
-   */
+  /** The sign of the integer. */
   sign: Sign;
-  /**
-   * The width of the integer in bits.
-   */
+  /** The width of the integer in bits. */
   width: number;
 }
 
-/**
- * An array type.
- */
+/** An array type. */
 export interface ArrayType extends BasicType<'array'> {
-  /**
-   * The length of the array.
-   */
+  /** The length of the array. */
   length: number;
-  /**
-   * The type of the array elements.
-   */
+  /** The type of the array elements. */
   type: AbiType;
 }
 
-/**
- * A tuple type.
- */
+/** A tuple type. */
 export interface TupleType extends BasicType<'tuple'> {
-  /**
-   * The types of the tuple elements.
-   */
+  /** The types of the tuple elements. */
   fields: AbiType[];
 }
 
-/**
- * A string type.
- */
+/** A string type. */
 export interface StringType extends BasicType<'string'> {
-  /**
-   * The length of the string.
-   */
+  /** The length of the string. */
   length: number;
 }
 
-/**
- * A struct type.
- */
+/** A struct type. */
 export interface StructType extends BasicType<'struct'> {
-  /**
-   * The fields of the struct.
-   */
+  /** The fields of the struct. */
   fields: ABIVariable[];
-  /**
-   * Fully qualified name of the struct.
-   */
+  /** Fully qualified name of the struct. */
   path: string;
 }
 
-/**
- * Aztec.nr function types.
- */
+/** An error could be a custom error of any regular type or a string error. */
+export type AbiErrorType =
+  | { error_kind: 'string'; string: string }
+  | { error_kind: 'fmtstring'; length: number; item_types: AbiType[] }
+  | ({ error_kind: 'custom' } & AbiType);
+
+const AbiErrorTypeSchema = z.union([
+  z.object({ error_kind: z.literal('string'), string: z.string() }),
+  z.object({ error_kind: z.literal('fmtstring'), length: z.number(), item_types: z.array(AbiTypeSchema) }),
+  z.object({ error_kind: z.literal('custom') }).and(AbiTypeSchema),
+]) satisfies ZodFor<AbiErrorType>;
+
+/** Aztec.nr function types. */
 export enum FunctionType {
   PRIVATE = 'private',
   PUBLIC = 'public',
   UNCONSTRAINED = 'unconstrained',
 }
 
-/**
- * The abi entry of a function.
- */
+/** The abi entry of a function. */
 export interface FunctionAbi {
-  /**
-   * The name of the function.
-   */
+  /** The name of the function. */
   name: string;
-  /**
-   * Whether the function is secret.
-   */
+  /** Whether the function is secret. */
   functionType: FunctionType;
-  /**
-   * Whether the function is internal.
-   */
+  /** Whether the function is internal. */
   isInternal: boolean;
-  /**
-   * Whether the function can alter state or not
-   */
+  /** Whether the function can alter state or not */
   isStatic: boolean;
-  /**
-   * Function parameters.
-   */
+  /** Function parameters. */
   parameters: ABIParameter[];
-  /**
-   * The types of the return values.
-   */
+  /** The types of the return values. */
   returnTypes: AbiType[];
-  /**
-   * Whether the function is flagged as an initializer.
-   */
+  /** The types of the errors that the function can throw. */
+  errorTypes: Partial<Record<string, AbiErrorType>>;
+  /** Whether the function is flagged as an initializer. */
   isInitializer: boolean;
 }
 
-/**
- * The artifact entry of a function.
- */
+export const FunctionAbiSchema = z.object({
+  name: z.string(),
+  functionType: z.nativeEnum(FunctionType),
+  isInternal: z.boolean(),
+  isStatic: z.boolean(),
+  isInitializer: z.boolean(),
+  parameters: z.array(z.object({ name: z.string(), type: AbiTypeSchema, visibility: z.enum(ABIParameterVisibility) })),
+  returnTypes: z.array(AbiTypeSchema),
+  errorTypes: z.record(AbiErrorTypeSchema),
+}) satisfies z.ZodType<FunctionAbi>;
+
+/** Debug metadata for a function. */
+export interface FunctionDebugMetadata {
+  /** Maps opcodes to source code pointers */
+  debugSymbols: DebugInfo;
+  /** Maps the file IDs to the file contents to resolve pointers */
+  files: DebugFileMap;
+}
+
+export const FunctionDebugMetadataSchema = z.object({
+  debugSymbols: z.object({
+    locations: z.record(
+      z.array(z.object({ span: z.object({ start: z.number(), end: z.number() }), file: z.number() })),
+    ),
+    brillig_locations: z.record(
+      z.record(z.array(z.object({ span: z.object({ start: z.number(), end: z.number() }), file: z.number() }))),
+    ),
+  }),
+  files: z.record(z.object({ source: z.string(), path: z.string() })),
+}) satisfies z.ZodType<FunctionDebugMetadata>;
+
+/** The artifact entry of a function. */
 export interface FunctionArtifact extends FunctionAbi {
   /** The ACIR bytecode of the function. */
   bytecode: Buffer;
-  /** The verification key of the function. */
+  /** The verification key of the function, base64 encoded, if it's a private fn. */
   verificationKey?: string;
   /** Maps opcodes to source code pointers */
   debugSymbols: string;
-  /**
-   * Public functions store their static assertion messages externally to the bytecode.
-   */
-  assertMessages?: Record<number, string>;
   /** Debug metadata for the function. */
   debug?: FunctionDebugMetadata;
 }
 
-/**
- * A file ID. It's assigned during compilation.
- */
+export const FunctionArtifactSchema = FunctionAbiSchema.and(
+  z.object({
+    bytecode: schemas.BufferB64,
+    verificationKey: z.string().optional(),
+    debugSymbols: z.string(),
+    debug: FunctionDebugMetadataSchema.optional(),
+  }),
+) satisfies ZodFor<FunctionArtifact>;
+
+/** A file ID. It's assigned during compilation. */
 export type FileId = number;
 
-/**
- * A pointer to a specific section of the source code.
- */
+/** A pointer to a specific section of the source code. */
 export interface SourceCodeLocation {
-  /**
-   * The section of the source code.
-   */
+  /** The section of the source code. */
   span: {
-    /**
-     * The byte where the section starts.
-     */
+    /** The byte where the section starts. */
     start: number;
-    /**
-     * The byte where the section ends.
-     */
+    /** The byte where the section ends. */
     end: number;
   };
-  /**
-   * The source code file pointed to.
-   */
+  /** The source code file pointed to. */
   file: FileId;
 }
 
@@ -256,65 +263,31 @@ export type BrilligFunctionId = number;
 
 export type OpcodeToLocationsMap = Record<OpcodeLocation, SourceCodeLocation[]>;
 
-/**
- * The debug information for a given function.
- */
+/** The debug information for a given function. */
 export interface DebugInfo {
-  /**
-   * A map of the opcode location to the source code location.
-   */
+  /** A map of the opcode location to the source code location. */
   locations: OpcodeToLocationsMap;
-  /**
-   * For each Brillig function, we have a map of the opcode location to the source code location.
-   */
+  /** For each Brillig function, we have a map of the opcode location to the source code location. */
   brillig_locations: Record<BrilligFunctionId, OpcodeToLocationsMap>;
 }
 
-/**
- * The debug information for a given program (a collection of functions)
- */
+/** The debug information for a given program (a collection of functions) */
 export interface ProgramDebugInfo {
-  /**
-   * A list of debug information that matches with each function in a program
-   */
+  /** A list of debug information that matches with each function in a program */
   debug_infos: Array<DebugInfo>;
 }
 
-/**
- * Maps a file ID to its metadata for debugging purposes.
- */
+/** Maps a file ID to its metadata for debugging purposes. */
 export type DebugFileMap = Record<
   FileId,
   {
-    /**
-     * The source code of the file.
-     */
+    /** The source code of the file. */
     source: string;
-    /**
-     * The path of the file.
-     */
+    /** The path of the file. */
     path: string;
   }
 >;
 
-/**
- * Type representing a note in use in the contract.
- */
-export type ContractNote = {
-  /**
-   * Note identifier
-   */
-  id: NoteSelector;
-  /**
-   * Type of the note (e.g., 'TransparentNote')
-   */
-  typ: string;
-  /**
-   * Fields of the note.
-   */
-  fields: NoteField[];
-};
-
 /** Type representing a field of a note (e.g. `amount` in `TokenNote`). */
 export type NoteField = {
   /** Name of the field (e.g. `amount`). */
@@ -325,77 +298,75 @@ export type NoteField = {
   nullable: boolean;
 };
 
-/**
- * Type representing a field layout in the storage of a contract.
- */
+export const NoteFieldSchema = z.object({
+  name: z.string(),
+  index: z.number(),
+  nullable: z.boolean(),
+}) satisfies z.ZodType<NoteField>;
+
+/** Type representing a note in use in the contract. */
+export type ContractNote = {
+  /** Note identifier */
+  id: NoteSelector;
+  /** Type of the note (e.g., 'TransparentNote') */
+  typ: string;
+  /** Fields of the note. */
+  fields: NoteField[];
+};
+
+export const ContractNoteSchema = z.object({
+  id: schemas.NoteSelector,
+  typ: z.string(),
+  fields: z.array(NoteFieldSchema),
+}) satisfies ZodFor<ContractNote>;
+
+/** Type representing a field layout in the storage of a contract. */
 export type FieldLayout = {
-  /**
-   * Slot in which the field is stored.
-   */
+  /** Slot in which the field is stored. */
   slot: Fr;
 };
 
-/**
- * Defines artifact of a contract.
- */
+/** Defines artifact of a contract. */
 export interface ContractArtifact {
-  /**
-   * The name of the contract.
-   */
+  /** The name of the contract. */
   name: string;
 
-  /**
-   * The version of compiler used to create this artifact
-   */
+  /** The version of compiler used to create this artifact */
   aztecNrVersion?: string;
 
-  /**
-   * The functions of the contract.
-   */
+  /** The functions of the contract. */
   functions: FunctionArtifact[];
-  /**
-   * The outputs of the contract.
-   */
+
+  /** The outputs of the contract. */
   outputs: {
     structs: Record<string, AbiType[]>;
     globals: Record<string, AbiValue[]>;
   };
-  /**
-   * Storage layout
-   */
+
+  /** Storage layout */
   storageLayout: Record<string, FieldLayout>;
-  /**
-   * The notes used in the contract.
-   */
+
+  /** The notes used in the contract. */
   notes: Record<string, ContractNote>;
 
-  /**
-   * The map of file ID to the source code and path of the file.
-   */
+  /** The map of file ID to the source code and path of the file. */
   fileMap: DebugFileMap;
 }
 
-/**
- * Debug metadata for a function.
- */
-export interface FunctionDebugMetadata {
-  /**
-   * Maps opcodes to source code pointers
-   */
-  debugSymbols: DebugInfo;
-  /**
-   * Maps the file IDs to the file contents to resolve pointers
-   */
-  files: DebugFileMap;
-  /**
-   * Public functions store their static assertion messages externally to the bytecode.
-   */
-  assertMessages?: Record<number, string>;
-}
-
-/**
- * Gets a function artifact including debug metadata given its name or selector.
- */
+export const ContractArtifactSchema: ZodFor<ContractArtifact> = z.object({
+  name: z.string(),
+  aztecNrVersion: z.string().optional(),
+  functions: z.array(FunctionArtifactSchema),
+  outputs: z.object({
+    structs: z.record(z.array(AbiTypeSchema)),
+    globals: z.record(z.array(AbiValueSchema)),
+  }),
+  storageLayout: z.record(z.object({ slot: schemas.Fr })),
+  notes: z.record(ContractNoteSchema),
+  fileMap: z.record(z.coerce.number(), z.object({ source: z.string(), path: z.string() })),
+});
+
+/** Gets a function artifact including debug metadata given its name or selector. */
 export function getFunctionArtifact(
   artifact: ContractArtifact,
   functionNameOrSelector: string | FunctionSelector,
@@ -432,7 +403,6 @@ export function getFunctionDebugMetadata(
     return {
       debugSymbols: programDebugSymbols.debug_infos[0],
       files: contractArtifact.fileMap,
-      assertMessages: functionArtifact.assertMessages,
     };
   }
   return undefined;

package/src/abi/decoder.ts

@@ -1,7 +1,7 @@
 import { AztecAddress } from '../aztec-address/index.js';
 import { type Fr } from '../fields/index.js';
 import { type ABIParameter, type ABIVariable, type AbiType } from './abi.js';
-import { isAztecAddressStruct } from './utils.js';
+import { isAztecAddressStruct, parseSignedInt } from './utils.js';
 
 /**
  * The type of our decoded ABI.
@@ -10,7 +10,6 @@ export type AbiDecoded = bigint | boolean | AztecAddress | AbiDecoded[] | { [key
 
 /**
  * Decodes values using a provided ABI.
- * Missing support for signed integer.
  */
 class AbiDecoder {
   constructor(private types: AbiType[], private flattened: Fr[]) {}
@@ -24,11 +23,16 @@ class AbiDecoder {
     switch (abiType.kind) {
       case 'field':
         return this.getNextField().toBigInt();
-      case 'integer':
+      case 'integer': {
+        const nextField = this.getNextField();
+
         if (abiType.sign === 'signed') {
-          throw new Error('Unsupported type: signed integer');
+          // We parse the buffer using 2's complement
+          return parseSignedInt(nextField.toBuffer(), abiType.width);
         }
-        return this.getNextField().toBigInt();
+
+        return nextField.toBigInt();
+      }
       case 'boolean':
         return !this.getNextField().isZero();
       case 'array': {

package/src/abi/encoder.ts

@@ -57,6 +57,8 @@ class ArgumentEncoder {
             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.fromString(arg.value));
           } else {
             throw new Error(`Argument for ${name} cannot be serialized to a field`);
           }

package/src/abi/event_selector.ts

@@ -81,4 +81,11 @@ export class EventSelector extends Selector {
   static random() {
     return EventSelector.fromBuffer(randomBytes(Selector.SIZE));
   }
+
+  toJSON() {
+    return {
+      type: 'EventSelector',
+      value: this.toString(),
+    };
+  }
 }

package/src/abi/utils.ts

@@ -48,3 +48,31 @@ export function isWrappedFieldStruct(abiType: AbiType) {
     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')}`);
+}