Implement Full Wallet Page with Balance, Assets, Activity History, and Fiat Off-Ramping

[0xdevcollins]

Create a comprehensive wallet page (/wallet) that extends the functionality of the wallet sheet component. This page provides users with a complete view of their abstracted wallet including balance overview, asset management, full transaction history, and the ability to off-ramp crypto earnings to fiat currency. Since wallet connection is abstracted, users don't need to manually connect—their wallet is automatically provisioned and managed by the platform.

Problem Statement

While the wallet sheet provides a quick overview, users need a dedicated page to:

• View detailed asset breakdowns and token holdings
• Access complete transaction history with filtering
• Off-ramp their crypto earnings to fiat (bank transfer, etc.)
• Manage withdrawal settings and preferences
• View pending and completed payouts

User Story
As a contributor who has earned bounty rewards, I want a dedicated wallet page where I can view all my earnings, manage my assets, and withdraw funds to my bank account so that I can access my rewards in fiat currency.

Acceptance Criteria

Page Layout & Navigation

• Create /wallet route accessible from header and wallet sheet "View More" link
• Implement responsive layout with proper mobile experience
• Add page metadata for SEO
• Include breadcrumb navigation
• Match existing app design language (dark theme, ambient glow)

Wallet Overview Section

• Display user's abstracted wallet address (truncated with copy)
• Show "Abstracted Wallet" indicator explaining no connection needed
• Display wallet creation date
• Show verification/security status

Balance Card Section

• Large balance display with total USD value
• Show balance breakdown by currency/token
• Display pending earnings (awaiting confirmation)
• Show available for withdrawal amount
• Include 24h/7d/30d balance change indicators

Assets Section (Extended)

• Full list of all token holdings
• Each asset displays: icon, name, symbol, amount, USD value, % of portfolio
• Sort options: value, name, recent
• Search/filter assets
• Empty state for new users
• Click asset to view token-specific transactions

Activity/Transaction History Section (Extended)

• Complete paginated transaction history
• Filter by type: All, Earnings, Withdrawals, Pending
• Filter by date range
• Search transactions
• Each transaction shows: type icon, description, amount, date, status, bounty link
• Transaction detail modal/expansion
• Export transaction history (CSV)

Off-Ramp / Withdrawal Section

• "Withdraw to Bank" primary action button
• Display connected bank accounts / payment methods
• Add new bank account / payment method flow
• Withdrawal amount input with max button
• Show withdrawal fees and estimated receive amount
• Withdrawal confirmation modal
• Pending withdrawals list with status tracking
• Withdrawal limits display (daily/monthly)

Security Section

• Two-factor authentication status and setup
• Withdrawal whitelist settings
• Recent security activity log
• Session management
• Technical Requirements

Edge Cases

• User has no bank accounts (show add account prompt)
• Withdrawal amount exceeds available balance
• Withdrawal amount below minimum
• Daily/monthly limit reached
• Bank account verification pending
• Two-factor authentication required for withdrawal
• Withdrawal processing failure
• Network error during submission
• Empty transaction history
• Empty asset list
• Very long transaction history (pagination)

[linear]

BOU-73

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#17 - feat: Built BountyCard component with shadcn composition [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 100 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[coderabbitai]

Coding Plan

Approach

Create a comprehensive /wallet page that displays users' abstracted wallet information including balance overview, asset management, transaction history with filtering/pagination, and fiat off-ramping capabilities. Since no wallet infrastructure currently exists, this requires building the complete data layer with mock data, API routes, and all UI components from scratch following existing codebase patterns.

Observations

This Next.js 15 application uses TanStack Query for data fetching, shadcn/ui components (New York style), and a dark theme with ambient glow effects. The project follows a mock-first architecture where API routes in app/api/ serve mock data during development. Type definitions live in types/, mock data generators in lib/mock-*.ts, and custom hooks in hooks/. Authentication uses better-auth with a mock user fallback in development. The UI uses container-based responsive layouts with consistent patterns across pages like /leaderboard, /bounty, and /discover. No wallet, payment, or financial infrastructure currently exists—only basic walletAddress, totalEarnings, and rewardAmount fields in leaderboard and bounty types.

Assumptions

Assumption 1: Wallet Sheet Scope

Options Considered:

1. Build a full wallet sheet component first, then the wallet page
2. Build the wallet page and add a minimal header trigger/link that navigates to /wallet

Chosen Option: 2

Rationale: Focus on the wallet page as the primary deliverable and add navigation entry points in the header. A full wallet sheet can be a follow-up enhancement.

Assumption 2: Off-Ramp Implementation Depth

Options Considered:

1. Integrate a real off-ramp provider (Transak, Coinbase Offramp, etc.)
2. Build mock UI and data structures that simulate the withdrawal flow for future integration

Chosen Option: 2

Rationale: Build complete UI flows with mock data following the existing development patterns. This creates the full user experience while deferring actual payment integration to when the backend infrastructure is ready.

Assumption 3: Security Features Implementation

Options Considered:

1. Implement actual 2FA and security features in the auth system
2. Build placeholder/display-only UI showing security status with mock data

Chosen Option: 2

