neuron-tai/docs/issues/40-devnet-dashboard-topup.md

US-040 — Devnet top-up button on the dashboard

Status: planned Priority: High (friends-test convenience — refill without on-chain deposits) Stage: Designed

Context

Once Caller Credit (US-039) is spent, the only refill path is a real USDT deposit through the treasury watcher — devnet Solana plumbing friends won't have. For test deployments the dashboard needs a "add $10" style button. This is a faucet: 0 disables it, and mainnet deployments must set 0.

Design

1. --devnet-topup N (USDT per click) on meshnet-tracker start; stack variable DEVNET_TOPUP. Default is the single constant DEFAULT_DEVNET_TOPUP_USDT = 1.0 in server.py (devnet-friendly alpha, revised 2026-07-06 — the alpha's public trackers are devnet-only).
2. POST /v1/account/topup — session-authenticated (same as key management). Body: {"api_key": "sk-mesh-..."}. Rules:
   • 404 when the feature is disabled (flag absent/0)
   • key must belong to the logged-in account (403 otherwise)
   • credits exactly the configured amount (client cannot choose it), note devnet-topup; returns the new balance
3. Dashboard: /v1/account response gains topup_amount (0 when disabled); when positive, each key row renders a +$N (devnet) button calling the endpoint.
4. Abuse bound: per-click amount is operator-set and requires a registered session; acceptable for a friends-test faucet. Mainnet deployments simply never set the flag. (Rate limiting is deliberately out of scope.)

Acceptance criteria

• Flag off: endpoint 404s, dashboard shows no top-up button
• Flag on: logged-in user tops up own key, balance rises by exactly N
• Topping up another account's key → 403
• python -m pytest passes from repo root