Handle low faucet balance in claim token API

[sudo-shashank]

Summary of changes

Changes introduced in this pull request:

• Check for low faucet balance and return error.
• Updated api doc

Preview URL: https://1fac3c2.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

• New Features

  • Added a pre-check for faucet token claims that verifies available balance and returns a clear error (“Faucet is empty, Request top‑up”) when funds are insufficient.

• Documentation

  • Added a “Faucet Top‑Up Requests” section describing behavior when the faucet is exhausted, with an example error and a link to request a top‑up.

[coderabbitai]

Walkthrough

Adds a docs section "Faucet Top-Up Requests" and inserts an SSR-gated faucet-balance pre-check into claim_token that queries rpc.wallet_balance and returns a ServerError if funds are insufficient before continuing the existing claim flow.

Changes

Cohort / File(s)	Summary of Changes
Documentation docs/api-documentation.md	Added "Faucet Top-Up Requests" section describing behavior when faucet is exhausted, example error, and link to request a top-up.
Faucet Server API src/faucet/server_api.rs	Added ensure_faucet_has_funds helper (feature-gated ssr) and a pre-check in claim_token that calls rpc.wallet_balance; returns ServerError ("Faucet is empty, Request top-up") if balance < required amount (drip + max gas estimate), otherwise proceeds with existing flow.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant C as Client
    participant S as Faucet Server (claim_token)
    participant R as RPC (wallet_balance)
    participant F as Existing Faucet Logic

    C->>S: POST /claim_token
    S->>R: wallet_balance(faucet_address)
    R-->>S: balance
    alt balance < required_amount
        S-->>C: 500 / ServerError "Faucet is empty, Request top-up"
    else balance >= required_amount
        S->>F: continue existing claim flow
        F-->>S: result
        S-->>C: response (unchanged)
    end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• Add automated tests for claim_token endpoint #319 — Tests and validations around claim_token flows; this PR adds a wallet balance pre-check that those tests should cover.

Possibly related PRs

• Calibnet token claim api #315 — Modifies claim_token endpoint; closely related to the same function changed here.
• Update claim token API to return transaction hash #321 — Also changes claim_token control flow/output (e.g., tx hash); relevant to interactions with this pre-check.

Suggested reviewers

• akaladarshi
• hanabi1224

Poem

A nibble, a drip, my whiskers twitch—
I peek the balance, find a glitch.
“Faucet empty,” soft I plea,
Send a top-up, then funds run free.
Hops resume when coins are fed—bravo! 🐇💧

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly and accurately summarizes the primary change of adding a low-faucet-balance check to the claim token API, making it clear and specific without unnecessary terms or noise.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ 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/claim-api-balance-check

---

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

[codecov-commenter]

Codecov Report

❌ Patch coverage is 0% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 39.09%. Comparing base (5c0da54) to head (d03d7bd).

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #327      +/-   ##
==========================================
- Coverage   39.37%   39.09%   -0.28%     
==========================================
  Files          40       40              
  Lines        2537     2555      +18     
==========================================
  Hits          999      999              
- Misses       1538     1556      +18     

☔ 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: 2

📜 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 1fac3c2.

📒 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 (2)

src/utils/rpc_context.rs (2)

• new (42-59)
• new (111-113)

src/faucet/controller.rs (1)

• new (24-85)

🪛 markdownlint-cli2 (0.18.1)

docs/api-documentation.md

157-157: Link text should be descriptive

(MD059, descriptive-link-text)

[coderabbitai]

Actionable comments posted: 0

♻️ Duplicate comments (2)

src/faucet/server_api.rs (2)

222-222: Balance check runs before rate limiting (duplicate concern).

The ensure_faucet_has_funds check runs here, but rate limiting occurs later in signed_fil_transfer (line 112) and signed_erc20_transfer (line 158). This creates a TOCTOU race window where concurrent requests can pass the balance check but then be serialized by rate limiting, as already noted in previous reviews.

---

257-274: Missing native FIL balance check for ERC-20 transfers (duplicate concern).

For CalibnetUSDFC (ERC-20 faucet), line 264 checks the ERC-20 token balance, but ERC-20 transfers require native FIL to pay gas fees. The faucet could have adequate ERC-20 tokens but insufficient native FIL for gas, leading to transaction failures after passing this check, as already noted in previous reviews.

🧹 Nitpick comments (1)

src/faucet/server_api.rs (1)

257-274: Add test coverage for the new balance validation logic.

Codecov reports 0% patch coverage for this file. Consider adding unit tests for ensure_faucet_has_funds to verify:

• Sufficient balance allows claims to proceed
• Insufficient balance returns the correct error
• Gas estimation is calculated correctly
• Edge cases (balance exactly at threshold, zero balance, etc.)

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f869b1a and d03d7bd.

📒 Files selected for processing (1)

• src/faucet/server_api.rs (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/faucet/server_api.rs (2)

src/utils/rpc_context.rs (2)

• new (42-59)
• new (111-113)

src/faucet/controller.rs (1)

• new (24-85)

⏰ 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). (3)

• GitHub Check: e2e
• GitHub Check: codedov
• GitHub Check: deploy