Rationale: Create display-only security section showing mock status. Actual security implementation is outside the scope of a wallet page ticket and would require auth system changes.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Data Foundation

Establish the complete data layer including TypeScript types, mock data generators, API routes, and data fetching hooks. This phase creates all the infrastructure needed for the wallet page to function.

Task 1: Define Wallet TypeScript Types

Create comprehensive type definitions for all wallet-related data structures that will be used throughout the wallet page.

• Create types/wallet.ts with interfaces for:
  • Wallet - address, createdAt, verificationStatus, securityLevel
  • WalletBalance - totalUsdValue, availableForWithdrawal, pendingEarnings, assets array, changeIndicators (24h/7d/30d)
  • Asset - id, name, symbol, iconUrl, amount, usdValue, portfolioPercentage
  • Transaction - id, type (earning/withdrawal/pending), description, amount, currency, usdValue, timestamp, status, bountyId (optional), bountyTitle (optional)
  • BankAccount - id, bankName, accountType, lastFourDigits, isVerified, isPrimary, addedAt
  • Withdrawal - id, amount, currency, usdValue, fee, netAmount, status, bankAccountId, createdAt, estimatedArrival
  • WithdrawalLimits - daily, monthly, used amounts
  • SecurityStatus - twoFactorEnabled, lastPasswordChange, activeSessions, recentActivity array
• Export filter/sort enums: TransactionType, TransactionStatus, AssetSortOption
• Add pagination types: PaginatedResponse<T> with items, total, page, pageSize, hasMore

Task 2: Create Mock Wallet Data

Build mock data generators that produce realistic wallet data for development, following the patterns established in lib/mock-leaderboard.ts and lib/mock-bounty.ts.

• Create lib/mock-wallet.ts with:
  • getMockWallet() - returns wallet with Stellar-format address (G...), creation date, verification status
  • getMockBalance() - generates balance with XLM, USDC holdings, pending earnings, random change indicators
  • getMockAssets() - array of 3-8 mock tokens with realistic amounts and USD values
  • getMockTransactions(page, limit, filters) - paginated transaction list with bounty references, supports type/date filtering
  • getMockBankAccounts() - 0-3 bank accounts with verification statuses
  • getMockWithdrawals() - pending and completed withdrawal history
  • getMockSecurityStatus() - mock 2FA status, sessions, activity log
• Use seeded randomness where appropriate for consistent mock data across refreshes
• Include realistic timestamps spanning the past 6 months for transaction history

Task 3: Create Wallet API Routes

Build Next.js API routes that serve mock wallet data with simulated network latency, following the pattern in app/api/leaderboard/route.ts.

• Create app/api/wallet/route.ts - GET returns wallet overview data
• Create app/api/wallet/balance/route.ts - GET returns balance and assets
• Create app/api/wallet/transactions/route.ts - GET with pagination and filter query params
• Create app/api/wallet/bank-accounts/route.ts - GET list, POST add new account
• Create app/api/wallet/withdrawals/route.ts - GET history, POST initiate withdrawal
• Create app/api/wallet/security/route.ts - GET security status
• Each route should include 200-500ms simulated delay using setTimeout
• Return appropriate error responses for edge cases (unauthorized, invalid params)

Task 4: Create Wallet Data Fetching Hooks

Build custom TanStack Query hooks for fetching and mutating wallet data, following patterns in hooks/use-user-mutations.ts and leaderboard hooks.

• Add wallet query keys to lib/query/query-keys.ts:
  • walletKeys.all, walletKeys.overview, walletKeys.balance, walletKeys.transactions(filters), walletKeys.bankAccounts, walletKeys.withdrawals, walletKeys.security
• Create hooks/use-wallet.ts with:
  • useWallet() - fetches wallet overview
  • useWalletBalance() - fetches balance with assets
  • useWalletTransactions(filters, page) - paginated transaction history
  • useWalletAssets() - derived from balance, with sorting/filtering support
• Create hooks/use-wallet-mutations.ts with:
  • useAddBankAccount() - mutation for adding bank account
  • useRemoveBankAccount() - mutation for removing bank account
  • useInitiateWithdrawal() - mutation for starting withdrawal
  • Each mutation should invalidate relevant queries on success and show toast notifications

🤖 Prompt for AI agents

This phase establishes the complete data layer for the wallet page, creating the
foundation for all wallet functionality with TypeScript types, mock data, API
routes, and data fetching hooks.

**Type Definitions (types/wallet.ts):**
- Create comprehensive interfaces for all wallet entities: `Wallet`,
`WalletBalance`, `Asset`, `Transaction`, `BankAccount`, `Withdrawal`,
`WithdrawalLimits`, `SecurityStatus`
- Key fields for `Wallet`: address, createdAt, verificationStatus, securityLevel
- Key fields for `WalletBalance`: totalUsdValue, availableForWithdrawal,
pendingEarnings, assets array, changeIndicators (24h/7d/30d)
- Key fields for `Transaction`: id, type, description, amount, currency,
usdValue, timestamp, status, optional bountyId and bountyTitle
- Export enums for `TransactionType`, `TransactionStatus`, `AssetSortOption`
- Create generic `PaginatedResponse<T>` type with items, total, page, pageSize,
hasMore

