Stable Balance

.gitignore

@@ -1,4 +1,5 @@
 node_modules/
+.claude/settings.local.json
 .env
 .env.*
 dist/

package.json

@@ -16,7 +16,7 @@
     "test:e2e:debug": "playwright test --debug"
   },
   "dependencies": {
-    "@breeztech/breez-sdk-spark": "^0.11.0-dev4",
+    "@breeztech/breez-sdk-spark": "file:vendor/breez-sdk-spark.tgz",
     "@headlessui/react": "^1.7.17",
     "@zxing/browser": "^0.1.5",
     "@zxing/library": "^0.21.3",

src/App.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useCallback } from 'react';
+import React, { useState, useEffect, useCallback, useRef } from 'react';
 import { WalletProvider } from './contexts/WalletContext';
 import LoadingSpinner from './components/LoadingSpinner';
 import PaymentReceivedCelebration from './components/PaymentReceivedCelebration';
@@ -7,6 +7,8 @@ import StagingGate from './components/StagingGate';
 import { ToastProvider, useToast } from './contexts/ToastContext';
 import AppShell from './components/layout/AppShell';
 import { useBreezSdk } from './hooks/useBreezSdk';
+import { FiatDataProvider } from './contexts/FiatDataContext';
+import { StableBalanceProvider, useStableBalance } from './contexts/StableBalanceContext';
 
 import HomePage from './pages/HomePage';
 import WalletPage from './pages/WalletPage';
@@ -18,19 +20,29 @@ import PasskeyPage from './pages/PasskeyPage';
 import SettingsPage from './pages/SettingsPage';
 import FiatCurrenciesPage from './pages/FiatCurrenciesPage';
 import { useIOSViewportFix } from './hooks/useIOSViewportFix';
-import type { Seed } from '@breeztech/breez-sdk-spark';
+import type { Seed, Payment } from '@breeztech/breez-sdk-spark';
 
 type Screen = 'home' | 'restore' | 'generate' | 'wallet' | 'getRefund' | 'settings' | 'backup' | 'fiatCurrencies' | 'passkey';
 
