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

package/src/tx/validator/error_texts.ts

@@ -0,0 +1,53 @@
+// Gas and fees
+export const TX_ERROR_INSUFFICIENT_FEE_PER_GAS = 'Insufficient fee per gas';
+export const TX_ERROR_INSUFFICIENT_FEE_PAYER_BALANCE = 'Insufficient fee payer balance';
+export const TX_ERROR_INSUFFICIENT_GAS_LIMIT = 'Gas limit is below the minimum fixed cost';
+export const TX_ERROR_GAS_LIMIT_TOO_HIGH = 'Gas limit is higher than the amount of gas that the AVM can process';
+
+// Phases
+export const TX_ERROR_SETUP_FUNCTION_NOT_ALLOWED = 'Setup function not on allow list';
+export const TX_ERROR_SETUP_FUNCTION_UNKNOWN_CONTRACT = 'Setup function targets unknown contract';
+export const TX_ERROR_SETUP_ONLY_SELF_WRONG_SENDER = 'Setup only_self function called with incorrect msg_sender';
+export const TX_ERROR_SETUP_NULL_MSG_SENDER = 'Setup function called with null msg sender';
+export const TX_ERROR_SETUP_WRONG_CALLDATA_LENGTH = 'Setup function called with wrong calldata length';
+
+// Nullifiers
+export const TX_ERROR_DUPLICATE_NULLIFIER_IN_TX = 'Duplicate nullifier in tx';
+export const TX_ERROR_EXISTING_NULLIFIER = 'Existing nullifier';
+
+// Metadata
+export const TX_ERROR_INVALID_EXPIRATION_TIMESTAMP = 'Invalid expiration timestamp';
+export const TX_ERROR_INCORRECT_L1_CHAIN_ID = 'Incorrect L1 chain id';
+export const TX_ERROR_INCORRECT_ROLLUP_VERSION = 'Incorrect rollup version';
+export const TX_ERROR_INCORRECT_VK_TREE_ROOT = 'Incorrect verification keys tree root';
+export const TX_ERROR_INCORRECT_PROTOCOL_CONTRACTS_HASH = 'Incorrect protocol contracts hash';
+
+// Proof
+export const TX_ERROR_INVALID_PROOF = 'Invalid proof';
+
+//Data
+export const TX_ERROR_INCORRECT_CALLDATA = 'Incorrect calldata for public call';
+export const TX_ERROR_CALLDATA_COUNT_MISMATCH = 'Wrong number of calldata for public calls';
+export const TX_ERROR_CALLDATA_COUNT_TOO_LARGE = 'Total calldata too large for enqueued public calls';
+export const TX_ERROR_CONTRACT_CLASS_LOG_COUNT = 'Mismatched number of contract class logs';
+export const TX_ERROR_CONTRACT_CLASS_LOG_LENGTH = 'Incorrect contract class logs length';
+export const TX_ERROR_CONTRACT_CLASS_LOGS = 'Mismatched contract class logs';
+export const TX_ERROR_CONTRACT_CLASS_LOG_SORTING = 'Incorrectly sorted contract class logs';
+export const TX_ERROR_INCORRECT_HASH = 'Incorrect tx hash';
+
+// Size
+export const TX_ERROR_SIZE_ABOVE_LIMIT = 'Transaction size above size limit';
+
+// Block header
+export const TX_ERROR_BLOCK_HEADER = 'Block header not found';
+
+// Contract instance
+export const TX_ERROR_INCORRECT_CONTRACT_ADDRESS = 'Incorrect contract instance deployment address';
+export const TX_ERROR_MALFORMED_CONTRACT_INSTANCE_LOG = 'Failed to parse contract instance deployment log';
+
+// Contract class
+export const TX_ERROR_INCORRECT_CONTRACT_CLASS_ID = 'Incorrect contract class id';
+export const TX_ERROR_MALFORMED_CONTRACT_CLASS_LOG = 'Failed to parse contract class registration log';
+
+// General
+export const TX_ERROR_DURING_VALIDATION = 'Unexpected error during validation';

package/src/tx/validator/tx_validator.ts

@@ -1,26 +1,29 @@
 import { z } from 'zod';
 
-import type { ZodFor } from '../../schemas/schemas.js';
+import { zodFor } from '../../schemas/schemas.js';
 import type { ProcessedTx } from '../processed_tx.js';
 import type { Tx } from '../tx.js';
+import type { TxHash } from '../tx_hash.js';
 
 export type AnyTx = Tx | ProcessedTx;
 