**Mock Data Generators (lib/mock-wallet.ts):**
- Follow patterns from existing `lib/mock-leaderboard.ts` and
`lib/mock-bounty.ts`
- Implement functions: `getMockWallet()`, `getMockBalance()`, `getMockAssets()`,
`getMockTransactions(page, limit, filters)`, `getMockBankAccounts()`,
`getMockWithdrawals()`, `getMockSecurityStatus()`
- Use Stellar-format addresses (starting with G) for wallet addresses
- Generate realistic XLM and USDC holdings with random change indicators
- Create 3-8 mock assets per wallet with proper amounts and USD values
- Generate paginated transactions with bounty references, supporting type and
date filtering
- Use seeded randomness for consistency and timestamps spanning past 6 months

**API Routes (app/api/wallet/):**
- Follow existing pattern from `app/api/leaderboard/route.ts`
- Create separate routes: `route.ts` (overview), `balance/route.ts`,
`transactions/route.ts`, `bank-accounts/route.ts`, `withdrawals/route.ts`,
`security/route.ts`
- All GET routes return mock data from the generators
- POST routes for `bank-accounts` and `withdrawals` simulate mutations
- Include 200-500ms simulated delay with `setTimeout`
- Handle pagination and filter query params in transactions route
- Return appropriate error responses (401 unauthorized, 400 invalid params)

**Data Fetching Hooks (hooks/):**
- Add wallet query keys to `lib/query/query-keys.ts` following existing
patterns: `walletKeys.all`, `walletKeys.overview`, `walletKeys.balance`,
`walletKeys.transactions(filters)`, etc.
- Create `hooks/use-wallet.ts` with query hooks: `useWallet()`,
`useWalletBalance()`, `useWalletTransactions(filters, page)`,
`useWalletAssets()`
- Create `hooks/use-wallet-mutations.ts` with mutation hooks:
`useAddBankAccount()`, `useRemoveBankAccount()`, `useInitiateWithdrawal()`
- Follow patterns from `hooks/use-user-mutations.ts`
- Each mutation should invalidate relevant queries on success and trigger toast
notifications
- Use TanStack Query with proper error handling and loading states

Phase 2: Page Structure & Navigation

Set up the wallet page route with proper layout, loading states, and navigation entry points from the header and throughout the app.

Task 1: Create Wallet Page Route Structure

Establish the wallet page route with proper Next.js conventions including loading states, error handling, and SEO metadata.

• Create app/wallet/page.tsx as a client component with "use client" directive
• Add metadata export for SEO: title "Wallet | Bounties", appropriate description
• Implement main page layout using container pattern: min-h-screen bg-background, container mx-auto px-4 py-8
• Add ambient glow background effect using existing .glow-effect CSS class pattern
• Create app/wallet/loading.tsx with skeleton layout matching the page structure
• Orchestrate data fetching using the wallet hooks, handle loading/error/empty states at page level
• Structure page with responsive grid: single column on mobile, sidebar layout on desktop for security section

Task 2: Add Navigation Entry Points

Integrate wallet page access into the global navigation and create the link infrastructure for the wallet sheet.

• Update components/global-navbar.tsx to add a wallet icon/button next to existing nav items
  • Use Wallet icon from lucide-react
  • Link to /wallet route
  • Show active state when on /wallet path using usePathname
• Create components/wallet/wallet-nav-button.tsx for the header trigger
  • Display small balance preview on hover (optional enhancement)
  • Include "View More" link behavior that navigates to /wallet
• Add breadcrumb component to wallet page using existing Breadcrumb UI component

Task 3: Create Wallet Overview Component

Build the wallet overview section displaying the abstracted wallet information and verification status.

• Create components/wallet/wallet-overview.tsx with Card layout
• Display wallet address with truncation (first 8...last 8 characters) and copy-to-clipboard button
  • Use existing copy patterns, show toast on successful copy
• Add "Abstracted Wallet" badge/indicator with tooltip explaining the platform manages the wallet
• Show wallet creation date formatted with date-fns or similar
• Display verification/security status with appropriate icons (Shield, CheckCircle from lucide-react)
• Use the dark card styling pattern: bg-background-card border-border/50

Task 4: Create Balance Card Component

Build the primary balance display component showing total value, breakdown, and change indicators.

• Create components/wallet/balance-card.tsx with prominent Card styling
• Display large total USD value as hero element with proper number formatting
• Create sub-section showing balance breakdown by token (XLM, USDC, etc.) in a grid/list
• Add pending earnings indicator with tooltip explaining these are awaiting confirmation
• Show "Available for Withdrawal" amount distinctly, this drives the withdrawal flow
• Implement change indicators (24h/7d/30d) with up/down arrows and percentage, colored green/red
• Use Tabs component for switching between time period views of change indicators

🤖 Prompt for AI agents

This phase creates the wallet page route structure, navigation integration, and
the primary wallet overview and balance display components.

