feat: stamping aztec version into contract artifacts (#22550)

Injects aztec stack version into Noir contract artifacts as it's a very
useful info for debugging and other purposes (like verifying our
backwards compatibility infra works).

Closes
[F-549](https://linear.app/aztec-labs/issue/F-549/include-aztecnr-and-stack-versions-in-contract-artifact)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

noir-projects/noir-contracts/bootstrap.sh

@@ -93,6 +93,20 @@ function get_contract_path {
 }
 export -f get_contract_path
 
+# Stamps the aztec version into a contract artifact JSON in place. Mirrors stampAztecVersion in
+# yarn-project/aztec/src/cli/cmds/compile.ts so monorepo-built artifacts match those produced by `aztec compile`.
+# On release builds (REF_NAME is valid semver) the tag without the leading "v" is used; otherwise "dev".
+function stamp_aztec_version {
+  local json_path=$1
+  # "dev" here corresponds to DEV_VERSION in yarn-project/stdlib/src/update-checker/dev_version.ts.
+  local version="dev"
+  semver check "$REF_NAME" 2>/dev/null && version="${REF_NAME#v}"
+  local tmp=$(mktemp)
+  jq --arg v "$version" '.aztec_version = $v' "$json_path" > "$tmp"
+  mv "$tmp" "$json_path"
+}
+export -f stamp_aztec_version
+
 # This compiles a noir contract, transpiles public functions, strips internal prefixes,
 # and generates verification keys for private functions via 'bb aztec_process'.
 # $1 is the input package name, $2 is the folder name (e.g. "contracts" or "examples")
@@ -113,6 +127,9 @@ function compile {
     $BB aztec_process -i $json_path
     cache_upload contract-$contract_hash.tar.gz $json_path
   fi
+  # Stamp the current version after the cache block so the field always matches the build's version, whether
+  # the artifact came from a fresh compile or a cache hit.
+  stamp_aztec_version "$json_path"
 }
 export -f compile
 

yarn-project/aztec.js/src/contract/contract.test.ts

@@ -8,6 +8,7 @@ import {
 } from '@aztec/stdlib/contract';
 import type { TxExecutionRequest, TxReceipt, UtilityExecutionResult } from '@aztec/stdlib/tx';
 import { OFFCHAIN_MESSAGE_IDENTIFIER } from '@aztec/stdlib/tx';
+import { DEV_VERSION } from '@aztec/stdlib/update-checker';
 
 import { type MockProxy, mock } from 'jest-mock-extended';
 
@@ -37,6 +38,7 @@ describe('Contract Class', () => {
 
   const defaultArtifact: ContractArtifact = {
     name: 'FooContract',
+    aztecVersion: DEV_VERSION,
     functions: [
       {
         name: 'bar',

yarn-project/aztec.js/src/contract/deploy_method.test.ts

@@ -5,6 +5,7 @@ import type { ContractInstanceWithAddress } from '@aztec/stdlib/contract';
 import { Gas } from '@aztec/stdlib/gas';
 import { PublicKeys } from '@aztec/stdlib/keys';
 import { OFFCHAIN_MESSAGE_IDENTIFIER, type OffchainEffect } from '@aztec/stdlib/tx';
+import { DEV_VERSION } from '@aztec/stdlib/update-checker';
 
 import { type MockProxy, mock } from 'jest-mock-extended';
 
@@ -18,6 +19,7 @@ describe('DeployMethod', () => {
 
   const artifact: ContractArtifact = {
     name: 'TestContract',
+    aztecVersion: DEV_VERSION,
     functions: [
       {
         name: 'constructor',

yarn-project/aztec.js/src/scripts/generate_protocol_contract_types.ts

@@ -63,6 +63,7 @@ function generateProtocolContractArtifact(input: ContractArtifact): string {
 
   return `{
   name: '${input.name}',
+  aztecVersion: '${input.aztecVersion}',
   functions: [
     ${functionsArray}
   ],

yarn-project/aztec.js/src/wallet/wallet.test.ts

@@ -18,6 +18,7 @@ import {
   TxSimulationResult,
   UtilityExecutionResult,
 } from '@aztec/stdlib/tx';
+import { DEV_VERSION } from '@aztec/stdlib/update-checker';
 
 import {
   type InteractionWaitOptions,
@@ -126,6 +127,7 @@ describe('WalletSchema', () => {
   it('registerContract', async () => {
     const mockArtifact: ContractArtifact = {
       name: 'TestContract',
+      aztecVersion: DEV_VERSION,
       functions: [],
       nonDispatchPublicFunctions: [],
       outputs: { structs: {}, globals: {} },
@@ -318,6 +320,7 @@ describe('WalletSchema', () => {
 
     const mockArtifact: ContractArtifact = {
       name: 'TestContract',
+      aztecVersion: DEV_VERSION,
       functions: [],
       nonDispatchPublicFunctions: [],
       outputs: { structs: {}, globals: {} },

yarn-project/aztec/src/cli/cmds/compile.ts

@@ -1,9 +1,10 @@
 import { findBbBinary } from '@aztec/bb.js';
 import type { LogFn } from '@aztec/foundation/log';
+import { getPackageVersion } from '@aztec/stdlib/update-checker';
 
 import { execFileSync } from 'child_process';
 import type { Command } from 'commander';
-import { readFile } from 'fs/promises';
+import { readFile, writeFile } from 'fs/promises';
 import { join } from 'path';
 
 import { readArtifactFiles } from './utils/artifacts.js';
@@ -25,6 +26,17 @@ async function collectContractArtifacts(): Promise<string[]> {
   return files.filter(f => Array.isArray(f.content.functions)).map(f => f.filePath);
 }
 
+/** Stamps the Aztec stack version into the contract artifacts. */
+async function stampAztecVersion(artifactPaths: string[]): Promise<void> {
+  const version = getPackageVersion();
+  for (const path of artifactPaths) {
+    const artifact = JSON.parse(await readFile(path, 'utf-8'));
+    // eslint-disable-next-line camelcase
+    artifact.aztec_version = version;
+    await writeFile(path, JSON.stringify(artifact, null, 2) + '\n');
+  }
+}
+
 /** Returns the set of package names that are contract crates in the current workspace. */
 async function getContractPackageNames(): Promise<Set<string>> {
   const contractNames = new Set<string>();
@@ -148,6 +160,8 @@ async function compileAztecContract(nargoArgs: string[], log: LogFn): Promise<vo
     log('Postprocessing contracts...');
     const bbArgs = artifacts.flatMap(a => ['-i', a]);
     await run(bb, ['aztec_process', ...bbArgs]);
+
+    await stampAztecVersion(artifacts);
   }
 
   log('Compilation complete!');

yarn-project/end-to-end/src/fixtures/setup.ts

@@ -47,6 +47,7 @@ import { protocolContractsHash } from '@aztec/protocol-contracts';
 import type { ProverNodeConfig } from '@aztec/prover-node';
 import { type PXEConfig, getPXEConfig } from '@aztec/pxe/server';
 import type { SequencerClient } from '@aztec/sequencer-client';
+import { ARTIFACT_VERSION_BEFORE_INJECTION } from '@aztec/stdlib/abi';
 import { type ContractInstanceWithAddress, getContractInstanceFromInstantiationParams } from '@aztec/stdlib/contract';
 import type { AztecNodeAdmin, AztecNodeDebug } from '@aztec/stdlib/interfaces/client';
 import { tryStop } from '@aztec/stdlib/interfaces/server';
@@ -260,6 +261,32 @@ export type EndToEndContext = {
   teardown: () => Promise<void>;
 };
 
+/**
+ * When CONTRACT_ARTIFACTS_VERSION is set (backwards compatibility testing), asserts that the loaded artifact's
+ * aztecVersion matches the expected version. This is a sanity check verifying that the legacy artifact resolver
+ * actually swapped in the correct version.
+ */
+function assertContractArtifactsVersion() {
+  const expected = process.env.CONTRACT_ARTIFACTS_VERSION;
+  if (!expected) {
+    return;
+  }
+  const { aztecVersion } = SponsoredFPCContract.artifact;
+  // TODO(F-557): Remove this bypass once pre-version artifacts are no longer tested.
+  if (aztecVersion === ARTIFACT_VERSION_BEFORE_INJECTION) {
+    createLogger('e2e:setup').info(
+      `Skipping artifact version check: artifact predates version injection (CONTRACT_ARTIFACTS_VERSION=${expected})`,
+    );
+    return;
+  }
+  if (aztecVersion !== expected) {
+    throw new Error(
+      `Artifact version mismatch: expected ${expected} but got ${aztecVersion}. ` +
+        `The legacy artifact resolver may not have swapped in the correct version.`,
+    );
+  }
+}
+
 /**
  * Sets up the environment for the end-to-end tests.
  * @param numberOfAccounts - The number of new accounts to be created once the PXE is initiated.
@@ -272,6 +299,7 @@ export async function setup(
   pxeOpts: Partial<PXEConfig> = {},
   chain: Chain = foundry,
 ): Promise<EndToEndContext> {
+  assertContractArtifactsVersion();
   let anvil: Anvil | undefined;
   try {
     opts.aztecTargetCommitteeSize ??= 0;

yarn-project/stdlib/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. */
@@ -384,11 +385,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[];
 
@@ -411,6 +418,7 @@ 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({
@@ -604,6 +612,7 @@ export function emptyFunctionArtifact(): FunctionArtifact {
 export function emptyContractArtifact(): ContractArtifact {
   return {
     name: '',
+    aztecVersion: DEV_VERSION,
     functions: [emptyFunctionArtifact()],
     nonDispatchPublicFunctions: [emptyFunctionAbi()],
     outputs: {

yarn-project/stdlib/src/abi/contract_artifact.ts

@@ -12,6 +12,7 @@ import {
 import {
   type ABIParameter,
   type ABIParameterVisibility,
+  ARTIFACT_VERSION_BEFORE_INJECTION,
   type AbiType,
   type BasicValue,
   type ContractArtifact,
@@ -51,6 +52,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);
@@ -276,10 +281,9 @@ function getStorageLayout(input: NoirCompiledContract) {
 }
 
 /**
- * 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 {
@@ -288,6 +292,7 @@ function generateContractArtifact(contract: NoirCompiledContract): ContractArtif
     }
     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))
@@ -302,15 +307,15 @@ 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 {
     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))

yarn-project/stdlib/src/contract/artifact_hash.test.ts

@@ -1,5 +1,6 @@
 import type { ContractArtifact } from '../abi/index.js';
 import { getTestContractArtifact } from '../tests/fixtures.js';
+import { DEV_VERSION } from '../update-checker/dev_version.js';
 import { computeArtifactHash } from './artifact_hash.js';
 
 describe('ArtifactHash', () => {
@@ -9,6 +10,7 @@ describe('ArtifactHash', () => {
       functions: [],
       nonDispatchPublicFunctions: [],
       name: 'Test',
+      aztecVersion: DEV_VERSION,
       outputs: {
         globals: {},
         structs: {},