EVM-37: EvmWebSocketBlockStream

[Puneethkumarck]

Context

The WebSocket block stream is the primary real-time data source for the EVM indexer. It subscribes to newHeads via eth_subscribe, detects reorgs by checking parent hashes, handles gap detection on reconnect, and fetches full block + receipt data via batch JSON-RPC. This is the most complex streaming adapter, analogous to the Solana WebSocketTransactionStream.

Specification

• Layer: Infrastructure (infrastructure/evm/EvmWebSocketBlockStream.java)
• Implements: EvmBlockStream domain port
• WebSocket: JDK java.net.http.WebSocket (no external WS library)
• Subscription: Sends eth_subscribe newHeads on connect
• Per-block flow (on each newHeads notification):
  1. Extract blockNumber + parentHash from notification
  2. Check reorg via ParentHashTracker: if stored hash for blockNumber - 1 does not match parentHash, reorg detected
  3. If reorg: delegate to ReorgHandler (cascade delete + re-index)
  4. Confirmation delay: if CONFIRMATION_BLOCKS > 0, only process blocks when chainHead - blockNumber >= confirmationBlocks
  5. Fetch full block + receipts via EvmJsonRpcClient.batchCall() (single batch with eth_getBlockByNumber + eth_getBlockReceipts)
  6. Parse via EvmTransactionParser into domain objects
  7. Enqueue block + transactions to consumers
• Reconnect handling:
  • On reconnect: run GapDetector.detectGap() + backfill() before resuming live stream
  • Uses shared ReconnectHandler pattern
  • Idle timeout: 60 seconds
• Track: Update ParentHashTracker after each successfully processed block

Acceptance Criteria

• Sends correct eth_subscribe newHeads JSON on WebSocket connect
• Processes newHeads notifications and fetches full block + receipts via batch RPC
• Detects reorg when parent hash does not match tracked hash
• Delegates reorg handling to ReorgHandler
• Runs gap detection on reconnect and backfills missing blocks
• Respects confirmation delay configuration
• Updates ParentHashTracker after each processed block
• Handles idle timeout (60s) and triggers reconnect
• Unit tests mock WebSocket and RPC client to verify subscription, reorg detection, and gap detection
• Integration test with mock WebSocket server verifies full flow to domain objects

Dependencies

• EVM-30: EvmJsonRpcClient (batch RPC for block + receipts)
• EVM-34: EvmTransactionParser (JSON to domain objects)
• EVM-35: ParentHashTracker (reorg detection)
• EVM-36: GapDetector (reconnect gap fill)
• EVM-20: ReorgHandler (reorg cascade)

References

• docs/evm-implementation-plan.md — Phase 3: EVM Infrastructure — Block Streaming & Parsing
• docs/evm-functional-spec.md — Section 2: Streaming Architecture, Reorg Handling
• docs/CODING_STANDARDS.md