**Wallet Page Route (app/wallet/):**
- Create `app/wallet/page.tsx` as a client component ("use client" directive)
- Add Next.js metadata export: title "Wallet | Bounties" with appropriate
description
- Use container layout pattern: `min-h-screen bg-background` with `container
mx-auto px-4 py-8`
- Apply ambient glow background effect using existing `.glow-effect` CSS class
- Create responsive grid: single column on mobile, sidebar layout on desktop
(security section in sidebar)
- Orchestrate data fetching with wallet hooks from Phase 1, handle
loading/error/empty states
- Create `app/wallet/loading.tsx` with skeleton components matching page
structure

**Navigation Integration:**
- Update `components/global-navbar.tsx` to add wallet navigation
- Add `Wallet` icon from lucide-react next to existing nav items
- Link to `/wallet` route with active state using `usePathname()` hook
- Create `components/wallet/wallet-nav-button.tsx` for header trigger with
optional balance preview on hover
- Add breadcrumb component to wallet page using existing Breadcrumb UI component

**Wallet Overview Component (components/wallet/wallet-overview.tsx):**
- Use Card component with dark styling: `bg-background-card border-border/50`
- Display wallet address truncated (first 8...last 8 characters)
- Add copy-to-clipboard button following existing patterns, show toast on
successful copy
- Include "Abstracted Wallet" badge with tooltip explaining platform management
- Format wallet creation date with date-fns or similar library
- Show verification/security status with icons (Shield, CheckCircle from
lucide-react)

**Balance Card Component (components/wallet/balance-card.tsx):**
- Create prominent Card with hero display of total USD value (large, formatted)
- Add balance breakdown sub-section showing tokens (XLM, USDC) in grid/list
layout
- Display pending earnings with tooltip explaining awaiting confirmation
- Highlight "Available for Withdrawal" amount distinctly as it drives withdrawal
flow
- Implement change indicators (24h/7d/30d) with arrows, percentages, color
coding (green for positive, red for negative)
- Use Tabs component for switching between time period views
- Apply proper number formatting for all currency values

Phase 3: Assets & Transaction History

Build the extended assets display and comprehensive transaction history with filtering, pagination, and export capabilities.

Task 1: Create Assets List Component

Build the full asset holdings display with sorting, filtering, and interaction capabilities.

• Create components/wallet/assets-section.tsx as the container component
• Create components/wallet/asset-item.tsx for individual asset rows displaying:
  • Token icon (use placeholder for mock), name, symbol
  • Amount held and USD value
  • Portfolio percentage with small progress bar visualization
• Implement sort controls using Select component: by value (default), name, recent activity
• Add search input to filter assets by name/symbol
• Create empty state component for users with no assets yet
• Make asset items clickable to filter transactions by that specific token

Task 2: Create Transaction History Component

Build the paginated transaction history section with comprehensive filtering and search.

• Create components/wallet/transaction-history.tsx as the main container
• Create components/wallet/transaction-item.tsx for individual transaction rows:
  • Type icon (ArrowDownLeft for earnings, ArrowUpRight for withdrawals, Clock for pending)
  • Description text (e.g., "Bounty reward: Fix login bug")
  • Amount with currency and USD equivalent
  • Timestamp formatted relatively (e.g., "2 hours ago") with full date on hover
  • Status badge using Badge component with appropriate variant
  • Link to associated bounty if applicable
• Implement filter bar with:
  • Type filter using Select: All, Earnings, Withdrawals, Pending
  • Date range picker using Calendar/Popover components
  • Search input for transaction descriptions
• Use useInfiniteQuery or offset pagination with "Load More" button
• Show transaction count and filtered result summary

Task 3: Create Transaction Detail Modal

Build the expanded transaction detail view for viewing complete transaction information.

• Create components/wallet/transaction-detail-dialog.tsx using Dialog component
• Display all transaction fields in organized layout:
  • Transaction ID (truncated with copy)
  • Full timestamp with timezone
  • Complete amount details (crypto amount, USD value at time of transaction)
  • Status with timeline if applicable (initiated → processing → completed)
  • Associated bounty link with preview card if applicable
  • Network transaction hash for on-chain transactions (mock for now)
• Add close button and keyboard navigation support (Escape to close)

Task 4: Implement Transaction Export

Add CSV export functionality for transaction history.

• Create lib/utils/export-transactions.ts utility function
• Function takes transaction array and converts to CSV format with columns: Date, Type, Description, Amount, Currency, USD Value, Status, Bounty
• Implement download trigger using blob URL and programmatic anchor click
• Add "Export CSV" button to transaction history header
• Include current filter context in exported filename (e.g., "transactions-earnings-2025.csv")

🤖 Prompt for AI agents

This phase builds the assets display and comprehensive transaction history with
filtering, pagination, detail views, and CSV export functionality.

**Assets List Components:**
- Create `components/wallet/assets-section.tsx` as container component
- Create `components/wallet/asset-item.tsx` for individual rows showing:
  - Token icon (placeholder for mock), name, symbol
  - Amount held and USD value with proper formatting
  - Portfolio percentage with progress bar visualization
- Implement sort controls using Select component with options: by value
(default), name, recent activity
- Add search Input component to filter by name/symbol
- Create empty state for no assets: "Start earning by completing bounties"
- Make asset items clickable to filter transaction history by that token

