@aztec/stdlib 0.0.1-commit.5476d83 → 0.0.1-commit.5914bae

package/src/abi/abi.ts

@@ -1,7 +1,7 @@
 /* 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';
@@ -154,11 +154,13 @@ 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 {
@@ -222,7 +224,20 @@ export const FunctionDebugMetadataSchema = z.object({
     acir_locations: z.record(z.number()),
     brillig_locations: z.record(z.record(z.number())),
   }),
-  files: z.record(z.object({ source: z.string(), path: z.string() })),
+  // `function_locations` is required in the static `DebugFileMap` type (noir-types compat), but legacy v4-next
+  // artifacts were compiled before this field existed — see {@link fillMissingFunctionLocations} for the full
+  // rationale. The preprocessor injects `[]` for missing entries so parsing succeeds; the cast restores the
+  // output type since `z.preprocess` widens the schema's input type to `unknown`.
+  files: z.preprocess(
+    fillMissingFunctionLocations,
+    z.record(
+      z.object({
+        source: z.string(),
+        path: z.string(),
+        function_locations: z.array(z.object({ start: z.number(), name: z.string() })),
+      }),
+    ),
+  ) as z.ZodType<DebugFileMap>,
 }) satisfies z.ZodType<FunctionDebugMetadata>;
 
 /** The artifact entry of a function. */
@@ -242,14 +257,16 @@ export interface FunctionArtifactWithContractName extends FunctionArtifact {
   contractName: string;
 }
 
-export const FunctionArtifactSchema = FunctionAbiSchema.and(
-  z.object({
-    bytecode: schemas.Buffer,
-    verificationKey: z.string().optional(),
-    debugSymbols: z.string(),
-    debug: FunctionDebugMetadataSchema.optional(),
-  }),
-) satisfies ZodFor<FunctionArtifact>;
+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. */
 type FileId = number;
@@ -301,6 +318,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,
@@ -309,9 +334,50 @@ export type DebugFileMap = Record<
     source: string;
     /** The path of the file. */
     path: string;
+    /** The range each function occupies in the file. */
+    function_locations: FunctionLocation[];
   }
 >;
 
+/**
+ * Preprocessor for {@link FunctionDebugMetadataSchema} / {@link ContractArtifactSchema} that injects an empty
+ * `function_locations` array on any file map entry missing it. Invoked via `z.preprocess(...)` before the strict
+ * object schema runs, so legacy inputs do not fail validation.
+ *
+ * Why this exists on v4-next (and not on `next` / v5):
+ *
+ *   - The Noir submodule on `next` was bumped past nightly-2026-03-19, which added `function_locations` to the
+ *     debug file map in the Noir `@aztec/noir-types` package and to every freshly-compiled artifact's `file_map`
+ *     entries. The matching stdlib change (making `DebugFileMap.function_locations` required) was done in one
+ *     go on `next`, so there `function_locations` is always present both at compile time and at runtime.
+ *
+ *   - On v4-next we had to cherry-pick the Noir bump (chore: Update Noir to nightly-2026-04-10 (#22393)) without
+ *     re-running the full noir-projects compilation pipeline, so the on-disk contract and protocol-circuit
+ *     artifacts (e.g. `yarn-project/protocol-contracts/artifacts/AuthRegistry.json`) still carry the pre-update
+ *     `file_map` shape with only `source` + `path`. Separately, `ivc-integration` compares our `DebugFileMap`
+ *     against the Noir-types `DebugFileMap`, which *does* require `function_locations`, so we cannot simply make
+ *     our own field optional — that would break the structural compatibility check.
+ *
+ *   - To satisfy both constraints at once we keep `function_locations` required in the static TypeScript type
+ *     (so `ivc-integration` keeps compiling) but relax the runtime input shape via this preprocessor (so legacy
+ *     artifacts keep parsing). Once all v4-next artifacts get regenerated with the new Noir compiler, this
+ *     helper — and both `z.preprocess(...)` wrappers — can be removed.
+ */
+function fillMissingFunctionLocations(val: unknown): unknown {
+  if (val && typeof val === 'object') {
+    for (const entry of Object.values(val as Record<string, unknown>)) {
+      if (
+        entry &&
+        typeof entry === 'object' &&
+        (entry as { function_locations?: unknown }).function_locations === undefined
+      ) {
+        (entry as { function_locations: FunctionLocation[] }).function_locations = [];
+      }
+    }
+  }
+  return val;
+}
+
 /** Type representing a field layout in the storage of a contract. */
 export type FieldLayout = {
   /** Slot in which the field is stored. */
@@ -342,28 +408,44 @@ export interface ContractArtifact {
   fileMap: DebugFileMap;
 }
 
-export const ContractArtifactSchema: ZodFor<ContractArtifact> = z.object({
-  name: z.string(),
-  functions: z.array(FunctionArtifactSchema),
-  nonDispatchPublicFunctions: z.array(FunctionAbiSchema),
-  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(),
+    functions: z.array(FunctionArtifactSchema),
+    nonDispatchPublicFunctions: z.array(FunctionAbiSchema),
+    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));
+          }
         }