+// Bridge component that feeds StableBalance formatter back to useBreezSdk via a mutable ref
+const StableBalanceFormatterBridge: React.FC<{ formatterRef: React.MutableRefObject<((payment: Payment) => string) | undefined> }> = ({ formatterRef }) => {
+  const stableBalance = useStableBalance();
+  useEffect(() => {
+    formatterRef.current = stableBalance.formatPaymentAmount;
+  }, [formatterRef, stableBalance.formatPaymentAmount]);
+  return null;
+};
+
 const AppContent: React.FC = () => {
   const [currentScreen, setCurrentScreen] = useState<Screen>('home');
   const [refundAnimationDirection, setRefundAnimationDirection] = useState<'left' | 'up'>('left');
   const [passkeySdkConnected, setPasskeySdkConnected] = useState(false);
   const { showToast } = useToast();
+  const formatPaymentAmountRef = useRef<((payment: Payment) => string) | undefined>(undefined);
 
   useIOSViewportFix();
 
-  const sdk = useBreezSdk(showToast);
+  const sdk = useBreezSdk(showToast, formatPaymentAmountRef);
 
   // Auto-navigate to wallet when SDK reconnects from saved mnemonic
   useEffect(() => {
@@ -162,8 +174,6 @@ const AppContent: React.FC = () => {
             walletInfo={sdk.walletInfo}
             transactions={sdk.transactions}
             unclaimedDeposits={sdk.unclaimedDeposits}
-            fiatRates={sdk.fiatRates}
-            fiatCurrencies={sdk.fiatCurrencies}
             refreshWalletData={sdk.refreshWalletData}
             isSyncing={sdk.isSyncing}
             error={sdk.error}
@@ -187,15 +197,20 @@ const AppContent: React.FC = () => {
   };
 
   return (
-    <WalletProvider client={sdk.sdk}>
-      {renderCurrentScreen()}
-      {sdk.celebrationAmount !== null && (
-        <PaymentReceivedCelebration
-          amount={sdk.celebrationAmount}
-          onClose={sdk.dismissCelebration}
-        />
-      )}
-      <InstallPrompt />
+    <WalletProvider client={sdk.sdk} isConnected={sdk.isConnected}>
+      <FiatDataProvider>
+        <StableBalanceProvider>
+          <StableBalanceFormatterBridge formatterRef={formatPaymentAmountRef} />
+          {renderCurrentScreen()}
+          {sdk.celebrationPayment !== null && (
+            <PaymentReceivedCelebration
+              payment={sdk.celebrationPayment}
+              onClose={sdk.dismissCelebration}
+            />
+          )}
+          <InstallPrompt />
+        </StableBalanceProvider>
+      </FiatDataProvider>
     </WalletProvider>
   );
 };

src/components/CollapsingWalletHeader.tsx

@@ -1,33 +1,45 @@
 import React, { useMemo, useState, useCallback, useRef, useEffect } from 'react';
-import type { GetInfoResponse, Rate, FiatCurrency } from '@breeztech/breez-sdk-spark';
+import type { GetInfoResponse, FiatCurrency } from '@breeztech/breez-sdk-spark';
 import { getFiatSettings } from '../services/settings';
 import { formatWithThinSpaces } from '../utils/formatNumber';
 import { useAnimatedNumber } from '../hooks/useAnimatedNumber';
+import { useStableBalance } from '../contexts/StableBalanceContext';
+import { useFiatData } from '../contexts/FiatDataContext';
+import { getTokenBalance, formatTokenAmount } from '../utils/tokenFormatting';
+import StableBalanceToggleFlow from './StableBalanceToggleFlow';
 
 interface CollapsingWalletHeaderProps {
   walletInfo: GetInfoResponse | null;
-  fiatRates: Rate[];
-  fiatCurrencies: FiatCurrency[];
   scrollProgress: number;
   onOpenMenu: () => void;
   onOpenBuyBitcoin?: () => void;
   isSyncing?: boolean;
+  refreshWalletData?: () => Promise<void>;
   hasRejectedDeposits?: boolean;
   onOpenGetRefund?: () => void;
 }
 
 const CollapsingWalletHeader: React.FC<CollapsingWalletHeaderProps> = ({
   walletInfo,
   scrollProgress,
-  fiatRates,
-  fiatCurrencies,
   onOpenMenu,
   onOpenBuyBitcoin,
   isSyncing,
+  refreshWalletData,
   hasRejectedDeposits,
   onOpenGetRefund,
 }) => {
+  const { fiatRates, fiatCurrencies } = useFiatData();
+  const stableBalance = useStableBalance();
   const [activeFiatIndex, setActiveFiatIndex] = useState(0);
+  const [toggleFlowOpen, setToggleFlowOpen] = useState(false);
+  const [toggleDirection, setToggleDirection] = useState<'toToken' | 'toBitcoin'>('toToken');
+
+  const handleSuffixTap = useCallback(() => {
+    if (stableBalance.isToggling) return;
+    setToggleDirection(stableBalance.isActive ? 'toBitcoin' : 'toToken');
+    setToggleFlowOpen(true);
+  }, [stableBalance]);
 
   // Build lookup maps for O(1) access (js-index-maps optimization)
   const ratesMap = useMemo(() => {
@@ -82,24 +94,37 @@ const CollapsingWalletHeader: React.FC<CollapsingWalletHeaderProps> = ({
     }
   }, [fiatCurrencyInfo.length]);
 
-  const balanceSat = walletInfo?.balanceSats || 0;
-
-  // Track when both balance and fiat are ready to trigger synced animation
-  const hasFiatData = fiatCurrencyInfo.length > 0;
+  // Compute balances
+  const btcBalanceSat = walletInfo?.balanceSats || 0;
+
+  const tokenBalanceInfo = useMemo(() => {
+    if (!stableBalance.isActive || !walletInfo?.tokenBalances || !stableBalance.tokenIdentifier) return null;
+    return getTokenBalance(walletInfo.tokenBalances, stableBalance.tokenIdentifier);
+  }, [stableBalance.isActive, walletInfo?.tokenBalances, stableBalance.tokenIdentifier]);
+
+  const tokenBalanceRaw = tokenBalanceInfo ? Number(tokenBalanceInfo.balance) : 0;
+
+  // Primary balance for animation (token base units or sats)
+  const primaryBalance = stableBalance.isActive ? tokenBalanceRaw : btcBalanceSat;
+
+  // Track when both balance and secondary data are ready to trigger synced animation
+  const hasSecondaryData = stableBalance.isActive
+    ? true
+    : fiatCurrencyInfo.length > 0;
   const [animationReady, setAnimationReady] = useState(false);
   const hasTriggeredAnimation = useRef(false);
-  
+
   useEffect(() => {
-    // Start animation only when BOTH balance and fiat are available
-    if (balanceSat > 0 && hasFiatData && !hasTriggeredAnimation.current) {
+    // Start animation only when BOTH balance and secondary data are available
+    if (primaryBalance > 0 && hasSecondaryData && !hasTriggeredAnimation.current) {
       hasTriggeredAnimation.current = true;
       setAnimationReady(true);
     }
-  }, [balanceSat, hasFiatData]);
-  
-  // Timeout fallback: if fiat doesn't load within 2s, animate balance anyway
+  }, [primaryBalance, hasSecondaryData]);
+
+  // Timeout fallback: if secondary data doesn't load within 2s, animate balance anyway
   useEffect(() => {
-    if (balanceSat > 0 && !hasTriggeredAnimation.current) {
+    if (primaryBalance > 0 && !hasTriggeredAnimation.current) {
       const timeout = setTimeout(() => {
         if (!hasTriggeredAnimation.current) {
           hasTriggeredAnimation.current = true;
@@ -108,34 +133,53 @@ const CollapsingWalletHeader: React.FC<CollapsingWalletHeaderProps> = ({
       }, 2000);
       return () => clearTimeout(timeout);
     }
-  }, [balanceSat]);
-  
+  }, [primaryBalance]);
+
   // Only animate from 80% when both are ready; otherwise show full value
   const animatedBalance = useAnimatedNumber(
-    animationReady ? balanceSat : 0,
+    animationReady ? primaryBalance : 0,
     { initialStartPercent: 0.8 }
   );
-  
+
   // Display: if animation started, use animated value; otherwise use actual balance
-  const displayBalance = animationReady ? animatedBalance : balanceSat;
+  const displayBalance = animationReady ? animatedBalance : primaryBalance;
 
   // Calculate current fiat value from display balance (so both animate together)
+  // Used only in non-stable-balance mode
   const currentFiat = useMemo(() => {
-    if (!hasFiatData || balanceSat === 0) return null;
-
+    if (stableBalance.isActive) return null;
+    if (!hasSecondaryData || btcBalanceSat === 0) return null;
+
     const info = fiatCurrencyInfo[activeFiatIndex % fiatCurrencyInfo.length];
     const btcValue = displayBalance / 100000000;
     const fiatValue = btcValue * info.rate;
-    
+
     return {
       ...info,
       value: fiatValue.toFixed(info.fractionSize),
     };
-  }, [fiatCurrencyInfo, activeFiatIndex, displayBalance, balanceSat, hasFiatData]);
+  }, [stableBalance.isActive, fiatCurrencyInfo, activeFiatIndex, displayBalance, btcBalanceSat, hasSecondaryData]);
+
+  // Stable balance secondary line
+  const stableSecondaryText = useMemo(() => {
+    if (!stableBalance.isActive) return null;
+    if (btcBalanceSat > 0) return `${formatWithThinSpaces(btcBalanceSat)} sats change`;
+    return null;
+  }, [stableBalance.isActive, tokenBalanceRaw, btcBalanceSat]);
 
   if (!walletInfo) return null;
 
+  // Format primary balance display
+  const formattedPrimaryBalance = stableBalance.isActive && stableBalance.displayConfig
+    ? formatTokenAmount(BigInt(displayBalance), stableBalance.displayConfig)
+    : formatWithThinSpaces(displayBalance);
+
+  const balanceSuffix = stableBalance.isActive ? 'USD' : 'sats';
+
+  const hasSecondaryLine = stableBalance.isActive ? !!stableSecondaryText : !!currentFiat;
+
   return (
+  <>
     <div className="relative overflow-hidden transition-all duration-200">
       {/* Glassmorphism background - extends into safe area */}
       <div
@@ -224,40 +268,54 @@ const CollapsingWalletHeader: React.FC<CollapsingWalletHeaderProps> = ({
                 isSyncing ? 'opacity-0' : 'opacity-100'
               }`}
             >
-              Balance<span className="text-spark-text-muted/50 mx-1.5">·</span><span className="text-spark-text-muted/50">sats</span>
+              Balance
+              <button
+                type="button"
+                onClick={handleSuffixTap}
+                disabled={stableBalance.isToggling}
+                className="inline-flex items-center cursor-pointer text-spark-text-muted/50 hover:text-spark-text-secondary transition-colors disabled:opacity-50 font-display text-xs font-medium tracking-widest uppercase"
+              >
+                <span className="mx-1.5">·</span>
+                <span className="px-1.5 py-0.5 rounded-full bg-white/5 hover:bg-white/10 active:scale-95 transition-all">{balanceSuffix}</span>
+              </button>
             </span>
           </div>
 
           {/* Main balance */}
-          <div 
-            className="inline-flex items-baseline justify-center" 
+          <div
+            className="inline-flex items-baseline justify-center"
             data-testid="wallet-balance"
           >
             <span className="balance-display">
-              {formatWithThinSpaces(displayBalance)}
+              {formattedPrimaryBalance}
             </span>
           </div>
 
-          {/* Fiat value with accent marks - always reserve space to prevent layout shift */}
+          {/* Secondary line - fiat value or BTC as fiat equivalent */}
           <div
             className={`mt-2 flex items-center justify-center gap-3 transition-opacity duration-200 ${
-              currentFiat ? 'opacity-100' : 'opacity-0'
-            } ${fiatCurrencyInfo.length > 1 ? 'cursor-pointer' : ''}`}
-            onClick={fiatCurrencyInfo.length > 1 ? handleFiatTap : undefined}
+              hasSecondaryLine ? 'opacity-100' : 'opacity-0'
+            } ${!stableBalance.isActive && fiatCurrencyInfo.length > 1 ? 'cursor-pointer' : ''}`}
+            onClick={!stableBalance.isActive && fiatCurrencyInfo.length > 1 ? handleFiatTap : undefined}
           >
             <span className="w-6 h-0.5 bg-spark-primary" style={{
               maskImage: 'linear-gradient(to right, transparent, black)',
               WebkitMaskImage: 'linear-gradient(to right, transparent, black)'
             }} />
             <span className="text-spark-text-secondary text-sm font-mono">
-              {currentFiat ? (
+              {stableBalance.isActive ? (
+                stableSecondaryText ? (
+                  <>{stableSecondaryText}</>
+                ) : (
+                  <span className="invisible">$0.00</span>
+                )
+              ) : currentFiat ? (
                 <>
                   {currentFiat.symbolPosition === 'before' ? currentFiat.symbol : ''}
                   {currentFiat.value}
                   {currentFiat.symbolPosition === 'after' ? ` ${currentFiat.symbol}` : ''}
                 </>
               ) : (
-                /* Invisible placeholder to reserve space */
                 <span className="invisible">$0.00</span>
               )}
             </span>
@@ -271,7 +329,16 @@ const CollapsingWalletHeader: React.FC<CollapsingWalletHeaderProps> = ({
         {/* Bottom spacing */}
         <div className="h-4" />
       </div>
+
     </div>
+
+    <StableBalanceToggleFlow
+      isOpen={toggleFlowOpen}
+      direction={toggleDirection}
+      onComplete={() => { refreshWalletData?.(); setToggleFlowOpen(false); }}
+      onCancel={() => setToggleFlowOpen(false)}
+    />
+  </>
   );
 };