Enforce instance-based daily request limit on testnet faucet

[Parsh]

Problem:

The testnetFaucet endpoint applies no cap on how many times a single app can request test satoshis per day. An app can call getTestcoins() an unlimited number of times, making it possible to drain faucet funds rapidly and starve other users of testnet coins.

Expected behaviour:

• Each app is identified by its appId when calling the faucet.
• An app is limited to 5 faucet requests per UTC calendar day.
• Requests beyond the daily limit are rejected with a clear error until the counter resets at midnight UTC.
• The client surfaces a user-readable message when the limit is reached.

[antuz123]

Feature Title

Testnet Faucet Daily Request Limit

Context

Bitcoin Keeper has a testnet faucet entry point inside Wallet Settings when Testnet mode is enabled from global app settings.

Current issue: the testnetFaucet endpoint has no per-app daily cap, so one app instance can repeatedly call getTestcoins() and drain faucet funds. The issue requires each app to be identified by appId, capped at 5 faucet requests per UTC calendar day, with requests beyond the limit rejected until midnight UTC. The app must show a user-readable message when the limit is reached. 

Goal

Prevent a single app instance from draining the testnet faucet while keeping the Receive Test Sats flow simple and understandable for users.

Non-Goals

• Do not change where Testnet mode is enabled.
• Do not add user accounts or login.
• Do not add mainnet faucet behavior.
• Do not apply the limit by wallet ID, address, IP, or device name unless needed as a backend fallback.
• Do not block normal testnet receive behavior outside faucet requests.

User Flow

User has Testnet mode enabled from global app settings.

User opens a testnet wallet.

User goes to:

Wallet Settings → Receive Test Sats

User requests test sats.

System sends faucet request with appId.

If the app has made fewer than 5 requests for the current UTC day:

• request is allowed
• faucet sends test sats
• existing success state is shown

If the app has already made 5 requests for the current UTC day:

• request is rejected
• app shows limit-reached message
• user remains on the Receive Test Sats screen

Counter resets at midnight UTC.

Screens / States

State: Wallet Settings entry

Screen type: Wallet Settings list item

Title: Receive Test Sats

Body copy: Receive test sats in your wallet

Button label: None. Existing row tap behavior.

Warnings/info text: None.

Error text: None.

Success text: None.

Behaviours:

• Show this row only when global Testnet mode is active.
• Hide this row in Mainnet mode.
• Tapping opens the existing Receive Test Sats flow.
• Do not add Testnet mode controls here.

Navigation transition:

• Wallet Settings → Receive Test Sats screen

State: Receive Test Sats default

Screen type: Existing Receive Test Sats screen

Title: Receive Test Sats

Body copy: Use existing body copy unless already inaccurate.

Primary button label: Receive

Warnings/info text:
You can request test sats up to 5 times per day.

Error text: None by default.

Success text: Use existing success message.

Behaviours:

• On primary action, call getTestcoins() with the app’s appId.
• Disable the primary button while the request is in progress.
• Prevent duplicate taps while one faucet request is pending.
• Do not count failed network attempts on the client as successful faucet usage unless backend confirms the request consumed quota.

Navigation transition:

• Back returns to Wallet Settings.

State: Faucet request successful

Screen type: Existing success state, toast, or inline confirmation

Title: Keep existing title if present.

Body copy: Keep existing success copy if present.

Primary button label: Existing button label.

Warnings/info text: None.

Error text: None.

Success text:
Test sats requested.

Behaviours:

• Show existing transaction/request feedback.
• Return user to existing post-success state.
• Do not expose technical transaction details unless existing flow already does.

Navigation transition:

• User may return to Wallet Settings or wallet screen using existing navigation.

State: Daily limit reached

Screen type: Inline error or bottom-sheet error using existing Keeper error pattern

Title: Daily Limit Reached

Body copy:
You can request test sats up to 5 times per day. Try again after midnight UTC.

Primary button label: OK

Warnings/info text: None.

Error text:
Daily limit reached. Try again after midnight UTC.

Success text: None.

Behaviours:

• Show this when backend rejects the faucet request because the app has reached 5 requests for the UTC day.
• Keep the user on the Receive Test Sats screen.
• Do not retry automatically.
• Re-enable the primary button only when the user can make another attempt, or leave it enabled and show the same backend-driven error if retried before reset.
• Prefer backend response as source of truth.

Navigation transition:

• OK dismisses the message and stays on Receive Test Sats.

State: Faucet unavailable or network error

Screen type: Existing Keeper error pattern

Title: Request Failed

Body copy:
Unable to request test sats. Check your connection and try again.

Primary button label: Try Again

Warnings/info text: None.

Error text:
Unable to request test sats.

Success text: None.

Behaviours:

• Use this only for non-quota errors.
• Do not show daily limit copy for generic failures.
• Allow retry.

Navigation transition:

• Try Again repeats request.
• Back returns to Wallet Settings.

Copy Requirements

Use:

• Receive Test Sats
• test sats
• Daily Limit Reached
• You can request test sats up to 5 times per day. Try again after midnight UTC.

Do not use:

• crypto faucet
• free coins
• claim coins
• tokens
• Vault

Button labels must remain short:

• Receive
• OK
• Try Again

Design Requirements

• Reuse existing Wallet Settings card/list styling shown in current app.
• Reuse existing row component with title, subtitle, divider, and chevron.
• Reuse existing error modal, bottom sheet, toast, or inline error component already used for request failures.
• Do not introduce a new faucet-specific visual pattern.
• Ensure the daily limit message does not truncate on small iPhone/Android widths.
• If buttons do not fit, use full-width stacked buttons.
• Do not shrink font sizes to fit error copy.

Existing Components

• Wallet Settings screen
• Settings row/list item component
• Existing Receive Test Sats screen or flow
• Existing loading state for async request
• Existing error modal/bottom sheet/toast pattern
• Existing success confirmation pattern

Existing Assets

No new assets required.

Assets & References

Reference screen:

• Wallet Settings screen with Receive Test Sats row visible when Testnet mode is enabled.

SVG Requirements

No SVG required.

Implementation Notes

• Backend must enforce the quota. Client-side limiting may be added only as a convenience, not as the security control.
• Faucet request must include appId.
• Limit key should be based on appId and UTC date.
• Limit is 5 successful faucet requests per UTC calendar day.
• Request 6 onward returns a structured quota error.
• Counter resets at midnight UTC.
• Backend response should include an error code that the client can map to daily-limit copy, for example FAUCET_DAILY_LIMIT_REACHED.
• Client must distinguish quota errors from network/server errors.
• Testnet mode is controlled from global app settings. Do not move or duplicate that setting into Wallet Settings.
• The Receive Test Sats row appears inside Wallet Settings only when Testnet mode is active.

Acceptance Criteria

• Given Testnet mode is off, Receive Test Sats is not shown in Wallet Settings.
• Given Testnet mode is on, Receive Test Sats is shown in Wallet Settings.
• Given an app has made 0 to 4 faucet requests today UTC, the next request is accepted.
• Given an app has made 5 faucet requests today UTC, the next request is rejected.
• Given a request is rejected due to quota, the app shows: You can request test sats up to 5 times per day. Try again after midnight UTC.
• Given the UTC date changes after midnight, the same appId can request test sats again.
• Given two different appIds request test sats, each has its own daily limit.
• Given the network fails, the app shows a generic request failure, not the daily limit message.
• Rapid repeated taps cannot bypass the limit or submit duplicate in-flight requests from the UI.
• Mainnet wallet behavior is unchanged.

Open Questions

None.