feat(ethexe/processor): exclude zero balance programs from processing

[playX18]

Closes #4690

Summary

Removes programs with zero balance from processing

How to test

cargo test -p ethexe-processor.

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 optimizes the program processing pipeline by filtering out programs that lack sufficient executable balance. By integrating database access into the state evaluation logic, the processor can now verify program balances before scheduling them for execution, preventing unnecessary processing overhead.

Highlights

• Program Filtering: Updated the processing logic to exclude programs with a zero executable balance from the execution queue.
• Dependency Injection: Updated the states function signature across OverlaidRunContext and CommonRunContext to accept the database, enabling state lookup during processing.
• Testing: Added a new test case to verify that programs with zero executable balance are correctly skipped during chunk partitioning.

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 updates the state retrieval logic in ethexe-processor to skip programs that have a zero executable balance. To support this, the database is now passed into the states function. The feedback highlights a critical safety concern: using .expect() on the database lookup during block processing can cause validator nodes to panic and crash if there is any database inconsistency. It is highly recommended to handle this lookup safely by returning a Result instead.

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

[claude]

Claude finished @playX18's task in 2m 25s —— View job

---

Code Review

• Read changed files and analyze diff
• Provide review feedback

---

The change is logically sound: programs with executable_balance == 0 can't pay for gas execution, so filtering them out of the processing queue is a correct optimization. The implementation is clean and the new test covers the core scenario well.

On the Gemini finding: The .expect() call is actually correct per this project's conventions. CLAUDE.md explicitly states: "Outside tests and mocks, don't reach for unwrap_or* on an Option/Result whose None/Err branch is supposedly impossible. Use expect("invariant") instead so a violation becomes a loud failure." State hashes in InBlockTransitions are populated from the parent block's finalized CAS state — if a hash appears in the transitions map, the corresponding ProgramState must be in the DB (it was written when that state was committed). A missing state is a genuine invariant violation that should panic loudly, not be silently skipped. The expect message is even descriptive. Gemini's suggestion to use ok_or_else(|| Error::NotFound)? would mask real corruption.

---

low: Missing test coverage for MessageType::Injected

File: ethexe/processor/src/handling/run/mod.rs lines 636–718

The new test only calls prepare_execution_chunks(&mut ctx, MessageType::Canonical). The filter in states() applies unconditionally to both canonical and injected queues. There's no test verifying that a program with injected_queue_size > 0 but executable_balance == 0 is also skipped. Since injected messages are cross-chain Ethereum messages, it's worth at least an explicit test (and possibly a comment) confirming this is the intended semantics — a program with a pending injected message but no executable balance will silently have that message deferred indefinitely.

Fix this →

---

low: Negated .any() is harder to read than .all()

File: ethexe/processor/src/handling/run/mod.rs lines 711–716

assert!(
    !chunk
        .iter()
        .any(|(program_id, state_hash)| *program_id == skipped
            && *state_hash == skipped_hash)
);

!iter.any(pred) is equivalent to iter.all(|x| !pred(x)) and reads more naturally in an assertion. Either form works; the negation just makes it take a moment longer to parse. Alternatively, since the concern is purely about the actor ID (there's only one state hash for skipped), this could be assert!(!chunk.iter().any(|(id, _)| *id == skipped)).

---

Overall: the approach is correct, the test covers the key cases, and the .expect() matches project conventions. The only meaningful gap is the lack of a test for the injected-queue path.