-      }
-      return structs;
+        return structs;
+      }),
+      globals: z.record(z.array(AbiValueSchema)),
     }),
-    globals: z.record(z.array(AbiValueSchema)),
+    storageLayout: z.record(z.object({ slot: schemas.Fr })),
+    // Legacy v4-next contract artifacts (e.g. `protocol-contracts/artifacts/AuthRegistry.json`) were emitted
+    // before Noir started including `function_locations` in their `file_map` entries — see
+    // {@link fillMissingFunctionLocations} for the full rationale. The preprocessor injects `[]` for missing
+    // entries so parsing succeeds without weakening the static `DebugFileMap` type.
+    fileMap: z.preprocess(
+      fillMissingFunctionLocations,
+      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 })),
-  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);

package/src/abi/authorization_selector.ts

@@ -1,6 +1,7 @@
 import { fromHex, toBigIntBE } from '@aztec/foundation/bigint-buffer';
-import { poseidon2HashBytes, randomBytes } from '@aztec/foundation/crypto';
-import type { Fr } from '@aztec/foundation/fields';
+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';
 

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;
 }

package/src/abi/contract_artifact.ts

@@ -1,5 +1,14 @@
 import { jsonParseWithSchema, jsonStringify } from '@aztec/foundation/json-rpc';
 
+import {
+  AZTEC_INITIALIZER_ATTRIBUTE,
+  AZTEC_ONLY_SELF_ATTRIBUTE,
+  AZTEC_PRIVATE_ATTRIBUTE,
+  AZTEC_PUBLIC_ATTRIBUTE,
+  AZTEC_UTILITY_ATTRIBUTE,
+  AZTEC_VIEW_ATTRIBUTE,
+  type NoirCompiledContract,
+} from '../noir/index.js';
 import {
   type ABIParameter,
   type ABIParameterVisibility,
@@ -14,16 +23,7 @@ import {
   type IntegerValue,
   type StructValue,
   type TypedStructFieldValue,
-} from '../abi/index.js';
-import {
-  AZTEC_INITIALIZER_ATTRIBUTE,
-  AZTEC_ONLY_SELF_ATTRIBUTE,
-  AZTEC_PRIVATE_ATTRIBUTE,
-  AZTEC_PUBLIC_ATTRIBUTE,
-  AZTEC_UTILITY_ATTRIBUTE,
-  AZTEC_VIEW_ATTRIBUTE,
-  type NoirCompiledContract,
-} from '../noir/index.js';
+} from './abi.js';
 
 /**
  * Serializes a contract artifact to a buffer for storage.

package/src/abi/decoder.ts

@@ -1,13 +1,32 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
+import { EthAddress } from '@aztec/foundation/eth-address';
 
 import { AztecAddress } from '../aztec-address/index.js';
-import type { ABIParameter, ABIVariable, AbiType } from './abi.js';
-import { isAztecAddressStruct, parseSignedInt } from './utils.js';
+import type { AbiType } from './abi.js';
+import { FunctionSelector } from './function_selector.js';
+import {
+  isAztecAddressStruct,
+  isEthAddressStruct,
+  isFunctionSelectorStruct,
+  isOptionStruct,
+  isWrappedFieldStruct,
+  parseSignedInt,
+} from './utils.js';
 
 /**
  * The type of our decoded ABI.
  */
