feat(pxe): implement minor/major oracle version tracking by benesjan · Pull Request #22254 · AztecProtocol/aztec-packages

benesjan · 2026-04-02T06:41:28Z

AI Summary

Implements F-507: minor/major oracle version tracking.

Splits ORACLE_VERSION (22) into ORACLE_VERSION_MAJOR (22) and ORACLE_VERSION_MINOR (0) on both Noir and TypeScript sides
Major version mismatch fails immediately (breaking changes must match exactly)
Minor version is stored by the PXE and used to provide enhanced error messages when an oracle callback is not found, indicating the contract likely needs a newer PXE/wallet version
Backward compatible: old contracts sending a single version field default to minor=0 via the optional parameter and legacy oracle mappings

Splits the oracle version from a single integer (22) into major.minor (22.0). Major version mismatches fail immediately (breaking changes). Minor version is stored and used to provide enhanced error messages when an oracle is not found - indicating the contract likely needs a newer PXE version. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Rename aztec_utl_assertCompatibleOracleVersion to aztec_utl_assertCompatibleOracleVersionV2 (2-arg: major, minor) - Add legacy mapping for old 1-arg oracle name - Improve "oracle not found" errors: suggest PXE upgrade when contract minor > PXE minor, suggest contract bug when PXE should support it - Add warning log when contract version is unexpectedly not set - Created F-546 to rename back on v5 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

benesjan · 2026-04-09T00:27:04Z

feat(pxe): implement minor/major oracle version tracking #22254 👈 (View in Graphite)
merge-train/fairies

This stack of pull requests is managed by Graphite. Learn more about stacking.

Co-authored-by: Martin Verzilli <martin@aztec-labs.com>

…r-oracle-version-tracking

mverzilli · 2026-04-09T08:58:55Z

+## Oracle versioning
+
+The set of oracles that the PXE exposes to private and utility functions is versioned, so that contracts can declare which oracles they expect to be available. Every contract compiled with `Aztec.nr` records the oracle version it was built against, and the PXE checks this version before executing any oracle call.
+
+The version uses two components, `major.minor`, with the following compatibility rules:
+
+- **`major`** must match exactly. A major bump is a breaking change — oracles were removed or their signatures changed — and a PXE on a different major cannot safely run the contract.
+- **`minor`** indicates additive changes (new oracles). The PXE uses a best-effort approach here: a contract compiled against a higher `minor` than the PXE supports is still allowed to run, and an error is only thrown if the contract actually invokes an oracle the PXE does not know about. In practice, a contract built with a newer Aztec.nr may not use any of the newly added oracles at all, in which case it runs fine on an older PXE.
+
+The canonical version constants live in the PXE (`ORACLE_VERSION_MAJOR` / `ORACLE_VERSION_MINOR` in `yarn-project/pxe/src/oracle_version.ts`) and in Aztec.nr (`noir-projects/aztec-nr/aztec/src/oracle/version.nr`). The two are kept in lockstep as part of each release.
+
+### Resolving a version mismatch
+
+If you see an error like _"Oracle '…' not found. … The contract was compiled with Aztec.nr oracle version X.Y, but this private execution environment only supports up to A.B"_, the contract uses oracle from a newer Aztec.nr than your PXE supports.
+
+To fix it, upgrade the software that ships the PXE (sandbox, wallet, or whatever embeds `@aztec/pxe`) to a release whose Aztec.nr version is at least as new as the one the contract was compiled with.
+
+If the PXE reports a version that _should_ include every oracle the contract needs but an oracle is still missing, that is a contract bug rather than a version problem and you should likely report it to the app developer.
+


Not sure this fits in a foundational topics doc. However we do need something to point at and we need to merge this soon so maybe we could track to move this somewhere else in a Linear issue?

Co-authored-by: Martin Verzilli <martin@aztec-labs.com>

…r-oracle-version-tracking

AztecBot · 2026-04-09T09:28:49Z

❌ Failed to cherry-pick to v4-next due to conflicts. (🤖) View backport run.

…#22254) Cherry-pick of d8c841d with conflicts in: - noir-projects/noir-contracts/contracts/protocol/aztec_sublib/src/oracle/version.nr

…tracking (#22432)

benesjan · 2026-04-09T10:30:25Z

Backport fixed in #22432

benesjan and others added 3 commits April 2, 2026 06:41

warning when contract version not set

bc20ef3

clarifying stuff

8087b2f

benesjan commented Apr 2, 2026

View reviewed changes

Comment thread yarn-project/pxe/src/contract_function_simulator/oracle/legacy_oracle_mappings.ts Outdated

benesjan and others added 2 commits April 2, 2026 07:39

AI slop revert

2f11cd4

benesjan commented Apr 2, 2026

View reviewed changes

Comment thread noir-projects/aztec-nr/aztec/src/oracle/version.nr

benesjan commented Apr 2, 2026

View reviewed changes

Comment thread noir-projects/noir-contracts/contracts/protocol/aztec_sublib/src/oracle/version.nr

benesjan commented Apr 2, 2026

View reviewed changes

Comment thread yarn-project/pxe/src/contract_function_simulator/oracle/legacy_oracle_mappings.ts

wip

ea30be2

benesjan commented Apr 2, 2026

View reviewed changes

Comment thread yarn-project/pxe/src/contract_function_simulator/oracle/utility_execution_oracle.ts Outdated

benesjan marked this pull request as ready for review April 2, 2026 08:25

benesjan requested a review from nventuro as a code owner April 2, 2026 08:25

benesjan requested review from mverzilli and removed request for nventuro April 2, 2026 08:25