Feature: Add WebSocket (WSS) Support for Block and Transaction Streaming

[snipe-dev]

Feature: Add WebSocket (WSS) Support for Block and Transaction Streaming

Motivation

Currently, block detection and transaction processing rely on HTTP RPC
calls via MultinodePublicClient.

While this approach provides strong reliability through consensus across
multiple nodes, it introduces latency due to polling-based block
detection.

We want to add WebSocket (WSS) support to:

• Receive new blocks faster
• Receive pending transactions in near real-time
• Preserve fault tolerance
• Maintain support for multiple nodes (both HTTP and WSS)
• Keep HTTP as the authoritative data source

The goal is to improve responsiveness without sacrificing reliability.

---

High-Level Requirements

1. Add WSS-based block subscription support.
2. Add optional pending transaction subscription.
3. Preserve HTTP multinode consensus as the source of truth.
4. Maintain support for multiple nodes for both:
   • HTTP data fetching
   • WSS event subscriptions
5. Ensure system stability when using unreliable/free RPC providers.
6. Avoid introducing race conditions or duplicate block processing.

---

Design Constraints

• HTTP remains the canonical source of block data.
• All block fetching must still go through MultinodePublicClient.
• processBlock() remains the single entry point for block
  processing.
• Deduplication logic must remain centralized in BlockReader.
• WSS must not bypass HTTP consensus.
• WSS failures must not break the system.

---

Proposed Direction (Open for Discussion)

We are currently exploring the following approach.

1. Introduce a simple WssClient

Responsibilities:

• Manage a list of WSS endpoints
• Maintain one active connection at a time
• Rotate to the next node on failure
• Use a watchdog to detect silent connections
• Emit:
  • block_hint
  • pending_tx
  • all_dead (optional)

Philosophy:

• One active WSS node
• Fast rotation on failure
• No panic on disconnects
• Free/unreliable nodes are expected

---

2. Integrate WSS directly into BlockReader

Instead of introducing a coordinator layer, integrate the WSS trigger
logic directly into BlockReader.

Conceptually:

WSS block event
        ↓
trigger block check
        ↓
HTTP getBlockNumber()  ← consensus
        ↓
fetch missing blocks via HTTP
        ↓
processBlock()

Key points:

• Polling remains active as a fallback mechanism.
• WSS only accelerates block detection.
• Only one block check may run at a time (guarded by a flag).
• If WSS stops emitting events, polling continues normally.

---

3. Multi-node Support

HTTP: - Already implemented via MultinodePublicClient - Consensus
strategies preserved

WSS: - Maintain a list of WSS endpoints - Rotate on: - connection
error - socket close - watchdog timeout (no events for N seconds)

No parallel active WSS connections in the initial version.

---

4. Pending Transactions (Optional Phase)

If enabled:

• Subscribe to newPendingTransactions
• Apply basic rate limiting
• Optionally filter by watchlist
• Emit pending_transaction events

Pending transactions are treated as non-authoritative signals and may be
ignored or throttled.

---

Edge Cases to Address

We are particularly interested in feedback on:

• Handling WSS ahead-of-HTTP situations
• Handling HTTP ahead-of-WSS situations
• Reorg implications
• Duplicate events
• WSS silent failure detection
• Preventing HTTP request storms from rapid WSS events
• Handling unstable/free RPC providers gracefully

---

Open Questions

• Should polling always remain enabled as fallback?
• Should we support configurable watchdog timeout?
• Should WSS rotation use fixed delay or exponential backoff?
• How aggressive should pending transaction filtering be?
• Should we log WSS failures at debug level only?

---

Status

Implementation has started based on the direction described above.

This issue is opened for:

• Architectural discussion
• Alternative design proposals
• Review of failure-handling strategy
• Contributions

The goal is to preserve existing reliability guarantees while improving latency.