Payments 6/8: Wallet onboarding and non-custodial payment UX for non-crypto-native users #143

Problem / Context

app/src/components/wallet/WalletButton.tsx only implements Freighter (window.freighter.requestAccess/getNetwork, lines 35-51); LOBSTR and xBull are explicit "coming soon" stubs (line 61). More importantly, nothing in the app ever calls signTransaction — the WalletAdapter interface in app/src/lib/wallet/types.ts declares it (line 25), but no concrete adapter implementing that interface exists anywhere in the codebase; WalletButton only ever calls Freighter's connect-time methods. The deposit flow shows a hardcoded fee string, '0.00001 XLM' (app/src/app/deposit/page.tsx line 46), instead of a real estimate, and never explains USDC trustlines, the protocol's non-custodial model, or what signing actually authorizes. EarlyExitModal's submit button (lines 88-98) has no handler at all — clicking "Exit Early" currently does nothing.

For a savings product explicitly aimed at users who may not be crypto-native (per this issue's scope), this is the layer that determines whether they can complete a payment at all.

Objective

Make wallet connection, transaction signing, and the surrounding trust/custody explanation actually work end-to-end for a first-time Stellar-wallet user.

Technical approach

• Implement a real WalletAdapter (per app/src/lib/wallet/types.ts) for Freighter that implements signTransaction, and wire it in as the concrete signer consumed by the SDK pipeline from Payments 2/8: Implement real Soroban transaction pipeline in the TypeScript SDK #139.
• Add USDC trustline detection before deposit: query the connected account's trustlines, and if the USDC trustline is missing, present a clear "Add USDC trustline" step (a separate signed transaction) before the deposit step, rather than letting the deposit fail opaquely at simulation.
• Replace the hardcoded fee string with a real resource-fee estimate sourced from the SDK's simulation step (Payments 2/8: Implement real Soroban transaction pipeline in the TypeScript SDK #139), with a one-line explanation that this is a network fee, not a YieldLadder fee — relevant for users who may otherwise conflate the two.
• Add a brief, persistent non-custodial explainer at the deposit confirmation step (step 3) grounded in the actual architecture from the README (e.g., "YieldLadder never takes custody of your funds — every withdrawal requires your own wallet signature"), not generic marketing copy.
• Wire EarlyExitModal's "Exit Early" button to the real, idempotency-guarded submission pipeline (Payments 2/8: Implement real Soroban transaction pipeline in the TypeScript SDK #139/Payments 3/8: Idempotency and duplicate-payment-submission prevention #140), including equivalent trust-and-fee context at the point of confirmation.
• Extend wallet support beyond Freighter (LOBSTR and/or xBull) if a suitable signing API is available; if not, explicitly scope this issue to Freighter and note the others as an intentional follow-up rather than leaving silent "coming soon" stubs unexplained in the UI.

Detailed scope

app/src/components/wallet/WalletButton.tsx, a new app/src/lib/wallet/freighterAdapter.ts (or similar) implementing WalletAdapter, app/src/app/deposit/page.tsx (fee display, trustline step, explainer copy), and app/src/components/EarlyExitModal.tsx (wire submit handler + explainer).

Important edge cases and failure scenarios

• Wallet installed but pointed at the wrong network (e.g., Freighter set to testnet while the app targets mainnet, or vice versa) — must be detected and clearly surfaced before the user attempts to sign, not discovered as an opaque submission failure.
• The trustline-addition transaction itself can fail or be rejected — the user must not be left stuck between "no trustline" and "deposit step" with no way back to retry or cancel cleanly.
• Multiple wallet extensions installed simultaneously can cause ambiguity in which provider's injected API responds — adapter selection must be explicit per the user's chosen provider, not "whichever loaded first."
• The fee estimate shown before signing may differ slightly from the fee actually charged (resource-fee variance under load) — decide whether to present a fixed estimate, a range, or an "up to" ceiling, and be honest about which.

Dependencies

Depends on #139 (a signer interface needs a real transaction pipeline to plug into) and benefits from #140 (idempotency guarding) already being in place so the newly-wired "Exit Early" button is safe by construction from day one.

Acceptance criteria

• A first-time Freighter user can connect, get prompted to add a USDC trustline if missing, deposit, and see a real (not hardcoded) fee estimate — demonstrated manually against testnet.
• EarlyExitModal's exit button performs a real, guarded early-exit transaction end to end.
• Deposit and early-exit confirmation screens contain accurate, architecture-grounded non-custodial explanation copy (not generic marketing language).

Definition of done

PR merged; a manual walkthrough (documented, ideally with screenshots or a short recording) shows a clean-account testnet wallet going from zero to a confirmed deposit, including trustline setup; no dead/unwired submit buttons remain anywhere in the payment flow.