@aztec/stdlib 0.0.0-test.1 → 0.0.1-commit.017a351

package/src/abi/abi.ts

@@ -1,13 +1,13 @@
 /* eslint-disable camelcase */
-import type { Fr } from '@aztec/foundation/fields';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import { createLogger } from '@aztec/foundation/log';
-import { type ZodFor, schemas } from '@aztec/foundation/schemas';
+import { schemas, zodFor } from '@aztec/foundation/schemas';
 
 import { inflate } from 'pako';
 import { z } from 'zod';
 
+import { DEV_VERSION } from '../update-checker/dev_version.js';
 import { FunctionSelector } from './function_selector.js';
-import { NoteSelector } from './note_selector.js';
 
 /** A basic value. */
 export interface BasicValue<T extends string, V> {
@@ -155,17 +155,19 @@ export type AbiErrorType =
   | { 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>;
+const AbiErrorTypeSchema = zodFor<AbiErrorType>()(
+  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),
+  ]),
+);
 
 /** Aztec.nr function types. */
 export enum FunctionType {
   PRIVATE = 'private',
   PUBLIC = 'public',
-  UNCONSTRAINED = 'unconstrained',
+  UTILITY = 'utility',
 }
 
 /** The abi entry of a function. */
@@ -174,8 +176,8 @@ export interface FunctionAbi {
   name: string;
   /** Whether the function is secret. */
   functionType: FunctionType;
-  /** Whether the function is internal. */
-  isInternal: boolean;
+  /** Whether the function is marked as `#[only_self]` and hence callable only from within the contract. */
+  isOnlySelf: boolean;
   /** Whether the function can alter state or not */
   isStatic: boolean;
   /** Function parameters. */
@@ -191,12 +193,12 @@ export interface FunctionAbi {
 export const FunctionAbiSchema = z.object({
   name: z.string(),
   functionType: z.nativeEnum(FunctionType),
-  isInternal: z.boolean(),
+  isOnlySelf: 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),
+  errorTypes: z.record(z.string(), AbiErrorTypeSchema.optional()),
 }) satisfies z.ZodType<FunctionAbi>;
 
 /** Debug metadata for a function. */
@@ -209,14 +211,28 @@ export interface FunctionDebugMetadata {
 
 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() }))),
-    ),
+    location_tree: z.object({
+      locations: z.array(
+        z.object({
+          parent: z.number().nullable(),
+          value: z.object({
+            span: z.object({ start: z.number(), end: z.number() }),
+            file: z.number(),
+          }),
+        }),
+      ),
+    }),
+    acir_locations: z.record(z.string(), z.number()),
+    brillig_locations: z.record(z.string(), z.record(z.string(), z.number())),
   }),
-  files: z.record(z.object({ source: z.string(), path: z.string() })),
+  files: z.record(
+    z.string(),
+    z.object({
+      source: z.string(),
+      path: z.string(),
+      function_locations: z.array(z.object({ start: z.number(), name: z.string() })),
+    }),
+  ),
 }) satisfies z.ZodType<FunctionDebugMetadata>;
 
 /** The artifact entry of a function. */
@@ -231,20 +247,27 @@ export interface FunctionArtifact extends FunctionAbi {
   debug?: FunctionDebugMetadata;
 }
 
-export const FunctionArtifactSchema = FunctionAbiSchema.and(
-  z.object({
-    bytecode: schemas.Buffer,
-    verificationKey: z.string().optional(),
-    debugSymbols: z.string(),
-    debug: FunctionDebugMetadataSchema.optional(),
-  }),
-) satisfies ZodFor<FunctionArtifact>;
+export interface FunctionArtifactWithContractName extends FunctionArtifact {
+  /** The name of the contract. */
+  contractName: string;
+}
+
+export const FunctionArtifactSchema = zodFor<FunctionArtifact>()(
+  FunctionAbiSchema.and(
+    z.object({
+      bytecode: schemas.Buffer,
+      verificationKey: z.string().optional(),
+      debugSymbols: z.string(),
+      debug: FunctionDebugMetadataSchema.optional(),
+    }),
+  ),
+);
 
 /** A file ID. It's assigned during compilation. */
-export type FileId = number;
+type FileId = number;
 
 /** A pointer to a specific section of the source code. */