**Transaction History Components:**
- Create `components/wallet/transaction-history.tsx` as main container
- Create `components/wallet/transaction-item.tsx` displaying:
- Type icons from lucide-react: ArrowDownLeft (earnings), ArrowUpRight
(withdrawals), Clock (pending)
  - Description text with bounty context when applicable
  - Amount with currency and USD equivalent
- Relative timestamp ("2 hours ago") with full date on hover using date-fns or
similar
  - Status Badge with appropriate variant based on transaction status
  - Link to bounty page if bountyId exists
- Implement filter bar with:
  - Type Select: All, Earnings, Withdrawals, Pending
  - Date range picker using Calendar and Popover components
  - Search Input for description filtering
- Use pagination (either `useInfiniteQuery` or offset-based) with "Load More"
button
- Display transaction count and filtered result summary text

**Transaction Detail Modal:**
- Create `components/wallet/transaction-detail-dialog.tsx` using Dialog
component from shadcn/ui
- Display organized layout with all transaction details:
  - Transaction ID truncated with copy button
  - Full timestamp with timezone
  - Crypto amount and USD value at transaction time
- Status timeline for multi-step transactions (initiated → processing →
completed)
  - Bounty link with preview card if applicable
  - Mock network transaction hash
- Implement keyboard navigation (Escape to close)

**CSV Export Utility:**
- Create `lib/utils/export-transactions.ts` with export function
- Convert transaction array to CSV format with columns: Date, Type, Description,
Amount, Currency, USD Value, Status, Bounty
- Implement download using Blob API and programmatic anchor click
- Add "Export CSV" button to transaction history header
- Include filter context in filename (e.g., "transactions-earnings-2025.csv")

Phase 4: Withdrawal Flow & Security

Implement the complete withdrawal/off-ramp flow including bank account management and the security settings section.

Task 1: Create Bank Account Management Components

Build the bank account listing and add account flow for withdrawal destinations.

• Create components/wallet/bank-accounts-section.tsx displaying connected accounts
• Create components/wallet/bank-account-item.tsx showing:
  • Bank name and account type (Checking/Savings)
  • Last 4 digits masked display (••••1234)
  • Verification status badge
  • Primary account indicator
  • Remove/edit actions in dropdown menu
• Create components/wallet/add-bank-account-dialog.tsx with multi-step form:
  • Step 1: Select country (affects available banks/formats)
  • Step 2: Enter bank details (routing number, account number, account holder name)
  • Step 3: Confirmation and verification notice
• Use React Hook Form with proper validation for bank account fields
• Show empty state prompting user to add first bank account

Task 2: Create Withdrawal Flow Components

Build the withdrawal initiation flow with amount input, confirmation, and status tracking.

• Create components/wallet/withdraw-section.tsx as the main withdrawal interface
• Create components/wallet/withdraw-form.tsx with:
  • Amount input with currency selector
  • "Max" button that fills available balance
  • Bank account selector (Select component with connected accounts)
  • Real-time fee calculation display
  • Net receive amount preview
  • Withdrawal limits indicator (daily/monthly with usage)
• Create components/wallet/withdraw-confirmation-dialog.tsx:
  • Summary of withdrawal details
  • Fee breakdown
  • Estimated arrival time
  • Confirm/Cancel actions
  • Terms acceptance checkbox if required
• Implement validation for: minimum amount, maximum amount, exceeds balance, exceeds limits
• Show appropriate error states for each validation failure

Task 3: Create Pending Withdrawals Display

Build the pending withdrawals tracking component showing in-progress and recent withdrawals.

• Create components/wallet/pending-withdrawals.tsx component
• Display list of pending withdrawals with:
  • Amount and destination bank
  • Status indicator (Processing, Pending Verification, Completed, Failed)
  • Initiated timestamp
  • Estimated arrival date
  • Progress indicator for multi-step process
• Show empty state when no pending withdrawals
• Include recent completed withdrawals (last 5) below pending section
• Add "View All" link that filters transaction history to withdrawals only

Task 4: Create Security Section

Build the security settings and status display section with placeholder functionality.

• Create components/wallet/security-section.tsx as collapsible Card on desktop sidebar
• Display 2FA status with enable/disable toggle (mock - shows toast that feature coming soon)
• Show withdrawal security settings:
  • Whitelist status indicator
  • Required confirmation method
• Display recent security activity log (last 5 events):
  • Login events
  • Withdrawal initiations
  • Settings changes
• Show active sessions count with "Manage Sessions" link (could link to future settings page)
• Use muted styling to indicate these are display-only features pending backend implementation

Task 5: Handle Edge Cases and Empty States

Ensure all edge cases listed in the ticket are properly handled with appropriate UI feedback.

• Create components/wallet/empty-state.tsx reusable component with icon, message, and optional CTA
• Implement empty states for:
  • No assets: "Start earning by completing bounties"
  • No transactions: "Your transaction history will appear here"
  • No bank accounts: "Add a bank account to withdraw funds"
