fix: integrate EC finality into chain follower

[hanabi1224]

Summary of changes

Changes introduced in this pull request:

Reference issue to close (if applicable)

Closes #7170

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

• Bug Fixes
  • Improved gossip block pre-fetch validation to better reference the finalized chain state, ensuring more accurate block acceptance decisions.
  • Strengthened chain finality window checks to properly reject blocks that fall outside the acceptable range relative to finalized state, improving overall chain synchronization consistency.

[coderabbitai]

Walkthrough

The PR integrates the EC finality calculator into block validation and chain synchronization workflows. The error type is updated to carry both epochs; the validator API is simplified to accept a single finalized_epoch; and the chain follower is wired to use ec_calculator_finalized_epoch() for pre-fetch validation and finality-window rejection logic.

Changes

EC Finality Calculator Integration

Layer / File(s)	Summary
Error variant refactoring src/chain_sync/validation.rs	GossipBlockRejectReason::EpochBeyondFinality converted from tuple variant (ChainEpoch, ChainEpoch) to struct variant with named epoch and finalized_epoch fields; label() matcher updated.
Validator API and epoch-range logic src/chain_sync/validation.rs	GossipBlockValidator::validate_pre_fetch signature simplified to accept finalized_epoch (replacing chain_finality and heaviest_epoch); validate_epoch_range updated to reject blocks below finalized_epoch using the new error variant; all unit tests updated to the new signature and error shape.
Chain follower EC finality wiring src/chain_sync/chain_follower.rs	Pre-fetch validation now passes cs.ec_calculator_finalized_epoch() instead of cs.heaviest_tipset().epoch(); add_full_tipset finality-window check replaced to directly compare tipset.epoch() against ec_calculator_finalized_epoch instead of computing epoch differences.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• #6769: Integrates the EC finality calculator into pre-fetch and finality checks as part of broader node-logic and API integration goals.
• #6767: Switches validation and chain-finality checks from static/heaviest-epoch-based heuristics to the EC finality calculator, aligning with FRC-0089 implementation.

Possibly related PRs

• ChainSafe/forest#7019: Modifies the same SyncStateMachine::add_full_tipset function in src/chain_sync/chain_follower.rs, affecting the tipset-processing flow.
• ChainSafe/forest#6886: Changes the gossiped-block pre-fetch path by modifying GossipBlockValidator::validate_pre_fetch and updating epoch-finality rejection logic.
• ChainSafe/forest#7112: Introduces the cs.ec_calculator_finalized_epoch() accessor via ChainStore caching that is wired in this PR.

Suggested reviewers

• sudo-shashank
• LesnyRumcajs

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: integrating EC finality into the chain follower component, which aligns with the primary objective of the PR.
Linked Issues check	✅ Passed	The PR successfully integrates the EC finality calculator into the chain follower via updated epoch validation logic in chain_follower.rs and validation.rs, meeting the core requirement of issue #7170.
Out of Scope Changes check	✅ Passed	All changes are directly related to integrating EC finality into the chain follower; no out-of-scope modifications were identified in the chain_sync component updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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 hm/chain-follower-finality

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch hm/chain-follower-finality

---

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

[coderabbitai]

🧹 Nitpick comments (1)

src/chain_sync/validation.rs (1)

511-517: ⚡ Quick win

Pin the finalized-epoch boundary in this test.

This only proves the epoch < finalized_epoch path and ignores the new payload fields. Matching the concrete { epoch, finalized_epoch } values and adding an epoch == finalized_epoch case would lock down the off-by-one contract this PR introduces.

🤖 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/chain_sync/validation.rs` around lines 511 - 517, The test currently only
asserts that validate_pre_fetch returns
GossipBlockRejectReason::EpochBeyondFinality but doesn't assert the concrete
epoch/finalized_epoch values nor test the boundary case; update the test that
calls GossipBlockValidator::new(&block).validate_pre_fetch(&genesis, 30, 100,
None, &seen).unwrap_err() to assert the concrete
GossipBlockRejectReason::EpochBeyondFinality { epoch: X, finalized_epoch: Y }
values (pin the finalized_epoch boundary) and add an additional assertion or
separate case where epoch == finalized_epoch to ensure the off-by-one behavior
is locked down (use the same functions/structs: GossipBlockValidator,
validate_pre_fetch, and GossipBlockRejectReason).

🤖 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.

Nitpick comments:
In `@src/chain_sync/validation.rs`:
- Around line 511-517: The test currently only asserts that validate_pre_fetch
returns GossipBlockRejectReason::EpochBeyondFinality but doesn't assert the
concrete epoch/finalized_epoch values nor test the boundary case; update the
test that calls GossipBlockValidator::new(&block).validate_pre_fetch(&genesis,
30, 100, None, &seen).unwrap_err() to assert the concrete
GossipBlockRejectReason::EpochBeyondFinality { epoch: X, finalized_epoch: Y }
values (pin the finalized_epoch boundary) and add an additional assertion or
separate case where epoch == finalized_epoch to ensure the off-by-one behavior
is locked down (use the same functions/structs: GossipBlockValidator,
validate_pre_fetch, and GossipBlockRejectReason).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ad26f426-9f02-468b-82a0-3902cb6464a0

📥 Commits

Reviewing files that changed from the base of the PR and between 45c8974 and bd7e7b7.

📒 Files selected for processing (2)

• src/chain_sync/chain_follower.rs
• src/chain_sync/validation.rs

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• filecoin-project/lotus (manual)

[codecov]

Codecov Report

❌ Patch coverage is 91.30435% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.37%. Comparing base (45c8974) to head (bd7e7b7).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/chain_sync/chain_follower.rs	50.00%	1 Missing ⚠️
src/chain_sync/validation.rs	95.23%	1 Missing ⚠️

Additional details and impacted files

Files with missing lines	Coverage Δ
src/chain_sync/chain_follower.rs	33.49% <50.00%> (-0.13%)	⬇️
src/chain_sync/validation.rs	88.52% <95.23%> (-0.06%)	⬇️

... and 8 files with indirect coverage changes

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 45c8974...bd7e7b7. 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.