feat(gtest): ethexe support

[playX18]

Closes #5404

Summary

Adds support for ethexe execution model to gtest

How to test

Run cargo nextest run -p gtest

Checklist

• PR title follows Conventional Commits (type(scope): description)
• Single logical change
• Tests added or updated (if logic changed)
• Docs updated (if needed)

---

Note

Medium Risk
Adds a second execution backend that changes how System and Program run blocks/messages and introduces new balance semantics; mistakes could cause tests to behave differently or hide regressions. Scope is contained to gtest and gated behind System::builder().execution_model(ExecutionModel::Ethexe).

Overview
Adds an opt-in ethexe execution model to gtest, letting tests run code processing and block execution through the real ethexe-processor backed by an in-memory ethexe-db (selected via System::builder().execution_model(ExecutionModel::Ethexe)).

Introduces an EthexeManager that stores/instruments code, registers programs, queues canonical events and injected transactions, executes blocks, and supports non-committing calculate_reply_for_handle; System/Program APIs now route queue_len, block execution, program lookup, message sending, and balance queries based on the selected model.

Extends BlockRunResult with ethexe_executable_balance_burned, adds helpers for ethexe executable/owned balance top-ups plus raw event/tx injection, updates docs and dev-deps (including demo-ping ethexe feature), and adds unit tests covering ethexe mode behavior and charging.

^{Reviewed by Cursor Bugbot for commit 311f869. Bugbot is set up for automated code reviews on this repo. Configure here.}

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
gtest/src/system.rs	3% smaller
Cargo.lock	Unsupported file format
gtest/Cargo.toml	Unsupported file format
gtest/src/ethexe.rs	0% smaller
gtest/src/lib.rs	Unsupported file format
gtest/src/log.rs	0% smaller
gtest/src/manager/block_exec.rs	0% smaller
gtest/src/program.rs	0% smaller
utils/gear-workspace-hack/Cargo.toml	Unsupported file format

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces support for the ethexe execution model within the gtest testing framework. By allowing users to opt into this model via a new SystemBuilder, the changes enable testing of ethexe-based programs using an in-memory database and the real ethexe processor. This includes necessary infrastructure for managing ethexe-specific state, balances, and message handling, ensuring that gtest remains a versatile tool for various execution environments.

Highlights

• Ethexe Execution Model Support: Added support for the ethexe execution model within the gtest framework, allowing developers to test ethexe-based programs.
• SystemBuilder Implementation: Introduced SystemBuilder to allow users to opt into the ethexe execution model during system initialization.
• EthexeManager Integration: Implemented EthexeManager to handle ethexe-specific block execution, state management, and message processing.
• System and Program Updates: Updated System and Program components to route execution and state management through the ethexe processor when enabled.
• Testing and Verification: Added comprehensive unit tests to verify ethexe integration, including raw event processing and reply calculation.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[playX18]

@cursor review, @claude review, @codex review

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[gemini-code-assist]

Code Review

This pull request introduces an Ethexe execution model to the gtest framework, enabling Gear programs to be tested using the real ethexe processor and an in-memory database. Key changes include the implementation of EthexeManager, a SystemBuilder for selecting between Vara and Ethexe execution models, and updates to Program and System to route execution and state management accordingly. Feedback focuses on performance optimizations for the block_on runtime, ensuring consistency in block height and timestamps between the Vara and Ethexe managers, and addressing the reporting of gas burned and the handling of message gas limits in Ethexe mode.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 311f869. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a501da8ab2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[StackOverflowExcept1on]

After #5401 we can also pass SyscallKind depending on how gtest was created (with which ExecutionModel)

[playX18]

@claude review

[claude]

Claude finished @playX18's task in 3m 45s —— View job

---

Code Review

The PR is well-structured and the core design is sound. The EthexeManager implementation, block_on singleton, calculate_reply_for_handle overlay isolation, and run_to_block routing are all correct. A few real issues below.

---

severity: medium — executable_balance_of panics on non-program IDs in ethexe mode

File: gtest/src/system.rs lines 581–588, gtest/src/ethexe.rs lines 220–222

System::balance_of (line 569) guards with ethexe.borrow().is_program(actor_id) before delegating. System::executable_balance_of does not — it calls ethexe.borrow().executable_balance_of(id) unconditionally, which reaches self.state(actor_id), which panics with unwrap_or_else(|| panic!("ethexe program {actor_id} not found")) if id is a user ID or an unregistered actor. Any test that calls sys.executable_balance_of(some_user_id) in ethexe mode will get an opaque internal panic instead of a usage error.

// system.rs ~583 — missing is_program guard (compare to balance_of at line 569)
pub fn executable_balance_of<ID: Into<ProgramIdWrapper>>(&self, id: ID) -> Value {
    let id = id.into().0;
    if let Some(ethexe) = self.ethexe() {
        ethexe.borrow().executable_balance_of(id)  // panics if id is not a registered program
    } else {
        0
    }
}

Fix this →

---

severity: medium — gas_allowance_spent is always zero in ethexe block results; spent_value() returns 0

File: gtest/src/ethexe.rs line 406

BlockRunResult::gas_allowance_spent is hardcoded to 0 in the ethexe path. BlockRunResult::spent_value() is derived from gas_allowance_spent * GAS_MULTIPLIER, so it always returns 0 in ethexe mode even when balance was burned. Tests that assert on spent_value() (e.g. the Vara piggy_bank test pattern) will silently pass with 0 in ethexe mode, hiding real execution cost. The actual cost is available via ethexe_executable_balance_burned but the asymmetry is not called out in BlockRunResult's field docs.

At minimum the gas_allowance_spent field or spent_value() doc should note this is always 0 in ethexe mode, directing users to ethexe_executable_balance_burned. A stronger fix would approximate it from the burned value the same way gas_burned is approximated.

---

severity: low — inheritor_of silently returns None for all ethexe programs

File: gtest/src/system.rs lines 439–450

System::inheritor_of delegates unconditionally to ProgramsStorageManager, which has no knowledge of ethexe programs. In ethexe mode it always returns None regardless of actual program state. Unlike the other ethexe-unsupported helpers (get_mailbox, read_state_bytes, save_memory_dump) which call usage_panic!, this one fails silently. It should either panic or be documented.

---

severity: low — mint_to / transfer operate on Vara accounts in ethexe mode without warning

File: gtest/src/system.rs lines 533–564

Both methods work against Accounts (the Vara balance store) and are not guarded against ethexe mode. A user who calls sys.mint_to(program_id, value) expecting to fund ethexe execution will get no error, no effect on the ethexe executable_balance, and a confusing "Attempt to mint value to a program" panic only if the ID happens to be in ProgramsStorageManager. Given that ethexe programs are not registered there, the panic won't fire either — the call silently succeeds but has no effect on ethexe state.

---

Notes on prior automated review comments

Several automated findings were already correctly handled in this revision:

• block_on: uses OnceLock for a shared multi-thread runtime and correctly handles the nested-async case with thread::scope — already matches the Gemini suggestion.
• run_to_block in ethexe mode: the ethexe branch (lines 285–297) calls self.run_next_block_with_allowance which routes to EthexeManager, and tracks height via self.block_height() which reads from the ethexe manager. The Cursor/Codex finding that it "bypasses" ethexe is incorrect.
• is_active_program for exited programs: EthexeManager::is_active_program (line 199) reads ProgramState from the database and checks matches!(state.program, Program::Active(_)) — exited/terminated programs are correctly excluded. The Cursor finding is wrong.

[playX18]

@cursor review

[cursor]

You have used all of your free Bugbot PR reviews.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.