feat(ethexe-rpc): add top-up option for reply calculation

[playX18]

Closes #5332

Summary

Adds a with_top_up parameter to the program_calculateReplyForHandle RPC so callers can optionally calculate replies for programs with depleted executable balance.

When enabled, the processor performs an internal overlay-only executable balance top-up before executing the query. Existing behavior remains unchanged when with_top_up is
false. The SDK also exposes an opt-in helper for top-up reply calculation.

How to test

cargo fmt
cargo check -p ethexe-rpc -p ethexe-sdk -p ethexe-processor
cargo test -p ethexe-processor overlay_execution_with_top_up_works_for_depleted_programs
cargo test -p ethexe-rpc

Notes

The RPC signature changes by adding the with_top_up boolean parameter. Existing SDK behavior remains unchanged through the default calculate_reply_for_handle path.

Checklist

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

[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 an optional top-up mechanism for reply calculations in the ethexe-rpc layer. By adding a with_top_up parameter, callers can now perform an internal overlay-only balance top-up for programs that have depleted their executable balance, ensuring that reply calculations can proceed even when funds are low. This change enhances the robustness of the RPC interface and provides better flexibility for SDK users.

Highlights

• RPC Update: Added a with_top_up boolean parameter to the program_calculateReplyForHandle RPC method to allow optional executable balance top-ups.
• Processor Logic: Implemented internal overlay-only executable balance top-up logic in the processor, triggered when with_top_up is enabled.
• SDK Helper: Exposed a new calculate_reply_for_handle_with_top_up helper method in the SDK for easier access to the top-up functionality.
• Testing: Added a new test case overlay_execution_with_top_up_works_for_depleted_programs to verify that programs with depleted balances can successfully process replies when the top-up option is used.

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. ↩

[gemini-code-assist]

Code Review

This pull request introduces support for executing programs with an automatic balance top-up during overlay execution for replies. It adds a with_top_up flag to the execution payload, handles the corresponding top-up event generation in the processor, and exposes this functionality via the RPC and SDK layers. The review feedback correctly points out that adding with_top_up: bool as a mandatory parameter to the JSON-RPC method is a breaking change for existing clients. It is recommended to change this parameter to Option<bool> to maintain backwards compatibility, defaulting to false when omitted.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[playX18]

@claude review, @codex review

[claude]

Claude finished @playX18's task in 1m 56s —— View job

---

PR Review: feat(ethexe-rpc): add top-up option for reply calculation

• Gathering context and reading changed files
• Analyzing changes
• Writing review

---

Summary

This PR adds an optional with_top_up boolean to program_calculateReplyForHandle so callers can simulate execution for programs whose executable_balance has been depleted. When enabled, the processor injects a synthetic ExecutableBalanceTopUpRequested event (overlay-only) before the MessageQueueingRequested event, funding the program just enough to run the query. On-chain state is never touched.

The implementation is clean and the approach is sound. A few findings below.

---

medium: calculate_reply_for_handle_at is a breaking SDK API change

ethexe/sdk/src/mirror.rs, calculate_reply_for_handle_at (line ~124)

The public method gained a required with_top_up: bool parameter. Any downstream SDK user who calls calculate_reply_for_handle_at directly will fail to compile after upgrading. The two convenience wrappers (calculate_reply_for_handle and the new calculate_reply_for_handle_with_top_up) insulate most callers, but the underlying method being public makes this a semver-breaking change that should be explicitly noted if ethexe-sdk follows versioning semantics. Consider making the helper private or deprecating it, or at minimum call it out in the PR description.

---

low: with_top_up is absent from the Display format on ExecutableDataForReply

ethexe/processor/src/lib.rs, lines 462–467

The derive_more #[display(...)] format string logs height, timestamp, program_id, source, payload len, value, and gas_allowance — but not with_top_up. The debug line at the top of execute_for_reply therefore won't show whether the top-up path was taken, making it harder to diagnose issues from logs.

// current
"Execution for reply at height {height} timestamp {timestamp}: \
 program_id: {program_id}, source: {source}, payload len: {}, \
 value: {value}, gas_allowance: {gas_allowance}", payload.len()

// suggested
"Execution for reply at height {height} timestamp {timestamp}: \
 program_id: {program_id}, source: {source}, payload len: {}, \
 value: {value}, gas_allowance: {gas_allowance}, with_top_up: {with_top_up}", payload.len()

Fix this →

---

low: EXECUTION_FOR_REPLY_TOP_UP_VALUE_PER_GAS = 100 is undocumented

ethexe/processor/src/lib.rs, line 181

The constant is used to compute gas_allowance * 100 as the top-up amount. With DEFAULT_BLOCK_GAS_LIMIT = 4_000_000_000_000, this produces a top-up of 400_000_000_000_000 — deliberately large to ensure execution can proceed for any gas budget. Without a comment, a future reader won't know if 100 is a meaningful ratio or an arbitrary "big number." A one-line explanation of the intent would help:

// Value-per-gas ratio used to ensure the program has enough executable
// balance to cover the full gas_allowance during overlay reply calculation.
const EXECUTION_FOR_REPLY_TOP_UP_VALUE_PER_GAS: u128 = 100;

---

What's done well

• The RPC parameter is correctly Option<bool> with unwrap_or(false), so JSON-RPC clients that omit the field keep their existing behavior — no breaking change there.
• Event ordering is correct: the top-up event is injected before MessageQueueingRequested, so the balance is available when the transition controller applies the queue.
• saturating_mul prevents any overflow in the top-up value calculation.
• The test covers both the failure path (depleted program, no top-up → error reply code) and the success path (with top-up → PONG), which is the right structure.
• The overlay-only design guarantees no on-chain state mutation.

---

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

ℹ️ 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".