feat: oracle version check (#16435)

benesjan · web-flow · commit 7534d8227fdd · 2025-09-02T06:34:02.000Z
Fixes #14979 This PR implements a version compatibility system between Aztec.nr contracts and the PXE oracle interface to prevent ambiguous errors from version mismatches. The oracle version is expected to be manually updated but to ensure that this does not get forgotten the build throws an error if an oracle interface hash constant needs updating.
diff --git a/noir-projects/aztec-nr/aztec/src/macros/functions/utils.nr b/noir-projects/aztec-nr/aztec/src/macros/functions/utils.nr
@@ -151,7 +151,9 @@ pub(crate) comptime fn transform_private(f: FunctionDefinition) {
 
     let context_finish = quote { context.finish() };
 
+    // A quote to be injected at the beginning of the function body.
     let to_prepend = quote {
+        dep::aztec::oracle::version::assert_compatible_oracle_version();
         $args_hasher
         $context_creation
         $assert_initializer
@@ -305,9 +307,9 @@ pub(crate) comptime fn transform_utility(f: FunctionDefinition) {
     // (`sync_private_state` function gets invoked by PXE::getPrivateEvents function).
     let message_discovery_call = create_message_discovery_call();
 
-    // Inject context creation, storage initialization, and message discovery call at the beginning of the function
-    // body.
+    // A quote to be injected at the beginning of the function body.
     let to_prepend = quote {
+        dep::aztec::oracle::version::assert_compatible_oracle_version();
         $context_creation
         $storage_init
         $message_discovery_call
@@ -375,7 +377,7 @@ pub(crate) comptime fn create_message_discovery_call() -> Quoted {
 ///   if (!from.eq(context.msg_sender())) {
 ///         assert_current_call_valid_authwit::<N>(&mut context, from);
 ///     } else {
-///         assert(authwit_nonce, "Invalid auhtwit nonce. When 'from' and 'msg_sender' are the same, authwit_nonce must be zero");
+///         assert(authwit_nonce, "Invalid authwit nonce. When 'from' and 'msg_sender' are the same, authwit_nonce must be zero");
 ///     }
 /// ```
 /// where `from` and `authwit_nonce` are the names of the parameters that are expected to be present in the function definition.
diff --git a/noir-projects/aztec-nr/aztec/src/oracle/mod.nr b/noir-projects/aztec-nr/aztec/src/oracle/mod.nr
@@ -22,6 +22,7 @@ pub mod logs;
 pub mod message_processing;
 pub mod notes;
 pub mod offchain_effect;
+pub mod version;
 pub mod random;
 pub mod shared_secret;
 pub mod storage;
diff --git a/noir-projects/aztec-nr/aztec/src/oracle/version.nr b/noir-projects/aztec-nr/aztec/src/oracle/version.nr
@@ -0,0 +1,38 @@
+/// The ORACLE_VERSION constant is used to check that the oracle interface is in sync between PXE and Aztec.nr. We need
+/// to version the oracle interface to ensure that developers get a reasonable error message if they use incompatible
+/// versions of Aztec.nr and PXE. The TypeScript counterpart is in `oracle_version.ts`.
+///
+/// @dev Whenever a contract function or Noir test is run, the `utilityAssertCompatibleOracleVersion` oracle is called and
+/// if the oracle version is incompatible an error is thrown.
+pub global ORACLE_VERSION: Field = 1;
+
+/// Asserts that the version of the oracle is compatible with the version expected by the contract.
+pub fn assert_compatible_oracle_version() {
+    // Safety: This oracle call returns nothing: we only call it to check Aztec.nr and Oracle interface versions are
+    // compatible. It is therefore always safe to call.
+    unsafe {
+        assert_compatible_oracle_version_wrapper();
+    }
+}
+
+unconstrained fn assert_compatible_oracle_version_wrapper() {
+    assert_compatible_oracle_version_oracle(ORACLE_VERSION);
+}
+
+#[oracle(utilityAssertCompatibleOracleVersion)]
+unconstrained fn assert_compatible_oracle_version_oracle(version: Field) {}
+
+mod test {
+    use super::{assert_compatible_oracle_version_oracle, ORACLE_VERSION};
+
+    #[test]
+    unconstrained fn compatible_oracle_version() {
+        assert_compatible_oracle_version_oracle(ORACLE_VERSION);
+    }
+
+    #[test(should_fail_with = "Incompatible oracle version. PXE is using version '1', but got a request for '318183437'.")]
+    unconstrained fn incompatible_oracle_version() {
+        let arbitrary_incorrect_version = 318183437;
+        assert_compatible_oracle_version_oracle(arbitrary_incorrect_version);
+    }
+}
diff --git a/noir-projects/aztec-nr/aztec/src/test/helpers/test_environment.nr b/noir-projects/aztec-nr/aztec/src/test/helpers/test_environment.nr
@@ -9,7 +9,11 @@ use crate::{
         ReturnsHash, UtilityCallInterface, UtilityContext,
     },
     hash::hash_args,
-    oracle::{execution::{get_block_number, get_timestamp}, execution_cache},
+    oracle::{
+        execution::{get_block_number, get_timestamp},
+        execution_cache,
+        version::assert_compatible_oracle_version,
+    },
     test::helpers::{txe_oracles, utils::ContractDeployment},
 };
 
@@ -102,6 +106,7 @@ impl PrivateContextOptions {
 impl TestEnvironment {
     /// Creates a new `TestEnvironment`. This function should only be called once per test.
     pub unconstrained fn new() -> Self {
+        assert_compatible_oracle_version();
         Self {
             light_account_secret: Counter::new(),
             contract_account_secret: Counter::new(),
diff --git a/noir-projects/aztec-nr/aztec/src/test/helpers/test_environment/test.nr b/noir-projects/aztec-nr/aztec/src/test/helpers/test_environment/test.nr
@@ -1,4 +1,5 @@
-use crate::test::helpers::test_environment::TestEnvironment;
+use crate::{oracle::version::ORACLE_VERSION, test::helpers::test_environment::TestEnvironment};
+use std::test::OracleMock;
 
 mod accounts;
 mod deployment;
@@ -310,3 +311,13 @@ unconstrained fn private_public_and_utility_context_share_default_chain_id() {
     assert_eq(private_chain_id, public_chain_id);
     assert_eq(private_chain_id, utility_chain_id);
 }
+
+#[test]
+unconstrained fn oracle_version_is_checked_upon_env_creation() {
+    let mock = OracleMock::mock("utilityAssertCompatibleOracleVersion");
+
+    let _env = TestEnvironment::new();
+
+    assert_eq(mock.times_called(), 1);
+    assert_eq(mock.get_last_params::<Field>(), ORACLE_VERSION);
+}
diff --git a/noir-projects/noir-contracts/Nargo.toml b/noir-projects/noir-contracts/Nargo.toml
@@ -46,6 +46,7 @@ members = [
     "contracts/test/no_constructor_contract",
     "contracts/test/note_getter_contract",
     "contracts/test/offchain_effect_contract",
+    "contracts/test/oracle_version_check_contract",
     "contracts/test/parent_contract",
     "contracts/test/pending_note_hashes_contract",
     "contracts/test/public_immutable_contract",
diff --git a/noir-projects/noir-contracts/contracts/test/oracle_version_check_contract/Nargo.toml b/noir-projects/noir-contracts/contracts/test/oracle_version_check_contract/Nargo.toml
@@ -0,0 +1,8 @@
+[package]
+name = "oracle_version_check_contract"
+authors = [""]
+compiler_version = ">=0.25.0"
+type = "contract"
+
+[dependencies]
+aztec = { path = "../../../../aztec-nr/aztec" }
diff --git a/noir-projects/noir-contracts/contracts/test/oracle_version_check_contract/src/main.nr b/noir-projects/noir-contracts/contracts/test/oracle_version_check_contract/src/main.nr
@@ -0,0 +1,17 @@
+use aztec::macros::aztec;
+
+/// Used to test that the oracle version check is performed when a private or utility function is called.
+#[aztec]
+pub contract OracleVersionCheck {
+    use aztec::macros::functions::{private, utility};
+
+    #[private]
+    fn private_function() -> Field {
+        0
+    }
+
+    #[utility]
+    unconstrained fn utility_function() -> Field {
+        0
+    }
+}
diff --git a/yarn-project/bootstrap.sh b/yarn-project/bootstrap.sh
@@ -70,6 +70,10 @@ function compile_all {
 
   get_projects | compile_project
 
+  # Run oracle version check for pxe after compilation
+  cd pxe && yarn check_oracle_version
+  cd ..
+
   cmds=('format --check')
   if [ "${TYPECHECK:-0}" -eq 1 ] || [ "${CI:-0}" -eq 1 ]; then
     # Fully type check and lint.
diff --git a/yarn-project/pxe/package.json b/yarn-project/pxe/package.json
@@ -17,7 +17,8 @@
     "clean": "rm -rf ./dest .tsbuildinfo ./src/config/package_info.ts",
     "test": "NODE_NO_WARNINGS=1 node --experimental-vm-modules ../node_modules/.bin/jest --passWithNoTests --maxWorkers=${JEST_MAX_WORKERS:-8}",
     "start": "LOG_LEVEL=${LOG_LEVEL:-debug} && node ./dest/bin/index.js",
-    "generate": "node ./scripts/generate_package_info.js"
+    "generate": "node ./scripts/generate_package_info.js",
+    "check_oracle_version": "node ./dest/bin/check_oracle_version.js"
   },
   "inherits": [
     "../package.common.json",
@@ -75,6 +76,7 @@
     "@aztec/protocol-contracts": "workspace:^",
     "@aztec/simulator": "workspace:^",
     "@aztec/stdlib": "workspace:^",
+    "json-stringify-deterministic": "1.0.12",
     "koa": "^2.16.1",
     "koa-router": "^12.0.0",
     "lodash.omit": "^4.5.0",
diff --git a/yarn-project/pxe/src/bin/check_oracle_version.ts b/yarn-project/pxe/src/bin/check_oracle_version.ts
@@ -0,0 +1,36 @@
+import { keccak256String } from '@aztec/foundation/crypto';
+
+import deterministicStringify from 'json-stringify-deterministic';
+
+import { Oracle } from '../contract_function_simulator/oracle/oracle.js';
+import { TypedOracle } from '../contract_function_simulator/oracle/typed_oracle.js';
+import { ORACLE_INTERFACE_HASH } from '../oracle_version.js';
+
+// Create a minimal mock implementation of TypedOracle to instantiate the Oracle class for interface verification.
+class OracleMock extends TypedOracle {}
+
+/**
+ * Verifies that the Oracle interface matches the expected interface hash.
+ *
+ * The Oracle interface needs to be versioned to ensure compatibility between Aztec.nr and PXE. This function computes
+ * a hash of the Oracle interface and compares it against a known hash. If they don't match, it means the interface has
+ * changed and the ORACLE_VERSION constant needs to be incremented and the ORACLE_INTERFACE_HASH constant needs to be
+ * updated.
+ *
+ * TODO(#16581): The following only takes into consideration changes to the oracles defined in Oracle.ts and omits TXE
+ * oracles. Ensure this checks TXE oracles as well. This hasn't been implemented yet since we don't have a clean TXE
+ * oracle interface like we do in PXE (i.e., there is no single Oracle class that contains only the oracles).
+ */
+function assertOracleInterfaceMatches(): void {
+  const oracle = new Oracle(new OracleMock());
+  // We use keccak256 here just because we already have it in the dependencies.
+  const oracleInterfaceHash = keccak256String(deterministicStringify(oracle.toACIRCallback()));
+  if (oracleInterfaceHash !== ORACLE_INTERFACE_HASH) {
+    // This check exists only to notify you when you need to update the ORACLE_VERSION constant.
+    throw new Error(
+      `The TypedOracle interface has changed, which implies a breaking change in the aztec.nr/PXE oracle interface. Update ORACLE_INTERFACE_HASH to ${oracleInterfaceHash} and bump ORACLE_VERSION in pxe/src/oracle_version.ts.`,
+    );
+  }
+}
+
+assertOracleInterfaceMatches();
diff --git a/yarn-project/pxe/src/contract_function_simulator/execution_data_provider.ts b/yarn-project/pxe/src/contract_function_simulator/execution_data_provider.ts
@@ -208,6 +208,12 @@ export interface ExecutionDataProvider {
    */
   getBlock(blockNumber: number): Promise<L2Block | undefined>;
 
+  /**
+   * Assert that the oracle version is compatible with the expected version.
+   * @param version - The expected version.
+   */
+  assertCompatibleOracleVersion(version: number): void;
+
   /**
    * Fetches the latest block number synchronized by the node.
    * @returns The block number.
diff --git a/yarn-project/pxe/src/contract_function_simulator/oracle/oracle.ts b/yarn-project/pxe/src/contract_function_simulator/oracle/oracle.ts
@@ -57,6 +57,11 @@ export class Oracle {
     }, {} as ACIRCallback);
   }
 
+  utilityAssertCompatibleOracleVersion([version]: ACVMField[]) {
+    this.typedOracle.utilityAssertCompatibleOracleVersion(Fr.fromString(version).toNumber());
+    return Promise.resolve([]);
+  }
+
   utilityGetRandomField(): Promise<ACVMField[]> {
     const val = this.typedOracle.utilityGetRandomField();
     return Promise.resolve([toACVMField(val)]);
diff --git a/yarn-project/pxe/src/contract_function_simulator/oracle/oracle_version_is_checked.test.ts b/yarn-project/pxe/src/contract_function_simulator/oracle/oracle_version_is_checked.test.ts
@@ -0,0 +1,108 @@
+import { Fr } from '@aztec/foundation/fields';
+import { OracleVersionCheckContractArtifact } from '@aztec/noir-test-contracts.js/OracleVersionCheck';
+import { WASMSimulator } from '@aztec/simulator/client';
+import { FunctionCall, FunctionSelector, FunctionType, encodeArguments } from '@aztec/stdlib/abi';
+import { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { ContractInstance } from '@aztec/stdlib/contract';
+import { GasFees, GasSettings } from '@aztec/stdlib/gas';
+import { BlockHeader, HashedValues, TxContext, TxExecutionRequest } from '@aztec/stdlib/tx';
+
+import { mock } from 'jest-mock-extended';
+
+import { ContractFunctionSimulator } from '../contract_function_simulator.js';
+import type { ExecutionDataProvider } from '../execution_data_provider.js';
+
+describe('Oracle Version Check test suite', () => {
+  const simulator = new WASMSimulator();
+
+  let executionDataProvider: ReturnType<typeof mock<ExecutionDataProvider>>;
+  let acirSimulator: ContractFunctionSimulator;
+  let contractAddress: AztecAddress;
+
+  beforeEach(async () => {
+    executionDataProvider = mock<ExecutionDataProvider>();
+
+    // Mock basic oracle responses
+    executionDataProvider.getChainId.mockResolvedValue(1);
+    executionDataProvider.getVersion.mockResolvedValue(1);
+    executionDataProvider.getTimestamp.mockResolvedValue(0n);
+    executionDataProvider.getBlockNumber.mockResolvedValue(1);
+    executionDataProvider.getPublicStorageAt.mockResolvedValue(Fr.ZERO);
+    executionDataProvider.loadCapsule.mockImplementation((_, __) => Promise.resolve(null));
+    executionDataProvider.getBlockHeader.mockResolvedValue(BlockHeader.empty());
+    executionDataProvider.getContractInstance.mockResolvedValue({
+      currentContractClassId: new Fr(42),
+      originalContractClassId: new Fr(42),
+    } as ContractInstance);
+
+    acirSimulator = new ContractFunctionSimulator(executionDataProvider, simulator);
+    contractAddress = await AztecAddress.random();
+  });
+
+  describe('private function execution', () => {
+    it('should call assertCompatibleOracleVersion oracle when private function is called', async () => {
+      // Load the artifact of the OracleVersionCheck::private_function contract function and set up the relevant oracle handler
+      const privateFunctionArtifact = {
+        ...OracleVersionCheckContractArtifact.functions.find(f => f.name === 'private_function')!,
+        contractName: OracleVersionCheckContractArtifact.name,
+      };
+      executionDataProvider.getFunctionArtifact.mockResolvedValue(privateFunctionArtifact);
+
+      // Form the execution request for the private function
+      const selector = await FunctionSelector.fromNameAndParameters(
+        'private_function',
+        privateFunctionArtifact.parameters,
+      );
+      const hashedArguments = await HashedValues.fromArgs(encodeArguments(privateFunctionArtifact, []));
+      const txRequest = TxExecutionRequest.from({
+        origin: contractAddress,
+        firstCallArgsHash: hashedArguments.hash,
+        functionSelector: selector,
+        txContext: TxContext.from({
+          chainId: new Fr(10),
+          version: new Fr(20),
+          gasSettings: GasSettings.default({ maxFeesPerGas: new GasFees(10, 10) }),
+        }),
+        argsOfCalls: [hashedArguments],
+        authWitnesses: [],
+        capsules: [],
+        salt: Fr.random(),
+      });
+
+      // Call the private function with arbitrary message sender and sender for tags
+      const msgSender = await AztecAddress.random();
+      const senderForTags = await AztecAddress.random();
+      await acirSimulator.run(txRequest, contractAddress, selector, msgSender, senderForTags);
+
+      expect(executionDataProvider.assertCompatibleOracleVersion).toHaveBeenCalledTimes(1);
+    }, 30_000);
+  });
+
+  describe('utility function execution', () => {
+    it('should call assertCompatibleOracleVersion oracle when utility function is called', async () => {
+      // Load the artifact of the OracleVersionCheck::utility_function contract function and set up the relevant oracle
+      // handler
+      const utilityFunctionArtifact = {
+        ...OracleVersionCheckContractArtifact.functions.find(f => f.name === 'utility_function')!,
+        contractName: OracleVersionCheckContractArtifact.name,
+      };
+      executionDataProvider.getFunctionArtifact.mockResolvedValue(utilityFunctionArtifact);
+
+      // Form the execution request for the utility function
+      const execRequest: FunctionCall = {
+        name: utilityFunctionArtifact.name,
+        to: contractAddress,
+        selector: FunctionSelector.empty(),
+        type: FunctionType.UTILITY,
+        isStatic: false,
+        args: encodeArguments(utilityFunctionArtifact, []),
+        returnTypes: utilityFunctionArtifact.returnTypes,
+      };
+
+      // Call the utility function
+      await acirSimulator.runUtility(execRequest, [], []);
+
+      expect(executionDataProvider.assertCompatibleOracleVersion).toHaveBeenCalledTimes(1);
+    }, 30_000);
+  });
+});
diff --git a/yarn-project/pxe/src/contract_function_simulator/oracle/typed_oracle.ts b/yarn-project/pxe/src/contract_function_simulator/oracle/typed_oracle.ts
@@ -44,6 +44,10 @@ class OracleMethodNotAvailableError extends Error {
  * and are unavailable by default.
  */
 export abstract class TypedOracle {
+  utilityAssertCompatibleOracleVersion(_version: number): void {
+    throw new OracleMethodNotAvailableError('utilityAssertCompatibleOracleVersion');
+  }
+
   utilityGetRandomField(): Fr {
     throw new OracleMethodNotAvailableError('utilityGetRandomField');
   }
diff --git a/yarn-project/pxe/src/contract_function_simulator/oracle/utility_execution_oracle.ts b/yarn-project/pxe/src/contract_function_simulator/oracle/utility_execution_oracle.ts
@@ -32,6 +32,10 @@ export class UtilityExecutionOracle extends TypedOracle {
     super();
   }
 
+  public override utilityAssertCompatibleOracleVersion(version: number): void {
+    this.executionDataProvider.assertCompatibleOracleVersion(version);
+  }
+
   public override utilityGetRandomField(): Fr {
     return Fr.random();
   }
diff --git a/yarn-project/pxe/src/contract_function_simulator/pxe_oracle_interface.ts b/yarn-project/pxe/src/contract_function_simulator/pxe_oracle_interface.ts
@@ -34,6 +34,7 @@ import type { UInt64 } from '@aztec/stdlib/types';
 
 import type { ExecutionDataProvider, ExecutionStats } from '../contract_function_simulator/execution_data_provider.js';
 import { MessageLoadOracleInputs } from '../contract_function_simulator/oracle/message_load_oracle_inputs.js';
+import { ORACLE_VERSION } from '../oracle_version.js';
 import type { AddressDataProvider } from '../storage/address_data_provider/address_data_provider.js';
 import type { CapsuleDataProvider } from '../storage/capsule_data_provider/capsule_data_provider.js';
 import type { ContractDataProvider } from '../storage/contract_data_provider/contract_data_provider.js';
@@ -232,6 +233,12 @@ export class PXEOracleInterface implements ExecutionDataProvider {
     return this.syncDataProvider.getBlockHeader();
   }
 
+  public assertCompatibleOracleVersion(version: number): void {
+    if (version !== ORACLE_VERSION) {
+      throw new Error(`Incompatible oracle version. Expected version ${ORACLE_VERSION}, got ${version}.`);
+    }
+  }
+
   /**
    * Fetches the latest block number synchronized by the node.
    * @returns The block number.
diff --git a/yarn-project/pxe/src/entrypoints/server/index.ts b/yarn-project/pxe/src/entrypoints/server/index.ts
diff --git a/yarn-project/pxe/src/oracle_version.ts b/yarn-project/pxe/src/oracle_version.ts
diff --git a/yarn-project/txe/src/oracle/txe_oracle.ts b/yarn-project/txe/src/oracle/txe_oracle.ts
diff --git a/yarn-project/txe/src/txe_service/txe_service.ts b/yarn-project/txe/src/txe_service/txe_service.ts
diff --git a/yarn-project/yarn.lock b/yarn-project/yarn.lock
