Add push-based peer head subscription

[tac0turtle]

Summary

• add the push-based ev_subscribeForkchoice WebSocket API
• add --subscribe-peer <WS_URL> and EV_SUBSCRIBE_PEER for full nodes without an EV node
• publish only forkchoices accepted as VALID by the local Reth engine
• apply received forkchoice directly to the subscriber's local engine so native Reth P2P downloads headers, bodies, and transactions
• allow synchronized subscribers to relay validated forkchoice updates downstream
• add operator documentation covering topology, trust boundaries, setup, verification, and troubleshooting

Why

Full nodes currently depend on an EV node to learn canonical head state even though Reth already has the protocol and validation needed to transfer blocks between execution clients. This change separates the control plane from the data plane:

• WebSocket selects head, safe, and finalized references.
• Native Reth P2P transfers the referenced block data.

The sequencer and its EV node remain unchanged.

Behavior

The publisher retains only its latest valid forkchoice, preventing unbounded subscriber backlogs. Each update includes chain ID, genesis hash, forkchoice hashes, and their block numbers.

Subscribers:

• reject chain identity mismatches and finality regressions
• allow legitimate head reorgs that preserve finality
• retry SYNCING or ACCEPTED forkchoice locally every three seconds
• quarantine an INVALID state until the publisher sends a changed forkchoice
• reconnect after transient WebSocket failures with bounded backoff

The WebSocket publisher and P2P block-data peer can be different nodes.

Operator impact

A publishing ev-reth enables --ws. A full node uses:

ev-reth node \
  --chain /path/to/genesis.json \
  --subscribe-peer wss://peer.example/rpc \
  --trusted-peers enode://<public-key>@<block-peer>:30303

The configured WebSocket endpoint is authoritative for forkchoice. Blocks remain subject to local Reth execution and consensus validation.

Validation

• cargo test -p ev-node head --lib — 6 passed
• cargo test -p ev-tests test_e2e_subscriber_syncs_evnode_block_over_native_reth_p2p -- --nocapture — passed
• just check-all — formatting, Clippy with warnings denied, and full workspace tests passed
• just check build-dev — workspace check and debug binary build passed
• git diff --check and documentation link validation passed

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1d0b8eed-13bf-4287-8908-9b521e5bcc79

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}