Add fallback for tx hash resolution by cid in claim token API

[sudo-shashank]

Summary of changes

Changes introduced in this pull request:

This PR fixes the issue reported in https://filecoinproject.slack.com/archives/C08UEF3HNLQ/p1760080099927249

• If we fail to resolve transaction hash from CID using Filecoin.EthGetTransactionHashByCid , we now return CID instead of Null.

Preview URL: https://7c29166.forest-explorer-preview.workers.dev

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

• Bug Fixes

  • Native token claim handling is more resilient: if an Ethereum transaction hash cannot be resolved, the response now falls back to returning the CID instead of failing.

• Documentation

  • API docs clarified: native token claim responses include the Ethereum transaction hash when resolvable; otherwise the CID is returned.

[coderabbitai]

Walkthrough

Adds a fallback in the native faucet claim flow: after submitting the signed message, the server attempts to fetch an Ethereum tx-hash via Filecoin.EthGetTransactionHashByCid and, on RPC error, logs a warning and returns the CID string. Documentation updated to clarify tx-hash vs CID behavior.

Changes

Cohort / File(s)	Summary
Docs - API clarification docs/api-documentation.md	Added note: native token claims return Ethereum tx hash when resolvable via Filecoin.EthGetTransactionHashByCid; otherwise return the CID.
Faucet server - native claim flow src/faucet/server_api.rs	Updated handle_native_claim to await eth_get_transaction_hash_by_cid(cid) and, on RPC error, log a warning and fall back to returning the CID string instead of propagating the error.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Faucet Server (handle_native_claim)
    participant F as Filecoin RPC

    C->>S: Submit signed native claim (CID)
    S->>F: EthGetTransactionHashByCid(CID)
    alt RPC returns tx-hash
        F-->>S: tx-hash
        note right of S #DFF2E1: Use tx-hash as result string
    else RPC error or no hash
        F--x S: error
        note right of S #FFF4E6: Log warning and fallback to CID string
    end
    S-->>C: 200 OK with result string (tx-hash or CID)

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Update claim token API to return transaction hash #321: Modifies native claim flow to use Filecoin.EthGetTransactionHashByCid and return a tx hash instead of a CID.
• Calibnet token claim api #315: Also updates src/faucet/server_api.rs / handle_native_claim to integrate tx-hash lookup and related behavior.

Suggested reviewers

• elmattic
• akaladarshi

Poem

I hop between hashes and CIDs with cheer,
If the chain is shy, a CID will appear.
A tiny fallback, a cautious little nod,
Claim confirmed — by tx or by pod.
((^._.^)ﾉ🌿)

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title succinctly and clearly describes adding a fallback for transaction hash resolution by CID in the claim token API, accurately reflecting the core change where the API now returns the CID when hash resolution fails.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ 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 shashank/fix-claim-token-api

---

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 0% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 39.31%. Comparing base (37b05f1) to head (7c29166).

Files with missing lines	Patch %	Lines
src/faucet/server_api.rs	0.00%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #326      +/-   ##
==========================================
- Coverage   39.37%   39.31%   -0.07%     
==========================================
  Files          40       40              
  Lines        2537     2541       +4     
==========================================
  Hits          999      999              
- Misses       1538     1542       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 37b05f1 and befe40c.

📒 Files selected for processing (2)

• docs/api-documentation.md (1 hunks)
• src/faucet/server_api.rs (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/faucet/server_api.rs (1)

src/utils/lotus_json/signed_message.rs (1)

• cid (36-42)

🔇 Additional comments (2)

src/faucet/server_api.rs (1)

292-296: Verify test coverage for the fallback path.

The codecov report indicates 0% coverage for these lines. The error fallback logic should be tested to ensure it behaves correctly when eth_get_transaction_hash_by_cid fails.

Consider adding a test case that:

1. Mocks eth_get_transaction_hash_by_cid to return an error
2. Verifies that the function returns the CID string
3. Confirms that appropriate logging occurs (if implemented per the previous comment)

docs/api-documentation.md (1)

19-21: Documentation accurately reflects the implementation.

The added documentation clearly describes the fallback behavior when transaction hash resolution fails, helping users understand what type of identifier they might receive.