-export interface SourceCodeLocation {
+interface SourceCodeLocation {
   /** The section of the source code. */
   span: {
     /** The byte where the section starts. */
@@ -264,12 +287,22 @@ export type OpcodeLocation = string;
 
 export type BrilligFunctionId = number;
 
-export type OpcodeToLocationsMap = Record<OpcodeLocation, SourceCodeLocation[]>;
+export type OpcodeToLocationsMap = Record<OpcodeLocation, number>;
+
+export type LocationNodeDebugInfo = {
+  parent: number | null;
+  value: SourceCodeLocation;
+};
+
+export type LocationTree = {
+  locations: LocationNodeDebugInfo[];
+};
 
 /** The debug information for a given function. */
 export interface DebugInfo {
   /** A map of the opcode location to the source code location. */
-  locations: OpcodeToLocationsMap;
+  location_tree: LocationTree;
+  acir_locations: OpcodeToLocationsMap;
   /** For each Brillig function, we have a map of the opcode location to the source code location. */
   brillig_locations: Record<BrilligFunctionId, OpcodeToLocationsMap>;
 }
@@ -280,6 +313,14 @@ export interface ProgramDebugInfo {
   debug_infos: Array<DebugInfo>;
 }
 
+/** The range a function occupies in a file. */
+export type FunctionLocation = {
+  /** The byte where the function starts. */
+  start: number;
+  /** The name of the function. */
+  name: string;
+};
+
 /** Maps a file ID to its metadata for debugging purposes. */
 export type DebugFileMap = Record<
   FileId,
@@ -288,58 +329,34 @@ export type DebugFileMap = Record<
     source: string;
     /** The path of the file. */
     path: string;
+    /** The range each function occupies in the file. */
+    function_locations: FunctionLocation[];
   }
 >;
 
-/** Type representing a field of a note (e.g. `amount` in `TokenNote`). */
-export type NoteField = {
-  /** Name of the field (e.g. `amount`). */
-  name: string;
-  /** Index where the note field starts in the serialized note array. */
-  index: number;
-  /** Whether the field can be unset when creating the note (in the partial notes flow). */
-  nullable: boolean;
-};
-
-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: NoteSelector.schema,
-  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: Fr;
 };
 
+/** Placeholder version injected into artifacts compiled before aztecVersion was added. TODO(F-557): Remove. */
+export const ARTIFACT_VERSION_BEFORE_INJECTION = 'FROM_RELEASE_BEFORE_VERSION_INJECTION';
+
 /** Defines artifact of a contract. */
 export interface ContractArtifact {
   /** The name of the contract. */
   name: string;
 
-  /** The version of compiler used to create this artifact */
-  aztecNrVersion?: string;
+  /** The version of the Aztec stack that compiled this artifact. */
+  aztecVersion: string;
 
-  /** The functions of the contract. */
+  /** The functions of the contract. Includes private and utility functions, plus the public dispatch function. */
   functions: FunctionArtifact[];
 
+  /** The public functions of the contract, excluding dispatch. */
+  nonDispatchPublicFunctions: FunctionAbi[];
+
   /** The outputs of the contract. */
   outputs: {
     structs: Record<string, AbiType[]>;
@@ -349,36 +366,42 @@ export interface ContractArtifact {
   /** Storage layout */
   storageLayout: Record<string, FieldLayout>;
 
-  /** The notes used in the contract. */
-  notes: Record<string, ContractNote>;
-
   /** The map of file ID to the source code and path of the file. */
   fileMap: DebugFileMap;
 }
 
-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)).transform(structs => {
-      for (const [key, value] of Object.entries(structs)) {
-        // We are manually ordering events and functions in the abi by path.
-        // The path ordering is arbitrary, and only needed to ensure deterministic order.
-        // These are the only arrays in the artifact with arbitrary order, and hence the only ones
-        // we need to sort.
-        if (key === 'events' || key === 'functions') {
-          structs[key] = (value as StructType[]).sort((a, b) => (a.path > b.path ? -1 : 1));
+export const ContractArtifactSchema = zodFor<ContractArtifact>()(
+  z.object({
+    name: z.string(),
+    aztecVersion: z.string().default(ARTIFACT_VERSION_BEFORE_INJECTION), // TODO(F-557): Remove default.
+    functions: z.array(FunctionArtifactSchema),
+    nonDispatchPublicFunctions: z.array(FunctionAbiSchema),
+    outputs: z.object({
+      structs: z.record(z.string(), z.array(AbiTypeSchema)).transform(structs => {
+        for (const [key, value] of Object.entries(structs)) {
+          // We are manually ordering events and functions in the abi by path.
+          // The path ordering is arbitrary, and only needed to ensure deterministic order.
+          // These are the only arrays in the artifact with arbitrary order, and hence the only ones
+          // we need to sort.
+          if (key === 'events' || key === 'functions') {
+            structs[key] = (value as StructType[]).sort((a, b) => (a.path > b.path ? -1 : 1));
+          }
         }
-      }
-      return structs;
+        return structs;
+      }),
+      globals: z.record(z.string(), z.array(AbiValueSchema)),
     }),
-    globals: z.record(z.array(AbiValueSchema)),
+    storageLayout: z.record(z.string(), z.object({ slot: schemas.Fr })),
+    fileMap: z.record(
+      z.coerce.number(),
+      z.object({
+        source: z.string(),
+        path: z.string(),
+        function_locations: z.array(z.object({ start: z.number(), name: z.string() })),
+      }),
+    ),
   }),
-  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() })),
-});
+);
 
 export function getFunctionArtifactByName(artifact: ContractArtifact, functionName: string): FunctionArtifact {
   const functionArtifact = artifact.functions.find(f => f.name === functionName);
@@ -395,28 +418,61 @@ export function getFunctionArtifactByName(artifact: ContractArtifact, functionNa
 export async function getFunctionArtifact(
   artifact: ContractArtifact,
   functionNameOrSelector: string | FunctionSelector,
-): Promise<FunctionArtifact> {
-  let functionArtifact;
-  if (typeof functionNameOrSelector === 'string') {
-    functionArtifact = artifact.functions.find(f => f.name === functionNameOrSelector);
-  } else {
-    const functionsAndSelectors = await Promise.all(
-      artifact.functions.map(async fn => ({
-        fn,
-        selector: await FunctionSelector.fromNameAndParameters(fn.name, fn.parameters),
-      })),
-    );
-    functionArtifact = functionsAndSelectors.find(fnAndSelector =>
-      functionNameOrSelector.equals(fnAndSelector.selector),
-    )?.fn;
-  }
+): Promise<FunctionArtifactWithContractName> {
+  const functionArtifact =
+    typeof functionNameOrSelector === 'string'
+      ? artifact.functions.find(f => f.name === functionNameOrSelector)
+      : await findFunctionArtifactBySelector(artifact, functionNameOrSelector);
   if (!functionArtifact) {
     throw new Error(`Unknown function ${functionNameOrSelector}`);
   }
 
   const debugMetadata = getFunctionDebugMetadata(artifact, functionArtifact);
 
-  return { ...functionArtifact, debug: debugMetadata };
+  return { ...functionArtifact, debug: debugMetadata, contractName: artifact.name };
+}
+
+/**
+ * Finds the function artifact within `artifact.functions` whose selector matches `selector`.
+ * Returns `undefined` if no match is found.
+ */
+export async function findFunctionArtifactBySelector(
+  artifact: ContractArtifact,
+  selector: FunctionSelector,
+): Promise<FunctionArtifact | undefined> {
+  const fnsAndSelectors = await Promise.all(
+    artifact.functions.map(async fn => ({
+      fn,
+      selector: await FunctionSelector.fromNameAndParameters(fn.name, fn.parameters),
+    })),
+  );
+  return fnsAndSelectors.find(({ selector: s }) => s.equals(selector))?.fn;
+}
+
+/**
+ * Finds the function abi (across both `functions` and `nonDispatchPublicFunctions`) whose selector
+ * matches `selector`. Returns `undefined` if no match is found.
+ */
+export async function findFunctionAbiBySelector(
+  artifact: ContractArtifact,
+  selector: FunctionSelector,
+): Promise<FunctionAbi | undefined> {
+  const fnsAndSelectors = await Promise.all(
+    getAllFunctionAbis(artifact).map(async fn => ({
+      fn,
+      selector: await FunctionSelector.fromNameAndParameters(fn.name, fn.parameters),
+    })),
+  );
+  return fnsAndSelectors.find(({ selector: s }) => s.equals(selector))?.fn;
+}
+
+/** Gets all function abis */
+export function getAllFunctionAbis(artifact: ContractArtifact): FunctionAbi[] {
+  return artifact.functions.map(f => f as FunctionAbi).concat(artifact.nonDispatchPublicFunctions || []);
+}
+
+export function parseDebugSymbols(debugSymbols: string): DebugInfo[] {
+  return JSON.parse(inflate(Buffer.from(debugSymbols, 'base64'), { to: 'string', raw: true })).debug_infos;
 }
 
 /**
@@ -432,14 +488,12 @@ export function getFunctionDebugMetadata(
   try {
     if (functionArtifact.debugSymbols && contractArtifact.fileMap) {
       // TODO(https://github.com/AztecProtocol/aztec-packages/issues/10546) investigate why debugMetadata is so big for some tests.
-      const programDebugSymbols = JSON.parse(
-        inflate(Buffer.from(functionArtifact.debugSymbols, 'base64'), { to: 'string', raw: true }),
-      );
+      const programDebugSymbols = parseDebugSymbols(functionArtifact.debugSymbols);
       // TODO(https://github.com/AztecProtocol/aztec-packages/issues/5813)
       // We only support handling debug info for the contract function entry point.
       // So for now we simply index into the first debug info.
       return {
-        debugSymbols: programDebugSymbols.debug_infos[0],
+        debugSymbols: programDebugSymbols[0],
         files: contractArtifact.fileMap,
       };
     }
@@ -465,14 +519,15 @@ export function getFunctionDebugMetadata(
  * @param contractArtifact - The contract artifact.
  * @returns An initializer function, or none if there are no functions flagged as initializers in the contract.
  */
-export function getDefaultInitializer(contractArtifact: ContractArtifact): FunctionArtifact | undefined {
-  const initializers = contractArtifact.functions.filter(f => f.isInitializer);
+export function getDefaultInitializer(contractArtifact: ContractArtifact): FunctionAbi | undefined {
+  const functionAbis = getAllFunctionAbis(contractArtifact);
+  const initializers = functionAbis.filter(f => f.isInitializer);
   return initializers.length > 1
-    ? initializers.find(f => f.name === 'constructor') ??
+    ? (initializers.find(f => f.name === 'constructor') ??
         initializers.find(f => f.name === 'initializer') ??
         initializers.find(f => f.parameters?.length === 0) ??
         initializers.find(f => f.functionType === FunctionType.PRIVATE) ??
-        initializers[0]
+        initializers[0])
     : initializers[0];
 }
 
@@ -484,9 +539,10 @@ export function getDefaultInitializer(contractArtifact: ContractArtifact): Funct
 export function getInitializer(
   contract: ContractArtifact,
   initializerNameOrArtifact: string | undefined | FunctionArtifact,
-): FunctionArtifact | undefined {
+): FunctionAbi | undefined {
   if (typeof initializerNameOrArtifact === 'string') {
-    const found = contract.functions.find(f => f.name === initializerNameOrArtifact);
+    const functionAbis = getAllFunctionAbis(contract);
+    const found = functionAbis.find(f => f.name === initializerNameOrArtifact);
     if (!found) {
       throw new Error(`Constructor method ${initializerNameOrArtifact} not found in contract artifact`);
     } else if (!found.isInitializer) {
@@ -502,3 +558,40 @@ export function getInitializer(
     return initializerNameOrArtifact;
   }
 }
+
+export function emptyFunctionAbi(): FunctionAbi {
+  return {
+    name: '',
+    functionType: FunctionType.PRIVATE,
+    isOnlySelf: false,
+    isStatic: false,
+    parameters: [],
+    returnTypes: [],
+    errorTypes: {},
+    isInitializer: false,
+  };
+}
+
+export function emptyFunctionArtifact(): FunctionArtifact {
+  const abi = emptyFunctionAbi();
+  return {
+    ...abi,
+    bytecode: Buffer.from([]),
+    debugSymbols: '',
+  };
+}
+
+export function emptyContractArtifact(): ContractArtifact {
+  return {
+    name: '',
+    aztecVersion: DEV_VERSION,
+    functions: [emptyFunctionArtifact()],
+    nonDispatchPublicFunctions: [emptyFunctionAbi()],
+    outputs: {
+      structs: {},
+      globals: {},
+    },
+    storageLayout: {},
+    fileMap: {},
+  };
+}

package/src/abi/authorization_selector.ts

@@ -0,0 +1,90 @@
+import { fromHex, toBigIntBE } from '@aztec/foundation/bigint-buffer';
+import { poseidon2HashBytes } from '@aztec/foundation/crypto/poseidon';
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import { hexSchemaFor } from '@aztec/foundation/schemas';
+import { BufferReader } from '@aztec/foundation/serialize';
+
+import { Selector } from './selector.js';
+
+/**
+ * An authorization selector is the first 4 bytes of the hash of an authorization struct signature.
+ */
+export class AuthorizationSelector extends Selector {
+  /** Branding for nominal typing. */
+  declare private readonly _branding: 'AuthorizationSelector';
+  /**
+   * 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 AuthorizationSelector(value);
+  }
+
+  /**
+   * Converts a field to selector.
+   * @param fr - The field to convert.
+   * @returns The selector.
+   */
+  static fromField(fr: Fr) {
+    return new AuthorizationSelector(Number(fr.toBigInt()));
+  }
+
+  /**
+   * Creates a selector from a signature.
+   * @param signature - Signature to generate the selector for (e.g. "CallAuthorization(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 AuthorizationSelector.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 AuthorizationSelector length ${buf.length} (expected ${Selector.SIZE}).`);
+    }
+    return AuthorizationSelector.fromBuffer(buf);
+  }
+
+  /**
+   * Creates an empty selector.
+   * @returns An empty selector.
+   */
+  static empty() {
+    return new AuthorizationSelector(0);
+  }
+
+  /**
+   * Creates a random selector.
+   * @returns A random selector.
+   */
+  static random() {
+    return AuthorizationSelector.fromBuffer(randomBytes(Selector.SIZE));
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  static get schema() {
+    return hexSchemaFor(AuthorizationSelector);
+  }
+}

package/src/abi/buffer.ts

@@ -1,4 +1,4 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 
 import chunk from 'lodash.chunk';
 
@@ -26,11 +26,32 @@ export function bufferAsFields(input: Buffer, targetLength: number): Fr[] {
 }
 
 /**
- * Recovers a buffer from an array of fields.
- * @param fields - An output from bufferAsFields.
- * @returns The recovered buffer.
+ * Recovers a buffer from an array of fields previously encoded with bufferAsFields.
+ *
+ * The first field encodes the byte length of the original buffer. The remaining fields
+ * each carry 31 bytes of payload (the leading byte of each 32-byte field element is skipped).
+ *
+ * If the declared byte length exceeds the bytes available from the payload fields, the result
+ * is zero-padded to the full declared length. This is important for correctness when the field
+ * array has been truncated (e.g. contract class logs reconstructed from blobs using a short
+ * emittedLength): without padding, the resulting buffer would be shorter than declared, causing
+ * bytecode commitment computations to diverge from what the circuit produced.
+ *
+ * @param fields - An output from bufferAsFields: [byteLength, ...payloadFields].
+ * @returns A buffer of exactly `byteLength` bytes.
  */
 export function bufferFromFields(fields: Fr[]): Buffer {
   const [length, ...payload] = fields;
-  return Buffer.concat(payload.map(f => f.toBuffer().subarray(1))).subarray(0, length.toNumber());
+  const byteLength = length.toNumber();
+  const raw = Buffer.concat(payload.map(f => f.toBuffer().subarray(1)));
+  if (raw.length >= byteLength) {
+    return raw.subarray(0, byteLength);
+  }
+  // Pad with zeros if the declared length exceeds the available payload bytes.
+  // This ensures the returned buffer always matches the declared length, so that
+  // downstream bytecode commitment computations are consistent even when the
+  // source field array was truncated (e.g. reconstructed from blob with a short emittedLength).
+  const result = Buffer.alloc(byteLength);
+  raw.copy(result);
+  return result;
 }