@aztec/stdlib 0.0.1-commit.c2eed6949 → 0.0.1-commit.c52d6e7

package/dest/world-state/world_state_revision.js

@@ -3,6 +3,12 @@ export class WorldStateRevision {
     forkId;
     blockNumber;
     includeUncommitted;
+    /**
+   * Sentinel `blockNumber` meaning "not pinned to any historical block; use the latest committed
+   * state of the underlying tree". Mirrors the `WorldStateRevision::LATEST` constant on the C++
+   * side (defined as `std::numeric_limits<uint32_t>::max()`). Distinct from `blockNumber === 0`,
+   * which pins to the initial / genesis state.
+   */ static LATEST = 0xffffffff;
     constructor(forkId, blockNumber, includeUncommitted){
         this.forkId = forkId;
         this.blockNumber = blockNumber;
@@ -12,7 +18,7 @@ export class WorldStateRevision {
         return `WorldStateRevision(forkId: ${this.forkId}, blockNumber: ${this.blockNumber}, includeUncommitted: ${this.includeUncommitted})`;
     }
     static empty() {
-        return new WorldStateRevision(0, 0, false);
+        return new WorldStateRevision(0, WorldStateRevision.LATEST, false);
     }
     static get schema() {
         return z.object({
@@ -22,23 +28,3 @@ export class WorldStateRevision {
         }).transform(({ forkId, blockNumber, includeUncommitted })=>new WorldStateRevision(forkId, blockNumber, includeUncommitted));
     }
 }
-export class WorldStateRevisionWithHandle extends WorldStateRevision {
-    handle;
-    constructor(forkId, blockNumber, includeUncommitted, handle){
-        super(forkId, blockNumber, includeUncommitted), this.handle = handle;
-    }
-    toWorldStateRevision() {
-        return new WorldStateRevision(this.forkId, this.blockNumber, this.includeUncommitted);
-    }
-    static fromWorldStateRevision(revision, handle) {
-        return new WorldStateRevisionWithHandle(revision.forkId, revision.blockNumber, revision.includeUncommitted, handle);
-    }
-    static get schema() {
-        return z.object({
-            forkId: z.number(),
-            blockNumber: z.number(),
-            includeUncommitted: z.boolean(),
-            handle: z.any()
-        }).transform(({ forkId, blockNumber, includeUncommitted, handle })=>new WorldStateRevisionWithHandle(forkId, blockNumber, includeUncommitted, handle));
-    }
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aztec/stdlib",
-  "version": "0.0.1-commit.c2eed6949",
+  "version": "0.0.1-commit.c52d6e7",
   "type": "module",
   "inherits": [
     "../package.common.json",
@@ -92,15 +92,15 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.892.0",
-    "@aztec/bb.js": "0.0.1-commit.c2eed6949",
-    "@aztec/blob-lib": "0.0.1-commit.c2eed6949",
-    "@aztec/constants": "0.0.1-commit.c2eed6949",
-    "@aztec/ethereum": "0.0.1-commit.c2eed6949",
-    "@aztec/foundation": "0.0.1-commit.c2eed6949",
-    "@aztec/l1-artifacts": "0.0.1-commit.c2eed6949",
-    "@aztec/noir-noirc_abi": "0.0.1-commit.c2eed6949",
+    "@aztec/bb.js": "6.0.0-nightly.20260807",
+    "@aztec/blob-lib": "0.0.1-commit.c52d6e7",
+    "@aztec/constants": "0.0.1-commit.c52d6e7",
+    "@aztec/ethereum": "0.0.1-commit.c52d6e7",
+    "@aztec/foundation": "0.0.1-commit.c52d6e7",
+    "@aztec/l1-artifacts": "6.0.0-nightly.20260807",
+    "@aztec/noir-noirc_abi": "6.0.0-nightly.20260807",
     "@google-cloud/storage": "^7.15.0",
-    "axios": "^1.13.5",
+    "axios": "^1.15.1",
     "json-stringify-deterministic": "1.0.12",
     "lodash.chunk": "^4.2.0",
     "lodash.isequal": "^4.5.0",
@@ -110,7 +110,7 @@
     "pako": "^2.1.0",
     "tslib": "^2.4.0",
     "viem": "npm:@aztec/viem@2.38.2",
-    "zod": "^3.23.8"
+    "zod": "^4"
   },
   "devDependencies": {
     "@jest/expect": "^30.0.0",
@@ -129,7 +129,8 @@
     "jest-mock-extended": "^4.0.0",
     "prettier": "^3.5.3",
     "ts-node": "^10.9.1",
-    "typescript": "^5.3.3"
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.0"
   },
   "files": [
     "dest",

package/src/abi/abi.ts

@@ -6,6 +6,7 @@ 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';
 
 /** A basic value. */
@@ -26,6 +27,14 @@ export type AbiValue =
   | IntegerValue
   | StructValue;
 
+/** An exported value together with the name of the global that produced it. */
+export interface AbiNamedValue {
+  /** The name of the exported global. */
+  name: string;
+  /** The exported value. */
+  value: AbiValue;
+}
+
 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() }),
@@ -181,14 +190,34 @@ export interface FunctionAbi {
   isStatic: boolean;
   /** Function parameters. */
   parameters: ABIParameter[];
-  /** The types of the return values. */
-  returnTypes: AbiType[];
+  /** The type of the value the function returns, or undefined if it returns nothing. */
+  returnType?: AbiType;
+  /**
+   * The same type as `returnType`, as a list that is either:
+   * - a single entry, when the function returns something. Multiple return values are expressed as a single `tuple`
+   *   type, so this never holds more than one entry.
+   * - empty, when the function returns nothing.
+   *
+   * @deprecated Read it through {@link getFunctionReturnType}.
+   */
+  returnTypes?: AbiType[];
   /** 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 type a function returns, or undefined if it returns nothing. Falls back to the deprecated `returnTypes` so that
+ * artifacts serialized before `returnType` existed still resolve.
+ */
+export function getFunctionReturnType(abi: Pick<FunctionAbi, 'returnType' | 'returnTypes'>): AbiType | undefined {
+  if (abi.returnTypes !== undefined && abi.returnTypes.length > 1) {
+    throw new Error(`Expected at most one return type, got ${abi.returnTypes.length}`);
+  }
+  return abi.returnType ?? abi.returnTypes?.[0];
+}
+
 export const FunctionAbiSchema = z.object({
   name: z.string(),
   functionType: z.nativeEnum(FunctionType),
@@ -196,7 +225,8 @@ export const FunctionAbiSchema = z.object({
   isStatic: z.boolean(),
   isInitializer: z.boolean(),
   parameters: z.array(z.object({ name: z.string(), type: AbiTypeSchema, visibility: z.enum(ABIParameterVisibility) })),
-  returnTypes: z.array(AbiTypeSchema),
+  returnType: AbiTypeSchema.optional(),
+  returnTypes: z.array(AbiTypeSchema).optional(),
   errorTypes: z.record(z.string(), AbiErrorTypeSchema.optional()),
 }) satisfies z.ZodType<FunctionAbi>;
 
@@ -221,10 +251,11 @@ export const FunctionDebugMetadataSchema = z.object({
         }),
       ),
     }),
-    acir_locations: z.record(z.number()),
-    brillig_locations: z.record(z.record(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.string(),
     z.object({
       source: z.string(),
       path: z.string(),
@@ -338,11 +369,17 @@ export type FieldLayout = {
   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 the Aztec stack that compiled this artifact. */
+  aztecVersion: string;
+
   /** The functions of the contract. Includes private and utility functions, plus the public dispatch function. */
   functions: FunctionArtifact[];
 
@@ -365,10 +402,11 @@ export interface ContractArtifact {
 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.array(AbiTypeSchema)).transform(structs => {
+      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.
@@ -380,9 +418,9 @@ export const ContractArtifactSchema = zodFor<ContractArtifact>()(
         }
         return structs;
       }),
-      globals: z.record(z.array(AbiValueSchema)),
+      globals: z.record(z.string(), z.array(AbiValueSchema)),
     }),
-    storageLayout: z.record(z.object({ slot: schemas.Fr })),
+    storageLayout: z.record(z.string(), z.object({ slot: schemas.Fr })),
     fileMap: z.record(
       z.coerce.number(),
       z.object({
@@ -410,20 +448,10 @@ export async function getFunctionArtifact(
   artifact: ContractArtifact,
   functionNameOrSelector: string | FunctionSelector,
 ): Promise<FunctionArtifactWithContractName> {
-  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;
-  }
+  const functionArtifact =
+    typeof functionNameOrSelector === 'string'
+      ? artifact.functions.find(f => f.name === functionNameOrSelector)
+      : await findFunctionArtifactBySelector(artifact, functionNameOrSelector);
   if (!functionArtifact) {
     throw new Error(`Unknown function ${functionNameOrSelector}`);
   }
@@ -433,6 +461,40 @@ export async function getFunctionArtifact(
   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 || []);
@@ -533,7 +595,6 @@ export function emptyFunctionAbi(): FunctionAbi {
     isOnlySelf: false,
     isStatic: false,
     parameters: [],
-    returnTypes: [],
     errorTypes: {},
     isInitializer: false,
   };
@@ -551,6 +612,7 @@ export function emptyFunctionArtifact(): FunctionArtifact {
 export function emptyContractArtifact(): ContractArtifact {
   return {
     name: '',
+    aztecVersion: DEV_VERSION,
     functions: [emptyFunctionArtifact()],
     nonDispatchPublicFunctions: [emptyFunctionAbi()],
     outputs: {

package/src/abi/authorization_selector.ts

@@ -7,18 +7,12 @@ import { BufferReader } from '@aztec/foundation/serialize';
 
 import { Selector } from './selector.js';
 
-/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
-
-/** Authorization selector branding */
-export interface AuthorizationSelector {
-  /** Brand. */
-  _branding: 'AuthorizationSelector';
-}
-
 /**
  * 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.

package/src/abi/buffer.ts

@@ -38,11 +38,23 @@ export function bufferAsFields(input: Buffer, targetLength: number): Fr[] {
  * bytecode commitment computations to diverge from what the circuit produced.
  *
  * @param fields - An output from bufferAsFields: [byteLength, ...payloadFields].
+ * @param maxByteLength - Optional upper bound on the declared byte length. When the field array comes
+ *   from untrusted input (e.g. a gossiped contract-class log), pass the payload capacity so an
+ *   attacker-declared length cannot force a large `Buffer.alloc` before the value is otherwise
+ *   rejected. Throws if the declared length exceeds it, before allocating.
  * @returns A buffer of exactly `byteLength` bytes.
  */
-export function bufferFromFields(fields: Fr[]): Buffer {
+export function bufferFromFields(fields: Fr[], maxByteLength?: number): Buffer {
+  // A valid bufferAsFields output always has at least the leading byte-length field, so an empty
+  // input encodes no data. Guard so `length` (the destructured head) is never undefined.
+  if (fields.length === 0) {
+    return Buffer.alloc(0);
+  }
   const [length, ...payload] = fields;
   const byteLength = length.toNumber();
+  if (maxByteLength !== undefined && byteLength > maxByteLength) {
+    throw new Error(`Declared byte length ${byteLength} exceeds maximum ${maxByteLength}`);
+  }
   const raw = Buffer.concat(payload.map(f => f.toBuffer().subarray(1)));
   if (raw.length >= byteLength) {
     return raw.subarray(0, byteLength);

package/src/abi/contract_artifact.ts

@@ -12,7 +12,10 @@ import {
 import {
   type ABIParameter,
   type ABIParameterVisibility,
+  ARTIFACT_VERSION_BEFORE_INJECTION,
+  type AbiNamedValue,
   type AbiType,
+  type AbiValue,
   type BasicValue,
   type ContractArtifact,
   ContractArtifactSchema,
@@ -51,6 +54,10 @@ export function contractArtifactFromBuffer(buffer: Buffer): ContractArtifact {
  */
 export function loadContractArtifact(input: NoirCompiledContract): ContractArtifact {
   if (isContractArtifact(input)) {
+    // TODO(F-557): Remove this fallback once pre-version artifacts are no longer tested.
+    if (!(input as unknown as Record<string, unknown>).aztecVersion) {
+      return { ...input, aztecVersion: ARTIFACT_VERSION_BEFORE_INJECTION };
+    }
     return input;
   }
   return generateContractArtifact(input);
@@ -161,9 +168,9 @@ function generateFunctionAbi(fn: NoirCompiledContractFunction, contract: NoirCom
     parameters = parameters.slice(1);
   }
 
-  let returnTypes: AbiType[] = [];
+  let returnType: AbiType | undefined;
   if (functionType === FunctionType.UTILITY) {
-    returnTypes = fn.abi.return_type ? [fn.abi.return_type.abi_type] : returnTypes;
+    returnType = fn.abi.return_type?.abi_type;
   } else {
     const pathToFind = `${contract.name}::${fn.name}_abi`;
     const abiStructs: AbiType[] = contract.outputs.structs['functions'];
@@ -175,10 +182,7 @@ function generateFunctionAbi(fn: NoirCompiledContractFunction, contract: NoirCom
         throw new Error('Could not generate contract function artifact');
       }
 
-      const returnTypeField = returnStruct.fields.find(field => field.name === 'return_type');
-      if (returnTypeField) {
-        returnTypes = [returnTypeField.type];
-      }
+      returnType = returnStruct.fields.find(field => field.name === 'return_type')?.type;
     }
   }
 
@@ -189,7 +193,10 @@ function generateFunctionAbi(fn: NoirCompiledContractFunction, contract: NoirCom
     isStatic,
     isInitializer: fn.custom_attributes.includes(AZTEC_INITIALIZER_ATTRIBUTE),
     parameters,
-    returnTypes,
+    returnType,
+    // Old consumers expect `returnTypes` property, not `returnType`. So we write both down for now, until we can
+    // safely remove the old version.
+    returnTypes: returnType ? [returnType] : [],
     errorTypes: fn.abi.error_types,
     ...(fn.assert_messages ? { assertMessages: fn.assert_messages } : undefined),
   };
@@ -241,20 +248,24 @@ function hasKernelFunctionInputs(params: ABIParameter[]): boolean {
 
 /**
  * Generates a storage layout for the contract artifact.
- * @param input - The compiled noir contract to get storage layout for
+ * @param contractName - The name of the compiled Noir contract.
+ * @param globals - The normalized globals exported by the contract.
  * @returns A storage layout for the contract.
  */
-function getStorageLayout(input: NoirCompiledContract) {
+function getStorageLayout(contractName: string, globals: Record<string, AbiValue[]>) {
   // 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 storageExports = globals.storage ?? [];
+  const storageForContract = storageExports.find((storageExport): storageExport is StructValue => {
+    if (storageExport.kind !== 'struct') {
+      return false;
+    }
     const contractNameField = storageExport.fields.find(field => field.name === 'contract_name')?.value as BasicValue<
       'string',
       string
     >;
-    return contractNameField.value === input.name;
+    return contractNameField.value === contractName;
   });
   const storageFields = storageForContract
     ? ((storageForContract.fields.find(field => field.name == 'fields') as TypedStructFieldValue<StructValue>).value
@@ -275,25 +286,42 @@ function getStorageLayout(input: NoirCompiledContract) {
   }, {});
 }
 
+function isAbiNamedValue(value: AbiNamedValue | AbiValue): value is AbiNamedValue {
+  return 'name' in value;
+}
+
+function normalizeContractOutputs(outputs: NoirCompiledContract['outputs']): ContractArtifact['outputs'] {
+  return {
+    structs: outputs.structs,
+    globals: Object.fromEntries(
+      Object.entries(outputs.globals).map(([tag, values]) => [
+        tag,
+        values.map(value => (isAbiNamedValue(value) ? value.value : value)),
+      ]),
+    ),
+  };
+}
+
 /**
- * Given a Nargo output generates an Aztec-compatible contract artifact.
+ * Given a post-processed Nargo output defined as `contract` generates an Aztec-compatible contract artifact.
+ *
  * Does not include public bytecode, apart from the public_dispatch function.
- * @param compiled - Noir build output.
- * @returns Aztec contract build artifact.
  */
 function generateContractArtifact(contract: NoirCompiledContract): ContractArtifact {
   try {
     if (!contract.transpiled) {
       throw new Error("Contract's public bytecode has not been transpiled");
     }
+    const outputs = normalizeContractOutputs(contract.outputs);
     return ContractArtifactSchema.parse({
       name: contract.name,
+      aztecVersion: contract.aztec_version,
       functions: contract.functions.filter(f => retainBytecode(f)).map(f => generateFunctionArtifact(f, contract)),
       nonDispatchPublicFunctions: contract.functions
         .filter(f => !retainBytecode(f))
         .map(f => generateFunctionAbi(f, contract)),
-      outputs: contract.outputs,
-      storageLayout: getStorageLayout(contract),
+      outputs,
+      storageLayout: getStorageLayout(contract.name, outputs.globals),
       fileMap: contract.file_map,
     });
   } catch (err) {
@@ -302,21 +330,22 @@ function generateContractArtifact(contract: NoirCompiledContract): ContractArtif
 }
 
 /**
- * Given a Nargo output generates an Aztec-compatible contract artifact.
+ * Given a post-processed Nargo output defined as `contract` generates an Aztec-compatible contract artifact.
+ *
  * Retains all public bytecode.
- * @param compiled - Noir build output.
- * @returns Aztec contract build artifact.
  */
 function generateContractArtifactForPublic(contract: NoirCompiledContract): ContractArtifact {
   try {
+    const outputs = normalizeContractOutputs(contract.outputs);
     return ContractArtifactSchema.parse({
       name: contract.name,
+      aztecVersion: contract.aztec_version,
       functions: contract.functions.map(f => generateFunctionArtifact(f, contract)),
       nonDispatchPublicFunctions: contract.functions
         .filter(f => !retainBytecode(f))
         .map(f => generateFunctionAbi(f, contract)),
-      outputs: contract.outputs,
-      storageLayout: getStorageLayout(contract),
+      outputs,
+      storageLayout: getStorageLayout(contract.name, outputs.globals),
       fileMap: contract.file_map,
     });
   } catch (err) {