feat(rpc): add Forest.ChainGetTipsetByParentState for trouble shooting state tree missing issues.

[hanabi1224]

Summary of changes

Changes introduced in this pull request:

• adds an RPC method to get tipset by its parent state tree root

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.

Summary by CodeRabbit

• New Features
  • Added a new chain RPC endpoint for querying tipsets by parent state, enabling enhanced blockchain state lookups.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This change adds a new RPC method ChainGetTipsetByParentState that retrieves the heaviest tipset matching a provided parent state CID. The chain_notify function signature is updated to accept an RPCState reference for accessing the chain store. The method is registered in the RPC framework and added to the test snapshot ignore list.

Changes

Cohort / File(s)	Summary
New RPC Method Implementation src/rpc/methods/chain.rs	Added public ChainGetTipsetByParentState enum implementing RpcMethod<1>. Handler accepts a parent state CID, queries the chain store for the heaviest tipset, and returns a matching tipset if found. Updated chain_notify function signature to accept RPCState<DB> reference for chain store access.
RPC Method Registration src/rpc/mod.rs	Registered ChainGetTipsetByParentState in the for_each_rpc_method macro to expose the new method through the RPC interface.
Test Configuration src/tool/subcommands/api_cmd/test_snapshots_ignored.txt	Added Forest.ChainGetTipsetByParentState to the snapshot ignore list.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Signature change to chain_notify: Verify no existing callers are affected by the addition of the RPCState parameter.
• RPC method handler logic: Confirm the chain store query and tipset matching logic correctly implements the intended behavior.
• Test implications: Ensure adding to snapshot ignores doesn't mask expected test coverage.

Suggested labels

RPC

Suggested reviewers

• sudo-shashank
• akaladarshi
• LesnyRumcajs

Pre-merge checks and finishing touches

❌ 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%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 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 a new RPC method Forest.ChainGetTipsetByParentState with a clear use case for troubleshooting state tree issues.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch hm/get-ts-by-parent-state

---

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

src/rpc/methods/chain.rs (2)

1262-1268: Remove the redundant .clone() call.

The .find() method already returns an owned Option<Tipset> from the iterator, so the .clone() is unnecessary.

 async fn handle( ctx: Ctx<impl Blockstore>, (parent_state,): Self::Params, ) -> Result<Self::Ok, ServerError> { Ok(ctx .chain_store() .heaviest_tipset() .chain(ctx.store()) - .find(|ts| ts.parent_state() == &parent_state) - .clone()) + .find(|ts| ts.parent_state() == &parent_state)) }

---

1248-1256: Consider adding a DESCRIPTION for API documentation consistency.

Other RPC methods include a DESCRIPTION field. Adding one here would improve the OpenRPC documentation.

 pub enum ChainGetTipsetByParentState {} impl RpcMethod<1> for ChainGetTipsetByParentState { const NAME: &'static str = "Forest.ChainGetTipsetByParentState"; const PARAM_NAMES: [&'static str; 1] = ["parentState"]; const API_PATHS: BitFlags<ApiPaths> = ApiPaths::all(); const PERMISSION: Permission = Permission::Read; + const DESCRIPTION: Option<&'static str> = Some( + "Returns the tipset matching the provided parent state CID by walking the chain from the heaviest tipset.", + ); type Params = (Cid,); type Ok = Option<Tipset>;

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 74a5f0c and 69a5f3c.

📒 Files selected for processing (3)

• src/rpc/methods/chain.rs (1 hunks)
• src/rpc/mod.rs (1 hunks)
• src/tool/subcommands/api_cmd/test_snapshots_ignored.txt (1 hunks)

🧰 Additional context used

🧠 Learnings (4)

📓 Common learnings

Learnt from: hanabi1224 Repo: ChainSafe/forest PR: 5944 File: src/chain/store/index.rs:0-0 Timestamp: 2025-08-18T03:09:47.932Z Learning: In Forest's tipset_by_height caching implementation, hanabi1224 prefers performance-conscious solutions that leverage finality guarantees rather than expensive chain walking for fork detection. The approach of constraining cache lookups to finalized epochs (using CHECKPOINT_INTERVAL >= CHAIN_FINALITY) provides fork safety without the performance cost of ancestry verification. 

Learnt from: hanabi1224 Repo: ChainSafe/forest PR: 5930 File: build.rs:64-77 Timestamp: 2025-08-13T09:43:20.301Z Learning: hanabi1224 prefers hard compile-time errors in build scripts rather than runtime safeguards or collision detection, believing it's better to fail fast and fix root causes of issues like malformed snapshot names. 

