Skip to content

fix: make tipset lookup-by-epoch table resilient on chain reorg#7288

Merged
hanabi1224 merged 9 commits into
mainfrom
hm/correct-ts-lookup-on-reorg
Jul 7, 2026
Merged

fix: make tipset lookup-by-epoch table resilient on chain reorg#7288
hanabi1224 merged 9 commits into
mainfrom
hm/correct-ts-lookup-on-reorg

Conversation

@hanabi1224

@hanabi1224 hanabi1224 commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Summary of changes

A Forest node got a wrong tipset lookup record at epoch 6155260 (likely from chain reorg) which caused state mismatch in validating tipset@6155285. This PR makes the tipset lookup population logic more robust in cases like chain reorg.

State mistach is gone after reboot with the fix:

2026-07-03T01:16:44.882303Z  WARN forest::daemon: Correcting tipset_by_height cache for epoch 6155260: expected [bafy2bzacebtht5qtftaslpvobj43z2ggmasmxovbkmepkucfonsbquiw3fefk, bafy2bzacednnpmrvxcz7lvzyloc2d5u4e3woglw22ni3ot4dxvn36glf2adky, bafy2bzaceb6f5ykj7skzlxsmxlaad5vhqnsadhnljmc3opjwxmffjjvhqbhj4, bafy2bzacecdkxjdzb7cjft65ezjy3rialezvua7zjcylhui5myqy4sjizij36, bafy2bzacedfa3vm4gsofrnxaclfqwhpe6crxll7nm7oan6auekdid4zgaiouy, bafy2bzacedm7touawm3yhhkwk35kteuipogtm4v54n5w3y4yvij3wf4hoixo2, bafy2bzacebyrakuf456bltrmhmsacy6nuaculu34ceyzmj243gkbtz5e426jm, bafy2bzacedjfboexujk46q2dqge2ccxijxnxszfhvp3wm5qdi45stm5t6pwyy], found [bafy2bzacedm7touawm3yhhkwk35kteuipogtm4v54n5w3y4yvij3wf4hoixo2]
2026-07-03T01:21:09.055192Z  INFO forest::daemon: Successfully re-populated tipset_by_height cache, took 4m 24s 173ms 793us 242ns, corrected 1 entries

Root cause of having the bad record is not fully clear, I don't see bad records on other long running nodes

2026-07-03T01:12:43.032797Z  INFO forest::daemon: Successfully re-populated tipset_by_height cache, took 8m 812ms 661us 323ns, corrected 0 entries

Sample output:

# calibnet
2026-07-06T18:18:15.374488Z  INFO forest::daemon: Successfully re-populated tipset_by_height cache, 0 entries added, 0 entries corrected, took 2m 25s 924ms 288us 894ns.

# mainnet
2026-07-06T18:30:56.445156Z  INFO forest::daemon: Successfully re-populated tipset_by_height cache, 0 entries added, 0 entries corrected, took 10m 40s 710ms 550us 459ns.

Changes introduced in this pull request:

Reference issue to close (if applicable)

Closes

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 chain finality handling by switching from tipset-based evaluation to an epoch-based predicate across chain queries and ancestor scanning.
    • Updated heaviest-tipset persistence to best-effort store the head’s tipset key at lookup-checkpoint epochs, with non-fatal warnings on failures.
    • Refreshed RPC cache warmup to pre-collect event data for the current tipset instead of loading a finalized tipset by height.
  • Refactor
    • Finality configuration now uses an epoch-based option (replacing the prior tipset-based configuration).

@hanabi1224 hanabi1224 added the RPC requires calibnet RPC checks to run on CI label Jul 2, 2026
@coderabbitai

coderabbitai Bot commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

Walkthrough

This PR switches ChainIndex and ChainStore finality checks from tipset-based predicates to epoch-based predicates, persists the heaviest tipset key at lookup checkpoints, and changes daemon warmup to collect events and repopulate lookup entries from the chain.

Changes

Epoch finality and chain store updates