• Add error boundaries for each major section to prevent full page crashes
• Implement inline error states for form validation failures
• Add loading skeletons for each async section using Skeleton component
• Create toast notifications for:
  • Successful withdrawal initiation
  • Bank account added/removed
  • Copy to clipboard actions
  • Network errors with retry option
• Handle network failures gracefully with retry buttons in error states

🤖 Prompt for AI agents

This phase implements the complete withdrawal/off-ramp flow with bank account
management, withdrawal forms, pending withdrawal tracking, security settings,
and comprehensive edge case handling.

**Bank Account Management:**
- Create `components/wallet/bank-accounts-section.tsx` as container for
connected accounts
- Create `components/wallet/bank-account-item.tsx` displaying:
  - Bank name and account type (Checking/Savings)
  - Masked last 4 digits (••••1234)
  - Verification Badge component
  - Primary account indicator
  - DropdownMenu with remove/edit actions
- Create `components/wallet/add-bank-account-dialog.tsx` as multi-step Dialog:
  - Step 1: Country selector (affects validation formats)
  - Step 2: Bank details form (routing number, account number, holder name)
  - Step 3: Confirmation and verification notice
- Use React Hook Form with validation rules for all bank fields
- Show empty state: "Add a bank account to withdraw funds"

**Withdrawal Flow:**
- Create `components/wallet/withdraw-section.tsx` as main interface
- Create `components/wallet/withdraw-form.tsx` with:
  - Amount Input with currency selector
  - "Max" button to fill available balance
  - Bank account Select component (populated from connected accounts)
  - Real-time fee calculation and display
  - Net receive amount preview
  - Withdrawal limits progress indicator (daily/monthly with used amounts)
- Create `components/wallet/withdraw-confirmation-dialog.tsx` Dialog with:
  - Withdrawal summary (amount, destination, fees)
  - Fee breakdown detail
  - Estimated arrival time
  - Confirm/Cancel buttons
  - Optional terms acceptance Checkbox
- Implement validation: minimum amount, maximum amount, balance check, limit
checks
- Display appropriate error messages for each validation failure

**Pending Withdrawals:**
- Create `components/wallet/pending-withdrawals.tsx` component
- Display pending withdrawals list with:
  - Amount and destination bank name
  - Status Badge: Processing, Pending Verification, Completed, Failed
  - Initiated timestamp formatted with date-fns
  - Estimated arrival date
  - Progress component for multi-step status
- Show empty state when no pending withdrawals
- Include recent completed withdrawals (last 5) in separate section
- Add "View All" link that navigates to transaction history with withdrawal
filter

**Security Section:**
- Create `components/wallet/security-section.tsx` as collapsible Card in desktop
sidebar
- Display 2FA status with toggle (mock - shows toast "Feature coming soon" on
interaction)
- Show withdrawal security settings: whitelist status, confirmation method
- Display recent security activity log (last 5 events): logins, withdrawals,
settings changes
- Show active sessions count with "Manage Sessions" link
- Use muted/subdued styling to indicate display-only status pending backend

**Edge Cases and Empty States:**
- Create reusable `components/wallet/empty-state.tsx` with icon, message,
optional CTA button
- Implement specific empty states:
  - No assets: "Start earning by completing bounties"
  - No transactions: "Your transaction history will appear here"
  - No bank accounts: "Add a bank account to withdraw funds"
- Add error boundaries around major sections
- Create Skeleton loading states for all async sections
- Implement toast notifications using existing toast system for:
  - Withdrawal initiation success
  - Bank account add/remove
  - Copy to clipboard
  - Network errors with retry actions
- Add retry buttons in error states for network failures
- Show inline validation errors in forms

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase establishes the complete data layer for the wallet page, creating the
foundation for all wallet functionality with TypeScript types, mock data, API
routes, and data fetching hooks.

**Type Definitions (types/wallet.ts):**
- Create comprehensive interfaces for all wallet entities: `Wallet`,
`WalletBalance`, `Asset`, `Transaction`, `BankAccount`, `Withdrawal`,
`WithdrawalLimits`, `SecurityStatus`
- Key fields for `Wallet`: address, createdAt, verificationStatus, securityLevel
- Key fields for `WalletBalance`: totalUsdValue, availableForWithdrawal,
pendingEarnings, assets array, changeIndicators (24h/7d/30d)
- Key fields for `Transaction`: id, type, description, amount, currency,
usdValue, timestamp, status, optional bountyId and bountyTitle
- Export enums for `TransactionType`, `TransactionStatus`, `AssetSortOption`
- Create generic `PaginatedResponse<T>` type with items, total, page, pageSize,
hasMore

**Mock Data Generators (lib/mock-wallet.ts):**
- Follow patterns from existing `lib/mock-leaderboard.ts` and
`lib/mock-bounty.ts`
- Implement functions: `getMockWallet()`, `getMockBalance()`, `getMockAssets()`,
`getMockTransactions(page, limit, filters)`, `getMockBankAccounts()`,
`getMockWithdrawals()`, `getMockSecurityStatus()`
- Use Stellar-format addresses (starting with G) for wallet addresses
- Generate realistic XLM and USDC holdings with random change indicators
- Create 3-8 mock assets per wallet with proper amounts and USD values
- Generate paginated transactions with bounty references, supporting type and
date filtering
- Use seeded randomness for consistency and timestamps spanning past 6 months