-export type AbiDecoded = bigint | boolean | string | AztecAddress | AbiDecoded[] | { [key: string]: AbiDecoded };
+export type AbiDecoded =
+  | bigint
+  | boolean
+  | string
+  | AztecAddress
+  | EthAddress
+  | FunctionSelector
+  | Fr
+  | AbiDecoded[]
+  | { [key: string]: AbiDecoded }
+  | undefined;
 
 /**
  * Decodes values using a provided ABI.
@@ -51,6 +70,20 @@ class AbiDecoder {
         if (isAztecAddressStruct(abiType)) {
           return new AztecAddress(this.getNextField().toBuffer());
         }
+        if (isEthAddressStruct(abiType)) {
+          return EthAddress.fromField(this.getNextField());
+        }
+        if (isFunctionSelectorStruct(abiType)) {
+          return FunctionSelector.fromField(this.getNextField());
+        }
+        if (isWrappedFieldStruct(abiType)) {
+          return this.getNextField();
+        }
+        if (isOptionStruct(abiType)) {
+          const isSome = this.decodeNext(abiType.fields[0].type);
+          const value = this.decodeNext(abiType.fields[1].type);
+          return isSome ? value : undefined;
+        }
 
         for (const field of abiType.fields) {
           struct[field.name] = this.decodeNext(field.type);
@@ -111,82 +144,3 @@ class AbiDecoder {
 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.kind}`);
-    }
-  }
-
-  /**
-   * 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

@@ -1,7 +1,13 @@
-import { Fr } from '@aztec/foundation/fields';
+import { Fr } from '@aztec/foundation/curves/bn254';
 
 import type { AbiType, FunctionAbi } from './abi.js';
-import { isAddressStruct, isBoundedVecStruct, isFunctionSelectorStruct, isWrappedFieldStruct } from './utils.js';
+import {
+  isAddressStruct,
+  isBoundedVecStruct,
+  isFunctionSelectorStruct,
+  isOptionStruct,
+  isWrappedFieldStruct,
+} from './utils.js';
 
 /**
  * Encodes arguments for a function call.
@@ -43,6 +49,32 @@ class ArgumentEncoder {
    * @param name - Name.
    */
   private encodeArgument(abiType: AbiType, arg: any, name?: string) {
+    if (isOptionStruct(abiType)) {
+      const optionType = abiType as Extract<AbiType, { kind: 'struct' }>;
+      const [isSomeField, valueField] = optionType.fields;
+
+      if (arg === undefined || arg === null) {
+        this.encodeArgument(isSomeField.type, false, `${name}._is_some`);
+        this.#encodeDefaultValue(valueField.type);
+        return;
+      }
+
+      if (typeof arg === 'object' && '_is_some' in arg) {
+        this.encodeArgument(isSomeField.type, arg._is_some, `${name}._is_some`);
+
+        if (arg._is_some) {
+          this.encodeArgument(valueField.type, arg._value, `${name}._value`);
+        } else {
+          this.#encodeDefaultValue(valueField.type);
+        }
+        return;
+      }
+
+      this.encodeArgument(isSomeField.type, true, `${name}._is_some`);
+      this.encodeArgument(valueField.type, arg, `${name}._value`);
+      return;
+    }
+
     if (arg === undefined || arg == null) {
       throw new Error(`Undefined argument ${name ?? 'unnamed'} of type ${abiType.kind}`);
     }
@@ -123,14 +155,17 @@ class ArgumentEncoder {
         }
         break;
       }
-      case 'integer':
-        if (typeof arg === 'string') {
-          const value = BigInt(arg);
-          this.flattened.push(new Fr(value));
+      case 'integer': {
+        const value = BigInt(arg);
+        if (abiType.sign === 'signed' && value < 0n) {
+          // Convert negative values to two's complement representation
+          const twosComplement = value + (1n << BigInt(abiType.width));
+          this.flattened.push(new Fr(twosComplement));
         } else {
-          this.flattened.push(new Fr(arg));
+          this.flattened.push(new Fr(value));
         }
         break;
+      }
       default:
         throw new Error(`Unsupported type: ${abiType.kind}`);
     }
