Merge pull request #596 from Henrichy/main

feat(frontend): add Stellar transaction signing progress feedback

Author: KuchiMercy

.github/workflows/ci.yml

@@ -1,15 +1,37 @@
 name: CI
 on: [push, pull_request]
 jobs:
-  test:
+  frontend-build:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [18, 20, 22]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
-      - run: npm ci 2>/dev/null || npm install
-      - run: npm test 2>/dev/null || echo "Tests completed"
+          node-version: 20
+          cache: npm
+          cache-dependency-path: apps/frontend/package-lock.json
+      - name: Install dependencies
+        working-directory: apps/frontend
+        run: npm ci
+      - name: Build
+        working-directory: apps/frontend
+        run: npm run build
+
+  backend-test-and-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: apps/backend/package-lock.json
+      - name: Install dependencies
+        working-directory: apps/backend
+        run: npm ci
+      - name: Test
+        working-directory: apps/backend
+        run: npm test -- --runInBand
+      - name: Build
+        working-directory: apps/backend
+        run: npm run build

apps/frontend/components/escrow/modals/ReleaseFundsModal.test.tsx

@@ -3,6 +3,10 @@ import { render, screen, fireEvent, waitFor } from "@testing-library/react";
 import ReleaseFundsModal from "./ReleaseFundsModal";
 import { IEscrowExtended } from "@/types/escrow";
 
+jest.mock("next/navigation", () => ({
+  useRouter: () => ({ push: jest.fn() }),
+}));
+
 // Mock TransactionTracker to simplify tests
 jest.mock("@/components/stellar/TransactionTracker", () => {
   return () => <div data-testid="transaction-tracker">Transaction Tracker Mock</div>;

apps/frontend/components/escrow/modals/ReleaseFundsModal.tsx

@@ -1,6 +1,7 @@
 "use client";
 
-import React, { useMemo, useState } from "react";
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { useRouter } from "next/navigation";
 import {
   AlertTriangle,
   CheckCircle2,
@@ -13,6 +14,7 @@ import {
 } from "lucide-react";
 import { IEscrowExtended } from "@/types/escrow";
 import TransactionTracker from "@/components/stellar/TransactionTracker";
+import { toast } from "sonner";
 
 type ReleaseMode = "manual" | "auto";
 
@@ -28,9 +30,27 @@ interface ReleaseFundsModalProps {
 }
 
 type Step = "review" | "confirm" | "success";
+type SigningPhase = "idle" | "building" | "waiting" | "submitting" | "confirming" | "complete" | "timeout";
 
 const PLATFORM_FEE_BPS = 50;
 const BPS_DENOMINATOR = 10_000;
+const NETWORK_FEE = "0.00001 XLM";
+const SIGNING_TIMEOUT_MS = 60_000;
+
+const getReleaseError = (error: unknown): string => {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalized = message.toLowerCase();
+  if (normalized.includes("balance") || normalized.includes("underfunded")) {
+    return "Insufficient balance to release funds, including the network fee.";
+  }
+  if (normalized.includes("sequence") || normalized.includes("tx_bad_seq")) {
+    return "Your wallet sequence number is out of date. Refresh your wallet and try again.";
+  }
+  if (normalized.includes("fetch") || normalized.includes("network")) {
+    return "A network error prevented the transaction from being submitted.";
+  }
+  return message || "Failed to release funds. Please try again.";
+};
 
 export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
   isOpen,
@@ -42,6 +62,7 @@ export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
   publicKey,
   network = "testnet",
 }) => {
+  const router = useRouter();
   const existingTxHash =
     (escrow as any).releaseTransactionHash ??
     (escrow as any).onChainReleaseHash ??
@@ -57,6 +78,8 @@ export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [txHash, setTxHash] = useState<string | null>(existingTxHash ?? null);
+  const [signingPhase, setSigningPhase] = useState<SigningPhase>("idle");
+  const abortControllerRef = useRef<AbortController | null>(null);
 
   const sellerAddress =
     escrow.counterpartyAddress || (escrow as any).sellerAddress || "Unknown";
@@ -94,12 +117,33 @@ export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
   }, [escrow.amount, escrow.asset]);
 
   const handleClose = () => {
+    abortControllerRef.current?.abort();
     setError(null);
     setIsSubmitting(false);
+    setSigningPhase("idle");
     setStep(isAlreadyReleased ? "success" : "review");
     onClose();
   };
 
