From 87546bc99f5aca1da148b91556d5c61e2329ed58 Mon Sep 17 00:00:00 2001
From: Muhammad-Al-amin <muhammadaminu2006@gmaail.com>
Date: Sat, 25 Jul 2026 18:11:29 +0100
Subject: [PATCH 1/4] feat(settings): add network environment status section
 and hook

Create a new `useNetworkEnvironment` hook that parses environment variables to classify network tier, format host URLs, determine vault status, and generate relevant warnings.
Add a new Network & Environment section to the settings screen displaying network details, RPC hosts, vault mode, masked contract ID, and environment warnings.
Export reusable types and the hook from the new `src/features/settings` module.
---
 app/(tabs)/settings.tsx                       | 681 ++++++++++++------
 src/features/settings/index.ts                |   7 +
 .../settings/useNetworkEnvironment.ts         | 156 ++++
 3 files changed, 643 insertions(+), 201 deletions(-)
 create mode 100644 src/features/settings/index.ts
 create mode 100644 src/features/settings/useNetworkEnvironment.ts

diff --git a/app/(tabs)/settings.tsx b/app/(tabs)/settings.tsx
index f92a9c2..84d6263 100644
--- a/app/(tabs)/settings.tsx
+++ b/app/(tabs)/settings.tsx
@@ -1,7 +1,32 @@
-import React, { useState } from 'react';
-import { View, Text, StyleSheet, ScrollView, Alert, Switch, TouchableOpacity } from 'react-native';
+import React, { useState, useMemo } from 'react';
+import {
+  View,
+  Text,
+  StyleSheet,
+  ScrollView,
+  Alert,
+  Switch,
+  TouchableOpacity,
+} from 'react-native';
 import { useRouter } from 'expo-router';
 import Constants from 'expo-constants';
+import {
+  Shield,
+  Sun,
+  Moon,
+  Monitor,
+  Users,
+  KeyRound,
+  Globe,
+  Server,
+  PiggyBank,
+  Info,
+  AlertTriangle,
+  ShieldAlert,
+  Activity,
+  ChevronRight,
+  CheckCircle2,
+} from 'lucide-react-native';
 import { Button } from '../../src/components/Button';
 import { SIZES, RADIUS, ThemeColors } from '../../src/constants/theme';
 import { useTheme } from '../../src/hooks/useTheme';
@@ -12,11 +37,9 @@ import {
 } from '../../src/utils/walletStorageErrors';
 import { useAppLockStore } from '../../src/store/appLockStore';
 import { ThemeMode } from '../../src/store/appStore';
-import { Moon, Sun, Monitor, Shield, Info } from 'lucide-react-native';
-import { Moon, Sun, Monitor, Shield, Info, Globe } from 'lucide-react-native';import { WalletResetConfirmModal } from '../../src/components/WalletResetConfirmModal';
-import { Moon, Sun, Monitor, Shield, AlertTriangle, Activity } from 'lucide-react-native';
-import { SecretKeyReveal } from '../../src/components/SecretKeyReveal';
 import { WalletResetConfirmModal } from '../../src/components/WalletResetConfirmModal';