Layer / File(s) Summary
Finality predicate refactor
src/chain/store/index.rs
ChainIndex stores and uses an epoch-finality callback, the builder now accepts with_is_epoch_finalized, tipset_by_height checks finalized epochs during scanning, and checkpoint helpers use the lookup interval constant.
Heaviest tipset persistence
src/chain/store/chain_store.rs
ChainStore::new wires the EC-finality epoch predicate into ChainIndex, and set_heaviest_tipset writes the head tipset key at lookup checkpoints while warning on persistence failures.
Daemon event cache warmup
src/daemon/mod.rs
Tipset cache warmup now calls EthEventHandler::collect_events with a matcher that always returns false, fills a local event buffer, and warns on collection failure.
Background lookup repopulation
src/daemon/mod.rs
The background warmup loop now scans chain tipsets at lookup checkpoints, repairs missing or mismatched lookup entries, and logs completion time.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

  • ChainSafe/forest#6780: Both PRs modify ChainStore/ChainIndex finality wiring and the related chain-finalization code paths.
  • ChainSafe/forest#7112: Both PRs touch EC-derived finalized epoch handling in ChainStore and the downstream cache/warmup flow.
  • ChainSafe/forest#7226: Both PRs change the daemon cache prefill path in src/daemon/mod.rs.

Suggested reviewers: LesnyRumcajs

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately reflects the main fix: keeping the tipset lookup-by-epoch table correct and resilient during chain reorgs.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch hm/correct-ts-lookup-on-reorg
✨ Simplify code
  • Create PR with simplified code
  • Commit simplified code in branch hm/correct-ts-lookup-on-reorg

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

@hanabi1224 hanabi1224 marked this pull request as ready for review July 2, 2026 17:36
@hanabi1224 hanabi1224 requested a review from a team as a code owner July 2, 2026 17:36
@hanabi1224 hanabi1224 requested review from LesnyRumcajs and akaladarshi and removed request for a team July 2, 2026 17:36

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/chain/store/chain_store.rs`:
- Around line 183-185: The write order in `ChainStore::set_heaviest_tipset`
should be changed so `set_tipset_key_at_epoch(&head)` happens before
`set_heaviest_tipset_key(head.key())`. Update the sequence around
`head.key().save(self.db())`, `db().set_tipset_key_at_epoch(&head)`, and
`db().set_heaviest_tipset_key(...)` so a failure in the epoch mapping does not
leave the durable head advanced ahead of the in-memory state and notifications.
🪄 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: a6c91500-0699-4278-bf7b-bd9e7c325f56

📥 Commits

Reviewing files that changed from the base of the PR and between c13f3c0 and 4f9e0a3.

📒 Files selected for processing (2)
  • src/chain/store/chain_store.rs
  • src/chain/store/index.rs
🔗 Linked repositories identified

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

  • filecoin-project/lotus (manual)

Comment thread src/chain/store/chain_store.rs Outdated
@hanabi1224 hanabi1224 force-pushed the hm/correct-ts-lookup-on-reorg branch from 4f9e0a3 to 7bcb805 Compare July 2, 2026 17:45
@hanabi1224 hanabi1224 force-pushed the hm/correct-ts-lookup-on-reorg branch from 7bcb805 to ddb71f4 Compare July 2, 2026 17:48

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/chain/store/index.rs`:
- Around line 184-189: The checkpoint lookup in `tipset_by_height` is trusting
`is_epoch_finalized` too early, which can let a stale forked tipset key be
reused or overwrite the cache. Update the logic around `checkpoint_from_epoch`
and the `set_heaviest_tipset`-written table entries so only finalized canonical
chain tipsets are accepted, or verify any loaded checkpoint is an ancestor of
the original `from` before replacing it. Apply the same fix to the corresponding
checkpoint update path in the nearby code that shares this logic.
🪄 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: 908d7131-0e93-47ab-a41b-5ca46f7bb486

📥 Commits

Reviewing files that changed from the base of the PR and between 4f9e0a3 and 7bcb805.

📒 Files selected for processing (3)
  • src/chain/store/chain_store.rs
  • src/chain/store/index.rs
  • src/daemon/mod.rs
🔗 Linked repositories identified

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

  • filecoin-project/lotus (manual)
💤 Files with no reviewable changes (1)
  • src/daemon/mod.rs
🚧 Files skipped from review as they are similar to previous changes (1)
  • src/chain/store/chain_store.rs

Comment thread src/chain/store/index.rs
@codecov