**API Routes (app/api/wallet/):**
- Follow existing pattern from `app/api/leaderboard/route.ts`
- Create separate routes: `route.ts` (overview), `balance/route.ts`,
`transactions/route.ts`, `bank-accounts/route.ts`, `withdrawals/route.ts`,
`security/route.ts`
- All GET routes return mock data from the generators
- POST routes for `bank-accounts` and `withdrawals` simulate mutations
- Include 200-500ms simulated delay with `setTimeout`
- Handle pagination and filter query params in transactions route
- Return appropriate error responses (401 unauthorized, 400 invalid params)

**Data Fetching Hooks (hooks/):**
- Add wallet query keys to `lib/query/query-keys.ts` following existing
patterns: `walletKeys.all`, `walletKeys.overview`, `walletKeys.balance`,
`walletKeys.transactions(filters)`, etc.
- Create `hooks/use-wallet.ts` with query hooks: `useWallet()`,
`useWalletBalance()`, `useWalletTransactions(filters, page)`,
`useWalletAssets()`
- Create `hooks/use-wallet-mutations.ts` with mutation hooks:
`useAddBankAccount()`, `useRemoveBankAccount()`, `useInitiateWithdrawal()`
- Follow patterns from `hooks/use-user-mutations.ts`
- Each mutation should invalidate relevant queries on success and trigger toast
notifications
- Use TanStack Query with proper error handling and loading states
===============================================================================

Task: 2

This phase creates the wallet page route structure, navigation integration, and
the primary wallet overview and balance display components.

**Wallet Page Route (app/wallet/):**
- Create `app/wallet/page.tsx` as a client component ("use client" directive)
- Add Next.js metadata export: title "Wallet | Bounties" with appropriate
description
- Use container layout pattern: `min-h-screen bg-background` with `container
mx-auto px-4 py-8`
- Apply ambient glow background effect using existing `.glow-effect` CSS class
- Create responsive grid: single column on mobile, sidebar layout on desktop
(security section in sidebar)
- Orchestrate data fetching with wallet hooks from Phase 1, handle
loading/error/empty states
- Create `app/wallet/loading.tsx` with skeleton components matching page
structure

**Navigation Integration:**
- Update `components/global-navbar.tsx` to add wallet navigation
- Add `Wallet` icon from lucide-react next to existing nav items
- Link to `/wallet` route with active state using `usePathname()` hook
- Create `components/wallet/wallet-nav-button.tsx` for header trigger with
optional balance preview on hover
- Add breadcrumb component to wallet page using existing Breadcrumb UI component

**Wallet Overview Component (components/wallet/wallet-overview.tsx):**
- Use Card component with dark styling: `bg-background-card border-border/50`
- Display wallet address truncated (first 8...last 8 characters)
- Add copy-to-clipboard button following existing patterns, show toast on
successful copy
- Include "Abstracted Wallet" badge with tooltip explaining platform management
- Format wallet creation date with date-fns or similar library
- Show verification/security status with icons (Shield, CheckCircle from
lucide-react)

**Balance Card Component (components/wallet/balance-card.tsx):**
- Create prominent Card with hero display of total USD value (large, formatted)
- Add balance breakdown sub-section showing tokens (XLM, USDC) in grid/list
layout
- Display pending earnings with tooltip explaining awaiting confirmation
- Highlight "Available for Withdrawal" amount distinctly as it drives withdrawal
flow
- Implement change indicators (24h/7d/30d) with arrows, percentages, color
coding (green for positive, red for negative)
- Use Tabs component for switching between time period views
- Apply proper number formatting for all currency values
===============================================================================

Task: 3

This phase builds the assets display and comprehensive transaction history with
filtering, pagination, detail views, and CSV export functionality.

**Assets List Components:**
- Create `components/wallet/assets-section.tsx` as container component
- Create `components/wallet/asset-item.tsx` for individual rows showing:
  - Token icon (placeholder for mock), name, symbol
  - Amount held and USD value with proper formatting
  - Portfolio percentage with progress bar visualization
- Implement sort controls using Select component with options: by value
(default), name, recent activity
- Add search Input component to filter by name/symbol
- Create empty state for no assets: "Start earning by completing bounties"
- Make asset items clickable to filter transaction history by that token

**Transaction History Components:**
- Create `components/wallet/transaction-history.tsx` as main container
- Create `components/wallet/transaction-item.tsx` displaying:
- Type icons from lucide-react: ArrowDownLeft (earnings), ArrowUpRight
(withdrawals), Clock (pending)
  - Description text with bounty context when applicable
  - Amount with currency and USD equivalent
- Relative timestamp ("2 hours ago") with full date on hover using date-fns or
similar
  - Status Badge with appropriate variant based on transaction status
  - Link to bounty page if bountyId exists
- Implement filter bar with:
  - Type Select: All, Earnings, Withdrawals, Pending
  - Date range picker using Calendar and Popover components
  - Search Input for description filtering
- Use pagination (either `useInfiniteQuery` or offset-based) with "Load More"
button
- Display transaction count and filtered result summary text

**Transaction Detail Modal:**
- Create `components/wallet/transaction-detail-dialog.tsx` using Dialog
component from shadcn/ui
- Display organized layout with all transaction details:
  - Transaction ID truncated with copy button
  - Full timestamp with timezone
  - Crypto amount and USD value at transaction time
- Status timeline for multi-step transactions (initiated → processing →
completed)
  - Bounty link with preview card if applicable
  - Mock network transaction hash
- Implement keyboard navigation (Escape to close)

**CSV Export Utility:**
- Create `lib/utils/export-transactions.ts` with export function
- Convert transaction array to CSV format with columns: Date, Type, Description,
Amount, Currency, USD Value, Status, Bounty
- Implement download using Blob API and programmatic anchor click
- Add "Export CSV" button to transaction history header
- Include filter context in filename (e.g., "transactions-earnings-2025.csv")
===============================================================================

Task: 4

This phase implements the complete withdrawal/off-ramp flow with bank account
management, withdrawal forms, pending withdrawal tracking, security settings,
and comprehensive edge case handling.

**Bank Account Management:**
- Create `components/wallet/bank-accounts-section.tsx` as container for
connected accounts
- Create `components/wallet/bank-account-item.tsx` displaying:
  - Bank name and account type (Checking/Savings)
  - Masked last 4 digits (••••1234)
  - Verification Badge component
  - Primary account indicator
  - DropdownMenu with remove/edit actions
- Create `components/wallet/add-bank-account-dialog.tsx` as multi-step Dialog:
  - Step 1: Country selector (affects validation formats)
  - Step 2: Bank details form (routing number, account number, holder name)
  - Step 3: Confirmation and verification notice
- Use React Hook Form with validation rules for all bank fields
- Show empty state: "Add a bank account to withdraw funds"

**Withdrawal Flow:**
- Create `components/wallet/withdraw-section.tsx` as main interface
- Create `components/wallet/withdraw-form.tsx` with:
  - Amount Input with currency selector
  - "Max" button to fill available balance
  - Bank account Select component (populated from connected accounts)
  - Real-time fee calculation and display
  - Net receive amount preview
  - Withdrawal limits progress indicator (daily/monthly with used amounts)
- Create `components/wallet/withdraw-confirmation-dialog.tsx` Dialog with:
  - Withdrawal summary (amount, destination, fees)
  - Fee breakdown detail
  - Estimated arrival time
  - Confirm/Cancel buttons
  - Optional terms acceptance Checkbox
- Implement validation: minimum amount, maximum amount, balance check, limit
checks
- Display appropriate error messages for each validation failure

**Pending Withdrawals:**
- Create `components/wallet/pending-withdrawals.tsx` component
- Display pending withdrawals list with:
  - Amount and destination bank name
  - Status Badge: Processing, Pending Verification, Completed, Failed
  - Initiated timestamp formatted with date-fns
  - Estimated arrival date
  - Progress component for multi-step status
- Show empty state when no pending withdrawals
- Include recent completed withdrawals (last 5) in separate section
- Add "View All" link that navigates to transaction history with withdrawal
filter

**Security Section:**
- Create `components/wallet/security-section.tsx` as collapsible Card in desktop
sidebar
- Display 2FA status with toggle (mock - shows toast "Feature coming soon" on
interaction)
- Show withdrawal security settings: whitelist status, confirmation method
- Display recent security activity log (last 5 events): logins, withdrawals,
settings changes
- Show active sessions count with "Manage Sessions" link
- Use muted/subdued styling to indicate display-only status pending backend

**Edge Cases and Empty States:**
- Create reusable `components/wallet/empty-state.tsx` with icon, message,
optional CTA button
- Implement specific empty states:
  - No assets: "Start earning by completing bounties"
  - No transactions: "Your transaction history will appear here"
  - No bank accounts: "Add a bank account to withdraw funds"
- Add error boundaries around major sections
- Create Skeleton loading states for all async sections
- Implement toast notifications using existing toast system for:
  - Withdrawal initiation success
  - Bank account add/remove
  - Copy to clipboard
  - Network errors with retry actions
- Add retry buttons in error states for network failures
- Show inline validation errors in forms

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[EA10-lite]

@EA10-lite has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi, I'd like to work on this issue

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

[EA10-lite]

@EA10-lite has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi, I'd like to work on this issue

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

[EA10-lite]

@EA10-lite has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hi, I'd like to work on this issue

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

[Michaelkingsdev]

@Michaelkingsdev has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I am Michael Kings, a seasoned full-stack developer with extensive experience in blockchain technology. I have a passion for building responsive and interactive user interfaces, and my backend logic is top-notch. With 4 years of experience, I am confident that I can tackle this issue. I have made over 50 contributions in onlydust in the past.
Please assign it to me.

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

[Villarley]

@Villarley has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hey team! I'm Santiago Full stack dev I have great experience with the js-sdk, would be an easy implementation!

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

[codebestia]

@codebestia has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hello Maintainer! Can i work on this?
ETA - 12 hours

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