Merge pull request #65 from spiffamani/feat/balance-warning

feat(wallet): add insufficient balance warning before tx submission

Author: johdanike

features/escrow/components/BalanceCheck.tsx

@@ -0,0 +1,145 @@
+'use client';
+
+import React from 'react';
+import { useWalletStore } from '@/store/walletStore';
+import { useWalletBalance } from '@/hooks/useWalletBalance';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface BalanceCheckProps {
+  /** Total XLM required for this transaction (escrow amount + estimated fee). */
+  requiredAmount: number;
+  /** Called when the user confirms and submits the transaction. */
+  onSubmit: () => void;
+  /** Optional label for the submit button. Defaults to "Confirm & Lock Escrow". */
+  submitLabel?: string;
+  /** Whether the parent form has additional validation errors that block submit. */
+  isFormInvalid?: boolean;
+}
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
+/**
+ * BalanceCheck — queries wallet balance before an escrow lock and renders a
+ * warning when the balance is insufficient.  The submit button is disabled
+ * only when the balance is *definitively* too low.
+ *
+ * Follows the Component → Hook → Service layered architecture:
+ *   BalanceCheck → useWalletBalance → walletService
+ */
+export function BalanceCheck({
+  requiredAmount,
+  onSubmit,
+  submitLabel = 'Confirm & Lock Escrow',
+  isFormInvalid = false,
+}: BalanceCheckProps) {
+  const address = useWalletStore((state) => state.address);
+  const { balance, isLoading, error, isInsufficient, refresh } =
+    useWalletBalance(address);
+
+  const insufficient = isInsufficient(requiredAmount);
+
+  // The button is disabled only when the balance is definitively insufficient
+  // OR when the parent form has other blocking validation errors.
+  const isSubmitDisabled = insufficient || isFormInvalid;
+
+  return (
+    <div className="space-y-3">
+      {/* ── Balance display ───────────────────────────────────────────────── */}
+      <div className="rounded-lg border border-gray-200 bg-gray-50 px-4 py-3">
+        <div className="flex items-center justify-between">
+          <span className="text-sm font-medium text-gray-600">Wallet Balance</span>
+
+          {isLoading ? (
+            <span className="text-sm text-gray-400 animate-pulse">Fetching…</span>
+          ) : error ? (
+            <button
+              type="button"
+              onClick={refresh}
+              className="text-sm text-blue-600 hover:underline"
+            >
+              Retry
+            </button>
+          ) : balance !== null ? (
+            <span
+              className={`text-sm font-semibold ${
+                insufficient ? 'text-red-600' : 'text-green-600'
+              }`}
+            >
+              {balance.toFixed(7)} XLM
+            </span>
+          ) : null}
+        </div>
+
+        <div className="mt-1 flex items-center justify-between">
+          <span className="text-sm font-medium text-gray-600">Required</span>
+          <span className="text-sm font-semibold text-gray-800">
+            {requiredAmount.toFixed(7)} XLM
+          </span>
+        </div>
+      </div>
+
+      {/* ── Insufficient balance warning ──────────────────────────────────── */}
+      {insufficient && (
+        <div
+          role="alert"
+          aria-live="polite"
+          className="flex items-start gap-2 rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-red-700"
+        >
+          {/* Warning icon */}
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            className="mt-0.5 h-5 w-5 shrink-0 text-red-500"
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            aria-hidden="true"
+          >
+            <path
+              fillRule="evenodd"
+              d="M8.257 3.099c.765-1.36 2.722-1.36 3.486 0l5.58 9.92c.75 1.334-.213 2.98-1.742 2.98H4.42c-1.53 0-2.493-1.646-1.743-2.98l5.58-9.92zM11 13a1 1 0 11-2 0 1 1 0 012 0zm-1-8a1 1 0 00-1 1v3a1 1 0 002 0V6a1 1 0 00-1-1z"
+              clipRule="evenodd"
+            />
+          </svg>
+
+          <div className="text-sm">
+            <p className="font-semibold">Insufficient balance</p>
+            <p className="mt-0.5">
+              You need at least{' '}
+              <span className="font-medium">{requiredAmount.toFixed(7)} XLM</span> to
+              complete this transaction. Your current balance is{' '}
+              <span className="font-medium">{balance!.toFixed(7)} XLM</span>.
+            </p>
+            <p className="mt-1 text-xs text-red-600">
+              Please top up your wallet before proceeding.
+            </p>
+          </div>
+        </div>
+      )}
+
+      {/* ── Balance fetch error (non-blocking) ────────────────────────────── */}
+      {error && !isLoading && (
+        <p className="text-xs text-amber-600">
+          ⚠️ Could not verify balance — you may still proceed, but ensure you have
+          sufficient XLM.
+        </p>
+      )}
+
+      {/* ── Submit button ─────────────────────────────────────────────────── */}
+      <button
+        type="button"
+        onClick={onSubmit}
+        disabled={isSubmitDisabled}
+        aria-disabled={isSubmitDisabled}
+        className={`w-full rounded-lg px-4 py-3 text-sm font-semibold transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2 ${
+          isSubmitDisabled
+            ? 'cursor-not-allowed bg-gray-200 text-gray-400'
+            : 'bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500'
+        }`}
+      >
+        {isLoading ? 'Checking balance…' : submitLabel}
+      </button>
+    </div>
+  );
+}
+
+export default BalanceCheck;

