feat(api): add pending transaction support in the eth subscription API

[akaladarshi]

Summary of changes

Changes introduced in this pull request:

• Adds support for the pending transaction API
• Refactor the existing subscription API's to use stream instead of creating extra channel to sending data to the sink

Reference issue to close (if applicable)

Closes #6031

Other information and links

Change checklist

• I have performed a self-review of my own code,
• I have made corresponding changes to the documentation. All new code adheres to the team's documentation standards,
• I have added tests that prove my fix is effective or that my feature works (if possible),
• I have made sure the CHANGELOG is up-to-date. All user-facing changes should be reflected in this document.

Outside contributions

• I have read and agree to the CONTRIBUTING document.
• I have read and agree to the AI Policy document. I understand that failure to comply with the guidelines will lead to rejection of the pull request.

Summary by CodeRabbit

Release Notes

• New Features

  • Implemented Ethereum pubsub subscriptions for pendingTransactions, logs, and newHeads with improved stream handling.
  • Added broadcast stream utility for converting receivers into async streams with automatic lag event handling.

• Refactor

  • Improved internal subscription architecture and stream management.

• Tests

  • Added tests for broadcast stream functionality and lag event behavior.

[coderabbitai]

Walkthrough

This PR refactors Ethereum pubsub subscriptions from a handle_subscription/JoinHandle pattern to a stream-based architecture, adding a broadcast stream utility, exposing a helper function for tx hash conversion, and removing now-obsolete chain.rs subscribers.

Changes

ETH Pubsub Stream-based Refactoring

Layer / File(s)	Summary
Broadcast stream infrastructure src/utils/broadcast/mod.rs, src/utils/broadcast/tests.rs	New subscription_stream utility wraps Tokio broadcast receivers into async streams, filtering lagged events and logging dropped messages; tests verify termination and lag-handling behavior.
ETH helper function visibility src/rpc/methods/eth.rs	eth_tx_hash_from_signed_message is promoted from private to pub(crate) to enable use by the new stream-based pendingTransactions subscription.
ETH pubsub stream-based subscription handlers src/rpc/methods/eth/pubsub.rs	EthPubSub::subscribe now routes to spawn_newHeads, spawn_logs, and spawn_pending_transactions helpers that build streams from chain/mempool updates; a new pipe_stream_to_sink generic serializes and forwards items to the JSON-RPC sink until termination.
Chain RPC helper cleanup src/rpc/methods/chain.rs	Removes new_heads and logs helper functions and their supporting imports (JoinHandle, Ethereum types) since the new stream-based pubsub implementation replaces them.
Dead code suppression refinement src/message_pool/msgpool/events.rs, src/message_pool/msgpool/msg_pool.rs	#[allow(dead_code)] attribute is relocated from MpoolUpdate enum level to only the Remove variant; removed from subscribe_to_updates for more precise warning control.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• ChainSafe/forest#5749: Introduced the initial NewHeads and Logs subscription support via chain::new_heads and chain::logs helpers that this PR replaces with a stream-based pattern.
• ChainSafe/forest#6402: Updates chain::new_heads to emit Ethereum block results—directly related to how this PR refactors the newHeads subscription pipeline.
• ChainSafe/forest#6965: Introduced MpoolUpdate with an enum-level #[allow(dead_code)] attribute that this PR refines by moving it to the specific Remove variant.

Suggested reviewers

• sudo-shashank
• LesnyRumcajs
• hanabi1224

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 70.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding pending transaction support to the eth subscription API, which is the primary objective of this PR.
Linked Issues check	✅ Passed	The PR successfully implements both completion criteria from issue #6031: pending transaction subscription support is added in eth/pubsub.rs, and integration test coverage is provided in broadcast/tests.rs.
Out of Scope Changes check	✅ Passed	All changes are directly related to the linked issue objectives: implementing pending transaction support and refactoring subscriptions to use streams instead of extra channels.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch akaladarshi/add-pending-tx-eth-subscribe

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch akaladarshi/add-pending-tx-eth-subscribe

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/rpc/methods/eth/pubsub.rs`:
- Around line 126-128: The stream currently iterates only changes.applies so
reverted tipsets are ignored; update the flat_map over
subscription_stream(head_rx) to emit both applies and reverts (e.g., pair each
tipset with a boolean or enum indicating is_revert) instead of only
changes.applies, then adjust the subsequent filter_map closure that binds ts to
accept that (tipset, is_revert) and produce log removal events for reverts and
normal events for applies; target the subscription_stream/head_rx pipeline and
the closure capturing ts in pubsub.rs so reorg-driven log removals are emitted.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 023ea685-f51d-4356-8476-c6eea9c54e3d

📥 Commits

Reviewing files that changed from the base of the PR and between dba0196 and 6f51115.

📒 Files selected for processing (7)

• src/message_pool/msgpool/events.rs
• src/message_pool/msgpool/msg_pool.rs
• src/rpc/methods/chain.rs
• src/rpc/methods/eth.rs
• src/rpc/methods/eth/pubsub.rs
• src/utils/broadcast/mod.rs
• src/utils/broadcast/tests.rs

💤 Files with no reviewable changes (2)

• src/message_pool/msgpool/msg_pool.rs
• src/rpc/methods/chain.rs

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Handle revert tipsets in logs subscriptions.

On Line 127, the stream only iterates changes.applies, so reverted tipsets are dropped and reorg-driven log removals cannot be emitted.

💡 Suggested fix

-    let stream = subscription_stream(head_rx)
-        .flat_map(|changes| futures::stream::iter(changes.applies))
+    let stream = subscription_stream(head_rx)
+        .flat_map(|changes| {
+            futures::stream::iter(
+                changes
+                    .reverts
+                    .into_iter()
+                    .chain(changes.applies.into_iter()),
+            )
+        })
         .filter_map(move |ts| {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/rpc/methods/eth/pubsub.rs` around lines 126 - 128, The stream currently
iterates only changes.applies so reverted tipsets are ignored; update the
flat_map over subscription_stream(head_rx) to emit both applies and reverts
(e.g., pair each tipset with a boolean or enum indicating is_revert) instead of
only changes.applies, then adjust the subsequent filter_map closure that binds
ts to accept that (tipset, is_revert) and produce log removal events for reverts
and normal events for applies; target the subscription_stream/head_rx pipeline
and the closure capturing ts in pubsub.rs so reorg-driven log removals are
emitted.

[codecov]

Codecov Report

❌ Patch coverage is 15.38462% with 66 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.27%. Comparing base (7d19be2) to head (6f51115).
⚠️ Report is 4 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/rpc/methods/eth/pubsub.rs	0.00%	66 Missing ⚠️

Additional details and impacted files

Files with missing lines	Coverage Δ
src/message_pool/msgpool/msg_pool.rs	87.75% <ø> (ø)
src/rpc/methods/chain.rs	57.93% <ø> (+2.28%)	⬆️
src/rpc/methods/eth.rs	65.68% <100.00%> (ø)
src/utils/broadcast/mod.rs	100.00% <100.00%> (ø)
src/rpc/methods/eth/pubsub.rs	0.00% <0.00%> (ø)

... and 29 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7d19be2...6f51115. Read the comment docs.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.