feat(txe): add oracle versioning for test environment by nchamo · Pull Request #23285 · AztecProtocol/aztec-packages

nchamo · 2026-05-14T16:46:18Z

Why we are doing this

PXE already has oracle versioning: every contract function begins with an assertCompatibleOracleVersion call, and PXE stores the contract's major.minor so that unknown-oracle errors include an actionable hint. The TXE test environment had nothing equivalent — an unknown oracle just gave an opaque dispatch error with no version context.

Our fix

Mirrors the PXE pattern for TXE, with a separate version namespace (TXE_ORACLE_VERSION_MAJOR/MINOR) to track the TXE-specific oracle interface independently.

At startup (TestEnvironment::new()), a new aztec_txe_assertCompatibleOracleVersion oracle call enforces a strict major-version check. On mismatch:

PXE: Incompatible private environment version: The contract was compiled with a newer/older version of Aztec.nr than your private environment supports. [...] See /errors/8 (expected oracle major version X, got Y)
TXE: Incompatible test environment version: The test was compiled with a newer/older version of Aztec.nr than your test environment supports. [...] See /errors/12 (expected test oracle major version X, got Y)

When an unknown oracle is called, TXE uses the stored minor version for three-way diagnostics (same logic as PXE's Proxy-based handler):

Case 1 — no version stored (version check was never called):

PXE: Oracle 'X' not found and the contract's oracle version is unknown (the version check oracle was not called before 'X'). This usually means the contract was not compiled with the #[aztec] macro, which injects the version check as the first oracle call in every private/utility external function. If you're using a custom entry point, ensure assert_compatible_oracle_version() is called before any other oracle calls. See /errors/8
TXE: Unknown oracle 'X'. The test appears to have been compiled with an older version of Aztec.nr that does not support test environment oracle versioning. Recompile the test with a compatible version of Aztec.nr. See /errors/12

Case 2 — minor version too high (test needs oracles this env doesn't have):

PXE: Oracle 'X' not found. This usually means the contract requires a newer private execution environment than you have. Upgrade your private execution environment to a compatible version. The contract was compiled with Aztec.nr oracle version A.B, but this private execution environment only supports up to C.D. See /errors/8
TXE: Unknown oracle 'X'. The test was compiled with Aztec.nr test oracle version A.B, but this test environment only supports up to C.D. Upgrade your test environment to a compatible version. See /errors/12

Case 3 — versions compatible (likely a bug):

PXE: Oracle 'X' not found. The contract's oracle version (A.B) is compatible with this private execution environment (C.D), so all standard oracles should be available. This could mean the contract was compiled against a modified version of Aztec.nr, or that it references an oracle that does not exist. See /errors/8
TXE: Unknown oracle 'X'. The test's oracle version (A.B) is compatible with this test environment (C.D), so all standard oracles should be available. This could mean the test was compiled against a modified version of Aztec.nr, or that it references an oracle that does not exist.

Not yet implemented: automatically detecting changes to the TXE oracle interface (the CI hash check that PXE has in check_oracle_version.ts). TXE oracles are spread across rpc_translator.ts and session handlers rather than a single Oracle class, making it harder to extract a clean interface to hash. Tracked in F-667.

Fixes F-648

…/f-648-add-txe-version-oracle # Conflicts: # docs/netlify.toml

nchamo · 2026-05-14T17:22:50Z


 :::warning
-Always use `aztec test` instead of `nargo test`. The `TestEnvironment` requires the TXE (Test eXecution Environment) oracle resolver.
+Always use `aztec test` instead of `nargo test`. The `TestEnvironment` requires the test environment oracle resolver provided by the `aztec` CLI.


I'm trying to remove the term "TXE" from all user facing docs/errors

nventuro · 2026-05-14T17:51:27Z


 :::warning
-Always use `aztec test` instead of `nargo test`. The `TestEnvironment` requires the TXE (Test eXecution Environment) oracle resolver.
+Always use `aztec test` instead of `nargo test`. The `TestEnvironment` requires the test environment oracle resolver provided by the `aztec` CLI.


nventuro · 2026-05-14T17:54:54Z

+            ` The test was compiled with Aztec.nr test oracle version` +
+            ` ${this.txeOracleVersion.major}.${this.txeOracleVersion.minor}, but this test environment` +
+            ` only supports up to ${TXE_ORACLE_VERSION_MAJOR}.${TXE_ORACLE_VERSION_MINOR}.` +
+            ` Upgrade your test environment to a compatible version.` +


upgrade the aztec cli, not 'the test env'

nventuro · 2026-05-14T17:55:15Z

+            ' See https://docs.aztec.network/errors/12';
+        } else if (this.txeOracleVersion.minor > TXE_ORACLE_VERSION_MINOR) {
+          versionHint =
+            ` The test was compiled with Aztec.nr test oracle version` +


Tests are not compiled, rather 'the test uses aztecnr vx.y' etc

nventuro · 2026-05-14T17:55:34Z

+        let versionHint: string;
+        if (!this.txeOracleVersion) {
+          versionHint =
+            ' The test appears to have been compiled with an older version of Aztec.nr that does not' +


same comment re. test compilation. may make people think they need to recompile contracts, which they dont

nventuro · 2026-05-14T17:56:03Z

+            ` The test's oracle version (${this.txeOracleVersion.major}.${this.txeOracleVersion.minor})` +
+            ` is compatible with this test environment` +
+            ` (${TXE_ORACLE_VERSION_MAJOR}.${TXE_ORACLE_VERSION_MINOR}), so all standard oracles should` +
+            ` be available. This could mean the test was compiled against a modified version of Aztec.nr,` +
+            ` or that it references an oracle that does not exist.`;


i don't think this message clearly conveys that we don't know wtf is wrong

AztecBot · 2026-05-14T19:11:56Z

✅ Successfully backported to backport-to-v4-next-staging #23291.

BEGIN_COMMIT_OVERRIDE feat(txe): add oracle versioning for test environment (#23285) feat: add basic gas settings to testenv (#23289) END_COMMIT_OVERRIDE

nchamo added 2 commits May 14, 2026 13:39

feat(txe): add oracle versioning for test environment

a0f839e

Merge remote-tracking branch 'origin/merge-train/fairies' into nchamo…

af51d26

…/f-648-add-txe-version-oracle # Conflicts: # docs/netlify.toml

nchamo requested a review from nventuro as a code owner May 14, 2026 16:46

nchamo self-assigned this May 14, 2026

nchamo added 2 commits May 14, 2026 14:01

fix(txe): use correct logger field name in setTxeOracleVersion

f5869c8

test(txe): update txe_session tests for new oracle error messages

cc8d41b

nchamo added ci-no-fail-fast Sets NO_FAIL_FAST in the CI so the run is not aborted on the first failure backport-to-v4-next labels May 14, 2026

nchamo commented May 14, 2026

View reviewed changes

nchamo requested a review from dbanks12 May 14, 2026 17:46

nventuro reviewed May 14, 2026

View reviewed changes

refactor(txe): clarify oracle version error messages

f053db6

nventuro approved these changes May 14, 2026

View reviewed changes

nchamo merged commit 76b6290 into merge-train/fairies May 14, 2026
14 checks passed

nchamo deleted the nchamo/f-648-add-txe-version-oracle branch May 14, 2026 19:10

AztecBot pushed a commit that referenced this pull request May 14, 2026

feat(txe): add oracle versioning for test environment (#23285)

0d96fc3

This was referenced May 14, 2026

chore: Accumulated backports to v4-next #23291

Merged

feat: merge-train/fairies #23290

Open

nchamo added a commit that referenced this pull request May 14, 2026

chore: Accumulated backports to v4-next (#23291)

7fe3a2a

BEGIN_COMMIT_OVERRIDE feat(txe): add oracle versioning for test environment (#23285) feat: add basic gas settings to testenv (#23289) END_COMMIT_OVERRIDE

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(txe): add oracle versioning for test environment#23285

feat(txe): add oracle versioning for test environment#23285
nchamo merged 5 commits into
merge-train/fairiesfrom
nchamo/f-648-add-txe-version-oracle

nchamo commented May 14, 2026 •

edited

Loading

Uh oh!

nchamo May 14, 2026

Uh oh!

nventuro May 14, 2026

Uh oh!

nventuro May 14, 2026

Uh oh!

nventuro May 14, 2026

Uh oh!

nventuro May 14, 2026

Uh oh!

nventuro May 14, 2026

Uh oh!

nventuro May 14, 2026

Uh oh!

Uh oh!

AztecBot commented May 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

nchamo commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why we are doing this

Our fix

Uh oh!

nchamo May 14, 2026

Choose a reason for hiding this comment

Uh oh!

nventuro May 14, 2026

Choose a reason for hiding this comment

Uh oh!

nventuro May 14, 2026

Choose a reason for hiding this comment

Uh oh!

nventuro May 14, 2026

Choose a reason for hiding this comment

Uh oh!

nventuro May 14, 2026

Choose a reason for hiding this comment

Uh oh!

nventuro May 14, 2026

Choose a reason for hiding this comment

Uh oh!

nventuro May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AztecBot commented May 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nchamo commented May 14, 2026 •

edited

Loading