+  useEffect(() => {
+    if (step !== "success") return;
+    const timeoutId = window.setTimeout(() => {
+      onClose();
+      router.push(`/escrow/${escrow.id}`);
+    }, 3_000);
+    return () => window.clearTimeout(timeoutId);
+  }, [escrow.id, onClose, router, step]);
+
+  const signingLabel = {
+    idle: "",
+    building: "Building Transaction",
+    waiting: "Waiting for Wallet",
+    submitting: "Submitting",
+    confirming: "Confirming",
+    complete: "Complete",
+    timeout: "Timed Out",
+  }[signingPhase];
+
   const handlePrimaryAction = async () => {
     if (step === "review") {
       setStep("confirm");
@@ -114,13 +158,22 @@ export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
 
       setIsSubmitting(true);
       setError(null);
+      setSigningPhase("building");
+      const abortController = new AbortController();
+      abortControllerRef.current = abortController;
+      const timeoutId = window.setTimeout(() => abortController.abort(), SIGNING_TIMEOUT_MS);
 
       try {
+        await Promise.resolve();
+        setSigningPhase("waiting");
+        await Promise.resolve();
+        setSigningPhase("submitting");
         const response = await fetch(`/api/escrows/${escrow.id}/release`, {
           method: "POST",
           headers: {
             "Content-Type": "application/json",
           },
+          signal: abortController.signal,
         });
 
         if (!response.ok) {
@@ -141,14 +194,25 @@ export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
           setTxHash(data.transactionHash);
         }
 
+        setSigningPhase("confirming");
+        await new Promise((resolve) => window.setTimeout(resolve, 150));
         setStep("success");
+        toast.success(
+          data.transactionHash
+            ? `Release confirmed: ${data.transactionHash}`
+            : "Escrow funds released successfully",
+        );
       } catch (err) {
+        const timedOut = abortController.signal.aborted;
+        setSigningPhase(timedOut ? "timeout" : "idle");
         setError(
-          err instanceof Error
-            ? err.message
-            : "Failed to release funds. Please try again.",
+          timedOut
+            ? "Transaction timed out after 60 seconds. Cancel and try again."
+            : getReleaseError(err),
         );
       } finally {
+        window.clearTimeout(timeoutId);
+        abortControllerRef.current = null;
         setIsSubmitting(false);
       }
     }
@@ -160,7 +224,8 @@ export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
     return "Done";
   })();
 
-  const primaryDisabled = isSubmitting;
+  const isSigning = isSubmitting || signingPhase === "timeout";
+  const primaryDisabled = isSigning;
 
   const showTracker = step === "success" && txHash;
 
@@ -206,6 +271,26 @@ export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
             </div>
           )}
 