hooks/useWalletBalance.ts

@@ -0,0 +1,82 @@
+import { useState, useEffect, useCallback } from 'react';
+import { walletService } from '@/services/walletService';
+
+export interface UseWalletBalanceResult {
+  /** Current XLM balance fetched from the backend. Null while loading or on error. */
+  balance: number | null;
+  /** True while the balance request is in-flight. */
+  isLoading: boolean;
+  /** Error message if the request failed, otherwise null. */
+  error: string | null;
+  /**
+   * Returns true when the balance is definitively known to be insufficient.
+   * False when balance is null (still loading / unknown) — never blocks on uncertainty.
+   */
+  isInsufficient: (requiredAmount: number) => boolean;
+  /** Manually re-fetch the balance. */
+  refresh: () => void;
+}
+
+/**
+ * useWalletBalance — fetches the XLM balance for the connected wallet.
+ *
+ * Follows the Component → Hook → Service pattern:
+ *   BalanceCheck (component) → useWalletBalance (hook) → walletService (service)
+ *
+ * The submit button must only be disabled when the balance is *definitively*
+ * lower than required — never when the balance is still loading or unknown.
+ */
+export function useWalletBalance(address: string | null): UseWalletBalanceResult {
+  const [balance, setBalance] = useState<number | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchBalance = useCallback(async () => {
+    if (!address) {
+      setBalance(null);
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    try {
+      const response = await walletService.getBalance(address);
+      if (response.success) {
+        setBalance(response.balance);
+      } else {
+        setError(response.message ?? 'Failed to fetch wallet balance');
+        setBalance(null);
+      }
+    } catch (err: any) {
+      setError(
+        err.response?.data?.message ?? 'An error occurred while fetching your balance'
+      );
+      setBalance(null);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [address]);
+
+  useEffect(() => {
+    fetchBalance();
+  }, [fetchBalance]);
+
+  const isInsufficient = useCallback(
+    (requiredAmount: number): boolean => {
+      // Only block when balance is definitively known and too low.
+      // When balance is null (loading or error) we do NOT block — uncertainty ≠ insufficient.
+      if (balance === null) return false;
+      return balance < requiredAmount;
+    },
+    [balance]
+  );
+
+  return {
+    balance,
+    isLoading,
+    error,
+    isInsufficient,
+    refresh: fetchBalance,
+  };
+}

services/walletService.ts

@@ -7,6 +7,12 @@ export interface DisconnectResponse {
   message: string;
 }
 
+export interface BalanceResponse {
+  success: boolean;
+  balance: number;   // XLM balance as a number
+  message?: string;
+}
+
 /**
  * walletService — responsible for all wallet-related API communication.
  * The hook calls this; components never call this directly.
@@ -18,4 +24,16 @@ export const walletService = {
     );
     return data;
   },
-};
+
+  /**
+   * Fetch the XLM balance for the given wallet address from the backend.
+   * The backend is the single source of truth — no Stellar SDK calls in the browser.
+   */
+  async getBalance(address: string): Promise<BalanceResponse> {
+    const { data } = await axios.get<BalanceResponse>(
+      `${API_BASE_URL}/api/wallet/balance`,
+      { params: { address } }
+    );
+    return data;
+  },
+};