Read vault and wallet USDC balances from Soroban instead of hardcoded values #1313

Summary

The balances users base funding decisions on are made up. The Billing page, the deposit modal and the Dashboard all show a vault balance of 284.62 and a wallet balance of 1260.5 USDC whatever the chain says. After a deposit, the UI adds the amount locally instead of reading the new balance back. This issue reads both balances from Stellar testnet through read-only Soroban simulation, and makes loading, error and stale states explicit.

Background and evidence

• src/App.tsx line 354 sets useState(284.62) for vaultBalance, and line 355 sets useState(1260.5) for walletBalance.
• These values feed:
  • the Billing vault cards (lines 692–704)
  • the modal balance tiles (lines 899–908)
  • the Max button (handleMax, line 532)
  • the "exceeds wallet balance" validation (line 434)
  • DashboardPage (line 664)
• After a confirmed deposit, line 578 sets the balance to startingBalance + approvedAmount, which is an optimistic local sum that is never reconciled with the chain.
• src/pages/DashboardOverview.tsx line 94 hardcodes the subtitle "Freighter Stellar Wallet (Public Net)" even though the app targets testnet.
• The contract interface (Callora-Contracts contracts/vault/src/lib.rs):
  • balance() (line 1231) returns the tracked vault balance in stroops (7 decimals).
  • get_usdc_token() (line 1261) returns the USDC SAC address. On testnet this is CAC7CFZ42L3LTTZCI4C3XI6UF7AHS2PYTNJ5QEG2PSLRGDGMWRQOZOT5 (docs/DEPLOYMENTS.md).
  • The SAC's balance(id) gives the wallet's USDC balance.

Scope

In scope

1. New module src/services/vaultReads.ts with:
   • readVaultBalance(): Promise<bigint>, which simulates balance() on STELLAR_VAULT_CONTRACT_ID.
   • readUsdcToken(): Promise<string>, which simulates get_usdc_token() and caches the result for the session.
   • readWalletUsdcBalance(address): Promise<bigint>, which simulates SAC balance(address).
   • All three use scValToNative, and stroops stay as bigint until formatting.
2. Hook useVaultBalances() returning { vault, wallet, status: "idle" | "loading" | "ready" | "error", error, refresh, updatedAt }.
   • The wallet read only runs once a Freighter address is known.
   • Requests are aborted or ignored when they are superseded.
3. Replace the hardcoded state in App.tsx with the hook.
   • Billing cards, modal tiles, Max and validation use real values.
   • While loading, show skeletons that do not shift layout.
   • On error, show an inline message with a Retry button, and never show 0 as if it were real.
4. Read back after deposit. After submitVaultDeposit resolves, call refresh() and show the chain value. Use the optimistic value only as a labelled "pending refresh" placeholder until the read returns.
5. Dashboard. Pass the same values to DashboardPage and correct the network label using STELLAR_NETWORK.

Out of scope

• Billing history, deposit preflight and trustline handling (separate issues).
• Backend /api/vault/balance integration.

Design constraints

• Money formatting must be exact. Convert stroops to a display string without going through Number for values above 2^53, and reuse or extend src/utils/format.ts.
• Make no network calls when no vault contract is configured. Show a "not configured" state instead.
• Simulation needs a source account. Use the connected address when there is one. Otherwise build the read with a valid, fixed, well-formed account and document why it is safe (simulation only, never signed).
• Debounce refreshes so opening and closing the modal does not flood the RPC. Allow at most one in-flight read per contract.
• WCAG 2.1 AA: balance updates are announced via a polite live region, and loading skeletons carry aria-busy.

Test plan

Add src/services/vaultReads.test.ts, and extend src/App.deposit.test.tsx and src/components/Dashboard.test.tsx as needed.

Regression proof. Row 5 fails on main, where line 578 computes the sum locally.

Acceptance criteria

• grep -n "284.62\|1260.5" src/App.tsx returns nothing.
• Billing, the deposit modal and the Dashboard show the same chain-sourced values.
• npx tsc -p tsconfig.json --noEmit, npm run build and npx vitest run pass.
• npm run test:coverage shows at least 90% line coverage for vaultReads.ts and the new hook.
• docs/Deposit-Flow.md describes the read-back.

Getting started

git checkout -b feat/onchain-vault-balances
npm ci
npx vitest run src/App.deposit.test.tsx
# read-only sanity check against the deployed vault:
stellar contract invoke --id CBJZLUKQBWDMZPKNJAVONZ7GCCWADSETRXWOPN5Z3XWAUNI4F2R7XDYQ --network testnet --send=no -- balance

PR requirements

• Link this issue.
• Include before and after screenshots of Billing and the Dashboard at 375px and 1280px.
• Include a short screen recording of a real testnet deposit followed by the balance refresh.
• Paste the test and coverage output, and keep the diff focused.
• Example commit: feat(vault): read vault and wallet balances via Soroban simulation.

Priority rationale

High. Wrong balances on a funding screen erode trust directly and can mislead users about money. The work spans Soroban simulation, i128 precision, async race handling and three surfaces that share state.