### [FRONTEND-11] Implement Persistent Wallet Session with useLocalStorage and Auto-Reconnect

[orunganiekan]

Points: 200
Labels: frontend, hooks, ux, freighter, session
Background: useWallet.ts stores publicKey in component state — it is lost on every page refresh. Every session requires the user to click "Connect Wallet" again and wait for Freighter to respond. useLocalStorage.ts already exists but is not used by useWallet. The useFreighterAvailable hook confirms Freighter is present, and Freighter's isConnected() can silently verify a persisted session. On reconnect, if the stored public key no longer matches the connected Freighter account (user switched accounts), the stale key must be cleared rather than used silently — this is a security concern since all contract reads and transaction builds use the public key as the sourcePublicKey.

Task: Update useWallet.ts to persist publicKey via useLocalStorage('wallet_public_key', null). On mount, if a stored key exists: call freighterService.isConnected() and freighterService.getPublicKey() silently — if the returned key matches the stored key, auto-restore the session without a user prompt. If the keys differ (account switch), clear storage and set publicKey = null. Expose sessionRestored: boolean in the return value so App.tsx can skip rendering the ConnectWallet screen during the auto-restore check. Add a connecting state that covers both manual connect and auto-restore.

Key files: - frontend/src/hooks/useWallet.ts — integrate useLocalStorage; add auto-reconnect logic; expose sessionRestored

• frontend/src/hooks/useLocalStorage.ts — verify it handles null serialization correctly (currently may not — audit)
• frontend/src/App.tsx — consume sessionRestored to show a loading state instead of ConnectWallet during restore
• frontend/src/__tests__/useFreighterAvailable.test.tsx — add test: stored key matching Freighter key restores session; mismatched key clears storage

Acceptance criteria: - [ ] publicKey persisted to localStorage under key 'wallet_public_key'

• On mount with a stored key, auto-reconnect attempt is made silently (no user prompt)
• Mismatched key (user switched Freighter account externally) clears storage and sets publicKey = null
• sessionRestored: boolean is false during check, true after check completes (regardless of outcome)
• App.tsx renders a loading indicator instead of ConnectWallet while !sessionRestored
• Test: stored key matches → publicKey restored; stored key mismatches → publicKey null
• npm run typecheck passes

[ekwe7]

@ekwe7 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would love to work on this issue. I have experience building production ready applications and collaborating through GitHub workflows. I'll carefully analyze the current implementation, propose a reliable solution, and submit a well-tested PR. My focus is on clean code, maintainability, and timely delivery

ℹ️ Repo Maintainers: To accept this application, review their application or assign @ekwe7 to this issue.

[Bug-Hunter-X]

@Bug-Hunter-X has applied to work on this issue as part of the Stellar Wave Program's 6th wave.


I understand the expected outcome and would love to work on this. I'll provide a solution that satisfies the acceptance criteria.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Bug-Hunter-X to this issue.

[Abd-Standard]

@Abd-Standard has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

please allow me to work on this issue maintainer

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Abd-Standard to this issue.

[drips-wave]

Congratulations, @Gbena-afk! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Gbena-afk: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