@@ -224,6 +259,14 @@ class ArgumentEncoder {
       this.encodeArgument(lenField.type, arg.length, 'len');
     }
   }
+
+  /**
+   * Appends the flattened zero value for an ABI type.
+   * Option::None still serializes the wrapped value, so we need to zero-fill its footprint.
+   */
+  #encodeDefaultValue(abiType: AbiType) {
+    this.flattened.push(...new Array(ArgumentEncoder.typeSize(abiType)).fill(Fr.ZERO));
+  }
 }
 
 /**

package/src/abi/event_metadata_definition.ts

@@ -1,8 +1,10 @@
 import type { AbiType } from './abi.js';
 import type { EventSelector } from './event_selector.js';
 
+/** Metadata for a contract event, used to decode emitted event logs back into structured data. */
 export type EventMetadataDefinition = {
   eventSelector: EventSelector;
   abiType: AbiType;
+  /** Names of the event's struct members (not serialized Noir Field elements). */
   fieldNames: string[];
 };

package/src/abi/event_selector.ts

@@ -1,6 +1,7 @@
 import { fromHex, toBigIntBE } from '@aztec/foundation/bigint-buffer';
-import { poseidon2HashBytes, randomBytes } from '@aztec/foundation/crypto';
-import type { Fr } from '@aztec/foundation/fields';
+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';
 

package/src/abi/function_call.ts

@@ -1,8 +1,11 @@
-import type { Fr } from '@aztec/foundation/fields';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { FieldsOf } from '@aztec/foundation/types';
 
+import { z } from 'zod';
+
 import { AztecAddress } from '../aztec-address/index.js';
-import { type AbiType, FunctionType } from './abi.js';
+import { schemas } from '../schemas/index.js';
+import { type AbiType, AbiTypeSchema, FunctionType } from './abi.js';
 import { FunctionSelector } from './function_selector.js';
 
 /** A request to call a function on a contract. */
@@ -43,12 +46,31 @@ export class FunctionCall {
     return new FunctionCall(...FunctionCall.getFields(fields));
   }
 
+  static get schema() {
+    return z
+      .object({
+        name: z.string(),
+        to: schemas.AztecAddress,
+        selector: schemas.FunctionSelector,
+        type: z.nativeEnum(FunctionType),
+        isStatic: z.boolean(),
+        hideMsgSender: z.boolean(),
+        args: z.array(schemas.Fr),
+        returnTypes: z.array(AbiTypeSchema),
+      })
+      .transform(FunctionCall.from);
+  }
+
+  public isPublicStatic(): boolean {
+    return this.type === FunctionType.PUBLIC && this.isStatic;
+  }
+
   /**
    * Creates an empty function call.
    * @returns an empty function call.
    */
   public static empty() {
-    return {
+    return FunctionCall.from({
       name: '',
       to: AztecAddress.ZERO,
       selector: FunctionSelector.empty(),
@@ -57,6 +79,6 @@ export class FunctionCall {
       isStatic: false,
       args: [],
       returnTypes: [],
-    };
+    });
   }
 }

package/src/abi/function_selector.ts

@@ -1,11 +1,12 @@
 import { fromHex, toBigIntBE } from '@aztec/foundation/bigint-buffer';
-import { poseidon2HashBytes, randomBytes } from '@aztec/foundation/crypto';
-import type { Fr } from '@aztec/foundation/fields';
+import { poseidon2HashBytes } from '@aztec/foundation/crypto/poseidon';
+import { randomBytes } from '@aztec/foundation/crypto/random';
+import type { Fr } from '@aztec/foundation/curves/bn254';
 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 { decodeFunctionSignature } from './function_signature_decoder.js';
 import { Selector } from './selector.js';
 
 /* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
@@ -38,6 +39,14 @@ export class FunctionSelector extends Selector {
     return new FunctionSelector(Number(fr.toBigInt()));
   }
 
+  static fromFieldOrUndefined(fr: Fr) {
+    try {
+      return FunctionSelector.fromField(fr);
+    } catch {
+      return undefined;
+    }
+  }
+
   static fromFields(fields: Fr[] | FieldReader) {
     const reader = FieldReader.asReader(fields);
     return FunctionSelector.fromField(reader.readField());