fix(paywall): block Pay when the balance is known to be too low

[pedro-pelicioni]

fix(paywall): block Pay when the balance is known to be too low

Branch: fix/74-balance-guard
Screenshots: harness/shots/before-empty-balance.png → harness/shots/after-empty-balance.png

The bug

handlePayment in packages/paywall/src/browser/StellarPaywall.tsx guards on an
empty string:

if (tokenBalanceFormatted === "") {
  const freshBalance = await refreshBalance();
  if (Number(freshBalance) < amount) { /* reject */ }
}

useStellarBalance fetches the balance in a useEffect as soon as address
becomes non-null, so by the time the Pay button is clickable
tokenBalanceFormatted is already populated and the whole block is skipped. A
connected wallet holding less than the price goes straight to signing and only
fails afterwards, at verify/settle, with an error that does not name the cause.

Reproduce

Connect a wallet with 0 USDC to a route priced at $0.51 and press Pay. The
wallet prompts for a signature; the failure arrives from the facilitator.

Rendering the real component against a stubbed balance of 0n confirms it:

	Pay label	disabled
before	Pay	false
after	Insufficient USDC	true

The change

• Always compare balance against the requirement before paying; re-read the
  balance first only when it is not known.
• Compare in raw atomic units via isBalanceInsufficient rather than
  Number(formatted) < amount. Both sides are already atomic units of the same
  asset, so the comparison is exact and independent of the asset's decimals. The
  old float path also lost precision above 2^53 — there is a test for that case.
• refreshBalance now resolves to bigint | null instead of the formatted
  string, so callers can make that comparison. It is only consumed inside this
  package.
• Disable Pay while the balance is known to be insufficient, and say why:
  current balance, the Circle faucet link on testnet, and an inline
  "check again" that re-reads the balance.

A null balance — never fetched, or the read failed — leaves Pay enabled.
Unknown is not treated as insufficient, so a transient RPC blip cannot lock
someone out of paying.

Tests

8 new cases in utils.test.ts covering unknown balance, unparseable amount,
below/exact/above the price, a zero-price requirement, and the 2^53 precision
case. pnpm test, pnpm typecheck and pnpm lint all pass.

---

Part of #74.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.