+export function getTxHash(tx: AnyTx): TxHash {
+  return 'txHash' in tx ? tx.txHash : tx.hash;
+}
+
 export function hasPublicCalls(tx: AnyTx): boolean {
   return tx.data.numberOfPublicCallRequests() > 0;
 }
 
-export type TxValidationResult =
-  | { result: 'valid' }
-  | { result: 'invalid'; reason: string[] }
-  | { result: 'skipped'; reason: string[] };
+export type TxValidationResult = { result: 'valid' } | { result: 'invalid'; reason: string[] };
 
-export interface TxValidator<T extends AnyTx = AnyTx> {
+export interface TxValidator<T = AnyTx> {
   validateTx(tx: T): Promise<TxValidationResult>;
 }
 
-export const TxValidationResultSchema = z.discriminatedUnion('result', [
-  z.object({ result: z.literal('valid'), reason: z.array(z.string()).optional() }),
-  z.object({ result: z.literal('invalid'), reason: z.array(z.string()) }),
-  z.object({ result: z.literal('skipped'), reason: z.array(z.string()) }),
-]) satisfies ZodFor<TxValidationResult>;
+export const TxValidationResultSchema = zodFor<TxValidationResult>()(
+  z.discriminatedUnion('result', [
+    z.object({ result: z.literal('valid') }),
+    z.object({ result: z.literal('invalid'), reason: z.array(z.string()) }),
+  ]),
+);

package/src/types/shared.ts

@@ -1,4 +1,4 @@
-import { type Bufferable, serializeToBuffer } from '@aztec/foundation/serialize';
+import { BufferSink, type Bufferable, type Sinkable, serializeToSink } from '@aztec/foundation/serialize';
 
 /**
  * Implementation of a vector. Matches how we are serializing and deserializing vectors in cpp (length in the first position, followed by the items).
@@ -11,8 +11,13 @@ export class Vector<T extends Bufferable> {
     public items: T[],
   ) {}
 
-  toBuffer() {
-    return serializeToBuffer(this.items.length, this.items);
+  toBuffer(): Buffer;
+  toBuffer(sink: BufferSink): void;
+  toBuffer(sink?: BufferSink): Buffer | void {
+    if (!sink) {
+      return BufferSink.serialize(this);
+    }
+    serializeToSink(sink, this.items.length, this.items as Sinkable[]);
   }
 
   toFriendlyJSON() {
@@ -26,20 +31,11 @@ export class Vector<T extends Bufferable> {
 export type UInt32 = number;
 
 /**
- * CircuitType replaces ComposerType for now. When using Plonk, CircuitType is equivalent to the information of the proving system that will be used
- * to construct a proof. In the future Aztec zk stack, more information must be specified (e.g., the curve over which circuits are  constructed;
- * Plonk vs Honk; zk-SNARK or just SNARK; etc).
+ * A type alias for a 64-bit unsigned integer.
  */
-export enum CircuitType {
-  STANDARD = 0,
-  ULTRA = 1,
-}
+export type UInt64 = bigint;
 
 /**
- * Rollup types.
+ * A type alias for a 128-bit unsigned integer.
  */
-export enum RollupTypes {
-  Base = 0,
-  Merge = 1,
-  Root = 2,
-}
+export type UInt128 = bigint;

package/src/update-checker/dev_version.ts

@@ -0,0 +1,2 @@
+/** Placeholder version returned when running from a local monorepo checkout rather than an npm-installed package. */
+export const DEV_VERSION = 'dev';

package/src/update-checker/index.ts

@@ -0,0 +1,3 @@
+export * from './dev_version.js';
+export * from './package_version.js';
+export * from './version_checker.js';

package/src/update-checker/package_version.ts

@@ -0,0 +1,17 @@
+import { fileURLToPath } from '@aztec/foundation/url';
+
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+
+import { DEV_VERSION } from './dev_version.js';
+
+/**
+ * Returns the package version from the stdlib `package.json`, or `DEV_VERSION` when the version is the `0.1.0`
+ * placeholder (which indicates a local monorepo checkout rather than an npm-installed package).
+ */
+export function getPackageVersion(): string {
+  const dir = dirname(fileURLToPath(import.meta.url));
+  const packageJsonPath = resolve(dir, '../../package.json');
+  const version = JSON.parse(readFileSync(packageJsonPath).toString()).version;
+  return version === '0.1.0' ? DEV_VERSION : version;
+}

package/src/update-checker/version_checker.ts

@@ -0,0 +1,65 @@
+import { createLogger } from '@aztec/foundation/log';
+import { RunningPromise } from '@aztec/foundation/promise';
+
+import { EventEmitter } from 'node:events';
+
+export type EventMap = {
+  newVersion: [{ name: string; currentVersion: string; latestVersion: string }];
+};
+
+export type VersionCheck = {
+  name: string;
+  currentVersion: string;
+  getLatestVersion: () => Promise<string | undefined>;
+};
+
+export class VersionChecker extends EventEmitter<EventMap> {
+  private runningPromise: RunningPromise;
+  constructor(
+    private checks: Array<VersionCheck>,
+    intervalCheckMs = 60_000,
+    private logger = createLogger('version_checker'),
+  ) {
+    super();
+    this.runningPromise = new RunningPromise(this.run, logger, intervalCheckMs);
+  }
+
+  public start(): void {
+    if (this.runningPromise.isRunning()) {
+      this.logger.warn('VersionChecker is already running');
+      return;
+    }
+
+    this.runningPromise.start();
+    this.logger.info('Version check started');
+  }
+
+  public trigger(): Promise<void> {
+    return this.runningPromise.trigger();
+  }
+
+  public async stop(): Promise<void> {
+    if (!this.runningPromise.isRunning()) {
+      this.logger.warn('VersionChecker is not running');
+      return;
+    }
+
+    await this.runningPromise.stop();
+    this.logger.info('Version checker stopped');
+  }
+
+  private run = async () => {
+    await Promise.allSettled(this.checks.map(check => this.checkVersion(check)));
+  };
+
+  private async checkVersion({ name, currentVersion, getLatestVersion }: VersionCheck): Promise<void> {
+    try {
+      const latestVersion = await getLatestVersion();
+      if (latestVersion && latestVersion !== currentVersion) {
+        this.emit('newVersion', { name, latestVersion, currentVersion });
+      }
+    } catch (err) {
+      this.logger.warn(`Error checking for new ${name} versions: ${err}`, { err });
+    }
+  }
+}

package/src/validators/errors.ts

@@ -0,0 +1,67 @@
+import type { SlotNumber } from '@aztec/foundation/branded-types';
+import type { Fr } from '@aztec/foundation/curves/bn254';
+import type { TxHash } from '@aztec/stdlib/tx';
+
+export class ValidatorError extends Error {
+  constructor(message: string) {
+    super(`Validator Error: ${message}`);
+  }
+}
+
+export class InvalidValidatorPrivateKeyError extends ValidatorError {
+  constructor() {
+    super('Invalid validator private key provided');
+  }
+}
+
+export class AttestationTimeoutError extends ValidatorError {
+  constructor(
+    public readonly collectedCount: number,
+    public readonly requiredCount: number,
+    public readonly slot: SlotNumber,
+  ) {
+    super(`Timeout collecting attestations for slot ${slot}: ${collectedCount}/${requiredCount}`);
+  }
+}
+
+export class TransactionsNotAvailableError extends ValidatorError {
+  constructor(txHashes: TxHash[]) {
+    super(`Transactions not available: ${txHashes.join(', ')}`);
+  }
+}
+
+export class FailedToReExecuteTransactionsError extends ValidatorError {
+  constructor(txHashes: TxHash[]) {
+    super(`Failed to re-execute transactions: ${txHashes.join(', ')}`);
+  }
+}
+
+export class ReExInitialStateMismatchError extends ValidatorError {
+  constructor(
+    public readonly expectedArchiveRoot: Fr,
+    public readonly actualArchiveRoot: Fr,
+  ) {
+    super('Re-execution initial state mismatch');
+  }
+}
+
+export class ReExStateMismatchError extends ValidatorError {
+  constructor(
+    public readonly expectedArchiveRoot: Fr,
+    public readonly actualArchiveRoot: Fr,
+  ) {
+    super('Re-execution state mismatch');
+  }
+}
+
+export class ReExFailedTxsError extends ValidatorError {
+  constructor(numFailedTxs: number) {
+    super(`Re-execution failed to process ${numFailedTxs} txs`);
+  }
+}
+
+export class ReExTimeoutError extends ValidatorError {
+  constructor() {
+    super('Re-execution timed out or failed to process all txs in the proposal');
+  }
+}

package/src/validators/index.ts

@@ -0,0 +1,3 @@
+export * from './errors.js';
+export * from './schemas.js';
+export type * from './types.js';

package/src/validators/schemas.ts

@@ -0,0 +1,90 @@
+import { schemas, zodFor } from '@aztec/foundation/schemas';
+
+import { z } from 'zod';
+
+import type {
+  SingleValidatorStats,
+  ValidatorMissedStats,
+  ValidatorStats,
+  ValidatorStatusHistory,
+  ValidatorStatusInSlot,
+  ValidatorsStats,
+} from './types.js';
+
+export const ValidatorStatusInSlotSchema = zodFor<ValidatorStatusInSlot>()(
+  z.enum([
+    'checkpoint-mined',
+    'checkpoint-valid',
+    'checkpoint-invalid',
+    'checkpoint-unvalidated',
+    'checkpoint-missed',
+    'blocks-missed',
+    'attestation-sent',
+    'attestation-missed',
+  ]),
+);
+
+export const ValidatorStatusHistorySchema = zodFor<ValidatorStatusHistory>()(
+  z.array(
+    z.object({
+      slot: schemas.SlotNumber,
+      status: ValidatorStatusInSlotSchema,
+    }),
+  ),
+);
+
+export const ValidatorStatusHistorySchemaArray = z.array(ValidatorStatusHistorySchema);
+
+export const ValidatorStatusHistorySchemaMap = z.record(z.string(), ValidatorStatusHistorySchemaArray);
+
+const ValidatorTimeStatSchema = z.object({
+  timestamp: schemas.BigInt,
+  slot: schemas.SlotNumber,
+  date: z.string(),
+});
+
+const ValidatorMissedStatsSchema = zodFor<ValidatorMissedStats>()(
+  z.object({
+    currentStreak: schemas.Integer,
+    rate: z.number().optional(),
+    count: schemas.Integer,
+    total: schemas.Integer,
+  }),
+);
+
+export const ValidatorStatsSchema = zodFor<ValidatorStats>()(
+  z.object({
+    address: schemas.EthAddress,
+    lastProposal: ValidatorTimeStatSchema.optional(),
+    lastAttestation: ValidatorTimeStatSchema.optional(),
+    totalSlots: schemas.Integer,
+    missedProposals: ValidatorMissedStatsSchema,
+    missedAttestations: ValidatorMissedStatsSchema,
+    history: ValidatorStatusHistorySchema,
+  }),
+);
+
+export const ValidatorsStatsSchema = zodFor<ValidatorsStats>()(
+  z.object({
+    stats: z.record(z.string(), ValidatorStatsSchema),
+    lastProcessedSlot: schemas.SlotNumber.optional(),
+    initialSlot: schemas.SlotNumber.optional(),
+    slotWindow: schemas.Integer,
+  }),
+);
+
+export const SingleValidatorStatsSchema = zodFor<SingleValidatorStats>()(
+  z.object({
+    validator: ValidatorStatsSchema,
+    allTimeEpochPerformance: z.array(
+      z.object({
+        missed: schemas.Integer,
+        total: schemas.Integer,
+        epoch: schemas.EpochNumber,
+      }),
+    ),
+    lastProcessedSlot: schemas.SlotNumber.optional(),
+    initialSlot: schemas.SlotNumber.optional(),
+    slotWindow: schemas.Integer,
+  }),
+);

package/src/validators/types.ts

@@ -0,0 +1,67 @@
+import type { EpochNumber, SlotNumber } from '@aztec/foundation/branded-types';
+import type { EthAddress } from '@aztec/foundation/eth-address';
+
+export type ValidatorStatusType = 'proposer' | 'attestation';
+
+/**
+ * Per-slot status for a validator.
+ *
+ * Proposer statuses (six-case taxonomy):
+ * - `blocks-missed`           — no block proposals seen for the slot (case 1).
+ * - `checkpoint-missed`       — block proposals seen but no checkpoint proposal (case 2).
+ * - `checkpoint-unvalidated`  — checkpoint proposal seen but local re-execution couldn't
+ *                               validate (missing txs, timeouts, etc.) (case 3).
+ * - `checkpoint-invalid`      — checkpoint proposal re-executed and rejected as invalid (case 4).
+ * - `checkpoint-valid`        — checkpoint proposal re-executed locally as valid (case 5).
+ * - `checkpoint-mined`        — checkpoint published on L1 (case 6).
+ *
+ * Attestor statuses:
+ * - `attestation-sent`        — attestation observed on P2P or in the published checkpoint.
+ * - `attestation-missed`      — committee member did not attest to a checkpoint proposal that
+ *                               was observed locally or published on L1.
+ */
+export type ValidatorStatusInSlot =
+  | 'checkpoint-mined'
+  | 'checkpoint-valid'
+  | 'checkpoint-invalid'
+  | 'checkpoint-unvalidated'
+  | 'checkpoint-missed'
+  | 'blocks-missed'
+  | 'attestation-sent'
+  | 'attestation-missed';
+
+export type ValidatorStatusHistory = { slot: SlotNumber; status: ValidatorStatusInSlot }[];
+
+export type ValidatorMissedStats = {
+  currentStreak: number;
+  rate?: number;
+  count: number;
+  total: number;
+};
+
+export type ValidatorStats = {
+  address: EthAddress;
+  lastProposal?: { timestamp: bigint; slot: SlotNumber; date: string };
+  lastAttestation?: { timestamp: bigint; slot: SlotNumber; date: string };
+  totalSlots: number;
+  missedProposals: ValidatorMissedStats;
+  missedAttestations: ValidatorMissedStats;
+  history: ValidatorStatusHistory;
+};
+
+export type ValidatorsStats = {
+  stats: Record<string, ValidatorStats>;
+  lastProcessedSlot?: SlotNumber;
+  initialSlot?: SlotNumber;
+  slotWindow: number;
+};
+
+export type ValidatorsEpochPerformance = Record<`0x${string}`, { missed: number; total: number }>;
+
+export type SingleValidatorStats = {
+  validator: ValidatorStats;
+  allTimeEpochPerformance: { missed: number; total: number; epoch: EpochNumber }[];
+  lastProcessedSlot?: SlotNumber;
+  initialSlot?: SlotNumber;
+  slotWindow: number;
+};

package/src/versioning/versioning.ts

@@ -1,13 +1,10 @@
+import type { Fr } from '@aztec/foundation/curves/bn254';
 import type { EthAddress } from '@aztec/foundation/eth-address';
-import type { Fr } from '@aztec/foundation/fields';
 import { jsonStringify } from '@aztec/foundation/json-rpc';
 
 import type Koa from 'koa';
 
-import type { ChainConfig } from '../config/config.js';
-
-// REFACTOR: This file is not a circuit-type, but at the moment we don't have any other
-// package common to all components that we can use for this shared code.
+import type { ChainConfig } from '../config/chain-config.js';
 
 /** Fields that identify a version of the Aztec protocol. Any mismatch between these fields should signal an incompatibility between nodes. */
 export type ComponentsVersions = {
@@ -16,22 +13,22 @@ export type ComponentsVersions = {
   // Note that we are using the rollup address as identifier in multiple places
   // such as the keystore, we need to change it so we can handle updates.
   l1RollupAddress: EthAddress;
-  l2ChainVersion: number;
-  l2ProtocolContractsTreeRoot: string;
+  rollupVersion: number;
+  l2ProtocolContractsHash: string;
   l2CircuitsVkTreeRoot: string;
 };
 
 /** Returns components versions from chain config. */
 export function getComponentsVersionsFromConfig(
   config: ChainConfig,
-  l2ProtocolContractsTreeRoot: string | Fr,
+  l2ProtocolContractsHash: string | Fr,
   l2CircuitsVkTreeRoot: string | Fr,
 ): ComponentsVersions {
   return {
     l1ChainId: config.l1ChainId,
-    l1RollupAddress: config.l1Contracts?.rollupAddress, // This should not be undefined, but sometimes the config lies to us and it is...
-    l2ChainVersion: config.version,
-    l2ProtocolContractsTreeRoot: l2ProtocolContractsTreeRoot.toString(),
+    l1RollupAddress: config.rollupAddress,
+    rollupVersion: config.rollupVersion,
+    l2ProtocolContractsHash: l2ProtocolContractsHash.toString(),
     l2CircuitsVkTreeRoot: l2CircuitsVkTreeRoot.toString(),
   };
 }
@@ -40,7 +37,7 @@ export function getComponentsVersionsFromConfig(
 export function compressComponentVersions(versions: ComponentsVersions): string {
   if (
     versions.l1RollupAddress === undefined ||
-    versions.l2ProtocolContractsTreeRoot === undefined ||
+    versions.l2ProtocolContractsHash === undefined ||
     versions.l2CircuitsVkTreeRoot === undefined
   ) {
     throw new Error(`Component versions are not set: ${jsonStringify(versions)}`);
@@ -50,8 +47,8 @@ export function compressComponentVersions(versions: ComponentsVersions): string
     '00',
     versions.l1ChainId,
     versions.l1RollupAddress.toString().slice(2, 10),
-    versions.l2ChainVersion,
-    versions.l2ProtocolContractsTreeRoot.toString().slice(2, 10),
+    versions.rollupVersion,
+    versions.l2ProtocolContractsHash.toString().slice(2, 10),
     versions.l2CircuitsVkTreeRoot.toString().slice(2, 10),
   ].join('-');
 }
@@ -65,14 +62,8 @@ export class ComponentsVersionsError extends Error {
 
 /** Checks if the compressed string matches against the expected versions. Throws on mismatch. */
 export function checkCompressedComponentVersion(compressed: string, expected: ComponentsVersions) {
-  const [
-    versionVersion,
-    l1ChainId,
-    l1RollupAddress,
-    l2ChainVersion,
-    l2ProtocolContractsTreeRoot,
-    l2CircuitsVkTreeRoot,
-  ] = compressed.split('-');
+  const [versionVersion, l1ChainId, l1RollupAddress, rollupVersion, l2ProtocolContractsHash, l2CircuitsVkTreeRoot] =
+    compressed.split('-');
   if (versionVersion !== '00') {
     throw new ComponentsVersionsError('version', '00', versionVersion);
   }
@@ -82,14 +73,14 @@ export function checkCompressedComponentVersion(compressed: string, expected: Co
   if (l1RollupAddress !== expected.l1RollupAddress.toString().slice(2, 10)) {
     throw new ComponentsVersionsError(`L1 address`, expected.l1RollupAddress.toString(), l1RollupAddress);
   }
-  if (l2ChainVersion !== expected.l2ChainVersion.toString()) {
-    throw new ComponentsVersionsError('L2 chain version', expected.l2ChainVersion.toString(), l2ChainVersion);
+  if (rollupVersion !== expected.rollupVersion.toString()) {
+    throw new ComponentsVersionsError('L2 chain version', expected.rollupVersion.toString(), rollupVersion);
   }
-  if (l2ProtocolContractsTreeRoot !== expected.l2ProtocolContractsTreeRoot.toString().slice(2, 10)) {
+  if (l2ProtocolContractsHash !== expected.l2ProtocolContractsHash.toString().slice(2, 10)) {
     throw new ComponentsVersionsError(
       `L2 protocol contracts vk tree root`,
-      expected.l2ProtocolContractsTreeRoot.toString(),
-      l2ProtocolContractsTreeRoot,
+      expected.l2ProtocolContractsHash.toString(),
+      l2ProtocolContractsHash,
     );
   }
   if (l2CircuitsVkTreeRoot !== expected.l2CircuitsVkTreeRoot.toString().slice(2, 10)) {
@@ -108,10 +99,10 @@ export function validatePartialComponentVersionsMatch(
 ) {
   for (const key of [
     'l1RollupAddress',
-    'l2ProtocolContractsTreeRoot',
+    'l2ProtocolContractsHash',
     'l2CircuitsVkTreeRoot',
     'l1ChainId',
-    'l2ChainVersion',
+    'rollupVersion',
   ] as const) {
     const actualValue = actual[key];
     const expectedValue = expected[key];
@@ -124,13 +115,21 @@ export function validatePartialComponentVersionsMatch(
 }
 
 /** Returns a Koa middleware that injects the versioning info as headers. */
-export function getVersioningMiddleware(versions: Partial<ComponentsVersions>) {
+export function getVersioningMiddleware(versions: Partial<ComponentsVersions>, opts?: { packageVersion?: string }) {
   return async (ctx: Koa.Context, next: () => Promise<void>) => {
-    await next();
-    for (const key in versions) {
-      const value = versions[key as keyof ComponentsVersions];
-      if (value !== undefined) {
-        ctx.set(`x-aztec-${key}`, value.toString());
+    try {
+      await next();
+    } finally {
+      // Always add version headers, even if there was an error
+      // This allows the client to detect version mismatches before processing other errors
+      for (const key in versions) {
+        const value = versions[key as keyof ComponentsVersions];
+        if (value !== undefined) {
+          ctx.set(`x-aztec-${key}`, value.toString());
+        }
+      }
+      if (opts?.packageVersion) {
+        ctx.set('x-aztec-packageVersion', opts.packageVersion);
       }
     }
   };

package/src/vks/index.ts

@@ -1,2 +1,2 @@
 export * from './verification_key.js';
-export * from './vk_witness_data.js';
+export * from './vk_data.js';