[Migration] Ethrex/py-ethclient Migration: Risk Mitigation Plan

[theo-learner]

Overview

Define mitigation actions for the top five migration risks when replacing op-geth with ethrex (py-ethclient) in OP Stack environments.

Risk Matrix

ID	Risk	Impact	Severity	Trigger Time
RK-001	Engine API missing/incomplete	L2 block production halt	🔴 Critical	Immediately
RK-002	Data directory incompatibility	Sync failure / invalid state bootstrap	🔴 Critical	Early rollout
RK-003	No metrics endpoint/port	Monitoring blind spots	🟠 High	Immediately
RK-004	Archive mode limitations	Historical query/explorer gaps	🟠 High	Mid-term operation
RK-005	Fusaka incompatibility	Network partition / block validation failures	🔴 Critical	At Fusaka activation

---

Mitigation Actions

RK-001: Engine API

• Implemented Engine API methods: engine_exchangeCapabilities, engine_getClientVersionV1, engine_forkchoiceUpdatedV1, engine_newPayloadV1, engine_getPayloadV1
• Dedicated Engine RPC port: --engine-port (default: 8551)
• JWT authentication option: --jwt-secret

RK-002: Data Directory Compatibility

• Geth-compatible CLI: --datadir alias
• Migration helper: scripts/migrate-chaindata.sh

RK-003: Metrics Availability

• Added /metrics endpoint
• Metrics port: --metrics-port (default: 6060)
• Exposed metrics: ethclient_up, eth_block_number, eth_peer_count, eth_syncing

RK-004: Archive Mode Constraints

• Explicit archive flag: --archive
• Prevents silent incorrect historical-state responses (returns RPC error instead)

RK-005: Fusaka Compatibility

• Pre-deployment check script added
• Network smoke test added
• Compliance tracking test added