From f15b0fa5f8ed403cffe6716b651cc7488c101815 Mon Sep 17 00:00:00 2001 From: Noah Akerityo Date: Fri, 29 May 2026 17:03:49 +0100 Subject: [PATCH] docs: update mobile guide for PWA installation and Lobstr wallet --- docs/mobile-app-guide.md | 853 +++++++-------------------------------- 1 file changed, 144 insertions(+), 709 deletions(-) diff --git a/docs/mobile-app-guide.md b/docs/mobile-app-guide.md index 7588eaf7..d86f2891 100644 --- a/docs/mobile-app-guide.md +++ b/docs/mobile-app-guide.md @@ -1,744 +1,179 @@ -# Stellar-Save Mobile App User Guide +# Stellar-Save Mobile Web & PWA User Guide πŸŒŠπŸ“± -Welcome to the Stellar-Save mobile app! This guide covers everything you need to know about using Stellar-Save on your iOS or Android device. +Welcome to the **Stellar-Save Mobile User Guide**! -## Getting Started +Stellar-Save is a decentralized, mobile-responsive Progressive Web App (PWA). Instead of requiring a heavy app download from the Apple App Store or Google Play Store, Stellar-Save runs directly in your mobile browser and connects securely to non-custodial Stellar wallets like **Lobstr**, **Albedo**, and **xbull**. -### Installation +This guide covers PWA installation, mobile wallet linking, step-by-step contribution flows, and troubleshooting common mobile errors. -**iOS (iPhone/iPad)** -1. Open the App Store -2. Search for "Stellar-Save" -3. Tap "Get" and authenticate with Face ID/Touch ID/password -4. Wait for installation to complete -5. Tap "Open" or find the app on your home screen - -**Android** -1. Open Google Play Store -2. Search for "Stellar-Save" -3. Tap "Install" -4. Wait for installation to complete -5. Tap "Open" or find the app in your app drawer - -### System Requirements - -**iOS** -- iOS 14.0 or later -- iPhone 6s or newer -- iPad (5th generation) or newer -- 50 MB free storage - -**Android** -- Android 8.0 (Oreo) or later -- 2 GB RAM minimum -- 100 MB free storage - -### First Launch Setup - -1. **Welcome Screen**: Tap "Get Started" -2. **Network Selection**: Choose Testnet (for learning) or Mainnet (for real savings) -3. **Wallet Setup**: - - Create new wallet, or - - Import existing wallet with seed phrase -4. **Biometric Authentication**: Enable Face ID/Touch ID/Fingerprint (recommended) -5. **Notifications**: Allow push notifications to stay updated on contributions and payouts -6. **Tutorial**: Complete the quick walkthrough (optional but recommended) - -## Mobile-Specific Features - -### Quick Actions (iOS) - -Long-press the Stellar-Save app icon for quick shortcuts: -- **View My Groups**: Jump directly to your active groups -- **Make Contribution**: Quick access to contribute to due groups -- **Check Balance**: View your XLM balance instantly -- **Scan QR Code**: Join a group via QR code - -### Home Screen Widgets - -**iOS Widgets** -- **Small Widget**: Shows next contribution due date and amount -- **Medium Widget**: Displays all active groups with status -- **Large Widget**: Full dashboard with contribution history - -To add: Long-press home screen β†’ Tap "+" β†’ Search "Stellar-Save" β†’ Select widget size - -**Android Widgets** -- **1x1 Widget**: Quick contribution button -- **2x2 Widget**: Group overview with next payout -- **4x2 Widget**: Full dashboard with recent activity - -To add: Long-press home screen β†’ Tap "Widgets" β†’ Find "Stellar-Save" β†’ Drag to home screen - -### Push Notifications - -Stay informed with real-time alerts: -- **Contribution Reminders**: 24 hours before cycle deadline -- **Payout Notifications**: When you receive funds -- **Group Updates**: New members join or group status changes -- **Cycle Completion**: When all members have contributed -- **Penalty Alerts**: If penalties are applied (when enabled) - -**Managing Notifications** -- iOS: Settings β†’ Stellar-Save β†’ Notifications -- Android: Settings β†’ Apps β†’ Stellar-Save β†’ Notifications - -### Biometric Security - -Protect your wallet with device biometrics: -- **iOS**: Face ID or Touch ID -- **Android**: Fingerprint or Face Unlock - -**Setup**: App Settings β†’ Security β†’ Enable Biometric Authentication - -**When Required**: -- Opening the app (optional) -- Making contributions -- Viewing seed phrase -- Changing security settings - -### Camera & QR Codes - -**Scanning QR Codes** -1. Tap the scan icon (camera) in the top-right corner -2. Point camera at QR code -3. Auto-detects group IDs, wallet addresses, or payment requests -4. Confirm action - -**Sharing Your Group** -1. Open your group -2. Tap "Share" icon -3. Select "QR Code" -4. Others can scan to join instantly - -**Permissions**: Grant camera access when prompted (Settings β†’ Stellar-Save β†’ Camera) - -### Offline Mode - -The app works partially offline with cached data. - -**Available Offline**: -- View your groups and contribution history -- Check your wallet balance (last synced) -- Review group details and member lists -- Access settings and help documentation - -**Requires Connection**: -- Making contributions -- Creating or joining groups -- Executing payouts -- Refreshing real-time data - -**Offline Indicator**: Yellow banner at top shows "Offline Mode" when disconnected - -**Syncing**: Data auto-syncs when connection is restored. Pull down to refresh manually. - -### Dark Mode - -Automatically adapts to your device's appearance settings. - -**Manual Override**: App Settings β†’ Appearance β†’ Light/Dark/Auto - -### Haptic Feedback - -Subtle vibrations confirm actions: -- Contribution submitted -- Payout received -- Error occurred -- Button taps (optional) - -**Disable**: App Settings β†’ Accessibility β†’ Haptic Feedback β†’ Off - -## Gesture Controls - -### Navigation Gestures - -**iOS** -- **Swipe Right**: Go back to previous screen -- **Swipe Down**: Dismiss modal/popup -- **Pull Down**: Refresh current view -- **Long Press**: Context menu (on groups, transactions) - -**Android** -- **Swipe Right/Back Button**: Return to previous screen -- **Swipe Down**: Dismiss modal or refresh (context-dependent) -- **Pull Down**: Refresh current view -- **Long Press**: Context menu - -### Group Management Gestures - -**Swipe Actions on Group List** -- **Swipe Left**: Quick actions menu - - Contribute - - View Details - - Share Group - - Leave Group (if allowed) -- **Swipe Right**: Mark as favorite (star icon appears) - -**Pull to Refresh**: Update group status and contribution data - -### Transaction History Gestures - -- **Tap Transaction**: View full details -- **Long Press**: Copy transaction ID or share -- **Swipe Left**: View on Stellar Explorer - -### Quick Contribution - -**Shortcut Gesture** (when contribution is due): -1. Swipe left on group in "My Groups" -2. Tap "Contribute" -3. Authenticate with biometrics -4. Contribution submitted - -## Screen-by-Screen Guide - -### Home Dashboard - -**Top Section** -- Total XLM balance -- Active groups count -- Next contribution due - -**Middle Section** -- Active groups list with status indicators -- Contribution progress bars -- Upcoming payout notifications - -**Bottom Navigation** -- Home (dashboard) -- Groups (browse/create) -- Activity (transaction history) -- Profile (settings/wallet) - -**Actions** -- Tap group card β†’ View group details -- Tap "+" button β†’ Create or join group -- Tap notification bell β†’ View all alerts - -### Group Details Screen - -**Header** -- Group name/ID -- Status badge (Active/Pending/Complete) -- Share and settings icons - -**Info Cards** -- Contribution amount -- Cycle duration -- Current cycle number -- Your payout position - -**Member List** -- Profile pictures (if available) -- Contribution status (βœ“ or pending) -- Tap member β†’ View contribution history - -**Action Buttons** -- Contribute (if due) -- View History -- Invite Members - -### Contribution Screen - -**Amount Display** -- Required contribution amount (large, centered) -- Your current balance -- Transaction fee estimate - -**Confirmation** -- Review details -- Authenticate with biometrics -- Submit transaction - -**Success Screen** -- Confirmation animation -- Transaction ID -- Share receipt option - -### Wallet Screen - -**Balance Overview** -- Available XLM -- Reserved (in active groups) -- Total value - -**Actions** -- Send XLM -- Receive (show QR code) -- Buy XLM (external link) -- Transaction history - -**Security** -- View seed phrase (requires authentication) -- Change PIN/biometrics -- Export wallet - -### Settings Screen - -**Account** -- Profile information -- Notification preferences -- Language selection - -**Security** -- Biometric authentication -- Auto-lock timeout -- Seed phrase backup - -**App** -- Network (Testnet/Mainnet) -- Appearance (Light/Dark) -- Haptic feedback -- Clear cache - -**Support** -- Help & FAQ -- Contact support -- App version - -## Mobile Troubleshooting - -### Connection Issues - -**Problem**: "Unable to connect to Stellar network" - -**Solutions**: -1. Check internet connection (WiFi or mobile data) -2. Toggle airplane mode on/off -3. Switch between WiFi and mobile data -4. Check Stellar network status at status.stellar.org -5. Try different network (Settings β†’ Network β†’ Switch RPC endpoint) - -**Problem**: "Transaction timeout" - -**Solutions**: -1. Ensure stable internet connection -2. Increase transaction timeout (Settings β†’ Advanced β†’ Timeout) -3. Retry transaction -4. Check Stellar network congestion - -### Wallet Issues - -**Problem**: "Insufficient balance" - -**Solutions**: -1. Check your XLM balance (Wallet tab) -2. Ensure you have enough for contribution + fees (~0.00001 XLM fee) -3. Add more XLM to your wallet -4. Check if funds are reserved in other groups - -**Problem**: "Cannot access wallet" - -**Solutions**: -1. Verify biometric authentication is working -2. Use PIN as fallback (tap "Use PIN" on auth screen) -3. Restart the app -4. Reinstall app and restore with seed phrase - -**Problem**: "Lost seed phrase" - -**Solutions**: -- If you still have app access: Settings β†’ Security β†’ View Seed Phrase β†’ Write it down -- If app is deleted: Seed phrase cannot be recovered. Funds are lost. -- Prevention: Always backup seed phrase securely - -### App Performance Issues - -**Problem**: App is slow or laggy - -**Solutions**: -1. Close and reopen the app -2. Clear app cache (Settings β†’ Clear Cache) -3. Free up device storage (need 100+ MB free) -4. Update to latest app version -5. Restart your device -6. Reinstall the app (backup seed phrase first!) - -**Problem**: App crashes on launch - -**Solutions**: -1. Force close and reopen -2. Restart device -3. Check for app updates -4. Reinstall app (backup seed phrase first!) -5. Check system requirements (iOS 14+/Android 8+) - -**Problem**: High battery drain - -**Solutions**: -1. Disable background refresh (iOS: Settings β†’ Stellar-Save β†’ Background App Refresh) -2. Reduce notification frequency -3. Enable dark mode -4. Close app when not in use - -### Notification Issues - -**Problem**: Not receiving notifications - -**Solutions**: -1. Check notification permissions (Device Settings β†’ Stellar-Save β†’ Notifications β†’ Allow) -2. Enable specific notification types (App Settings β†’ Notifications) -3. Check Do Not Disturb mode is off -4. Restart device -5. Reinstall app - -**Problem**: Too many notifications - -**Solutions**: -1. App Settings β†’ Notifications β†’ Customize -2. Disable non-essential alerts -3. Set quiet hours (iOS only) - -### Contribution Issues - -**Problem**: "Contribution failed" - -**Solutions**: -1. Verify contribution amount matches group requirement -2. Check XLM balance (including fees) -3. Ensure group is active (not paused or complete) -4. Check if you already contributed this cycle -5. Verify network connection -6. Try again in a few minutes - -**Problem**: "Contribution not showing" - -**Solutions**: -1. Pull down to refresh group screen -2. Check transaction history (Activity tab) -3. Verify transaction on Stellar Explorer (tap transaction β†’ View on Explorer) -4. Wait for blockchain confirmation (usually <5 seconds) -5. Contact support if not resolved in 5 minutes - -### QR Code Issues - -**Problem**: "Cannot scan QR code" - -**Solutions**: -1. Grant camera permission (Settings β†’ Stellar-Save β†’ Camera) -2. Ensure good lighting -3. Hold device steady, 6-12 inches from code -4. Clean camera lens -5. Manually enter group ID instead (tap "Enter Manually") - -**Problem**: "Invalid QR code" - -**Solutions**: -1. Verify QR code is for Stellar-Save (not another app) -2. Ask sender to regenerate QR code -3. Try manual entry with group ID - -### Biometric Authentication Issues - -**Problem**: Face ID/Touch ID not working - -**Solutions**: -1. Verify biometrics work in other apps -2. Re-enroll biometrics in device settings -3. Use PIN as fallback (tap "Use PIN") -4. Disable and re-enable in app (Settings β†’ Security β†’ Biometric Authentication) - -**Problem**: "Too many failed attempts" - -**Solutions**: -1. Wait 30 seconds and try again -2. Use PIN instead -3. Restart app - -### Data Sync Issues - -**Problem**: "Data out of sync" - -**Solutions**: -1. Pull down to refresh -2. Check internet connection -3. Log out and log back in (Settings β†’ Account β†’ Sign Out) -4. Clear cache (Settings β†’ Clear Cache) -5. Reinstall app (backup seed phrase first!) - -### Platform-Specific Issues - -**iOS Issues** - -**Problem**: App not updating in background - -**Solution**: Settings β†’ General β†’ Background App Refresh β†’ Enable for Stellar-Save - -**Problem**: Widget not updating - -**Solution**: Remove and re-add widget, or restart device - -**Android Issues** - -**Problem**: App killed by battery optimization - -**Solution**: Settings β†’ Apps β†’ Stellar-Save β†’ Battery β†’ Unrestricted - -**Problem**: Notifications delayed - -**Solution**: Disable battery optimization for Stellar-Save - -## Offline Mode Details - -### What's Cached - -The app stores recent data locally for offline access: -- Last 30 days of transaction history -- All group details and member lists -- Your wallet balance (last synced) -- App settings and preferences - -**Cache Size**: ~10-50 MB depending on activity - -### Offline Limitations - -**Cannot Do Offline**: -- Make contributions (requires blockchain transaction) -- Create or join groups -- Execute payouts -- Refresh real-time data -- Update group settings - -**Can Do Offline**: -- View cached groups and history -- Read documentation and FAQ -- Check last known balance -- Plan future contributions -- Export transaction reports - -### Sync Behavior - -**Auto-Sync Triggers**: -- App opens with internet connection -- Connection restored after offline period -- Manual pull-to-refresh -- Every 5 minutes when app is active - -**Sync Indicators**: -- Green checkmark: Data is current -- Yellow clock: Syncing in progress -- Red warning: Sync failed, data may be stale - -**Conflict Resolution**: Server data always takes precedence over cached data - -### Managing Offline Data - -**Clear Cache**: Settings β†’ Storage β†’ Clear Cache (frees space, requires re-sync) - -**Download for Offline**: Settings β†’ Offline Mode β†’ Download All Groups (pre-caches data) - -## Accessibility Features - -### Screen Reader Support - -**iOS VoiceOver** -- All buttons and elements are labeled -- Swipe right/left to navigate -- Double-tap to activate -- Three-finger swipe to scroll - -**Android TalkBack** -- Full screen reader support -- Swipe gestures for navigation -- Explore by touch enabled - -**Enable**: Device Settings β†’ Accessibility β†’ VoiceOver/TalkBack - -### Visual Accessibility - -**Large Text**: Supports Dynamic Type (iOS) and Font Size (Android) -- Device Settings β†’ Display β†’ Text Size - -**High Contrast**: Automatically adapts to system high contrast mode - -**Color Blind Mode**: Settings β†’ Accessibility β†’ Color Blind Friendly (uses patterns + colors) - -**Reduce Motion**: Respects system reduce motion settings (disables animations) - -### Hearing Accessibility - -**Visual Alerts**: All audio alerts have visual equivalents (flashes, banners) - -**Haptic Feedback**: Vibration confirms actions for users who can't hear audio cues - -### Motor Accessibility - -**Large Touch Targets**: All buttons meet minimum 44x44pt size - -**Simplified Gestures**: All swipe actions have button alternatives - -**Voice Control**: Compatible with iOS Voice Control and Android Voice Access - -## Tips & Best Practices - -### Battery Optimization - -- Enable dark mode -- Reduce notification frequency -- Disable background refresh if not needed -- Close app when not actively using - -### Data Usage - -- App uses ~1-5 MB per month for typical usage -- Downloading group data: ~100 KB per group -- Transactions: ~1 KB each -- Use WiFi for initial setup and large syncs - -### Security Best Practices - -1. **Enable Biometrics**: Faster and more secure than PIN -2. **Backup Seed Phrase**: Write it down, store securely offline -3. **Use Strong PIN**: 6+ digits, not birthdate or simple patterns -4. **Enable Auto-Lock**: Settings β†’ Security β†’ Auto-Lock β†’ 1 minute -5. **Verify Addresses**: Always double-check recipient addresses -6. **Beware Phishing**: Only download from official app stores - -### Performance Tips - -- Keep app updated to latest version -- Restart app weekly to clear memory -- Clear cache monthly (Settings β†’ Clear Cache) -- Maintain 100+ MB free storage on device -- Close other apps if experiencing lag - -### Group Management on Mobile - -- Use widgets for quick status checks -- Enable contribution reminders -- Favorite important groups (swipe right) -- Use QR codes to invite members in person -- Check notifications daily - -## Getting Help - -### In-App Support - -- **Help Center**: Settings β†’ Help & FAQ -- **Contact Support**: Settings β†’ Contact Support (includes device info automatically) -- **Report Bug**: Settings β†’ Report a Problem - -### Community Support - -- **Telegram**: @StellarSave -- **Discord**: discord.gg/stellarsave -- **GitHub**: github.com/Xoulomon/Stellar-Save/issues - -### Emergency Support - -**Lost Access**: If you lose your device but have your seed phrase, install the app on a new device and restore your wallet. - -**Compromised Wallet**: If you suspect your wallet is compromised: -1. Immediately transfer funds to a new wallet -2. Create new wallet with new seed phrase -3. Leave all groups (if possible) -4. Contact support +--- -**App Critical Bug**: If the app is unusable: -1. Check for updates in app store -2. Visit status.stellar.org for network issues -3. Use web version at app.stellarsave.io as backup -4. Contact support with device details +## πŸ—ΊοΈ Table of Contents +1. [πŸ“₯ Progressive Web App (PWA) Installation](#1-progressive-web-app-pwa-installation) +2. [πŸ’³ Connecting Your Mobile Wallet (Lobstr, etc.)](#2-connecting-your-mobile-wallet-lobstr-etc) +3. [πŸ’Έ Step-by-Step Mobile Contribution Flow](#3-step-by-step-mobile-contribution-flow) +4. [🎨 Mobile UI Wireframes & Layouts](#4-mobile-ui-wireframes--layouts) +5. [πŸ”§ Troubleshooting Mobile Transactions](#5-troubleshooting-mobile-transactions) -## Screenshots Guide +--- -> **Note**: Screenshots will be added when the mobile app is released. This section describes what will be shown. +## πŸ“₯ 1. Progressive Web App (PWA) Installation -### iOS Screenshots +Installing Stellar-Save as a PWA puts a lightweight icon on your home screen, enables fast loading, and allows the app to feel like a native mobile app without taking up device storage. -1. **Home Dashboard** - Overview of active groups and balance -2. **Group Details** - Detailed view of a savings group -3. **Contribution Flow** - Step-by-step contribution process -4. **Wallet Screen** - Balance and transaction history -5. **QR Code Scanner** - Joining a group via QR code -6. **Notifications** - Push notification examples -7. **Widgets** - Home screen widget variations -8. **Dark Mode** - App appearance in dark mode +### iOS (Safari) +1. Open the **Safari** app on your iPhone or iPad. +2. Navigate to your Stellar-Save deployment URL (e.g., `https://app.stellarsave.io`). +3. Tap the **Share** button (the square icon with an arrow pointing up at the bottom navigation bar). +4. Scroll down and tap **Add to Home Screen**. +5. Give the app a name (e.g., "Stellar-Save") and tap **Add** in the top-right corner. +6. The icon will now appear on your home screen! -### Android Screenshots +### Android (Chrome) +1. Open the **Google Chrome** app on your Android device. +2. Navigate to the Stellar-Save URL. +3. Tap the **three vertical dots** in the top-right corner. +4. Tap **Install app** or **Add to Home Screen**. +5. Follow the on-screen prompt to confirm installation by tapping **Install**. +6. Chrome will add the app to your home screen and app drawer automatically. -1. **Home Dashboard** - Material Design interface -2. **Group List** - Swipe actions demonstration -3. **Contribution Screen** - Making a contribution -4. **Navigation Drawer** - Side menu navigation -5. **Widgets** - Android widget examples -6. **Biometric Auth** - Fingerprint authentication -7. **Offline Mode** - Offline indicator and cached data -8. **Settings** - App configuration options +> [!NOTE] +> PWA installation is optional but highly recommended. It disables the browser address bar, giving you more screen space and smoother navigation. -## Frequently Asked Questions +--- -### General Mobile Questions +## πŸ’³ 2. Connecting Your Mobile Wallet (Lobstr, etc.) -**Q: Is the mobile app free?** -A: Yes, the app is completely free. You only pay Stellar network fees (~0.00001 XLM per transaction). +Stellar-Save does not store your private keys or seed phrase. All transactions are securely signed using external wallet apps. We recommend the **Lobstr mobile wallet** for the best mobile experience. -**Q: Which is better, iOS or Android version?** -A: Both versions have feature parity. Choose based on your device. +### Linking the Lobstr Mobile Wallet +1. Open the Stellar-Save PWA on your mobile home screen. +2. Tap the **Connect Wallet** button in the top header. +3. Select **Lobstr Wallet** from the list of connection options. +4. The PWA will trigger a **Stellar Wallet Link** connection: + * **On the same device**: You will be automatically deep-linked and redirected to your Lobstr app. + * **On a separate device**: A QR code will appear. Open the Lobstr app, tap the camera icon in the top right, and scan the QR code. +5. In the Lobstr app, you will see a prompt saying **"Connect to Stellar-Save"**. +6. Review the permissions and tap **Approve**. +7. Return to the Stellar-Save PWA. Your wallet address and XLM balance will now be visible in the header! -**Q: Can I use the same wallet on mobile and web?** -A: Yes, import your seed phrase to access the same wallet on any platform. +``` +[Stellar-Save PWA] ──► Tap Connect ──► Select Lobstr ──► Deep Link/QR ──► [Lobstr App] ──► Tap Approve ──► Linked! +``` -**Q: Does the app work on tablets?** -A: Yes, optimized for both phones and tablets (iPad and Android tablets). +--- -**Q: Is my data private?** -A: Yes, all data is stored locally or on the blockchain. We don't collect personal information. +## πŸ’Έ 3. Step-by-Step Mobile Contribution Flow -### Technical Questions +Contributing to your savings group on mobile is secure and takes under 30 seconds. Because each contribution requires transferring funds from your wallet to the smart contract, you must approve the transfer in your Lobstr app. -**Q: Why does the app need camera permission?** -A: Only for scanning QR codes to join groups or send XLM. You can deny and enter IDs manually. +### Step 1: Open Your Group +1. In the Stellar-Save PWA, tap the **My Groups** tab. +2. Tap on the group card you want to contribute to (e.g., "Family Savings Pool"). -**Q: Why does the app need notification permission?** -A: To alert you about contributions, payouts, and group updates. Optional but recommended. +### Step 2: Initiate Contribution +1. Review the required contribution amount (e.g., `50 XLM` or `10 USDC`). +2. Tap the prominent purple **Contribute** button. +3. If this is a custom token group (like USDC), the app will first request a **Token Allowance Approval**. Tap **Approve Allowance**. -**Q: Can I use the app without biometrics?** -A: Yes, you can use a PIN instead. Biometrics are optional but recommended. +### Step 3: Approve in Lobstr Wallet +1. The Stellar-Save PWA will automatically open your **Lobstr** mobile wallet via a secure deep link. +2. A **Transaction Review** screen will appear in Lobstr showing: + * **Operation**: Invoke Host Function (Soroban Smart Contract) + * **Contract ID**: `C...` (Stellar-Save contract) + * **Amount**: Your contribution amount (e.g., `50 XLM`) + * **Fee**: Network resource fee (~0.00001 XLM) +3. Authenticate using your Lobstr passcode, Face ID, or Fingerprint. +4. Tap **Confirm & Sign**. Wait 3 seconds for the transaction to be submitted to the Stellar network. -**Q: How much storage does the app use?** -A: 50-100 MB for the app, plus 10-50 MB for cached data. +### Step 4: Confirm Success +1. Once Lobstr completes the signing, switch back to your browser or PWA. +2. A success screen will display a green checkmark animation along with your transaction receipt. +3. Pull down to refresh your group detailsβ€”you will see a green checkmark next to your name for the current cycle! -**Q: Does the app work on older devices?** -A: Requires iOS 14+ or Android 8+. Older devices are not supported. +> [!IMPORTANT] +> **Token Allowance:** For custom tokens like USDC, you will perform the signing flow twice: once for the `approve` transaction (granting the contract permission to pull the tokens) and once for the `contribute` transaction. -### Troubleshooting Questions +--- -**Q: Why is my contribution not showing?** -A: Blockchain confirmations take 3-5 seconds. Pull down to refresh. If still missing after 5 minutes, check transaction history. +## 🎨 4. Mobile UI Wireframes & Layouts + +Here are mock visual wireframes illustrating the mobile-responsive interface for key application screens. + +### πŸ“± Dashboard UI Layout +The dashboard is designed for thumb-friendly interaction with prominent cards and progress indicators: + +```mermaid +graph TD + subgraph Mobile Screen (Dashboard) + A[Header: Stellar-Save Logo & Wallet Connect] + B["Card: Total Active Balance (500 XLM)"] + C["Section: My Savings Groups"] + D["Group 1: Family Pool (Progress: 80%) [Contribute Button]"] + E["Group 2: Trade Circle (Progress: 33%) [Contribute Button]"] + F[Footer Navigation: Home / Groups / History / Settings] + end + A --> B + B --> C + C --> D + C --> E + E --> F + D --> F +``` + +*For a high-fidelity visual preview, see the mock image below:* +![Stellar-Save Mobile Dashboard Mockup](images/mobile-dashboard.png) -**Q: The app keeps crashing, what do I do?** -A: Update to latest version, restart device, or reinstall (backup seed phrase first!). +--- -**Q: I forgot my PIN, how do I reset it?** -A: You cannot reset your PIN. You must reinstall and restore with your seed phrase. +### πŸ’Έ Contribution Authorization Flow +This wireframe shows the transition from the PWA contribution screen to the Lobstr signing modal: + +```mermaid +graph LR + subgraph Stellar-Save PWA + A["Group Details"] + B["Contribute Button"] + C["PWA Awaiting Signature..."] + end + + subgraph Lobstr Wallet App + D["Deep Link Opened"] + E["Sign Soroban Tx?"] + F["[Confirm Button]"] + end + + A --> B + B -->|Deep Link Linkage| D + D --> E + E --> F + F -->|Confirm & Sign| C +``` + +*For a high-fidelity visual preview of the Lobstr signing screen, see the mock image below:* +![Lobstr Signing Confirmation Mockup](images/lobstr-sign.png) -**Q: Can I recover my wallet without the seed phrase?** -A: No. The seed phrase is the only way to recover your wallet. Always keep it backed up securely. +--- -## Version History +## πŸ”§ 5. Troubleshooting Mobile Transactions -### v1.0.0 (Upcoming) -- Initial mobile app release -- iOS and Android support -- Core ROSCA functionality -- Biometric authentication -- Push notifications -- QR code scanning -- Offline mode -- Home screen widgets +Mobile operating systems have strict background app policies. Here is how to fix common transaction errors. -### Future Updates -- Multi-language support -- In-app XLM purchases -- Advanced analytics -- Group chat -- Recurring contribution automation -- Apple Watch / Wear OS support +### 1. Connection Dropouts / Link Fails +* **Symptom**: Tapping "Contribute" does not redirect to the Lobstr app, or the PWA gets stuck loading indefinitely. +* **Resolution**: + 1. Ensure both your browser and the Lobstr app are updated to the latest versions. + 2. If the deep link fails to trigger, copy the Group ID, open the Lobstr in-app browser (if available), and navigate to the Stellar-Save site within Lobstr itself. + 3. Close other background apps to free up device memory. ---- +### 2. Insufficient XLM for Transaction Fees +* **Symptom**: The Lobstr app returns an error stating `Insufficient Balance` or `Fee Payment Failed`. +* **Resolution**: Even if you are contributing custom tokens (like USDC), Stellar requires a tiny amount of native **XLM** in your wallet to pay for transaction gas fees. Always maintain at least **1–2 XLM** (under $0.20) in your wallet to cover fee overheads. -**Need more help?** Visit our [main user guide](user-guide.md) or contact support through the app. +### 3. Reentrancy Block / Duplicate Click +* **Symptom**: Transaction fails with `Error Code: 5002` or `Contract Reentered`. +* **Resolution**: This occurs if you tap the "Contribute" button multiple times quickly on a laggy connection. The smart contract locks itself during a transfer to prevent reentrancy attacks. Close the app, wait 10 seconds, refresh, and tap once. -**Ready to get started?** Download Stellar-Save from the [App Store](https://apps.apple.com/stellarsave) or [Google Play](https://play.google.com/store/apps/stellarsave). \ No newline at end of file +### 4. Background Sleep / Timeout +* **Symptom**: After signing in Lobstr, you return to the PWA and see a "Transaction Timeout" or "Session Expired" error. +* **Resolution**: iOS and Android will sometimes freeze background browser tabs while you are signing in another app. To prevent this, sign the transaction in Lobstr within **15 seconds** and switch back to Safari/Chrome immediately. \ No newline at end of file