codecov Bot commented Jul 2, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 49.56522% with 58 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.17%. Comparing base (0db0e9f) to head (5079fb5).
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
src/daemon/mod.rs 0.00% 27 Missing ⚠️
src/chain/store/index.rs 70.83% 12 Missing and 2 partials ⚠️
src/chain/store/chain_store.rs 63.15% 5 Missing and 2 partials ⚠️
src/db/car/many.rs 0.00% 3 Missing ⚠️
src/db/parity_db/gc.rs 0.00% 3 Missing ⚠️
...tool/subcommands/api_cmd/generate_test_snapshot.rs 0.00% 3 Missing ⚠️
src/db/parity_db.rs 87.50% 0 Missing and 1 partial ⚠️
Additional details and impacted files
Files with missing lines Coverage Δ
src/chain_sync/chain_follower.rs 32.18% <ø> (ø)
src/db/memory.rs 89.87% <100.00%> (+0.26%) ⬆️
src/db/mod.rs 56.41% <ø> (ø)
src/db/parity_db.rs 69.59% <87.50%> (+3.44%) ⬆️
src/db/car/many.rs 54.68% <0.00%> (-0.63%) ⬇️
src/db/parity_db/gc.rs 31.42% <0.00%> (-0.69%) ⬇️
...tool/subcommands/api_cmd/generate_test_snapshot.rs 6.49% <0.00%> (-0.09%) ⬇️
src/chain/store/chain_store.rs 70.62% <63.15%> (-0.40%) ⬇️
src/chain/store/index.rs 86.64% <70.83%> (-3.96%) ⬇️
src/daemon/mod.rs 24.35% <0.00%> (ø)

... and 10 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 0db0e9f...5079fb5. 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.

@LesnyRumcajs

Copy link
Copy Markdown
Member

@hanabi1224 Can you summarize the root cause?

@hanabi1224 hanabi1224 force-pushed the hm/correct-ts-lookup-on-reorg branch from 940e4af to fe1916b Compare July 3, 2026 01:00

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
src/daemon/mod.rs (1)

845-848: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Hoist cs.ec_calculator_finalized_epoch() out of the filter closure. It’s invariant here, so compute it once before the loop.

🤖 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/daemon/mod.rs` around lines 845 - 848, Hoist the invariant
finalized-epoch lookup out of the filter closure in the tipset iteration loop.
In the `head.chain(cs.db())` loop, compute `cs.ec_calculator_finalized_epoch()`
once before the `for ts` statement in `src/daemon/mod.rs`, then reuse that local
value inside the `filter` predicate alongside
`ChainIndex::is_tipset_lookup_checkpoint(ts.epoch())`.
🤖 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/daemon/mod.rs`:
- Around line 845-848: Hoist the invariant finalized-epoch lookup out of the
filter closure in the tipset iteration loop. In the `head.chain(cs.db())` loop,
compute `cs.ec_calculator_finalized_epoch()` once before the `for ts` statement
in `src/daemon/mod.rs`, then reuse that local value inside the `filter`
predicate alongside `ChainIndex::is_tipset_lookup_checkpoint(ts.epoch())`.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: bbd82c1d-382c-422d-ae33-b2c00c5f4a8b

📥 Commits

Reviewing files that changed from the base of the PR and between ad13037 and 940e4af.

📒 Files selected for processing (1)
  • src/daemon/mod.rs
🔗 Linked repositories identified

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

  • filecoin-project/lotus (manual)

@hanabi1224 hanabi1224 force-pushed the hm/correct-ts-lookup-on-reorg branch from fe1916b to 712eabb Compare July 3, 2026 01:12
Comment thread src/chain/store/chain_store.rs
@hanabi1224 hanabi1224 force-pushed the hm/correct-ts-lookup-on-reorg branch from 1de1065 to dc2528f Compare July 6, 2026 18:14
@hanabi1224 hanabi1224 force-pushed the hm/correct-ts-lookup-on-reorg branch from dc2528f to dff772b Compare July 6, 2026 18:21
Comment thread src/chain/store/chain_store.rs
@LesnyRumcajs

Copy link
Copy Markdown
Member

Hm, stateful tests are failing. Is it related to the change?

@hanabi1224

Copy link
Copy Markdown
Contributor Author

Hm, stateful tests are failing. Is it related to the change?

@LesnyRumcajs I don't think so, it passed before I made the log level change. Retrying

@hanabi1224 hanabi1224 enabled auto-merge July 7, 2026 10:56
@hanabi1224 hanabi1224 added this pull request to the merge queue Jul 7, 2026
@github-merge-queue github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Jul 7, 2026
@hanabi1224 hanabi1224 added this pull request to the merge queue Jul 7, 2026
Merged via the queue into main with commit a4620a7 Jul 7, 2026
54 of 56 checks passed
@hanabi1224 hanabi1224 deleted the hm/correct-ts-lookup-on-reorg branch July 7, 2026 12:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

RPC requires calibnet RPC checks to run on CI

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants