refactor(malachite): restructure service initialization and externalities

[grishasobol]

Summary

This PR refactors the Malachite consensus service initialization and externalities layer to improve separation of concerns and enable better testability. Key changes:

• New MalachiteServiceStarter: Extracted service initialization logic into a separate builder type that prepares all components before starting the core engine. This decouples configuration from runtime state.

• Restructured EthexeExternalities: Simplified the externalities struct by:

  • Moving configuration into a dedicated ExternalitiesConfig struct
  • Replacing Option<SimpleBlockData> chain head with a new ChainHead type that tracks both latest observed and synced Ethereum blocks
  • Changing Mutex<VecDeque> pending events to RwLock<VecDeque> for async-safe access
  • Making mempool optional (Option<Arc<dyn Mempool>>) to support non-validator nodes

• Updated Externalities trait:

  • validate_block_above now returns Acceptance<(), String> instead of bool for richer rejection reasons
  • process_mb_proposal and process_mb_finalized are now async (.await on event emission)
  • validate_block_above takes &BlockPayload instead of owned value

• New ChainHead type: Encapsulates chain head state with separate fields for latest observed and latest synced Ethereum blocks, plus a notification mechanism for async coordination.

• Renamed core types: MalachiteConfig → MalachiteServiceConfig, MalachiteService → MalachiteCore (in ethexe-malachite-core), improving clarity about which layer each type belongs to.

• Added Acceptance<A, R> enum: New generic type in ethexe-common for representing accepted/rejected validation results with optional rejection reasons.

These changes improve code organization, enable better async/await patterns, and make the service more testable by separating initialization concerns from runtime behavior.

How to test

• Existing unit tests in ethexe/malachite/service/tests/restart_resilience.rs have been updated and should pass
• Core consensus tests in ethexe/malachite/core/tests/multi_validators.rs updated for new Acceptance return type
• Integration tests in ethexe/service/src/tests/ updated for new config and starter types
• Run cargo nextest run -p "ethexe-*" to verify all ethexe crates pass

Notes

• This is a refactoring with no functional changes to consensus behavior
• The MalachiteServiceStarter pattern enables future improvements like lazy initialization and better error handling during startup
• Async changes to externalities methods require callers to .await event emission, improving integration with async runtime
• Non-validator nodes now properly handle the absence of a mempool via Option<Arc<dyn Mempool>>

https://claude.ai/code/session_014FBHbneaDtHjPcJDWgV4j4

[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 refactors the Malachite consensus service initialization and externalities layer. The primary goal is to improve the separation of concerns and testability by introducing a builder-pattern starter, simplifying the externalities structure, and adopting more robust async patterns. These changes do not alter consensus behavior but significantly improve the codebase's maintainability and integration with async runtimes.

Highlights

• Service Initialization Refactor: Introduced MalachiteServiceStarter to decouple service configuration from runtime state, enabling better testability and future lazy initialization.
• Externalities Layer Restructuring: Simplified EthexeExternalities by introducing ExternalitiesConfig, replacing mutable state with RwLock, and making the mempool optional to support non-validator nodes.
• Async API Improvements: Updated Externalities trait methods to be async and introduced the Acceptance<A, R> enum for richer validation feedback.
• Type Renaming and Cleanup: Renamed MalachiteConfig to MalachiteServiceConfig and MalachiteService to MalachiteCore (in the core crate) to improve layer clarity.

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

[grishasobol]

@claude opus review

[claude]

Claude finished @grishasobol's task in 3m 20s —— View job

---

Opus review — refactor(malachite): restructure service initialization and externalities

• Gather context (diff, key files)
• Review service/starter/externalities restructuring
• Review ChainHead, Acceptance, async changes
• Post review findings

Summary. Clean, well-motivated refactor. Extracting MalachiteServiceStarter to separate "prepare components" from "launch core" is a good split, the ChainHead register (separate latest / latest_synced with a Notify) is a clear improvement over the old Option<SimpleBlockData>, and threading Acceptance<(), String> through validate_block_above so rejection reasons get logged (app.rs:353, app.rs:457) is a real win for debuggability. The lost-wakeup handling in wait_for_proposable_content (enable() before the select!) and the FIFO-preserving try_emit_or_queue/drain_pending_events pair look correct. Mostly cleanup items below — no correctness blockers found.

---

severity: medium — leftover scratch comment merged into the event loop

File: ethexe/service/src/lib.rs line 988

// +_+_+ ??? whether we really need this?
// Non-proposer nodes (validators that didn't propose ...

The +_+_+ ??? marker reads like an unresolved note to self. Either resolve the question (does a non-proposer really need to compute_mb on BlockFinalized, or is it redundant with the BlockProposal path?) and keep the explanatory comment, or drop the marker. Shipping ??? into the orchestrator's hot path is the kind of thing that outlives everyone's memory of why it was there. Fix this →

---

severity: medium — stale crate docs reference removed API

File: ethexe/malachite/service/src/lib.rs lines 14-15, 29-30, 37-39

The module doc still describes the pre-refactor API:

• "it calls receive_new_chain_head on each ObserverEvent::BlockSynced" — that method is gone; the service now calls receive_new_eb (on ObserverEvent::Block) and receive_eb_synced (on BlockSynced).
• The "Driver methods" list names receive_new_chain_head.
• "Construct with MalachiteService::new(config, db, signer, validator_pub_key, mempool)" — construction is now via MalachiteServiceStarter::new(...).start(); there is no MalachiteService::new.

Since the rename is the headline of this PR, the doc should move with it. Fix this →

---

severity: low — validator set assigned twice; one clone() is wasted

File: ethexe/service/src/lib.rs lines 511-538

malachite_service_config already gets the set via .with_validators(malachite_validator_set.clone()) at line 516, then line 537-538 re-applies it:

let malachite_config = malachite_service_config.with_validators(malachite_validator_set);

The second with_validators is redundant and the .clone() at 516 exists only to feed it. Drop the clone at 516 and the re-assignment at 537-538 (pass malachite_service_config straight into the starter), or remove the 516 call and keep the move at 537. Looks like a refactor artifact. Fix this →

---

severity: low — confusing log message wording

File: ethexe/service/src/lib.rs line 535

log::info!("Malachite not local role: {role}",);

"Malachite not local role: validator" is hard to parse and has a trailing comma. Likely intended something like "Malachite node role: {role}".

---

severity: low — error message and a TODO comment still use the old type name

• ethexe/malachite/service/src/starter.rs:50 — anyhow!("MalachiteConfig::validators is empty") should read MalachiteServiceConfig::validators.
• ethexe/malachite/service/src/config.rs:28 (and the from_home_dir area) — fine, but worth a grep for any other MalachiteConfig / MalachiteService::new string references left behind by the rename.

---

severity: low — MalachiteServiceStarter::new is async but never awaits

File: ethexe/malachite/service/src/starter.rs:40-128

new contains no .await (all the awaited work is in start). It compiles fine and the async keeps API symmetry with start, but clippy::unused_async would flag it under pedantic. Optional — keep if the symmetry is deliberate.

---

Minor observations (no action required)

• validate_block_above uses limit = touched.len().max(MAX_TOUCHED_PROGRAMS_PER_MB) while build_block_above drops all injected txs once initial touched exceeds the cap. The asymmetry is safe (the validator side still rejects any MB that grows touched beyond the cap), but the two paths diverging is exactly what TODO ethexe-malachite: extract shared helper for producer/validator EB-advance check #5477 calls out — worth keeping that ticket alive.
• Full nodes get a fresh PrivateKey::random() libp2p identity on every restart (starter.rs:78). Intended per the doc comment, just noting the peer-id churn.
• ChainHead uses two independent RwLocks (latest, latest_synced); all writers are the single service event loop, so there's no cross-field race, but the invariant "only the run loop writes these" is worth a one-line comment on the struct since the locks technically permit concurrent writers.
  · branch gsobol/ethexe/tune-malachite-errors

[gemini-code-assist]

Code Review

This pull request refactors the 'ethexe-malachite' consensus service, introducing 'MalachiteServiceStarter' to separate initialization from execution, updating 'EthexeExternalities' and 'quarantine' to use the 'Acceptance' enum, and converting 'InjectedTxMempool' to use async methods with 'RwLock'. Feedback on these changes includes removing a temporary debug comment in 'ethexe/service/src/lib.rs', replacing a panic with an error in 'externalities.rs', using more idiomatic 'ok_or_else' error conversions in 'quarantine.rs', and reverting or documenting an unintended timeout change in 'starter.rs'.

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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f154c85e86

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