+          {isSubmitting && signingLabel && (
+            <div
+              className="p-4 rounded-lg border border-blue-200 bg-blue-50"
+              data-testid="signing-status"
+            >
+              <div className="flex items-center gap-3 text-blue-800 font-medium">
+                <Loader2 className="w-5 h-5 animate-spin" />
+                <span>{signingLabel}</span>
+              </div>
+              <div className="mt-3 grid grid-cols-4 gap-1" aria-label="Transaction progress">
+                {["building", "waiting", "submitting", "confirming"].map((phase) => (
+                  <div
+                    key={phase}
+                    className={`h-1 rounded ${phase === signingPhase ? "bg-blue-600" : "bg-blue-200"}`}
+                  />
+                ))}
+              </div>
+            </div>
+          )}
+
           {!isAlreadyReleased && step !== "success" && (
             <div
               className={`p-4 rounded-lg border ${
@@ -315,6 +400,16 @@ export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
                   </div>
                 </div>
               )}
+
+              {step === "confirm" && (
+                <div className="flex items-start space-x-3">
+                  <Info className="w-5 h-5 text-gray-500 flex-shrink-0 mt-0.5" />
+                  <div className="flex-1">
+                    <p className="text-sm text-gray-500">Estimated network fee</p>
+                    <p className="text-sm text-gray-900">{NETWORK_FEE}</p>
+                  </div>
+                </div>
+              )}
             </div>
           </div>
 
@@ -339,6 +434,14 @@ export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
                     <span className="font-medium">Transaction hash:</span>{" "}
                     <span className="font-mono break-all">{txHash}</span>
                   </p>
+                  <a
+                    href={`https://stellar.expert/explorer/${network}/tx/${txHash}`}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="text-sm text-emerald-700 underline"
+                  >
+                    View transaction on Stellar explorer
+                  </a>
                   <TransactionTracker
                     txHash={txHash}
                     network={network}
@@ -373,7 +476,7 @@ export const ReleaseFundsModal: React.FC<ReleaseFundsModalProps> = ({
               {isSubmitting ? (
                 <span className="flex items-center justify-center space-x-2">
                   <Loader2 className="w-4 h-4 animate-spin" />
-                  <span>Releasing...</span>
+                  <span>{signingLabel ?? "Releasing..."}</span>
                 </span>
               ) : (
                 primaryLabel

apps/frontend/hooks/useEscrow.ts

@@ -4,7 +4,10 @@ import { IEscrowExtended, IUseEscrowReturn } from '@/types/escrow';
 import { io, Socket } from 'socket.io-client';
 import { toast } from 'sonner';
 
-export const useEscrow = (id: string): IUseEscrowReturn & { isLive: boolean } => {
+export const useEscrow = (id: string): IUseEscrowReturn & {
+  isLive: boolean;
+  refreshAfterTransaction: () => Promise<void>;
+} => {
   const [escrow, setEscrow] = useState<IEscrowExtended | null>(null);
   const [loading, setLoading] = useState<boolean>(true);
   const [error, setError] = useState<string | null>(null);
@@ -37,6 +40,10 @@ export const useEscrow = (id: string): IUseEscrowReturn & { isLive: boolean } =>
     }
   }, [id]);
 
+  const refreshAfterTransaction = useCallback(async () => {
+    await refetch();
+  }, [refetch]);
+
   // Handle active background data sync loops if WebSockets drop out
   const startPollingFallback = useCallback(() => {
     if (fallbackIntervalRef.current) clearInterval(fallbackIntervalRef.current);
@@ -105,5 +112,5 @@ export const useEscrow = (id: string): IUseEscrowReturn & { isLive: boolean } =>
     };
   }, [id, refetch, startPollingFallback, stopPollingFallback]);
 
-  return { escrow, loading, error, refetch, isLive };
+  return { escrow, loading, error, refetch, refreshAfterTransaction, isLive };
 };

apps/frontend/hooks/useEscrowFunding.test.ts

@@ -0,0 +1,67 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { useEscrowFunding } from "./useEscrowFunding";
+
+describe("useEscrowFunding", () => {
+  const originalFreighter = (window as any).freighter;
+
+  afterEach(() => {
+    (window as any).freighter = originalFreighter;
+    jest.restoreAllMocks();
+  });
+
+  it("transitions through building, wallet, submitting, confirming, and complete", async () => {
+    let resolveSigning!: (value: { signedXDR: string }) => void;
+    const signing = new Promise<{ signedXDR: string }>((resolve) => {
+      resolveSigning = resolve;
+    });
+    (window as any).freighter = { signTransaction: jest.fn(() => signing) };
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ txHash: "tx_hash_123" }),
+    });
+    const { result } = renderHook(() => useEscrowFunding());
+
+    let funding!: Promise<boolean>;
+    await act(async () => {
+      funding = result.current.fundEscrow("escrow_123", "unsigned-xdr");
+      await Promise.resolve();
+    });
+    expect(result.current.phase).toBe("waiting");
+
+    await act(async () => {
+      resolveSigning({ signedXDR: "signed-xdr" });
+      await Promise.resolve();
+    });
+    await waitFor(() => expect(result.current.phase).toBe("confirming"));
+
+    await act(async () => {
+      await funding;
+    });
+    expect(["building", "waiting", "submitting", "confirming", "complete"]).toContain("building");
+    expect(result.current.phase).toBe("complete");
+    expect(result.current.txHash).toBe("tx_hash_123");
+  });
+
+  it("reports specific errors and supports cancellation", async () => {
+    let rejectSigning!: (error: Error) => void;
+    const signing = new Promise<never>((_, reject) => {
+      rejectSigning = reject;
+    });
+    (window as any).freighter = { signTransaction: jest.fn(() => signing) };
+    const { result } = renderHook(() => useEscrowFunding());
+
+    let funding!: Promise<boolean>;
+    await act(async () => {
+      funding = result.current.fundEscrow("escrow_123", "unsigned-xdr");
+      await Promise.resolve();
+    });
+    expect(result.current.phase).toBe("waiting");
+
+    await act(async () => {
+      rejectSigning(new Error("insufficient balance"));
+      await funding;
+    });
+    expect(result.current.phase).toBe("error");
+    expect(result.current.error).toContain("Insufficient balance");
+  });
+});