Learnt from: hanabi1224 Repo: ChainSafe/forest PR: 6057 File: src/cli/subcommands/f3_cmd.rs:0-0 Timestamp: 2025-09-09T10:37:17.947Z Learning: hanabi1224 prefers having default timeouts (like 10m for --no-progress-timeout) to prevent commands from hanging indefinitely, even when the timeout flag isn't explicitly provided by users. This fail-fast approach is preferred over requiring explicit flag usage. 

📚 Learning: 2025-10-17T14:24:47.046Z

Learnt from: hanabi1224 Repo: ChainSafe/forest PR: 6167 File: src/tool/subcommands/state_compute_cmd.rs:89-91 Timestamp: 2025-10-17T14:24:47.046Z Learning: In `src/tool/subcommands/state_compute_cmd.rs`, when using `ReadOpsTrackingStore` to generate minimal snapshots, `HEAD_KEY` should be written to `db.tracker` (not `db` itself) before calling `export_forest_car()`, because the export reads from the tracker MemoryDB which accumulates only the accessed data during computation. 

Applied to files:

• src/tool/subcommands/api_cmd/test_snapshots_ignored.txt
• src/rpc/methods/chain.rs

📚 Learning: 2025-08-18T03:09:47.932Z

Learnt from: hanabi1224 Repo: ChainSafe/forest PR: 5944 File: src/chain/store/index.rs:0-0 Timestamp: 2025-08-18T03:09:47.932Z Learning: In Forest's tipset_by_height caching implementation, hanabi1224 prefers performance-conscious solutions that leverage finality guarantees rather than expensive chain walking for fork detection. The approach of constraining cache lookups to finalized epochs (using CHECKPOINT_INTERVAL >= CHAIN_FINALITY) provides fork safety without the performance cost of ancestry verification. 

Applied to files:

• src/tool/subcommands/api_cmd/test_snapshots_ignored.txt

📚 Learning: 2025-08-08T12:11:55.266Z

Learnt from: hanabi1224 Repo: ChainSafe/forest PR: 5867 File: src/ipld/util.rs:461-487 Timestamp: 2025-08-08T12:11:55.266Z Learning: Forest (src/ipld/util.rs, Rust): In UnorderedChainStream::poll_next, dropping `extract_sender` (when no more tipsets and the extract queue is empty) is the intended shutdown signal for workers. Any subsequent attempt to enqueue work after this drop is a logic error and should be treated as an error; do not change `send()` to ignore a missing sender. 

Applied to files:

• src/rpc/methods/chain.rs

🧬 Code graph analysis (1)

src/rpc/methods/chain.rs (1)

src/blocks/tipset.rs (2)

• parent_state (350-352)
• parent_state (517-519)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)

• GitHub Check: Coverage
• GitHub Check: Build forest binaries on Linux AMD64
• GitHub Check: tests-release
• GitHub Check: tests
• GitHub Check: Build Ubuntu
• GitHub Check: Build MacOS
• GitHub Check: cargo-publish-dry-run
• GitHub Check: All lint checks

🔇 Additional comments (3)

src/rpc/mod.rs (1)

91-91: LGTM!

The new RPC method is correctly registered in the for_each_rpc_method macro, following the established pattern and placed logically after other Forest.Chain* methods.

src/tool/subcommands/api_cmd/test_snapshots_ignored.txt (1)

84-84: LGTM!

The new RPC method is correctly added to the test snapshots ignore list, maintaining alphabetical order. This is appropriate for a Forest-specific method that doesn't have a Lotus counterpart for comparison.

src/rpc/methods/chain.rs (1)

1271-1302: LGTM!

The chain_notify function signature update to accept &RPCState<DB> is appropriate and aligns with how it's called in src/rpc/mod.rs (line 530-531). The implementation correctly uses the chain store from the RPC state to get the heaviest tipset and subscribe to head changes.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 40.40%. Comparing base (74a5f0c) to head (69a5f3c).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/rpc/methods/chain.rs	0.00%	11 Missing ⚠️

Additional details and impacted files

Files with missing lines	Coverage Δ
src/rpc/mod.rs	15.10% <ø> (ø)
src/rpc/methods/chain.rs	20.79% <0.00%> (-0.27%)	⬇️

... and 8 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 74a5f0c...69a5f3c. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.