Skip to content

refactor(engine-api): reuse reth engine pipeline for custom L2 APIs #32

@panos-xyz

Description

@panos-xyz

Background

Morph-Reth currently supports custom L2 engine RPCs (engine_assembleL2Block, engine_validateL2Block, engine_newL2Block, engine_newSafeL2Block).
Historically, the implementation used a custom API-layer import/commit path instead of reth's engine pipeline (newPayload + forkchoiceUpdated + engine tree).

This increases maintenance complexity, duplicates validation/import logic, and makes behavior diverge from reth engine pipeline semantics.

Functional Description

Refactor custom L2 engine API implementation to reuse reth engine pipeline while keeping external Morph engine RPC interfaces compatible.

Key goals:

  1. Keep Morph custom engine RPC method signatures and behavior compatible.
  2. Route block validation/import through reth engine tree (newPayload + FCU) instead of manual DB append path.
  3. Preserve Morph-specific semantics (pre-/post-MPTFork state_root handling, withdraw_trie_root validation, custom header fields).
  4. Reduce duplicated API-layer caching/state tracking logic.

Scope

  • Refactor morph-engine-api to reuse reth engine pipeline for:
    • engine_validateL2Block
    • engine_newL2Block
    • engine_newSafeL2Block
  • Add/maintain deterministic ExecutableL2Data -> MorphExecutionData conversion for engine submission
  • Move Morph-specific validation into engine validator path:
    • pre-/post-MPTFork state_root behavior
    • withdraw_trie_root post-execution validation
  • Replace legacy API-layer import/canonical management path
  • Add engine-state tracking for head/forkchoice reads used by custom engine API
  • Remove obsolete compatibility code and redundant API-layer caches
  • Update tests/docs accordingly

Acceptance Criteria

  • engine_validateL2Block and engine_newL2Block work through reth engine pipeline (newPayload + FCU)
  • Morph custom engine RPC interfaces remain compatible for existing callers
  • pre-MPTFork and post-MPTFork state_root behavior is preserved
  • withdraw_trie_root validation is preserved in engine validator path
  • Legacy manual API-layer append/canonical path is removed from main flow
  • cargo check --workspace passes
  • Related tests pass

Operational Note

Current sync/import performance is highly sensitive to engine state-root algorithm selection on Morph workloads.
In practice, --engine.legacy-state-root may be required for acceptable throughput in this engine-API-driven sync mode.
(Performance tuning is tracked separately from this refactor task.)

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions