doc: explain const FINALITY_CHAIN_EXTRA_EPOCHS

[hanabi1224]

Summary of changes

Adds doc on FINALITY_CHAIN_EXTRA_EPOCHS with help from Claude Code.

(The original code has limited comment explaining this constant: https://github.com/filecoin-project/lotus/blob/master/chain/ecfinality/cache.go#L51)

Changes introduced in this pull request:

Reference issue to close (if applicable)

Closes #6866

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

• Documentation
  • Expanded explanation of how chain finality status is determined, including use of extra epochs when building the sample for threshold checks and how empty/skip rounds consume sample slots without increasing meaningful epoch count — improving operator understanding. No runtime behavior or public interfaces were changed.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.02%. Comparing base (19d1045) to head (d4104ef).
⚠️ Report is 3 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

Files with missing lines	Coverage Δ
src/rpc/methods/chain.rs	55.68% <ø> (ø)

... and 21 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 755b8e0...d4104ef. 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.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ec0ba2af-5ebb-4f87-bedc-4978a7dd24e1

📥 Commits

Reviewing files that changed from the base of the PR and between 0b69506 and d4104ef.

📒 Files selected for processing (1)

• src/rpc/methods/chain.rs

✅ Files skipped from review due to trivial changes (1)

• src/rpc/methods/chain.rs

---

Walkthrough

Added inline documentation in ChainGetTipSetFinalityStatus::get_ec_finality_threshold_depth_and_tipset introducing FINALITY_CHAIN_EXTRA_EPOCHS = 5, explaining its role as a tail buffer for bisection sampling and notes on null rounds consuming sample slots.

Changes

Cohort / File(s)	Summary
Documentation Addition src/rpc/methods/chain.rs	Inserted doc comments around FINALITY_CHAIN_EXTRA_EPOCHS: usize = 5 describing why extra epochs are fetched for the sample passed to find_threshold_depth, rationale for the value 5, and the effect of null rounds on sample slots.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• feat(rpc): impl Filecoin.ChainGetTipSetFinalityStatus #6811: Introduced ChainGetTipSetFinalityStatus and the context where FINALITY_CHAIN_EXTRA_EPOCHS is used.
• feat: finality calculator #6785: Implements the ec_finality calculator (including find_threshold_depth) that uses the sampling behavior documented here.

Suggested labels

RPC

Suggested reviewers

• akaladarshi
• LesnyRumcajs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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 'doc: explain const FINALITY_CHAIN_EXTRA_EPOCHS' clearly and concisely describes the main change: adding documentation/explanation for a specific constant.
Linked Issues check	✅ Passed	The PR adds doc comments explaining the constant's purpose and rationale, addressing the core objective [#6866]. However, it does not explicitly reference the Lotus implementation or detailed rationale for the value 5.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to addressing the documentation requirement in linked issue #6866; no unrelated modifications were introduced.

_{✏️ 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/doc-finality-extra-expochs

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch hm/doc-finality-extra-expochs

---

_{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 the current code and only fix it if needed.

Inline comments:
In `@src/rpc/methods/chain.rs`:
- Around line 1199-1209: Update the doc comment for FINALITY_CHAIN_EXTRA_EPOCHS
to remove the incorrect claim that find_threshold_depth probes up to
chain_finality and instead state that the chain sample is built with
chain_finality + FINALITY_CHAIN_EXTRA_EPOCHS to provide a buffer for null
rounds, while the actual bisect probe depth is capped by BISECT_HIGH (450
epochs); reference find_threshold_depth, FINALITY_CHAIN_EXTRA_EPOCHS,
BISECT_HIGH and chain_finality in the revised text so readers understand the
sample sizing vs. the bisect probe limit.

🪄 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: 17ac952e-cd03-4470-83e6-e0e381fa2a33

📥 Commits

Reviewing files that changed from the base of the PR and between 19d1045 and 5481a24.

📒 Files selected for processing (1)

• src/rpc/methods/chain.rs