+import { SecretKeyReveal } from '../../src/components/SecretKeyReveal';
+import { useNetworkEnvironment, EnvironmentWarning } from '../../src/features/settings';
 
 const THEME_OPTIONS: { mode: ThemeMode; label: string; Icon: typeof Sun }[] = [
   { mode: 'light', label: 'Light', Icon: Sun },
@@ -24,25 +47,29 @@ const THEME_OPTIONS: { mode: ThemeMode; label: string; Icon: typeof Sun }[] = [
   { mode: 'system', label: 'System', Icon: Monitor },
 ];
 
+const WARNING_ICON = {
+  info: Info,
+  warning: AlertTriangle,
+  error: ShieldAlert,
+} as const;
+
 export default function SettingsScreen() {
   const router = useRouter();
   const { clearWallet, getSecretKey } = useWalletStore();
   const { colors, themeMode, setThemeMode } = useTheme();
   const { isLockEnabled, enableLock, disableLock, authenticate } = useAppLockStore();
+  const env = useNetworkEnvironment();
+
   const [showSecret, setShowSecret] = useState(false);
   const [secretKey, setSecretKey] = useState<string | null>(null);
   const [showResetModal, setShowResetModal] = useState(false);
   const [isResetting, setIsResetting] = useState(false);
 
-  const styles = createStyles(colors);
+  const styles = useMemo(() => createStyles(colors), [colors]);
 
-  // Read version from Expo manifest, with graceful fallback
   const appVersion = Constants.expoConfig?.version ?? Constants.nativeAppVersion ?? '1.0.0';
   const appName = Constants.expoConfig?.name ?? 'Stellar PocketPay';
 
-  // Read network from environment variable, with a fallback
-  const activeNetwork = process.env.EXPO_PUBLIC_STELLAR_NETWORK ?? 'TESTNET';
-
   const handleExportKey = async () => {
     if (!showSecret) {
       const secret = await getSecretKey();
@@ -50,10 +77,7 @@ export default function SettingsScreen() {
         setSecretKey(secret);
         setShowSecret(true);
       } else {
-        Alert.alert(
-          'Unable to Access Secret Key',
-          WALLET_SECRET_ACCESS_MESSAGE
-        );
+        Alert.alert('Unable to Access Secret Key', WALLET_SECRET_ACCESS_MESSAGE);
       }
     } else {
       setShowSecret(false);
@@ -61,9 +85,7 @@ export default function SettingsScreen() {
     }
   };
 
-  const handleSignOut = () => {
-    setShowResetModal(true);
-  };
+  const handleSignOut = () => setShowResetModal(true);
 
   const handleResetConfirm = async () => {
     setIsResetting(true);
@@ -99,37 +121,32 @@ export default function SettingsScreen() {
 
   return (
     <>
-      <ScrollView style={styles.container}>
-        {/* Preferences */}
+      <ScrollView style={styles.container} contentContainerStyle={styles.content}>
+        {/* ── Preferences ────────────────────────────────────────── */}
         <View style={styles.section}>
           <Text style={styles.sectionTitle}>Preferences</Text>
+
           <View style={styles.card}>
             <View style={styles.row}>
               <View style={styles.rowLeft}>
-                <Shield color={colors.primary} size={24} />
+                <Shield color={colors.primary} size={20} />
                 <View style={styles.rowTextGroup}>
                   <Text style={styles.rowText}>App Lock</Text>
                   <Text style={styles.rowHelper}>
                     Require biometrics or passcode to open
                   </Text>
                 </View>
-                <Switch
-                  value={isLockEnabled}
-                  onValueChange={handleToggleLock}
-                  trackColor={{ false: colors.border, true: colors.primary }}
-                />
               </View>
+              <Switch
+                value={isLockEnabled}
+                onValueChange={handleToggleLock}
+                trackColor={{ false: colors.border, true: colors.primary }}
+              />
             </View>
-            <Switch
-              value={isLockEnabled}
-              onValueChange={handleToggleLock}
-              trackColor={{ false: colors.border, true: colors.primary }}
-            />
-          </View>
 
-          <View style={styles.divider} />
+            <View style={styles.divider} />
 
-          <View style={styles.themeRow}>
+            <View style={styles.themeRow}>
               {THEME_OPTIONS.map(({ mode, label, Icon }) => {
                 const selected = themeMode === mode;
                 return (
@@ -137,9 +154,15 @@ export default function SettingsScreen() {
                     key={mode}
                     style={[styles.themeOption, selected && styles.themeOptionSelected]}
                     onPress={() => setThemeMode(mode)}
+                    activeOpacity={0.7}
                   >
-                    <Icon color={selected ? colors.primary : colors.textMuted} size={20} />
-                    <Text style={[styles.themeOptionLabel, selected && styles.themeOptionLabelSelected]}>
+                    <Icon color={selected ? colors.primary : colors.textMuted} size={18} />
+                    <Text
+                      style={[
+                        styles.themeOptionLabel,
+                        selected && styles.themeOptionLabelSelected,
+                      ]}
+                    >
                       {label}
                     </Text>
                   </TouchableOpacity>
@@ -147,91 +170,175 @@ export default function SettingsScreen() {
               })}
             </View>
           </View>
+        </View>
 
-        {/* Wallet */}
+        {/* ── Wallet ─────────────────────────────────────────────── */}
         <View style={styles.section}>
           <Text style={styles.sectionTitle}>Wallet</Text>
+
           <View style={styles.card}>
-            <Button
-              title="Address Book / Contacts"
-              variant="outline"
+            <TouchableOpacity
+              style={[styles.row, styles.rowInteractive]}
               onPress={() => router.push('/contacts')}
-              style={styles.menuButtonLast}
+              activeOpacity={0.7}
+            >
+              <View style={styles.rowLeft}>
+                <Users color={colors.primary} size={20} />
+                <View style={styles.rowTextGroup}>
+                  <Text style={styles.rowText}>Address Book</Text>
+                  <Text style={styles.rowHelper}>Saved contacts and addresses</Text>
+                </View>
+              </View>
+              <ChevronRight color={colors.textMuted} size={18} />
+            </TouchableOpacity>
+
+            <View style={styles.divider} />
+
+            <TouchableOpacity
+              style={[styles.row, styles.rowInteractive]}
+              onPress={handleExportKey}
+              activeOpacity={0.7}
+            >
+              <View style={styles.rowLeft}>
+                <KeyRound color={colors.primary} size={20} />
+                <View style={styles.rowTextGroup}>
+                  <Text style={styles.rowText}>
+                    {showSecret ? 'Hide Secret Key' : 'Export Secret Key'}
+                  </Text>
+                  <Text style={styles.rowHelper}>
+                    {showSecret ? 'Collapse the revealed key' : 'View and back up your secret key'}
+                  </Text>
+                </View>
+              </View>
+              <ChevronRight color={colors.textMuted} size={18} />
+            </TouchableOpacity>
+
+            {showSecret && secretKey ? (
+              <>
+                <View style={styles.divider} />
+                <View style={styles.revealContainer}>
+                  <SecretKeyReveal secretKey={secretKey} />
+                </View>
+              </>
+            ) : null}
+          </View>
+        </View>
+
+        {/* ── Network & Environment (NEW) ────────────────────────── */}
+        <View style={styles.section}>
+          <Text style={styles.sectionTitle}>Network &amp; Environment</Text>
+
+          {/* Warnings */}
+          {env.warnings.length > 0 && (
+            <View style={styles.warningsStack}>
+              {env.warnings.map((w, idx) => (
+                <WarningBanner key={idx} warning={w} styles={styles} colors={colors} />
+              ))}
+            </View>
+          )}
+
+          <View style={styles.card}>
+            <EnvRow
+              styles={styles}
+              colors={colors}
+              Icon={Globe}
+              label="Network"
+              value={env.networkLabel}
+              valueEmphasis
+              badge={
+                env.networkTier === 'mainnet'
+                  ? { text: 'Live', tone: 'error' }
+                  : env.networkTier === 'testnet'
+                    ? { text: 'Test', tone: 'info' }
+                    : { text: 'Custom', tone: 'warning' }
+              }
+            />
+            <View style={styles.divider} />
+            <EnvRow
+              styles={styles}
+              colors={colors}
+              Icon={Server}
+              label="Horizon Server"
+              value={env.horizonHost}
+            />
+            <View style={styles.divider} />
+            <EnvRow
+              styles={styles}
+              colors={colors}
+              Icon={Server}
+              label="Soroban RPC"
+              value={env.sorobanHost}
+            />
+            <View style={styles.divider} />
+            <EnvRow
+              styles={styles}
+              colors={colors}
+              Icon={PiggyBank}
+              label="Vault Mode"
+              value={env.vaultMode === 'configured' ? 'Smart Contract' : 'Local Mock'}
+              badge={
+                env.vaultMode === 'configured'
+                  ? { text: 'Real', tone: 'success' }
+                  : { text: 'Mock', tone: 'warning' }
+              }
             />
+            {env.vaultMode === 'configured' ? (
+              <>
+                <View style={styles.divider} />
+                <EnvRow
+                  styles={styles}
+                  colors={colors}
+                  Icon={CheckCircle2}
+                  label="Contract"
+                  value={env.vaultContractLabel}
+                />
+              </>
+            ) : null}
           </View>
         </View>
 
-        {/* About */}
+        {/* ── About ──────────────────────────────────────────────── */}
         <View style={styles.section}>
           <Text style={styles.sectionTitle}>About</Text>
+
           <View style={styles.card}>
-            <View style={styles.aboutRow}>
-              <Info color={colors.textSecondary} size={20} />
-              <View style={styles.aboutTextGroup}>
-                <Text style={styles.aboutLabel}>App Name</Text>
-                <Text style={styles.aboutValue}>{appName}</Text>
-              </View>
-            </View>
-            <View style={styles.aboutDivider} />
-            <View style={styles.aboutRow}>
-              <Info color={colors.textSecondary} size={20} />
-              <View style={styles.aboutTextGroup}>
-                <Text style={styles.aboutLabel}>Version</Text>
-                <Text style={styles.aboutValue}>{appVersion}</Text>
-              </View>
-            </View>
-            <View style={styles.aboutDivider} />
-            <View style={styles.aboutRow}>
-              <Info color={colors.textSecondary} size={20} />
-              <View style={styles.aboutTextGroup}>
-                <Text style={styles.aboutLabel}>Network</Text>
-                {/* Dynamically display active network with fallback */}
-                <Text style={styles.aboutValue}>{activeNetwork}</Text>
-              </View>
-            </View>
-                <Text style={styles.aboutLabel}>Version</Text>
-                <Text style={styles.aboutValue}>{appVersion}</Text>
-              </View>
-            </View>
-            <View style={styles.aboutDivider} />
-            <View style={styles.aboutRow}>
-              <Info color={colors.textSecondary} size={20} />
-              <View style={styles.aboutTextGroup}>
-                <Text style={styles.aboutLabel}>Network</Text>
-                {/* Dynamically display active network with fallback */}
-                <Text style={styles.aboutValue}>{activeNetwork}</Text>
-              </View>
-            <View style={styles.row}>
-              <Text style={styles.aboutLabel}>App Name</Text>
-              <Text style={styles.rowValue}>{appName}</Text>
-            </View>
-            <View style={styles.divider} />
-            <View style={styles.row}>
-              <Text style={styles.aboutLabel}>Version</Text>
-              <Text style={styles.rowValue}>{appVersion}</Text>
-            </View>
+            <EnvRow
+              styles={styles}
+              colors={colors}
+              Icon={Info}
+              label="App Name"
+              value={appName}
+            />
             <View style={styles.divider} />
-            <View style={styles.row}>
-              <Text style={styles.aboutLabel}>Network</Text>
-              <Text style={styles.rowValue}>Testnet</Text>
-            </View>
+            <EnvRow
+              styles={styles}
+              colors={colors}
+              Icon={Info}
+              label="Version"
+              value={appVersion}
+            />
             <View style={styles.divider} />
             <TouchableOpacity
-              style={[styles.row, styles.rowLast]}
+              style={[styles.row, styles.rowInteractive]}
               onPress={() => router.push('/diagnostics')}
+              activeOpacity={0.7}
             >
               <View style={styles.rowLeft}>
                 <Activity color={colors.primary} size={20} />
-                <Text style={[styles.aboutLabel, { marginLeft: SIZES.sm }]}>Diagnostics</Text>
+                <View style={styles.rowTextGroup}>
+                  <Text style={styles.rowText}>Diagnostics</Text>
+                  <Text style={styles.rowHelper}>Advanced status and logs</Text>
+                </View>
               </View>
-              <Text style={styles.rowValue}>View</Text>
+              <ChevronRight color={colors.textMuted} size={18} />
             </TouchableOpacity>
           </View>
         </View>
 
-        <View style={[styles.section, { marginTop: SIZES.xl }]}>
+        {/* ── Sign Out ───────────────────────────────────────────── */}
+        <View style={[styles.section, styles.dangerSection]}>
           <Button
-            title="Sign Out & Clear Wallet"
+            title="Sign Out &amp; Clear Wallet"
             variant="danger"
             onPress={handleSignOut}
           />
@@ -248,108 +355,280 @@ export default function SettingsScreen() {
   );
 }
 
-const createStyles = (colors: ThemeColors) => StyleSheet.create({
-  container: {
-    flex: 1,
-    backgroundColor: colors.background,
-    padding: SIZES.lg,
-  },
-  section: {
-    marginBottom: SIZES.xl,
-  },
-  sectionTitle: {
-    color: colors.textSecondary,
-    fontSize: 14,
-    fontWeight: '500',
-    marginBottom: SIZES.sm,
-    textTransform: 'uppercase',
-    letterSpacing: 1,
-  },
-  card: {
-    backgroundColor: colors.surface,
-    borderRadius: RADIUS.lg,
-    overflow: 'hidden',
-    borderWidth: 1,
-    borderColor: colors.border,
-  },
-  row: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyInBetween: 'space-between',
-    padding: SIZES.lg,
-  },
-  rowLeft: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    flex: 1,
-  },
-  rowTextGroup: {
-    marginLeft: SIZES.md,
-    flex: 1,
-  },
-  rowText: {
-    color: colors.textPrimary,
-    fontSize: 16,
-  },
-  rowHelper: {
-    color: colors.textMuted,
-    fontSize: 12,
-    marginTop: 2,
-  },
-  divider: {
-    height: 1,
-    backgroundColor: colors.border,
-    marginHorizontal: SIZES.lg,
-  },
-  themeRow: {
-    flexDirection: 'row',
-    padding: SIZES.sm,
-    gap: SIZES.sm,
-  },
-  themeOption: {
-    flex: 1,
-    alignItems: 'center',
-    paddingVertical: SIZES.sm,
-    borderRadius: RADIUS.md,
-  },
-  themeOptionSelected: {
-    backgroundColor: colors.surfaceLight,
-  },
-  themeOptionLabel: {
-    color: colors.textMuted,
-    fontSize: 12,
-    marginTop: 4,
-  },
-  themeOptionLabelSelected: {
-    color: colors.primary,
-  },
-  aboutRow: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    paddingVertical: SIZES.md,
-    paddingHorizontal: SIZES.lg,
-  },
-  aboutTextGroup: {
-    marginLeft: SIZES.md,
-  },
-  aboutLabel: {
-    color: colors.textMuted,
-    fontSize: 12,
-  },
-  aboutValue: {
-    color: colors.textPrimary,
-    fontSize: 16,
-    fontWeight: '500',
-  },
-  aboutDivider: {
-    height: 1,
-    backgroundColor: colors.border,
-    marginHorizontal: SIZES.lg,
-  },
-  menuButtonLast: {
-    borderWidth: 0,
-    borderRadius: 0,
-    justifyContent: 'flex-start',
-    paddingHorizontal: SIZES.lg,
-  },
-});
\ No newline at end of file
+// ─── Sub-components ──────────────────────────────────────────────────────
+
+type BadgeTone = 'info' | 'success' | 'warning' | 'error';
+
+interface EnvRowBadge {
+  text: string;
+  tone: BadgeTone;
+}
+
+interface EnvRowProps {
+  styles: ReturnType<typeof createStyles>;
+  colors: ThemeColors;
+  Icon: React.ComponentType<{ size?: number; color?: string }>;
+  label: string;
+  value: string;
+  valueEmphasis?: boolean;
+  badge?: EnvRowBadge;
+}
+
+function EnvRow({
+  styles,
+  colors,
+  Icon,
+  label,
+  value,
+  valueEmphasis,
+  badge,
+}: EnvRowProps) {
+  return (
+    <View style={styles.row}>
+      <View style={styles.rowLeft}>
+        <Icon size={20} color={colors.primary} />
+        <View style={styles.rowTextGroup}>
+          <Text style={styles.rowLabel}>{label}</Text>
+          <View style={styles.rowValueGroup}>
+            <Text
+              style={[
+                styles.rowValue,
+                valueEmphasis && styles.rowValueEmphasis,
+              ]}
+              numberOfLines={1}
+              ellipsizeMode="middle"
+            >
+              {value}
+            </Text>
+            {badge ? <Badge styles={styles} colors={colors} badge={badge} /> : null}
+          </View>
+        </View>
+      </View>
+    </View>
+  );
+}
+
+function Badge({
+  styles,
+  colors,
+  badge,
+}: {
+  styles: ReturnType<typeof createStyles>;
+  colors: ThemeColors;
+  badge: EnvRowBadge;
+}) {
+  const bg = {
+    info: 'rgba(0, 229, 255, 0.12)',
+    success: 'rgba(0, 230, 118, 0.12)',
+    warning: 'rgba(255, 196, 0, 0.12)',
+    error: 'rgba(255, 61, 0, 0.12)',
+  }[badge.tone];
+
+  const fg = {
+    info: colors.primary,
+    success: colors.success,
+    warning: colors.warning,
+    error: colors.error,
+  }[badge.tone];
+
+  return (
+    <View style={[styles.badge, { backgroundColor: bg }]}>
+      <Text style={[styles.badgeText, { color: fg }]}>{badge.text}</Text>
+    </View>
+  );
+}
+
+function WarningBanner({
+  warning,
+  styles,
+  colors,
+}: {
+  warning: EnvironmentWarning;
+  styles: ReturnType<typeof createStyles>;
+  colors: ThemeColors;
+}) {
+  const Icon = WARNING_ICON[warning.severity];
+  const borderColor =
+    warning.severity === 'error'
+      ? colors.error
+      : warning.severity === 'warning'
+        ? colors.warning
+        : colors.primary;
+
+  const bgColor =
+    warning.severity === 'error'
+      ? 'rgba(255, 61, 0, 0.08)'
+      : warning.severity === 'warning'
+        ? 'rgba(255, 196, 0, 0.08)'
+        : 'rgba(0, 229, 255, 0.08)';
+
+  const fg = borderColor;
+
+  return (
+    <View style={[styles.warningBanner, { backgroundColor: bgColor, borderColor }]}>
+      <Icon color={fg} size={18} style={styles.warningIcon} />
+      <View style={styles.warningBody}>
+        <Text style={[styles.warningTitle, { color: fg }]}>{warning.title}</Text>
+        <Text style={[styles.warningMessage, { color: colors.textSecondary }]}>
+          {warning.message}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+// ─── Styles ──────────────────────────────────────────────────────────────
+
+const createStyles = (colors: ThemeColors) =>
+  StyleSheet.create({
+    container: {
+      flex: 1,
+      backgroundColor: colors.background,
+    },
+    content: {
+      padding: SIZES.lg,
+      paddingBottom: SIZES.xxl * 2,
+    },
+    section: {
+      marginBottom: SIZES.xl,
+    },
+    dangerSection: {
+      marginTop: SIZES.md,
+    },
+    sectionTitle: {
+      color: colors.textSecondary,
+      fontSize: 12,
+      fontWeight: '600',
+      marginBottom: SIZES.sm,
+      textTransform: 'uppercase',
+      letterSpacing: 1.2,
+    },
+    card: {
+      backgroundColor: colors.surface,
+      borderRadius: RADIUS.lg,
+      overflow: 'hidden',
+      borderWidth: 1,
+      borderColor: colors.border,
+    },
+    row: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+      padding: SIZES.lg,
+    },
+    rowInteractive: {
+      // Subtle press feedback is handled by TouchableOpacity activeOpacity
+    },
+    rowLeft: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      flex: 1,
+    },
+    rowTextGroup: {
+      marginLeft: SIZES.md,
+      flex: 1,
+    },
+    rowText: {
+      color: colors.textPrimary,
+      fontSize: 16,
+      fontWeight: '500',
+    },
+    rowHelper: {
+      color: colors.textMuted,
+      fontSize: 12,
+      marginTop: 2,
+      lineHeight: 16,
+    },
+    rowLabel: {
+      color: colors.textMuted,
+      fontSize: 12,
+    },
+    rowValueGroup: {
+      marginTop: 3,
+      flexDirection: 'row',
+      alignItems: 'center',
+      flexWrap: 'wrap',
+      gap: SIZES.xs,
+    },
+    rowValue: {
+      color: colors.textPrimary,
+      fontSize: 14,
+      fontWeight: '500',
+      maxWidth: 220,
+    },
+    rowValueEmphasis: {
+      fontSize: 15,
+      fontWeight: '600',
+    },
+    badge: {
+      paddingHorizontal: SIZES.sm,
+      paddingVertical: 2,
+      borderRadius: RADIUS.round,
+    },
+    badgeText: {
+      fontSize: 10,
+      fontWeight: '700',
+      letterSpacing: 0.4,
+      textTransform: 'uppercase',
+    },
+    divider: {
+      height: StyleSheet.hairlineWidth,
+      backgroundColor: colors.border,
+      marginHorizontal: SIZES.lg,
+    },
+    themeRow: {
+      flexDirection: 'row',
+      padding: SIZES.sm,
+      gap: SIZES.sm,
+    },
+    themeOption: {
+      flex: 1,
+      alignItems: 'center',
+      paddingVertical: SIZES.md,
+      borderRadius: RADIUS.md,
+    },
+    themeOptionSelected: {
+      backgroundColor: colors.surfaceLight,
+    },
+    themeOptionLabel: {
+      color: colors.textMuted,
+      fontSize: 12,
+      marginTop: 4,
+      fontWeight: '500',
+    },
+    themeOptionLabelSelected: {
+      color: colors.primary,
+      fontWeight: '600',
+    },
+    revealContainer: {
+      paddingHorizontal: SIZES.lg,
+      paddingBottom: SIZES.lg,
+    },
+    warningsStack: {
+      gap: SIZES.sm,
+      marginBottom: SIZES.md,
+    },
+    warningBanner: {
+      flexDirection: 'row',
+      alignItems: 'flex-start',
+      borderRadius: RADIUS.md,
+      borderWidth: 1,
+      padding: SIZES.md,
+      gap: SIZES.sm,
+    },
+    warningIcon: {
+      marginTop: 1,
+    },
+    warningBody: {
+      flex: 1,
+    },
+    warningTitle: {
+      fontSize: 13,
+      fontWeight: '700',
+      marginBottom: 2,
+    },
+    warningMessage: {
+      fontSize: 12,
+      lineHeight: 17,
+    },
+  });
diff --git a/src/features/settings/index.ts b/src/features/settings/index.ts
new file mode 100644
index 0000000..c257667
--- /dev/null
+++ b/src/features/settings/index.ts
@@ -0,0 +1,7 @@
+export { useNetworkEnvironment } from './useNetworkEnvironment';
+export type {
+  NetworkTier,
+  VaultMode,
+  EnvironmentWarning,
+  NetworkEnvironment,
+} from './useNetworkEnvironment';
diff --git a/src/features/settings/useNetworkEnvironment.ts b/src/features/settings/useNetworkEnvironment.ts
new file mode 100644
index 0000000..024cf66
--- /dev/null
+++ b/src/features/settings/useNetworkEnvironment.ts
@@ -0,0 +1,156 @@
+import { useMemo } from 'react';
+import { isVaultConfigured, getVaultContractId } from '../../services/vault';
+
+export type NetworkTier = 'mainnet' | 'testnet' | 'custom';
+
+export type VaultMode = 'configured' | 'mock';
+
+export interface EnvironmentWarning {
+  severity: 'info' | 'warning' | 'error';
+  title: string;
+  message: string;
+}
+
+export interface NetworkEnvironment {
+  networkName: string;
+  networkTier: NetworkTier;
+  networkLabel: string;
+  horizonHost: string;
+  sorobanHost: string;
+  vaultMode: VaultMode;
+  vaultContractLabel: string;
+  warnings: EnvironmentWarning[];
+}
+
+const KNOWN_MAINNET_NAMES = new Set(['MAINNET', 'PUBLIC', 'LIVENET', 'PROD', 'PRODUCTION']);
+const KNOWN_TESTNET_NAMES = new Set(['TESTNET', 'TEST', 'FUTURENET', 'SANDBOX', 'STANDALONE']);
+
+function classifyNetworkTier(rawName: string): NetworkTier {
+  const upper = rawName.trim().toUpperCase();
+  if (KNOWN_MAINNET_NAMES.has(upper)) return 'mainnet';
+  if (KNOWN_TESTNET_NAMES.has(upper)) return 'testnet';
+  return 'custom';
+}
+
+function prettyNetworkLabel(tier: NetworkTier, rawName: string): string {
+  switch (tier) {
+    case 'mainnet':
+      return 'Public Network (Mainnet)';
+    case 'testnet':
+      return 'Testnet';
+    default:
+      return rawName || 'Custom Network';
+  }
+}
+
+function extractHost(url: string | undefined): string {
+  if (!url) return '—';
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname || url;
+  } catch {
+    // Fallback: strip protocol and path with simple string ops
+    const withoutProto = url.replace(/^[a-zA-Z]+:\/\//, '');
+    const withoutPath = withoutProto.split('/')[0];
+    return withoutPath || url;
+  }
+}
+
+function maskContractId(contractId: string): string {
+  const trimmed = contractId.trim();
+  if (!trimmed) return '—';
+  if (trimmed.length <= 12) return trimmed;
+  const first = trimmed.slice(0, 6);
+  const last = trimmed.slice(-6);
+  return `${first}…${last}`;
+}
+
+function buildWarnings(
+  networkTier: NetworkTier,
+  vaultConfigured: boolean,
+  vaultContractId: string
+): EnvironmentWarning[] {
+  const warnings: EnvironmentWarning[] = [];
+
+  if (networkTier === 'mainnet') {
+    warnings.push({
+      severity: 'error',
+      title: 'Mainnet in use',
+      message:
+        'This app is connected to the public Stellar network. Real XLM with monetary value will be moved by any transactions you send. Double-check every payment before confirming.',
+    });
+  }
+
+  if (networkTier === 'testnet') {
+    warnings.push({
+      severity: 'info',
+      title: 'Testnet only',
+      message:
+        'This app runs on the Stellar Testnet. Testnet XLM has no real monetary value and balances may be reset by the network at any time.',
+    });
+  }
+
+  if (networkTier === 'custom') {
+    warnings.push({
+      severity: 'warning',
+      title: 'Custom network configured',
+      message:
+        'A non-standard network name is set in EXPO_PUBLIC_STELLAR_NETWORK. Horizon, Soroban RPC, and the passphrase must all match this network or operations will fail.',
+    });
+  }
+
+  if (!vaultConfigured) {
+    warnings.push({
+      severity: 'info',
+      title: 'Vault running in mock mode',
+      message:
+        'No Soroban vault contract is configured (EXPO_PUBLIC_VAULT_CONTRACT_ID is not set). Vault deposits and withdrawals simulate locally — no on-chain funds move.',
+    });
+  } else if (!vaultContractId) {
+    warnings.push({
+      severity: 'warning',
+      title: 'Vault contract ID missing',
+      message:
+        'The vault reported itself as configured but no contract ID could be read. Vault operations may not reach the intended contract.',
+    });
+  }
+
+  return warnings;
+}
+
+/**
+ * Hook that derives a user-safe summary of the currently configured network
+ * and vault environment. No raw secrets or full URLs are exposed — hostnames
+ * and truncated identifiers only.
+ */
+export function useNetworkEnvironment(): NetworkEnvironment {
+  return useMemo(() => {
+    const rawNetwork = process.env.EXPO_PUBLIC_STELLAR_NETWORK ?? 'TESTNET';
+    const networkName = rawNetwork.trim() || 'TESTNET';
+    const networkTier = classifyNetworkTier(networkName);
+
+    const horizonUrl = process.env.EXPO_PUBLIC_STELLAR_HORIZON_URL;
+    const sorobanUrl = process.env.EXPO_PUBLIC_SOROBAN_RPC_URL;
+
+    const vaultConfigured = isVaultConfigured();
+    const vaultContractId = getVaultContractId();
+
+    const vaultMode: VaultMode = vaultConfigured ? 'configured' : 'mock';
+    const vaultContractLabel = vaultConfigured
+      ? maskContractId(vaultContractId)
+      : 'Mock (no contract)';
+
+    const warnings = buildWarnings(networkTier, vaultConfigured, vaultContractId);
+
+    return {
+      networkName,
+      networkTier,
+      networkLabel: prettyNetworkLabel(networkTier, networkName),
+      horizonHost: extractHost(horizonUrl),
+      sorobanHost: extractHost(sorobanUrl),
+      vaultMode,
+      vaultContractLabel,
+      warnings,
+    };
+  }, []);
+}

From b49418a8b5fafeb203cc2cd7e7b66244e7d1d2d0 Mon Sep 17 00:00:00 2001
From: Muhammad-Al-amin <muhammadaminu2006@gmaail.com>
Date: Sat, 25 Jul 2026 18:31:03 +0100
Subject: [PATCH 2/4] docs: add release testing checklist

Add comprehensive manual QA checklist for tagged release builds,
create `docs/release-testing-checklist.md`, and link it in the
main README's documentation table of contents.
---
 README.md                         |   1 +
 docs/release-testing-checklist.md | 273 ++++++++++++++++++++++++++++++
 2 files changed, 274 insertions(+)
 create mode 100644 docs/release-testing-checklist.md

diff --git a/README.md b/README.md
index 755cfa0..be7ce6f 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,7 @@ React Native Expo wallet for Stellar Testnet. The app aims to feel polished and
 - [Mobile Wallet Security FAQ](./docs/WALLET_SECURITY_FAQ.md) - Local storage, secret handling, reset behaviors, and security guarantees
 - [Accessibility Checklist](./docs/accessibility.md) - Mobile accessibility audit checklist for labels, touch targets, contrast, focus, screen-reader, and error/loading states
 - [UI State Catalogue](./docs/ui-states.md) - Screen-by-screen loading, empty, error, success, disabled, and pending states for wallet, send, receive, transactions, contacts, and vault
+- [Release Testing Checklist](./docs/release-testing-checklist.md) - Manual QA checklist run before every tagged build, covering wallet, payment, vault, errors, and environment verification
 
 > ⚠️ **This app runs on the Stellar Testnet only.** Testnet XLM has no real monetary value. Read the [Security Guide](docs/security.md) before storing or sharing any keys.
 
diff --git a/docs/release-testing-checklist.md b/docs/release-testing-checklist.md
new file mode 100644
index 0000000..855c8e3
--- /dev/null
+++ b/docs/release-testing-checklist.md
@@ -0,0 +1,273 @@
+# PocketPay Mobile — Release Testing Checklist
+
+Run this checklist before any tagged release build (staging or production). Each box represents a manual verification step performed on a real device or simulator using the exact bundle that will ship.
+
+- **Tester:** ____________________________
+- **Release version:** (e.g. 1.4.0) ______
+- **Build / commit hash:** __________________
+- **Date tested:** ____ / ____ / _________
+- **Final result:** &nbsp; ✅ PASS &nbsp; / &nbsp; ⚠️ PASS WITH NOTES &nbsp; / &nbsp; ❌ FAIL
+
+---
+
+## 0. Pre-Test Setup & Build Verification
+
+Run these steps *before* executing any user journey. Failures here block further testing.
+
+- [ ] Build installs without errors on at least **one iOS device/simulator** and **one Android device/emulator**
+- [ ] No Metro bundler warnings about missing polyfills when the app boots (watch for `Buffer`, `process`, or `getRandomValues` references in the console)
+- [ ] Splash screen renders, app transitions to a screen without crashing within 10 seconds
+- [ ] Expo manifest version in **Settings → About → Version** matches the version you are releasing
+- [ ] Open **Settings → Network & Environment** and **confirm every line matches the target release**:
+  - [ ] Network row shows the correct tier: Testnet / Custom / (if applicable) Mainnet
+  - [ ] Tier badge tone is correct: `Test` (info) / `Custom` (warning) / `Live` (error)
+  - [ ] Horizon Server hostname matches target network
+  - [ ] Soroban RPC hostname matches target network
+  - [ ] Vault Mode badge: `Real` (success) only when `EXPO_PUBLIC_VAULT_CONTRACT_ID` is set for this build; else `Mock` (warning)
+  - [ ] If Vault Mode = Real: Contract row shows **truncated** (6-ellipsis-6) contract ID, NOT the full 56-char contract address
+  - [ ] Warnings stack shows the correct banners for the build: at minimum "Testnet only" (testnet), "Vault running in mock mode" (no contract ID), "Custom network configured" (custom name), or "Mainnet in use" (live)
+  - [ ] **No secret, full URL, or full contract ID appears anywhere in the Settings screen** (copy all visible text and grep the paste if unsure)
+
+### 0.1 Test Accounts Required
+
+Prepare these 2 accounts *before* starting the checklist. Use Testnet only; never real keys.
+
+| Role | Notes |
+|---|---|
+| **Account A (Fresh)** | No existing wallet on the test device. Will test Create Wallet, Fund via Friendbot, first-send, first-time vault. |
+| **Account B (Restored)** | Pre-existing wallet on a wiped device. Will test Import Secret Key, balance restore, tx pagination, matured vault lock withdrawal. |
+
+---
+
+## 1. Build Smoke Tests — Happy-Path Boot
+
+- [ ] ✨ **Fresh start (Account A):** Delete the app, reinstall, and launch. No crash on first run. The **Create Wallet / Import Wallet** choice screen loads.
+- [ ] ✨ **Cold start (Account B):** Close the app from the app switcher, re-open. Wallet is still loaded and the Home balance screen renders in under 5 seconds.
+- [ ] ✨ **App Lock gate:** Open Settings, enable App Lock, background and foreground the app. The **Lock screen overlay** appears and blocks access until biometrics or device passcode succeeds.
+- [ ] ✨ **Network offline:** Disable all network connectivity. The red **OfflineBanner** drops down from the top of all tab screens and remains visible until connectivity returns.
+- [ ] ✨ **Theme system:** Change theme between Light → Dark → System in Settings. Every tab re-renders and background/text colors update correctly. Re-open the app; the chosen theme persists.
+
+---
+
+## 2. Wallet Flows — Create, Import, Persistence
+
+### 2.1 Wallet Creation (Account A)
+
+- [ ] Tap **Create New Wallet** from the auth landing
+- [ ] **Step 1 Generate** — taps Generate, shows public key (G...) and secret key (S...) without crashing
+- [ ] **Step 2 Reveal** — secret key is displayed, copy-to-clipboard copies it correctly (paste somewhere to verify)
+- [ ] **Step 3 Confirm** — "I backed up my keys" checkbox → Continue completes without crashing
+- [ ] **Backup Reminder modal** appears on Home after creation
+- [ ] Acknowledge the modal. After next app launch it does **not** reappear.
+- [ ] Tap **Fund my Wallet** (Friendbot). Within ~15 seconds the balance updates from `0.0000000` to roughly `10,000.0000000` XLM.
+- [ ] **Export Secret Key** from Settings → Wallet. After authentication the secret key matches what was copied during creation.
+- [ ] Toggle **Hide Secret Key** again; secret value is removed from screen and clipboard (verify a paste yields non-secret text if applicable).
+
+### 2.2 Wallet Import (Account B)
+
+- [ ] Delete app + reinstall (or Sign Out from previous test), choose **Import Wallet**
+- [ ] Type random garbage (not a valid StrKey) into the secret field → validation error, import is blocked
+- [ ] Paste Account B's valid secret → import succeeds, redirects to Home
+- [ ] Balance matches Account B's last-known on-chain balance (to within 1 ledger close, ~5 s)
+- [ ] Transaction history loads the last page of operations (older dates as you scroll down)
+
+### 2.3 Sign Out & Wallet Erasure
+
+- [ ] Settings → **Sign Out & Clear Wallet** → the destructive confirm modal appears
+- [ ] Tap **Cancel** → wallet is NOT cleared, still authenticated, modal dismisses
+- [ ] Repeat → tap **Confirm** → SecureStore and AsyncStorage wallet data are cleared, app redirects to auth landing (Create/Import)
+- [ ] Background + foreground the app after sign-out: user is **still** on the auth landing (no stuck half-authenticated state)
+
+### 2.4 Address Book / Contacts
+
+- [ ] Settings → **Address Book** → empty state renders (if no contacts)
+- [ ] Add a contact with name "Alice" and a valid Testnet G-address → saves, list updates
+- [ ] Add the **same G-address** again under "Bob" → duplicate guard blocks save; error message shown
+- [ ] Add the **same name** "Alice" with a different valid G-address → duplicate guard blocks save (name + address uniqueness both enforced)
+- [ ] Delete Alice → row removed, list shrinks
+- [ ] Reopen app → deleted contact does not reappear; surviving contacts are preserved
+
+---
+
+## 3. Payment Flows — Send, Receive, Review, Success
+
+### 3.1 Receive
+
+- [ ] Navigate to **Receive tab/button**
+- [ ] QR code renders without errors (no blurry or broken SVG box)
+- [ ] Copy public key button → clipboard matches what's shown on the Home screen and on Receive
+- [ ] Share sheet opens from the Receive screen (if available on that platform)
+- [ ] Scan the QR with a second device — decoded content is the plain G-address (no extra prefix, no suffix whitespace)
+
+### 3.2 Scan → Prefill Send
+
+- [ ] Navigate to **Scan** → camera permission request (first run only) is granted
+- [ ] Scan the QR code from Receive above → scanner auto-dismisses and prefills the **Send** destination
+- [ ] Amount field is still empty and memo field is still empty (no accidental data leaking from QR if none was encoded)
+
+### 3.3 Send XLM — Happy Path
+
+> Use Account A → Account B on Testnet. Send exactly `50.0000000` XLM with memo `Rent-August` for regression.
+
+- [ ] **Send form** — destination (G-address), amount, memo all filled. No validation errors.
+- [ ] **Review screen** shows: correct source, correct destination (or truncated + label if contact), correct 50 XLM amount, fee estimate, memo `Rent-August`
+- [ ] Tap **Sign & Send**. Phase overlay progresses: Review → Handoff → Signing → Submitting → Complete (no stuck intermediate phase)
+- [ ] Within 30s app transitions to **Payment Success** screen
+- [ ] Success screen displays the transaction hash. Copy hash → paste to stellar.expert via `getExplorerTxUrl()` — page resolves to the correct operation.
+- [ ] Go back to Home → Account A balance decreased by `~50.0000100` (50 XLM + fee)
+- [ ] Go to Activity / History → top of list contains **a new row** for today, destination matches Account B, amount matches
+- [ ] Tap that history row → **Transaction Detail** screen opens with memo `Rent-August` visible, correct fee, correct operation type (payment)
+
+### 3.4 Send — Negative Validation Cases
+
+- [ ] Send to an invalid address (random text, missing first G, wrong length) → **address validation** blocks navigation to Review screen; inline error shown
+- [ ] Send `0` XLM → **amount validation** fails (positive amount required)
+- [ ] Send `99,999,999` XLM (more than balance + reserve) → **submit fails** gracefully, inline error banner shows under the Sign button, balance is NOT decreased, retry button / dismiss works.
+- [ ] Send with a memo containing > **28 UTF-8 bytes** (e.g. 14 CJK characters × 3 bytes each) → memo validation error, Review not reached.
+
+### 3.5 Send — Cancel & Dismiss Recovery
+
+- [ ] Begin Send → navigate to Review. Press the hardware/OS back button or tap Back on the nav. App returns to Send form with fields intact.
+- [ ] Begin send, reach the in-progress **Signing phase overlay** → no cancel button/action should be able to double-submit. Rapid double-tap Sign & Send → **only one** submission reaches Horizon (confirm via stellar.expert hash count later).
+
+---
+
+## 4. Vault Flows — Mock & Real Contract Paths
+
+The vault has two runtime modes. Run BOTH sub-sections for any build that could ship with either configuration.
+
+### 4.1 Mock Mode (default; `EXPO_PUBLIC_VAULT_CONTRACT_ID` unset)
+
+- [ ] Navigate to Vault tab → **Vault Intro Modal** first run appears. Acknowledge. It does **not** reappear on next tab visit.
+- [ ] **Network & Environment card in Settings still shows "Vault running in mock mode" warning banner** (confirms the mock isn't silently treated as real)
+- [ ] Vault balance starts at `0.0000000` XLM, vault balance row shows `Local Mock` label or equivalent
+- [ ] Tap **Deposit** → enter valid amount, confirm modal, submit. In mock mode the operation "succeeds" within 2 seconds and balance increases by that amount.
+- [ ] Tap **Withdraw** → amount exceeds balance → validation fails inline, submit blocked.
+- [ ] Withdraw an amount ≤ balance → succeeds, balance decreases by that amount, remainder on-chain (or mock remainder) is sensible.
+
+### 4.2 Time-Lock Flows (works in BOTH mock + real)
+
+- [ ] Create a **30-day lock** from the vault screen → lock appears in the list under Pending with countdown of ~30 days
+- [ ] Try to **Withdraw Pending** lock → action is disabled / fails with "not yet matured" copy (exact wording depends on build — confirm no funds move)
+- [ ] Simulate a matured lock (for tests, either set device clock forward in mock-only, or use a pre-seeded matured test lock):
+  - [ ] Lock appears under **Matured** section with "Available to withdraw" label
+  - [ ] Initiate **Withdraw matured lock** → eligibility evaluation runs server-side (NOT from UI state alone) in the store action
+  - [ ] After success → lock is **removed from list** only after the on-chain (or mock) transaction succeeds, never before.
+  - [ ] Vault balance increases by exactly the locked principal + any rewards shown at lock creation.
+- [ ] Repeat matured withdrawal rapidly on the same lock → server-side guard or optimistic client-side guard prevents double-withdrawal.
+
+### 4.3 Real Soroban Contract Mode (when `EXPO_PUBLIC_VAULT_CONTRACT_ID` is configured)
+
+- [ ] Open Settings → Network & Environment → Vault Mode badge reads `Real` (success tone), Contract row shows truncated ID
+- [ ] Vault Intro Modal does **not** show a warning that says "this is a mock" (copy should be correct for real mode)
+- [ ] Any successful deposit shows up on-chain (verify via stellar.expert / Soroban RPC) within 1 ledger close.
+- [ ] Any successful withdrawal decreases vault balance on-chain and in-app within 10 seconds.
+
+---
+
+## 5. Error Handling & Edge-Case Regression
+
+### 5.1 Network Errors
+
+- [ ] **Home screen, Pull-to-refresh while offline** → offline banner, spinner eventually stops, no crash, last-known balance still visible.
+- [ ] **Horizon server returns 5xx during balance refresh** → NetworkStatusBanner with severity warning appears, shows copy "Unable to reach Stellar network" (or team's chosen error copy), balance stays at cached value.
+- [ ] **Soroban RPC returns error during vault balance load** → vault card shows a per-card error state (not crash) while Home and History still render with their Horizon data.
+
+### 5.2 Wallet Storage Corruption Recovery
+
+- [ ] **Mimic corrupt secret storage** (manual test: inject empty string / invalid JSON into SecureStore key `pocketpay_wallet_secret` via dev tools if possible) → next app boot:
+  - [ ] Invalid value is silently deleted (see walletStore test cases)
+  - [ ] User lands on **auth landing** (not stuck on half-authenticated Home)
+  - [ ] No crash, no red screen, no raw error message displayed to user beyond a polite toast if implemented
+- [ ] **Sign Out** after corruption is repeatable; re-import valid secret afterwards succeeds and rehydrates balance from chain.
+
+### 5.3 React Error Boundary
+
+- [ ] Trigger a synthetic render-time error via **Diagnostics screen** (or a local dev-only method of throwing inside child render):
+  - [ ] **ErrorBoundaryFallback** screen appears — full overlay, not a partial crash
+  - [ ] Fallback has a reload/retry CTA
+  - [ ] Global exception handler runs: check for the `reportError` funnel call in console/monitoring (if Sentry wired)
+
+### 5.4 Signing Handoff State Machine
+
+Use the diagnostics panel or store inspection to verify phase never jumps backwards:
+
+- [ ] Signing phases progress exactly `idle → review → handoff → signing → submitting → completed`
+- [ ] Failure path phases exactly `… → failed` with a structured error type; re-tap resets cleanly from failed back to review
+- [ ] Cancel path phases exactly `… → cancelled`; restart from review works
+
+---
+
+## 6. Accessibility Spot Checks (Mobile)
+
+Full audit → [Accessibility Checklist](./accessibility.md). For releases, at minimum spot-check:
+
+- [ ] Every tappable row in Settings, History, Vault list has an accessible label (`accessibilityLabel`) and a 44×44 pt minimum touch target
+- [ ] Home screen balance is marked as a header / heading (not just a `<Text>`) for screen-reader navigation
+- [ ] The Sign & Send button on the Review screen has `accessibilityRole="button"` and a descriptive label that **includes the amount** if possible (not just "Next")
+- [ ] Error banners and warning banners announce themselves as live regions and read their full title + message on TalkBack/VoiceOver
+- [ ] Vault countdown labels are exposed as Text nodes, not just rendered SVG/gradients that screen readers skip
+- [ ] Dark mode: vault success badge, warning badge, and error banner text all meet **minimum 4.5:1 contrast** (eye-check or use dev-tools color picker)
+
+---
+
+## 7. Settings, Persistence & Environment Final Checks
+
+- [ ] **Settings → About → Diagnostics** link → Diagnostics screen opens and shows redacted counters only. Full G-address never appears; instead `hasPublicKey: true/false` is shown.
+- [ ] Close the app from task switcher, re-open:
+  - [ ] Theme choice persists (light/dark/system)
+  - [ ] App Lock toggle persists (enabled yesterday still enabled today)
+  - [ ] Contacts list persists (Alice/Bob rows same as last session)
+  - [ ] Backup reminder acknowledged flag persists
+  - [ ] Vault intro modal acknowledged flag persists
+- [ ] Change network name `EXPO_PUBLIC_STELLAR_NETWORK=CUSTOMNET` in a test build → Settings → Network & Environment:
+  - [ ] Label says `CUSTOMNET` (correct raw name)
+  - [ ] Tier badge = `Custom` (warning tone)
+  - [ ] Warning banner stack **now includes** "Custom network configured" advisory
+
+---
+
+## 8. Cross-Platform & Environment Matrix
+
+Fill one row per device-config combination tested. Minimum for release = 4 cells completed.
+
+| OS       | Device / Simulator | Theme    | Vault Mode | Result (✅/⚠️/❌) | Notes |
+|---|---|---|---|---|---|
+| iOS 18+  | iPhone 15 / SE 3rd gen | Light    | Mock     | | |
+| iOS 18+  | iPhone 15 / SE 3rd gen | Dark     | Mock     | | |
+| Android 14+ | Pixel 8 / emulator 64-bit | System | Real (if applicable) | | |
+| Android 14+ | Pixel 8 / emulator 64-bit | Light  | Mock     | | |
+| *Optional:* Tablet (iPadOS / Android Tab) | | | | | |
+
+---
+
+## 9. Automated Checks (Record Results)
+
+Run locally before tagging the release. Copy-paste output or note exit codes.
+
+| Automated Step | Command | Result |
+|---|---|---|
+| TypeScript strict | `npx tsc --noEmit` | ✅ exit 0 / ❌ ___ errors |
+| Jest suite | `npm test` (pinned jest-expo preset) | ✅ ___ passed / ❌ ___ failed |
+| SDK API baseline | `npm run api:check` | ✅ matches baseline / ❌ drift |
+| Expo doctor | `npx expo-doctor` | ✅ 0 issues / ⚠️ ___ warnings |
+| Deduplicated pagination (walletStore) | Verified via `__tests__/walletStore.pagination.test.ts` | ✅ / ❌ |
+| Matured withdrawal server-side eligibility | Verified via `__tests__/vaultStore.withdrawMaturedLock.test.ts` & `maturedLockWithdrawal.test.ts` | ✅ / ❌ |
+| Global error handler install | Verified via `__tests__/globalErrorHandler.test.tsx` | ✅ / ❌ |
+| Backup reminder persistence | Verified via `__tests__/BackupReminderModal.test.tsx` | ✅ / ❌ |
+
+---
+
+## 10. Final Sign-Off
+
+- [ ] All Phase 0 → 9 checks above that apply to this build have been run.
+- [ ] Any ⚠️ / ❌ items have a **written note** describing the bug, linked issue ticket, or explicit approval to ship with the known issue.
+- [ ] No Mainnet build was shipped without **Phase 0.1 Network tier = Live (error)** banner confirmation and a second human confirming `EXPO_PUBLIC_STELLAR_NETWORK_PASSPHRASE` matches the public network passphrase.
+- [ ] Release notes / CHANGELOG have been updated to reflect user-facing changes.
+- [ ] Screenshots in README.md (if committed for this release) were captured using Testnet-only dummy accounts with **no real or shared secret keys**.
+
+---
+
+**Release Manager sign-off:**
+
+Name: ________________________ &nbsp; Signature: ________________________ &nbsp; Date: ____ / ____ / ____

From c96013089d895ae8574fdc9472a61c478be05333 Mon Sep 17 00:00:00 2001
From: Muhammad-Al-amin <muhammadaminu2006@gmaail.com>
Date: Sat, 25 Jul 2026 18:42:50 +0100
Subject: [PATCH 3/4] docs: add navigation map doc and update README link

Create comprehensive navigation-map.md contributor reference covering all app routes, route groups, deep links, feature ownership boundaries, and onboarding guidance. Add a link to this new documentation in the root README.md.
---
 README.md              |   1 +
 docs/navigation-map.md | 260 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 261 insertions(+)
 create mode 100644 docs/navigation-map.md

diff --git a/README.md b/README.md
index be7ce6f..6a8a2c8 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,7 @@ React Native Expo wallet for Stellar Testnet. The app aims to feel polished and
 - [Accessibility Checklist](./docs/accessibility.md) - Mobile accessibility audit checklist for labels, touch targets, contrast, focus, screen-reader, and error/loading states
 - [UI State Catalogue](./docs/ui-states.md) - Screen-by-screen loading, empty, error, success, disabled, and pending states for wallet, send, receive, transactions, contacts, and vault
 - [Release Testing Checklist](./docs/release-testing-checklist.md) - Manual QA checklist run before every tagged build, covering wallet, payment, vault, errors, and environment verification
+- [Navigation Map](./docs/navigation-map.md) - Contributor reference: 20 routes, 3 route groups, deep links, feature ownership grid, and route-addition assumptions
 
 > ⚠️ **This app runs on the Stellar Testnet only.** Testnet XLM has no real monetary value. Read the [Security Guide](docs/security.md) before storing or sharing any keys.
 
diff --git a/docs/navigation-map.md b/docs/navigation-map.md
new file mode 100644
index 0000000..02d24e2
--- /dev/null
+++ b/docs/navigation-map.md
@@ -0,0 +1,260 @@
+# PocketPay Mobile — Navigation Map
+
+This document answers the onboarding questions:
+
+- *"Which screen file do I open to edit the Home balance view?"*
+- *"Which store slice owns wallet create/import vs. vault time-locks?"*
+- *"What happens if I add a new route group inside `app/` — do I need to update the auth gate?"*
+- *"Which screen do users land on after a successful payment?"*
+
+All file paths are relative to repository root. All routes use **Expo Router v6 file-based routing**. For routing internals see the [Expo Router documentation](https://docs.expo.dev/router/introduction/).
+
+---
+
+## 1. Route Inventory (20 Routes Across 3 Groups)
+
+Expo Router converts files in `app/` directly to routes. Parentheses in directory names (e.g. `(auth)`) are **route groups** — they organize layout nesting but do NOT appear in the URL / deep link path.
+
+### 1.1 Unauthenticated Route Group: `(auth)/`
+
+Shown when `walletStore.walletChecked === true` AND `publicKey === null` (no wallet on device). Stack navigator inside [app/(auth)/_layout.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/(auth)/_layout.tsx).
+
+| Route Path        | File on Disk                                                 | Purpose                                                      | Primary Entry: Navigate Here From…          |
+| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------- |
+| `/` (in auth)     | [app/(auth)/index.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/(auth)/index.tsx) | Landing tile: **Create New Wallet** vs **Import Existing**   | RootLayout auth gate / app cold start        |
+| `/create`         | [app/(auth)/create.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/(auth)/create.tsx) | 3-step onboarding: Generate → Reveal keys → Confirm backup   | `(auth)/index` [Create New Wallet]           |
+| `/import`         | [app/(auth)/import.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/(auth)/import.tsx) | Paste secret → StrKey validation → activate wallet           | `(auth)/index` [Import Existing]             |
+
+### 1.2 Authenticated Tab Group: `(tabs)/`
+
+Shown when `walletStore.publicKey != null` AND `walletStore.walletChecked === true`. Bottom-tab navigator inside [app/(tabs)/_layout.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/(tabs)/_layout.tsx). Adds an `OfflineBanner` at the top on all tabs.
+
+| Route Path       | File on Disk                                                 | Tab Label | Purpose                                                      |
+| ---------------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ |
+| `/` (tabs home)  | [app/(tabs)/index.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/(tabs)/index.tsx) | Home      | XLM Balance, Public Key, **Fund my Wallet** button, Backup reminder modal, 5 most-recent transactions |
+| `/history`       | [app/(tabs)/history.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/(tabs)/history.tsx) | Activity  | **SectionList grouped by date**, filter chips (All/Sent/Received), cursor-based pagination, pull-to-refresh, empty CTA → Send |
+| `/vault`         | [app/(tabs)/vault.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/(tabs)/vault.tsx) | Vault     | Soroban Savings Vault: balance card, Deposit / Withdraw CTAs, Pending/Matured lock lists, intro/education modals |
+| `/settings`      | [app/(tabs)/settings.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/(tabs)/settings.tsx) | Settings  | 4 sections — Preferences (theme, app lock), Wallet (export, sign out), Network & Environment (new), About (version, diagnostics) |
+
+### 1.3 Stack / Modal Routes (Outside Groups)
+
+Presented modally, or pushed onto the stack above the tabs.
+
+| Route Path            | File on Disk                                                 | Presentation | Purpose                                                      | Primary Entry: Navigate Here From…          |
+| --------------------- | ------------------------------------------------------------ | ------------ | ------------------------------------------------------------ | -------------------------------------------- |
+| `/send`               | [app/send.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/send.tsx) | Stack push   | Payment form: destination, amount, memo. Validates before navigation to review. | Home [Send XLM], Activity [New Payment] CTA, contact row tap, scan success |
+| `/receive`            | [app/receive.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/receive.tsx) | Stack push   | Public-key QR code, address copy + share sheet              | Home [Receive] icon / button                 |
+| `/scan`               | [app/scan.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/scan.tsx) | Stack push   | `expo-camera` QR scanner. On valid decode → navigates back to `/send` with `?destination=` prefilled. | Home [Scan] icon, Send form [Scan] button    |
+| `/review-transaction` | [app/review-transaction.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/review-transaction.tsx) | Modal-like push | 8-phase Sign & Send flow: review summary → handoff → signing → submitting → completed / failed → success screen | Send form [Review]                           |
+| `/payment-success`    | [app/payment-success.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/payment-success.tsx) | `replace` (no back history) | Post-send confirmation: big success checkmark, tx hash copy, explorer link, Back to Home | Review transaction [phase → completed]       |
+| `/contacts`           | [app/contacts.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/contacts.tsx) | Stack push   | Address book: list, search, add/edit/delete, duplicate guards. Tapping a contact pushes to `/send` with destination prefilled. | Settings [Address Book], Send form [Pick contact] |
+| `/diagnostics`        | [app/diagnostics.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/diagnostics.tsx) | Stack push   | Read-only dev/debug panel: redacted `getDiagnostics()` JSON, environment summary, synthetic-error trigger if enabled | Settings → About → [Open Diagnostics]       |
+| `/transaction/:id`    | [app/transaction/[id].tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/transaction/%5Bid%5D.tsx) | Stack push   | **Dynamic route** (segment `:id = operation id`): single-transaction detail view, memo, fee, source/dest, explorer link | Activity row tap, Home recent-list tap      |
+| `/vault/:id`          | [app/vault/[id].tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/vault/%5Bid%5D.tsx) | Stack push   | Dynamic: deep-linkable vault overview / account view (placeholder/detail) | Vault header card, from external deep link  |
+| `/vault-lock/:id`     | [app/vault-lock/[id].tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/vault-lock/%5Bid%5D.tsx) | Stack push   | Dynamic: single time-lock detail — countdown, status, mature-withdraw CTA | Vault list row tap, matured notification     |
+
+---
+
+## 2. Navigation Tree — ASCII Diagram
+
+Read top-down from the single JS entry point `expo-router/entry`. Arrow `→` means "navigates to"; `—` means "wraps as child"; `↩` means "navigates back with result / prefilled params".
+
+```
+                                     package.json: "main": "expo-router/entry"
+                                                  │
+                                                  ▼
+                                      app/_layout.tsx (Root Stack)
+                                      ├─ preload: shim.js (polyfills FIRST)
+                                      ├─ ErrorBoundary + LockScreen wrap
+                                      └─ Auth redirect gate (walletChecked + publicKey)
+                                                   │
+                              ┌─ NO wallet ───────┴───────── YES wallet ──┐
+                              │                                           │
+                              ▼                                           ▼
+                    (auth)/_layout.tsx                          (tabs)/_layout.tsx
+                   ┌────────────────────┐                      ┌─── OFFLINE BANNER ────┐
+                   │ index (Create/Imp) │                      │  Home     Activity     │
+                   │  ▼            ▼    │                      │  Vault    Settings     │
+                   │ create      import │                      └────────────────────────┘
+                   └────────────────────┘                                  │
+                                                              ┌────────────┴─────────────┬──────────────┬────────────┬───────────────┐
+                                                              ▼                         ▼              ▼            ▼              ▼
+                                                          /send                    /receive       /scan       /contacts    /diagnostics
+                                                              │  (form validates)                 │
+                                                              ▼                                   └── on decode: /send ?destination=...
+                                                     /review-transaction
+                                                              │
+                                                     (8-phase signer SM)
+                                                              │ success: replace (no back)
+                                                              ▼
+                                                     /payment-success  →  "Back to Home"  →  /(tabs)
+
+                         DYNAMIC DEEP-LINKABLE ROUTES (stack-pushed from within their parent screen)
+                         ├─ /transaction/:id     ← tap row in Home recent / Activity list
+                         ├─ /vault/:id           ← tap Vault header / deep link scheme://stellar-pocketpay/vault/123
+                         └─ /vault-lock/:id      ← tap lock row in Vault list
+```
+
+### 2.1 Back-Stack Behavior — Key Rules
+
+Document these behaviors explicitly when modifying navigation:
+
+- `/payment-success` uses **`router.replace`**, not `push`. The user cannot go "Back to signing" → always jumps to Home. This prevents accidental duplicate sends. See: [app/review-transaction.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/review-transaction.tsx)
+- RootLayout auth gate uses **`router.replace`** when swapping `(auth)`↔`(tabs)`. This means tapping hardware Back after sign-out does NOT pop a tab screen back into view. See: [app/_layout.tsx auth gate](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/_layout.tsx#L46-L66)
+- `/scan` calls **`router.back()` after setting params** on a successful decode. This returns to the form, preserving what the user had already typed into Amount/Memo before scanning. See [app/scan.tsx](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/app/scan.tsx).
+- Dynamic routes `/transaction/:id`, `/vault/:id`, `/vault-lock/:id` accept **both deep links and programmatic pushes**. They must render gracefully even when the parent store state is empty (e.g. user taps a stored deep link before the wallet loads — show a loading or "Wallet not loaded yet" placeholder).
+
+### 2.2 Deep Links (Scheme: `stellar-pocketpay://`)
+
+Configured in `app.json` → `scheme: "stellar-pocketpay"`. Currently 5 deep-link targets are supported because Expo Router maps file paths 1:1 to scheme paths:
+
+| Deep link                           | Resolves to                        | Prerequisite                          |
+| ----------------------------------- | ---------------------------------- | ------------------------------------- |
+| `stellar-pocketpay:///`             | Home (if wallet) or auth (if not)  | —                                     |
+| `stellar-pocketpay:///send?destination=G…` | Prefilled Send form          | `destination` must be valid strkey    |
+| `stellar-pocketpay:///receive`      | Receive screen                     | wallet loaded                         |
+| `stellar-pocketpay:///transaction/tx-123` | Transaction detail          | wallet loaded; tx-123 must exist in store |
+| `stellar-pocketpay:///vault-lock/4` | Single lock detail view           | wallet loaded + id 4 in vaultStore.locks |
+
+---
+
+## 3. Feature Boundaries & Ownership Grid
+
+This is the most important section for contributors. If you are working on *feature X*, the "OWNED BY" columns tell you which files to edit and which you should touch only via exported actions/hooks.
+
+**Legend:**
+
+- 🟢 **Primary — edit here first.** The file owns the logic/UI for this feature.
+- 🟡 **Secondary — read-only / call via exported hooks/actions.** Depend on this, do not modify unless the feature needs a new capability.
+- 🔗 **Deep dependency — rarely need to modify.** Core layout/shell, shared types, shared components.
+- 🚫 **Never modify for this feature.** Would break invariants.
+
+### 3.1 Ownership Grid (7 Feature Areas)
+
+| Feature Area             | UI Entry: File(s) 🟢                                        | Hooks / Feature Logic 🟢                                   | Store Owner 🟢                                                | Service Layer 🟡                                              | Shared Components 🟡 |
+| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------- |
+| **1. Wallet Lifecycle**  | `(auth)/create.tsx` `(auth)/import.tsx` `(tabs)/settings.tsx Wallet section` | — (inline orchestration in screen; import logic helper `parseStoredSecret` in store) | [store/walletStore.ts](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/src/store/walletStore.ts) — create/import/export/clear, backup reminders | [services/stellar.ts](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/src/services/stellar.ts#L17-L24) — `generateKeypair`, `validateSecretKey`; also SecureStore via store | SecretKeyReveal, WalletResetConfirmModal, BackupReminderModal |
+| **2. Balance / History** | `(tabs)/index.tsx` (Top 5 + Balance card) `(tabs)/history.tsx` `transaction/[id].tsx` | Pagination inside walletStore actions; pull-to-refresh inline | walletStore → balance, transactions[], nextCursor, isLoadingMore | stellar.ts → fetchXlmBalance, fetchTransactionsPage, getExplorerTxUrl | TransactionListItem, EmptyState, NetworkStatusBanner |
+| **3. Send / Receive**    | `send.tsx` `receive.tsx` `review-transaction.tsx` `payment-success.tsx` `scan.tsx` | **[hooks/useSignerHandoff.ts](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/src/hooks/useSignerHandoff.ts)** — 8-phase orchestrator; validation.ts pure funcs | walletStore (getSecretKey, refresh after send), **[store/signerStore.ts](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/src/store/signerStore.ts)** — handoff phases, lastResult | stellar.ts → sendXlmTransaction, fetchBaseFee; signer.ts → LocalSigner; pocketpay-sdk → validatePublicKey | QrScanner, FundButton, SigningConfirmModal, PaymentErrorBanner, DirtyFormConfirm |
+| **4. QR / Scanner**      | `scan.tsx` `receive.tsx` (QR render)                        | — (inline Expo Camera barcode callbacks)                   | walletStore publicKey read only                              | —                                                            | **QrScanner** (component)  + react-native-qrcode-svg lib |
+| **5. Address Book**      | `contacts.tsx` + Send form contact picker flow              | dedup helpers in `utils/contacts.ts`                       | [store/appStore.ts](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/src/store/appStore.ts) → contacts[] + addContactIfUnique + removeContact | — (persists via AsyncStorage inside appStore actions)        | FormField, ConfirmModal     |
+| **6. Vault**             | `(tabs)/vault.tsx` `vault/[id].tsx` `vault-lock/[id].tsx`   | **[features/vault/](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/src/features/vault)** — maturedLockWithdrawal, useMaturedLockWithdrawal, useVaultDepositForm, useVault | **[store/vaultStore.ts](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/src/store/vaultStore.ts)** — balance, locks[], isConfigured | **[services/vault.ts](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/src/services/vault.ts)** — Soroban RPC calls; stellar.ts — mock fallbacks | All Vault* Modal & List components (MaturedLockWithdrawalModal, VaultIntroModal, LockDurationSelector, …) |
+| **7. Settings / Network / Theme / AppLock** | `(tabs)/settings.tsx` `diagnostics.tsx`             | **NEW:** [features/settings/useNetworkEnvironment.ts](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/src/features/settings/useNetworkEnvironment.ts) (Network tier, hostname mask, warnings); [hooks/useTheme.ts](file:///c:/Users/Muhammad/.trae/Grantfox/pocketpay-mobile/src/hooks/useTheme.ts) | appStore (theme, init), walletStore (secret export, clear), appLockStore (lock flag, biometrics authenticateAsync), vaultStore (locks purge, intro reset) | stellar.ts/vault.ts read only (isVaultConfigured); AsyncStorage + SecureStore via stores | AsyncActionButton, ConfirmModal, LockScreen |
+
+### 3.2 Cross-Feature Boundary Rules (Hard Invariants)
+
+1. **No screen imports a `services/` module directly.** Always go through the owning store/hook. The single exception today is `getExplorerTxUrl()` (pure string formatter — may be relaxed).
+2. **No store imports another store.** If store A needs store B's data, read it inline inside the screen/hook with two separate `useXxxStore(…)` calls and combine locally.
+3. **`features/` modules never import from `app/` (screens).** Features are pure logic + hooks; dependency arrow must point from app→features, never reverse.
+4. **`components/` never import a store.** Always pass props/callbacks from the screen. This keeps the 36-component library portable.
+
+---
+
+## 4. End-to-End Payment Flow — Navigation Path (Send → Review → Success)
+
+Contributor onboarding reference: every step along the send/receive user journey with navigation events marked.
+
+```
+ USER ACTIONS                  FILES / NAV EVENTS
+ ─────────────────             ─────────────────────────────────────────────────────────────────
+ ▼ Taps [Send XLM]             Home (index.tsx) → router.push('/send')
+   on Home tile
+ │
+ ▼ Enters: dest + amount +     /send.tsx
+   memo. [Scan] also ok →        ├─ Validates address, amount, memo (inline)
+   prefills dest                  └─ All pass? → router.push('/review-transaction?dest=...&amt=...&memo=...')
+ │
+ ▼ Review screen renders:      /review-transaction.tsx
+   amount + fee + dest + memo    ├─ signerStore.startReview() → phase = 'review'
+   "Sign & Send" CTA             ├─ USER TAPS [Sign & Send]
+ │                                │   ├─ useSignerHandoff.initiateSigning()
+ │                                │   └─ phases: handoff → signing → submitting → completed
+ │                                │         └─ service call: stellar.sendXlmTransaction
+ │                                │
+ │                                └─ phase==='completed' → setTimeout 1500ms →
+ │                                                                 router.replace('/payment-success?hash=...')
+ ▼ "Payment successful" +       /payment-success.tsx
+   hash + explorer link          └─ [Back to Home] → router.replace('/(tabs)')
+                                                                  │
+ User is back on Home.           └─ walletStore.refreshWalletData(publicKey) has fired automatically
+                                     → new balance visible, top of Activity shows the new row
+```
+
+**Why `replace` instead of `push` here?** If `payment-success` used `push`, the user could tap "Back" on the OS and land on Review Transaction *again*, with a stale amount already pre-signed and the Sign button still clickable — an invite for double-spend UX bugs. `replace` cleans the stack.
+
+---
+
+## 5. Route Assumptions & Adding New Routes
+
+When you add a new route under `app/`, these assumptions are baked into the current architecture — **you are opting in to all of them** unless you explicitly modify the root layout or create a new route group.
+
+### 5.1 Assumption A — Every route gets the 3 safety wrappers automatically
+
+Every file under `app/` (including new ones you add) inherits, top-down:
+
+1. **Polyfills loaded FIRST** via `shim.js` at `app/_layout.tsx:1` (Buffer, process, crypto.getRandomValues). If you add a new screen that imports StellarSdk before root renders (don't), it will throw.
+2. **`ErrorBoundary` → `ErrorBoundaryFallback`** on render exceptions. (No partial crashes.)
+3. **`GestureHandlerRootView`** → if your screen uses swipeable rows, gesture handlers work without re-wrapping.
+4. **App Lock gate (`LockScreen` wrapper around `<Slot/>`)** — if `appLockStore.isLockEnabled && !isAuthenticated`, the screen is hidden behind biometrics regardless of how the user arrived (deep link, OS relaunch, or push notification).
+5. **`NetworkStatusBanner` / `OfflineBanner`** — in `(tabs)/` sub-layout, banners render. Outside `(tabs)/`, you may need to include it yourself if offline behavior matters for the new screen.
+
+### 5.2 Assumption B — Auth redirection gate runs for EVERY route, not just group roots
+
+The `useEffect` in `app/_layout.tsx` (lines 46–66) redirects to `/(auth)` or `/(tabs)` based on:
+
+- `appStore.isInitialized === true` AND
+- `walletStore.walletChecked === true`
+
+**If you add a new route in a new group, e.g. `(payments)/something.tsx`**, the root layout still knows nothing about it and will redirect based on the same two rules. If your new group is **meant to be reachable without a wallet** (e.g. a marketing onboarding flow), move it inside `(auth)/` — the gate redirects *any* wallet-absent route into the `(auth)` group.
+
+### 5.3 Assumption C — Deep links always work (file path = URL)
+
+Because we use `scheme: "stellar-pocketpay"` and Expo Router's filesystem-routing 1:1 mapping, any new file `/app/foo/bar.tsx` will instantly be reachable via `stellar-pocketpay:///foo/bar`.
+
+**Secure your new routes the same way the existing ones are.** Example safe patterns:
+
+- Dynamic routes `/transaction/:id` and `/vault-lock/:id` should check `publicKey` on mount and redirect to `/(auth)` when missing (never render a partial screen with empty on-chain data).
+- If the parameter references a non-existent ID (user hand-edited the scheme URL), show a user-friendly "Transaction not found" state inside the dynamic screen — not a crash.
+
+### 5.4 Assumption D — The `(tabs)` root and `(auth)` root both mount at `/`
+
+Two files are both named `index.tsx` inside different route groups: `(auth)/index.tsx` and `(tabs)/index.tsx`. **Only one renders at a time**, decided by the root redirect gate.
+
+This means:
+
+- ❌ Do NOT add a top-level `app/index.tsx` alongside the two group index files — it will win the routing ambiguity and break the gate.
+- ✅ When you want to add a *new unauthenticated screen*, always add it inside `(auth)/` as a sibling of `create.tsx`.
+- ✅ When you want to add a *new authenticated tab* (e.g. `explore`), add it inside `(tabs)/` AND add its tab entry in `(tabs)/_layout.tsx` tabs config.
+
+---
+
+## 6. Cross-Reference — Other Docs Related to Navigation & Features
+
+This document is one of several contributor references in `docs/`.
+
+| Document                                                     | What It Covers / Cross-Reference |
+| ------------------------------------------------------------ | --------------------------------- |
+| [screen-inventory.md](./screen-inventory.md)                 | Per-screen UI state catalog (loading / empty / error / …). Complementary to this nav map: use it after you've found the right file. |
+| [user-flows.md](./user-flows.md)                             | 9 detailed diagrams of user journeys, including onboarding, send, vault lock maturity. Read this before editing a flow you haven't touched. |
+| [signer-handoff-design.md](./signer-handoff-design.md)       | The 8-phase signer state machine's original design rationale, external signer/hardware wallet roadmap. |
+| [vault-integration-assumptions.md](./vault-integration-assumptions.md) | Contract addresses, test accounts, mock-vs-real switch. Required context before modifying `/vault`, `/vault/:id`, or `/vault-lock/:id`. |
+| [release-testing-checklist.md](./release-testing-checklist.md) | Manual QA that re-traces every route above. If you change a route or add a new one, **you MUST add corresponding boxes to this checklist.** |
+| [accessibility.md](./accessibility.md)                       | A11y labels, touch targets, focus order, announcements — apply to *every* new route you add. |
+| [contacts.md](./contacts.md)                                 | Address book duplicate rules, data model, expected edge cases — specific to `/contacts`. |
+| [qr-payment-requests.md](./qr-payment-requests.md)           | QR format / BIP-21 style prefix plans, future extensions — specific to `/receive` + `/scan`. |
+
+---
+
+## 7. Quick Finder — "I Need To Change … Where?"
+
+Contributor cheat sheet. If you're about to make one of these common changes, open the left file first.
+
+| Change Goal                                                  | Open This First 🎯                                             | Also Check                                                   |
+| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| Add a new bottom-tab screen                                  | `(tabs)/_layout.tsx` → add Tabs.Screen entry, then create the file | root auth gate in `_layout.tsx` if it needs special auth rules |
+| Add a new pre-auth onboarding step                           | Add under `(auth)/` as a sibling of `create.tsx`, register in `(auth)/_layout.tsx` stack | release-testing-checklist §2 wallet flows                   |
+| Change the "what screen after sign-in / after sign-out" rule | Auth gate in `app/_layout.tsx` lines 46–66                    | LockScreen component for app-lock behavior                  |
+| Rename a route file                                          | 1) Rename the file; 2) Update every `router.push('/old-path')` site-wide (grep for the string); 3) Add a redirect or note the deep-link breakage | deep-link table §2.2 (changing file names breaks scheme URLs) |
+| Add a new Store slice (e.g. `nftStore`)                      | Create under `src/store/nftStore.ts`, follow slice pattern (no cross-store imports), initialize in its own module top scope. Never add to a single root combine store. | `shim.js` if new service/SDK requires an extra polyfill      |
+| Add a new feature section in Settings                        | `(tabs)/settings.tsx` as a new `<View>` section + new sub-constants in `features/settings/useNetworkEnvironment.ts` if env-derived | release-testing-checklist §7 Settings/Persistence           |
+| Add a new payment / signing path (e.g. MUXED account, XLM path with base64 memo) | `/send.tsx` validators + `review-transaction.tsx` + `stellar.ts` send helper; route navigation stays the same | signer-handoff-design.md, user-flows.md § send payment flow |

From b1507109092282be6c4001b4f9be04ba13e16a45 Mon Sep 17 00:00:00 2001
From: Muhammad-Al-amin <muhammadaminu2006@gmaail.com>
Date: Sun, 26 Jul 2026 00:37:38 +0100
Subject: [PATCH 4/4] feat(VaultEmptyState): add vault empty and loading state
 component

handle vault loading states while fetching balance and locks, display tailored empty state messages for both configured and unconfigured vaults, add deposit and learn more action buttons, and support mock/testnet warning messaging
---
 app/(tabs)/vault.tsx               |  72 ++++-----
 src/components/VaultEmptyState.tsx | 236 +++++++++++++++++++++++++++++
 2 files changed, 263 insertions(+), 45 deletions(-)
 create mode 100644 src/components/VaultEmptyState.tsx

diff --git a/app/(tabs)/vault.tsx b/app/(tabs)/vault.tsx
index 0df3d10..5d933a6 100644
--- a/app/(tabs)/vault.tsx
+++ b/app/(tabs)/vault.tsx
@@ -5,6 +5,7 @@ import { VaultLockList } from '../../src/components/VaultLockList';
 import { VaultConfirmModal } from '../../src/components/VaultConfirmModal';
 import { VaultIntroModal } from '../../src/components/VaultIntroModal';
 import { VaultLockEducationModal } from '../../src/components/VaultLockEducationModal';
+import { VaultEmptyState } from '../../src/components/VaultEmptyState';
 import { Input } from '../../src/components/Input';
 import { AsyncActionButton } from '../../src/components/AsyncActionButton';
 import { SIZES, RADIUS, ThemeColors } from '../../src/constants/theme';
@@ -59,6 +60,10 @@ export default function VaultScreen() {
   const isVaultUnavailable = !publicKey;
   const isMissingContractId = isVaultUnavailable && !isConfigured;
   const isMissingRpcUrl = false; // For now, default to testnet RPC
+  const hasBalance = !isLoadingBalance && parseFloat(balance) > 0;
+  const hasLocks = !isLoadingLocks && locks.length > 0;
+  const hasError = Boolean(balanceError);
+  const isEmpty = !isVaultUnavailable && !hasBalance && !hasLocks && !hasError;
 
   // Initial setup
   useEffect(() => {
@@ -281,6 +286,16 @@ export default function VaultScreen() {
             See docs/vault-ui-guidance.md for more information.
           </Text>
         </View>
+      ) : isEmpty ? (
+        <VaultEmptyState
+          isConfigured={isConfigured}
+          isLoadingBalance={isLoadingBalance}
+          isLoadingLocks={isLoadingLocks}
+          isMock={!isConfigured}
+          onDeposit={() => handleAction('deposit')}
+          onLearnMore={() => setIntroVisible(true)}
+          isSubmittingDeposit={depositForm.isSubmitting || (isSubmitting && pendingAction === 'deposit')}
+        />
       ) : (
         <View style={styles.form}>
           <Input
@@ -320,21 +335,14 @@ export default function VaultScreen() {
             disabled={isSubmitting || depositForm.isSubmitting}
             style={styles.lockButton}
           />
-          <View style={styles.mockLockSection}>
-            <Text style={styles.mockLockTitle}>Mock Active Locks</Text>
-            <TouchableOpacity 
-              style={styles.mockLockItem}
-              onPress={() => router.push('/vault-lock/mock-id-123')}
-            >
-              <View>
-                <Text style={styles.mockLockAmount}>500.0000000 XLM</Text>
-                <Text style={styles.mockLockSubtitle}>Locked • Matures in 15 days</Text>
-              </View>
-              <View style={styles.mockLockBadge}>
-                 <Text style={styles.mockLockBadgeText}>VIEW</Text>
-              </View>
-            </TouchableOpacity>
-          </View>
+          {locks.length === 0 ? (
+            <View style={styles.mockLockSection}>
+              <Text style={styles.mockLockTitle}>No active locks yet</Text>
+              <Text style={styles.mockLockHint}>
+                Use "Set Aside for 30 Days" above to create a time-locked deposit.
+              </Text>
+            </View>
+          ) : null}
         </View>
       )}
     </ScrollView>
@@ -465,40 +473,14 @@ const createStyles = (colors: ThemeColors) => StyleSheet.create({
     color: colors.textSecondary,
     fontSize: 14,
     fontWeight: '500',
-    marginBottom: SIZES.md,
+    marginBottom: SIZES.xs,
     textTransform: 'uppercase',
     letterSpacing: 1,
   },
-  mockLockItem: {
-    backgroundColor: colors.surface,
-    padding: SIZES.md,
-    borderRadius: RADIUS.md,
-    borderWidth: 1,
-    borderColor: colors.border,
-    flexDirection: 'row',
-    alignItems: 'center',
-    justifyContent: 'space-between',
-  },
-  mockLockAmount: {
-    color: colors.textPrimary,
-    fontSize: 16,
-    fontWeight: 'bold',
-  },
-  mockLockSubtitle: {
+  mockLockHint: {
     color: colors.textMuted,
-    fontSize: 12,
-    marginTop: 4,
-  },
-  mockLockBadge: {
-    backgroundColor: 'rgba(255, 196, 0, 0.1)',
-    paddingHorizontal: SIZES.sm,
-    paddingVertical: 4,
-    borderRadius: RADIUS.full,
-  },
-  mockLockBadgeText: {
-    color: colors.warning,
-    fontSize: 12,
-    fontWeight: '600',
+    fontSize: 13,
+    lineHeight: 18,
   },
   unavailableCard: {
     backgroundColor: colors.surface,
diff --git a/src/components/VaultEmptyState.tsx b/src/components/VaultEmptyState.tsx
new file mode 100644
index 0000000..de33e83
--- /dev/null
+++ b/src/components/VaultEmptyState.tsx
@@ -0,0 +1,236 @@
+import React, { useMemo } from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { PiggyBank, Lock, ArrowRightCircle, HelpCircle, Sparkles } from 'lucide-react-native';
+import { SIZES, RADIUS, ThemeColors } from '../constants/theme';
+import { useTheme } from '../hooks/useTheme';
+import { EmptyState } from './EmptyState';
+import { AsyncActionButton } from './AsyncActionButton';
+
+export interface VaultEmptyStateProps {
+  isConfigured: boolean;
+  isLoadingBalance: boolean;
+  isLoadingLocks: boolean;
+  onDeposit: () => void;
+  onLearnMore: () => void;
+  isSubmittingDeposit?: boolean;
+  /** Honest-feature-readiness override for the warning tone of the secondary message. True shows a stronger
+   *  Testnet / mock caveat sentence rather than a "safe" savings pitch. */
+  isMock?: boolean;
+}
+
+export const VaultEmptyState: React.FC<VaultEmptyStateProps> = ({
+  isConfigured,
+  isLoadingBalance,
+  isLoadingLocks,
+  onDeposit,
+  onLearnMore,
+  isSubmittingDeposit = false,
+  isMock = true,
+}) => {
+  const { colors } = useTheme();
+  const styles = useMemo(() => createStyles(colors), [colors]);
+
+  if (isLoadingBalance || isLoadingLocks) {
+    return (
+      <EmptyState
+        icon={<PiggyBank color={colors.textMuted} size={48} />}
+        title="Loading your vault"
+        message="Reading balance and any active locks. This should only take a moment."
+      />
+    );
+  }
+
+  const title = isConfigured
+    ? 'Your vault is ready to use'
+    : 'Set aside XLM in the vault';
+
+  const message = isConfigured
+    ? "Deposit funds from your wallet to start saving, or create a time-lock to keep funds untouched until a future date."
+    : "Deposit funds from your wallet to start saving. When a contract isn't configured, all actions run in preview mode — no real on-chain transactions are submitted yet.";
+
+  const featureNote = isMock
+    ? 'Currently in preview: Testnet balances and mock locks only.'
+    : undefined;
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.iconWrapperOuter}>
+        <View style={styles.iconRing}>
+          <PiggyBank color={colors.primary} size={40} />
+        </View>
+        <View style={[styles.badge, isConfigured ? styles.badgeReal : styles.badgeMock]}>
+          {isConfigured ? (
+            <Sparkles color={colors.primary} size={14} />
+          ) : (
+            <HelpCircle color={colors.warning} size={14} />
+          )}
+        </View>
+      </View>
+
+      <Text style={styles.title}>{title}</Text>
+      <Text style={styles.message}>{message}</Text>
+
+      <View style={styles.features}>
+        <View style={styles.featureRow}>
+          <View style={[styles.featureIcon, { backgroundColor: 'rgba(0, 229, 255, 0.12)' }]}>
+            <ArrowRightCircle color={colors.primary} size={18} />
+          </View>
+          <View style={styles.featureText}>
+            <Text style={styles.featureTitle}>Deposit from your wallet</Text>
+            <Text style={styles.featureBody}>
+              Move XLM into the vault whenever you want to separate savings from spending.
+            </Text>
+          </View>
+        </View>
+
+        <View style={styles.featureRow}>
+          <View style={[styles.featureIcon, { backgroundColor: 'rgba(123, 97, 255, 0.12)' }]}>
+            <Lock color={colors.secondary} size={18} />
+          </View>
+          <View style={styles.featureText}>
+            <Text style={styles.featureTitle}>Lock funds for later</Text>
+            <Text style={styles.featureBody}>
+              Create a time-lock and the funds cannot be withdrawn until the unlock date has passed.
+            </Text>
+          </View>
+        </View>
+      </View>
+
+      {featureNote ? (
+        <View style={styles.note}>
+          <Text style={styles.noteText}>{featureNote}</Text>
+        </View>
+      ) : null}
+
+      <View style={styles.actions}>
+        <AsyncActionButton
+          title="Make your first deposit"
+          onPress={onDeposit}
+          isLoading={isSubmittingDeposit}
+          loadingText="Preparing deposit…"
+          style={styles.primaryButton}
+        />
+        <AsyncActionButton
+          title="Learn more about the vault"
+          variant="outline"
+          onPress={onLearnMore}
+          style={styles.secondaryButton}
+        />
+      </View>
+    </View>
+  );
+};
+
+const createStyles = (colors: ThemeColors) =>
+  StyleSheet.create({
+    container: {
+      backgroundColor: colors.surface,
+      borderRadius: RADIUS.lg,
+      borderWidth: 1,
+      borderColor: colors.border,
+      padding: SIZES.xl,
+      alignItems: 'center',
+      marginBottom: SIZES.lg,
+    },
+    iconWrapperOuter: {
+      position: 'relative',
+      marginBottom: SIZES.lg,
+    },
+    iconRing: {
+      width: 88,
+      height: 88,
+      borderRadius: 44,
+      justifyContent: 'center',
+      alignItems: 'center',
+      backgroundColor: 'rgba(0, 229, 255, 0.10)',
+      borderWidth: 2,
+      borderColor: 'rgba(0, 229, 255, 0.20)',
+    },
+    badge: {
+      position: 'absolute',
+      right: -4,
+      bottom: -4,
+      width: 28,
+      height: 28,
+      borderRadius: 14,
+      alignItems: 'center',
+      justifyContent: 'center',
+      borderWidth: 2,
+      borderColor: colors.surface,
+    },
+    badgeReal: {
+      backgroundColor: 'rgba(0, 230, 118, 0.15)',
+    },
+    badgeMock: {
+      backgroundColor: 'rgba(255, 196, 0, 0.18)',
+    },
+    title: {
+      color: colors.textPrimary,
+      fontSize: 20,
+      fontWeight: 'bold',
+      textAlign: 'center',
+      marginBottom: SIZES.sm,
+    },
+    message: {
+      color: colors.textSecondary,
+      fontSize: 14,
+      textAlign: 'center',
+      lineHeight: 20,
+      marginBottom: SIZES.lg,
+      paddingHorizontal: SIZES.xs,
+    },
+    features: {
+      width: '100%',
+      marginBottom: SIZES.lg,
+    },
+    featureRow: {
+      flexDirection: 'row',
+      alignItems: 'flex-start',
+      paddingVertical: SIZES.sm,
+    },
+    featureIcon: {
+      width: 36,
+      height: 36,
+      borderRadius: 18,
+      justifyContent: 'center',
+      alignItems: 'center',
+      marginRight: SIZES.md,
+      marginTop: 2,
+    },
+    featureText: { flex: 1 },
+    featureTitle: {
+      color: colors.textPrimary,
+      fontSize: 15,
+      fontWeight: '600',
+      marginBottom: 2,
+    },
+    featureBody: {
+      color: colors.textSecondary,
+      fontSize: 13,
+      lineHeight: 18,
+    },
+    note: {
+      width: '100%',
+      backgroundColor: 'rgba(255, 196, 0, 0.1)',
+      paddingHorizontal: SIZES.md,
+      paddingVertical: SIZES.sm,
+      borderRadius: RADIUS.md,
+      marginBottom: SIZES.lg,
+    },
+    noteText: {
+      color: colors.warning,
+      fontSize: 12,
+      lineHeight: 18,
+      textAlign: 'center',
+    },
+    actions: {
+      width: '100%',
+    },
+    primaryButton: {
+      width: '100%',
+      marginBottom: SIZES.sm,
+    },
+    secondaryButton: {
+      width: '100%',
+    },
+  });