Add Session Expiration for Persisted Wallet State

[pragmaticAweds]

Context & Impact

The StellarWalletProvider.tsx restores wallet address and wallet ID from localStorage on every page load with no expiration check. If a user connected their wallet a week ago and the wallet's permissions have changed, or the Freighter session has expired, the app displays a stale "connected" state. Any transaction attempt will then fail with a confusing wallet error instead of prompting the user to reconnect.

Why this matters: Stale wallet sessions create a false sense of connection. Users see their address displayed and assume they're ready to transact, but the underlying wallet session may have expired. The first transaction attempt fails, and the error message doesn't indicate that reconnecting would fix it.

Scope

• Store a timestamp alongside the wallet address in localStorage
• Check the timestamp on restore — if older than a configurable TTL (e.g., 24 hours), clear the session
• Add a "session expired" state that prompts the user to reconnect
• Verify the wallet is actually accessible (ping kit.getAddress()) on session restore
• Show a subtle UI indicator when the session was auto-restored vs. freshly connected

Implementation Guidelines

• Store stellar_wallet_timestamp alongside existing stellar_wallet_address and stellar_wallet_id
• On restore, compare Date.now() - savedTimestamp > TTL — if expired, clear all wallet data
• Default TTL: 24 hours (configurable via a constant)
• After restoring from localStorage, verify the wallet is still accessible with a lightweight check
• If verification fails, clear the session and show a "Please reconnect your wallet" prompt
• Update the timestamp on every successful transaction to keep active sessions alive

Acceptance Criteria

• Wallet session timestamp is stored in localStorage alongside address
• Sessions older than 24 hours are automatically cleared on page load
• Users see a "Please reconnect" prompt when their session has expired
• Fresh wallet connections store a new timestamp
• Successful transactions refresh the session timestamp
• The TTL is configurable via a constant (not hardcoded in multiple places)
• Wallet verification on restore catches expired Freighter sessions
• No false "connected" states after session expiration

Getting Started

1. Read src/providers/StellarWalletProvider.tsx — focus on the localStorage restore logic (lines 71-90)
2. Add stellar_wallet_timestamp to the save/restore flow
3. Create a SESSION_TTL constant (default: 24 hours in milliseconds)
4. Add timestamp check in the restore useEffect
5. Add a lightweight verification call after restore (kit.getAddress() in a try-catch)
6. If expired or verification fails, clear storage and set state to disconnected
7. Test by manually setting an old timestamp in localStorage and refreshing

---

PR Submission Guide

This section applies to every PR for this issue. Follow it exactly.

Before You Start

• Fork the repository first if you haven't already — all contributions must come from a fork
• Pull the latest main branch: git checkout main && git pull origin main
• Create your feature branch from main: git checkout -b feat/<issue-number>-wallet-session-expiry

While Working

• Make atomic commits — one concern per commit, each commit must build
• Use Conventional Commits: feat(scope): description, fix(scope): description
• Keep your branch up to date: git pull origin main --rebase regularly

Before Submitting the PR

• Pull latest main and rebase: git checkout main && git pull origin main && git checkout <your-branch> && git rebase main
• Ensure the build passes: pnpm build
• Ensure linting passes: pnpm lint
• Record a screen recording of your implementation showing the feature/fix working in the browser. Attach it to the PR.

PR Requirements

• Link this issue in your PR description using Closes #<issue-number>
• Fill out the full PR template — Summary, What Was Implemented, Implementation Details, How to Test
• Attach your screen recording demonstrating the implementation
• Request a review from a maintainer

PRs without a screen recording or without a linked issue will not be reviewed. Failure to meet PR requirements may lead to PR rejection.

[Trovic1]

@Trovic1 has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

I have a strong background in React and the Stellar SDK, specifically with managing wallet states and provider patterns. I can implement the SESSION_TTL logic within StellarWalletProvider.tsx, ensuring that localStorage is properly validated against both a 24-hour timestamp and a live kit.getAddress() check to eliminate stale "connected" states.
I’ll ensure the session refreshes on successful transactions and provide a clean "Please reconnect" flow as requested.

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

[drips-wave]

Congratulations, @Trovic1! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on March 30, 2026.

🧑‍💻 @Trovic1: 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 🌊