From 43d7462834daf7803784566a16a221649d343db2 Mon Sep 17 00:00:00 2001
From: libby-coder <libbyharper89@gmail.com>
Date: Sat, 22 Aug 2026 18:10:11 +0100
Subject: [PATCH 1/2] feat: add wallet network-switch guard with persistent
 session restore (Closes #25)

Extends useWallet() with session restore that verifies Freighter's isAllowed()
grant (not just a localStorage flag, so a revoked/stale session self-heals) and
a live WatchWalletChanges-backed guard that detects the wrong Stellar network
and guides the user to switch inside the extension, since Freighter has no API
to switch networks on a dApp's behalf. NetworkGuard surfaces this app-wide, and
EscrowFundingWizard now blocks progress past wallet-connect on the wrong
network. Also wires WalletButton into the navbar, where it was defined but
never mounted.
---
 .env.example                                  |   5 +
 README.md                                     |  45 ++-
 src/app/layout.tsx                            |   2 +
 src/components/Navbar.tsx                     |   3 +
 src/components/WalletButton.tsx               |  29 +-
 src/components/escrow/EscrowFundingWizard.tsx |  10 +-
 .../escrow/steps/ConnectWalletStep.tsx        |  21 +-
 src/components/wallet/NetworkGuard.tsx        |  49 +++
 src/components/wallet/index.ts                |   1 +
 src/lib/config.ts                             |  10 +
 src/lib/test/wallet.test.tsx                  | 307 ++++++++++++++++++
 src/lib/wallet.ts                             | 167 ++++++++--
 12 files changed, 605 insertions(+), 44 deletions(-)
 create mode 100644 src/components/wallet/NetworkGuard.tsx
 create mode 100644 src/components/wallet/index.ts
 create mode 100644 src/lib/test/wallet.test.tsx

diff --git a/.env.example b/.env.example
index ee0eed5..8e6538b 100644
--- a/.env.example
+++ b/.env.example
@@ -3,3 +3,8 @@
 
 # Base URL of the GuildWorkman API. Defaults to the hosted instance if unset.
 NEXT_PUBLIC_API_BASE_URL=http://localhost:8080
+
+# Stellar network the wallet-connection layer expects Freighter to be on.
+# One of PUBLIC | TESTNET | FUTURENET. Defaults to TESTNET if unset, matching
+# the Soroban contracts' current deployment target.
+NEXT_PUBLIC_STELLAR_NETWORK=TESTNET
diff --git a/README.md b/README.md
index dc2477c..2f7e276 100644
--- a/README.md
+++ b/README.md
@@ -199,14 +199,39 @@ Java backend that doesn't exist today.
 Rather than pretend that integration is further along than it is, the
 frontend currently does two honest things:
 
-1. **A real wallet connection.** The navbar's "Connect Wallet" button
-   (`src/components/WalletButton.tsx`, `src/lib/wallet.ts`) uses
+1. **A real, resilient wallet connection.** The navbar's "Connect Wallet"
+   button (`src/components/WalletButton.tsx`, `src/lib/wallet.ts`) uses
    `@stellar/freighter-api` to connect an actual Freighter wallet, showing a
-   truncated address, network (Testnet/Mainnet), and a disconnect option. If
-   the Freighter extension isn't installed, it shows an "Install Freighter"
-   hint instead of failing silently. This makes **no contract calls** —
-   booking, payment, and review logic are all unchanged and still go through
-   the backend API/Paystack.
+   truncated address, network (Testnet/Mainnet/Futurenet), and a disconnect
+   option. If the Freighter extension isn't installed, it shows an "Install
+   Freighter" hint instead of failing silently. This makes **no contract
+   calls** — booking, payment, and review logic are all unchanged and still
+   go through the backend API/Paystack.
+
+   On top of the base connection, `useWallet()` (`src/lib/wallet.ts`) adds:
+   - **Session restore across reloads** — a localStorage flag is only a fast
+     hint; the actual restore verifies Freighter's own `isAllowed()` grant
+     before trusting it, so a session revoked inside the extension (or a
+     browser profile that never had it) self-heals instead of showing a
+     stale "connected" UI.
+   - **A live network-switch guard** — Freighter has no API to switch its
+     own network on a dApp's behalf (a deliberate security boundary), so
+     `useWallet` runs Freighter's `WatchWalletChanges` poller for the life
+     of a session and exposes `isWrongNetwork` / `expectedNetwork`.
+     `NetworkGuard` (`src/components/wallet/NetworkGuard.tsx`, mounted
+     app-wide in `src/app/layout.tsx`) shows a banner guiding the user to
+     switch inside Freighter and clears itself automatically once the
+     watcher detects the change — no reload or manual recheck required,
+     though a "check again" button short-circuits the wait.
+     `EscrowFundingWizard`'s connect-wallet step additionally **blocks
+     progress** past that step while on the wrong network, since funding
+     escrow there isn't recoverable after the fact.
+   - The expected network is configurable via `NEXT_PUBLIC_STELLAR_NETWORK`
+     (defaults to `TESTNET` — see `.env.example`).
+
+   No new dependencies were added — `WatchWalletChanges` and `isAllowed()`
+   are both part of the `@stellar/freighter-api` version already in
+   `package.json`.
 2. **An informational trust layer.** The homepage sections (`Hero`,
    `HowItWorks`, `StatsBand`) plus "Escrow protected" badges on worker cards
    and the booking flow explain in plain language what the contracts *will* do
@@ -222,13 +247,15 @@ src/
   components/
     ui/           # design-system primitives (Button, Input, Select, Card, Badge)
     brand/        # the marks as components (Logo, NorthStar, AdinkraPattern)
+    wallet/       # NetworkGuard — app-wide wrong-network banner
     *.tsx         # page-level and shared client components
   lib/
     api.ts        # typed API client — every backend call goes through here
-    config.ts     # API_BASE_URL resolution
+    config.ts     # API_BASE_URL / EXPECTED_STELLAR_NETWORK resolution
     types.ts      # shared request/response types
     constants.ts  # category list and skill-detail seed data
-    wallet.ts     # useWallet() hook wrapping @stellar/freighter-api
+    wallet.ts     # useWallet() hook — connect/session-restore/network-guard
+                   # on top of @stellar/freighter-api
 public/
   assets/         # images used across the app
   brand/          # exported logo marks (SVG masters + 4x PNGs)
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index e3661a2..80c1163 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -7,6 +7,7 @@ import Footer from "@/components/Footer";
 import { ThemeProvider } from "@/components/theme";
 import { NotificationProvider } from "@/components/notifications/useNotifications";
 import NotificationToast from "@/components/notifications/NotificationToast";
+import { NetworkGuard } from "@/components/wallet";
 import { themeScript } from "@/lib/theme";
 
 const inter = Inter({
@@ -42,6 +43,7 @@ export default function RootLayout({
         <ThemeProvider>
           <NotificationProvider>
             <Navbar />
+            <NetworkGuard />
             <main className="flex-1">{children}</main>
             <Footer />
             <NotificationToast />
diff --git a/src/components/Navbar.tsx b/src/components/Navbar.tsx
index ef5738f..ebe4992 100644
--- a/src/components/Navbar.tsx
+++ b/src/components/Navbar.tsx
@@ -6,6 +6,7 @@ import { HiMenu, HiX } from "react-icons/hi";
 import Logo from "./brand/Logo";
 import ThemeToggle from "./ThemeToggle";
 import NotificationCenter from "./notifications/NotificationCenter";
+import WalletButton from "./WalletButton";
 import { buttonClasses } from "./ui/Button";
 
 const navLinks = [
@@ -35,6 +36,7 @@ export default function Navbar() {
         <div className="ml-auto hidden items-center gap-2 sm:flex">
           <ThemeToggle />
           <NotificationCenter />
+          <WalletButton />
           <Link href="/login" className={buttonClasses("outline", "sm")}>
             Log in
           </Link>
@@ -72,6 +74,7 @@ export default function Navbar() {
             ))}
           </nav>
           <div className="mt-3 flex flex-col gap-2">
+            <WalletButton variant="mobile" />
             <Link href="/login" onClick={() => setOpen(false)} className={buttonClasses("outline", "md")}>
               Log in
             </Link>
diff --git a/src/components/WalletButton.tsx b/src/components/WalletButton.tsx
index d501c75..3574d40 100644
--- a/src/components/WalletButton.tsx
+++ b/src/components/WalletButton.tsx
@@ -2,20 +2,24 @@
 
 import { useEffect, useRef, useState } from "react";
 import { HiLink, HiChevronDown, HiLogout } from "react-icons/hi";
-import { truncateAddress, useWallet } from "@/lib/wallet";
-
-const NETWORK_LABELS: Record<string, string> = {
-  PUBLIC: "Mainnet",
-  TESTNET: "Testnet",
-  FUTURENET: "Futurenet",
-};
+import { NETWORK_LABELS, truncateAddress, useWallet } from "@/lib/wallet";
 
 interface WalletButtonProps {
   variant?: "navbar" | "mobile";
 }
 
 export default function WalletButton({ variant = "navbar" }: WalletButtonProps) {
-  const { address, network, connecting, error, freighterMissing, connect, disconnect } = useWallet();
+  const {
+    address,
+    network,
+    connecting,
+    error,
+    freighterMissing,
+    isWrongNetwork,
+    expectedNetwork,
+    connect,
+    disconnect,
+  } = useWallet();
   const [open, setOpen] = useState(false);
   const rootRef = useRef<HTMLDivElement>(null);
 
@@ -30,7 +34,7 @@ export default function WalletButton({ variant = "navbar" }: WalletButtonProps)
   }, []);
 
   const baseButton =
-    "inline-flex items-center gap-2 rounded-full border border-white/40 px-4 py-1.5 text-sm text-white hover:bg-white/10 transition-colors";
+    "inline-flex items-center gap-2 rounded-full border border-line px-4 py-1.5 text-sm text-ink hover:border-navy-2 transition-colors";
 
   if (address) {
     return (
@@ -39,7 +43,7 @@ export default function WalletButton({ variant = "navbar" }: WalletButtonProps)
           onClick={() => setOpen((o) => !o)}
           className={`${baseButton} ${variant === "mobile" ? "w-full justify-between" : ""}`}
         >
-          <span className="h-2 w-2 rounded-full bg-ok shrink-0" />
+          <span className={`h-2 w-2 rounded-full shrink-0 ${isWrongNetwork ? "bg-gold-deep" : "bg-ok"}`} />
           {truncateAddress(address)}
           <HiChevronDown className={`transition-transform ${open ? "rotate-180" : ""}`} />
         </button>
@@ -48,6 +52,11 @@ export default function WalletButton({ variant = "navbar" }: WalletButtonProps)
             <div className="px-4 py-3 border-b border-line">
               <p className="text-xs text-muted">Connected to</p>
               <p className="text-sm font-medium">{network ? NETWORK_LABELS[network] ?? network : "Stellar"}</p>
+              {isWrongNetwork && (
+                <p className="text-xs font-semibold text-gold-deep mt-1">
+                  Switch to {NETWORK_LABELS[expectedNetwork] ?? expectedNetwork} in Freighter
+                </p>
+              )}
               <p className="text-xs text-muted mt-1 break-all">{address}</p>
             </div>
             <button
diff --git a/src/components/escrow/EscrowFundingWizard.tsx b/src/components/escrow/EscrowFundingWizard.tsx
index 7738cd1..be11e7c 100644
--- a/src/components/escrow/EscrowFundingWizard.tsx
+++ b/src/components/escrow/EscrowFundingWizard.tsx
@@ -110,11 +110,14 @@ export default function EscrowFundingWizard({ bookingRef, amount, workerName }:
     await wallet.connect();
   }
 
+  // Only advance past this step once the wallet is both connected *and* on
+  // the expected network — funding on the wrong network isn't recoverable
+  // after the fact, so the guard has to block progress here, not just warn.
   useEffect(() => {
-    if (wallet.address && state.name === "connectWallet") {
+    if (wallet.address && !wallet.isWrongNetwork && state.name === "connectWallet") {
       dispatch({ type: "WALLET_CONNECTED", address: wallet.address });
     }
-  }, [wallet.address, state.name]);
+  }, [wallet.address, wallet.isWrongNetwork, state.name]);
 
   async function handleFund() {
     dispatch({ type: "FUND_START" });
@@ -184,6 +187,9 @@ export default function EscrowFundingWizard({ bookingRef, amount, workerName }:
             connecting={wallet.connecting}
             freighterMissing={wallet.freighterMissing}
             error={wallet.error}
+            isWrongNetwork={wallet.isWrongNetwork}
+            network={wallet.network}
+            expectedNetwork={wallet.expectedNetwork}
             onConnect={handleConnectWallet}
           />
         )}
diff --git a/src/components/escrow/steps/ConnectWalletStep.tsx b/src/components/escrow/steps/ConnectWalletStep.tsx
index efd1898..17d9a51 100644
--- a/src/components/escrow/steps/ConnectWalletStep.tsx
+++ b/src/components/escrow/steps/ConnectWalletStep.tsx
@@ -1,12 +1,15 @@
 import { FaWallet } from "react-icons/fa6";
 import Button from "@/components/ui/Button";
-import { truncateAddress } from "@/lib/wallet";
+import { NETWORK_LABELS, truncateAddress } from "@/lib/wallet";
 
 interface ConnectWalletStepProps {
   address: string | null;
   connecting: boolean;
   freighterMissing: boolean;
   error: string | null;
+  isWrongNetwork: boolean;
+  network: string | null;
+  expectedNetwork: string;
   onConnect: () => void;
 }
 
@@ -15,8 +18,13 @@ export default function ConnectWalletStep({
   connecting,
   freighterMissing,
   error,
+  isWrongNetwork,
+  network,
+  expectedNetwork,
   onConnect,
 }: ConnectWalletStepProps) {
+  const expectedLabel = NETWORK_LABELS[expectedNetwork] ?? expectedNetwork;
+
   return (
     <div>
       <h2 className="font-heading text-xl font-semibold">Connect your wallet</h2>
@@ -24,7 +32,16 @@ export default function ConnectWalletStep({
         We use your Stellar wallet to fund the escrow contract directly — no card details needed.
       </p>
 
-      {address ? (
+      {address && isWrongNetwork ? (
+        <div className="rounded-xl border border-gold-deep/30 bg-gold/15 p-4">
+          <p className="font-mono text-sm font-semibold text-ink">{truncateAddress(address)}</p>
+          <p role="alert" className="mt-2 text-sm text-ink">
+            <span className="font-semibold">Wrong network</span> — connected to{" "}
+            {network ? NETWORK_LABELS[network] ?? network : "an unrecognized network"}, but escrow funding requires{" "}
+            {expectedLabel}. Switch to {expectedLabel} in the Freighter extension to continue.
+          </p>
+        </div>
+      ) : address ? (
         <div className="flex items-center gap-3 rounded-xl border border-ok/30 bg-ok/10 p-4">
           <FaWallet className="text-ok" aria-hidden />
           <span className="font-mono text-sm font-semibold text-ink">{truncateAddress(address)}</span>
diff --git a/src/components/wallet/NetworkGuard.tsx b/src/components/wallet/NetworkGuard.tsx
new file mode 100644
index 0000000..0d2ab2c
--- /dev/null
+++ b/src/components/wallet/NetworkGuard.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import { useState } from "react";
+import { HiExclamationCircle } from "react-icons/hi";
+import Button from "@/components/ui/Button";
+import { NETWORK_LABELS, useWallet } from "@/lib/wallet";
+
+/**
+ * App-wide banner that appears whenever a connected wallet is on the wrong
+ * Stellar network. Freighter has no API to switch its own network on a
+ * dApp's behalf, so this guides the user through doing it themselves rather
+ * than pretending to do it for them — the underlying `useWallet` watcher
+ * clears the banner automatically once it detects the switch (usually
+ * within a few seconds); "Check again" just short-circuits that wait.
+ */
+export default function NetworkGuard() {
+  const { address, network, isWrongNetwork, expectedNetwork, recheckNetwork } = useWallet();
+  const [checking, setChecking] = useState(false);
+
+  if (!address || !isWrongNetwork) return null;
+
+  const currentLabel = network ? NETWORK_LABELS[network] ?? network : "an unrecognized network";
+  const expectedLabel = NETWORK_LABELS[expectedNetwork] ?? expectedNetwork;
+
+  async function handleRecheck() {
+    setChecking(true);
+    await recheckNetwork();
+    setChecking(false);
+  }
+
+  return (
+    <div role="alert" className="sticky top-16 z-40 border-b border-gold-deep/30 bg-gold/15">
+      <div className="mx-auto flex max-w-6xl flex-col gap-3 px-5 py-3 text-sm text-ink sm:flex-row sm:items-center sm:justify-between md:px-10">
+        <div className="flex items-start gap-2">
+          <HiExclamationCircle className="mt-0.5 shrink-0 text-lg text-gold-deep" aria-hidden />
+          <p>
+            <span className="font-semibold">Wrong network —</span> your wallet is connected to{" "}
+            <span className="font-semibold">{currentLabel}</span>, but GuildWorkman runs on{" "}
+            <span className="font-semibold">{expectedLabel}</span>. Open the Freighter extension and switch its
+            network to {expectedLabel}; this banner clears itself once it detects the change.
+          </p>
+        </div>
+        <Button type="button" variant="outline" size="sm" onClick={handleRecheck} disabled={checking} className="shrink-0">
+          {checking ? "Checking…" : "I've switched — check again"}
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/src/components/wallet/index.ts b/src/components/wallet/index.ts
new file mode 100644
index 0000000..a93cb3f
--- /dev/null
+++ b/src/components/wallet/index.ts
@@ -0,0 +1 @@
+export { default as NetworkGuard } from "./NetworkGuard";
diff --git a/src/lib/config.ts b/src/lib/config.ts
index f59af86..493ef31 100644
--- a/src/lib/config.ts
+++ b/src/lib/config.ts
@@ -1,2 +1,12 @@
 export const API_BASE_URL =
   process.env.NEXT_PUBLIC_API_BASE_URL ?? "https://guildworkman-api.onrender.com";
+
+/** The Stellar networks Freighter can be connected to. */
+export type StellarNetwork = "PUBLIC" | "TESTNET" | "FUTURENET";
+
+/** The network GuildWorkman's escrow flow expects the connected wallet to be
+    on. Defaults to Testnet, matching the Soroban contracts' current
+    deployment target (see the README's "Web3 / Stellar touches" section) —
+    override via NEXT_PUBLIC_STELLAR_NETWORK once a mainnet deployment exists. */
+export const EXPECTED_STELLAR_NETWORK: StellarNetwork =
+  (process.env.NEXT_PUBLIC_STELLAR_NETWORK as StellarNetwork | undefined) ?? "TESTNET";
diff --git a/src/lib/test/wallet.test.tsx b/src/lib/test/wallet.test.tsx
new file mode 100644
index 0000000..3d791de
--- /dev/null
+++ b/src/lib/test/wallet.test.tsx
@@ -0,0 +1,307 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+/** `@stellar/freighter-api` talks to a real browser extension over
+    postMessage — nothing jsdom can answer. Mocked here (via `vi.hoisted` so
+    the factory below can reference it) so `useWallet` is driven purely
+    through controllable promises and a fake `WatchWalletChanges`. */
+const freighter = vi.hoisted(() => {
+  type WatchCallback = (params: {
+    address: string;
+    network: string;
+    networkPassphrase: string;
+    error?: unknown;
+  }) => void;
+
+  class FakeWatchWalletChanges {
+    static instances: FakeWatchWalletChanges[] = [];
+    cb: WatchCallback | null = null;
+    stopped = false;
+    constructor(public timeout: number) {
+      FakeWatchWalletChanges.instances.push(this);
+    }
+    watch(cb: WatchCallback) {
+      this.cb = cb;
+      return {};
+    }
+    stop() {
+      this.stopped = true;
+    }
+  }
+
+  return {
+    isConnected: vi.fn(),
+    isAllowed: vi.fn(),
+    getAddress: vi.fn(),
+    requestAccess: vi.fn(),
+    getNetwork: vi.fn(),
+    FakeWatchWalletChanges,
+  };
+});
+
+vi.mock("@stellar/freighter-api", () => ({
+  isConnected: freighter.isConnected,
+  isAllowed: freighter.isAllowed,
+  getAddress: freighter.getAddress,
+  requestAccess: freighter.requestAccess,
+  getNetwork: freighter.getNetwork,
+  WatchWalletChanges: freighter.FakeWatchWalletChanges,
+}));
+
+import { useWallet } from "../wallet";
+
+const SESSION_KEY = "gw_wallet_connected";
+
+function latestWatcher() {
+  const instances = freighter.FakeWatchWalletChanges.instances;
+  return instances[instances.length - 1];
+}
+
+/** Minimal consumer exposing the hook's values through DOM attributes. */
+function WalletConsumer() {
+  const wallet = useWallet();
+  return (
+    <div
+      data-address={wallet.address ?? ""}
+      data-network={wallet.network ?? ""}
+      data-connecting={String(wallet.connecting)}
+      data-restoring={String(wallet.restoring)}
+      data-wrong-network={String(wallet.isWrongNetwork)}
+      data-error={wallet.error ?? ""}
+      data-freighter-missing={String(wallet.freighterMissing)}
+    >
+      <button data-testid="connect" onClick={() => wallet.connect()}>
+        connect
+      </button>
+      <button data-testid="disconnect" onClick={() => wallet.disconnect()}>
+        disconnect
+      </button>
+      <button data-testid="recheck" onClick={() => wallet.recheckNetwork()}>
+        recheck
+      </button>
+    </div>
+  );
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  window.localStorage.clear();
+  freighter.FakeWatchWalletChanges.instances.length = 0;
+  freighter.isConnected.mockReset();
+  freighter.isAllowed.mockReset();
+  freighter.getAddress.mockReset();
+  freighter.requestAccess.mockReset();
+  freighter.getNetwork.mockReset();
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  vi.restoreAllMocks();
+});
+
+/** Flushes the microtask queue a few times inside `act`, enough for the
+    hook's chained `await`s (isConnected -> isAllowed -> Promise.all) to
+    settle and their resulting state updates to flush into the DOM. */
+async function flush(times = 6) {
+  for (let i = 0; i < times; i++) {
+    await act(async () => {
+      await Promise.resolve();
+    });
+  }
+}
+
+async function render() {
+  act(() => {
+    root.render(<WalletConsumer />);
+  });
+  await flush();
+}
+
+function attr(name: string) {
+  return container.firstElementChild!.getAttribute(name);
+}
+
+async function click(testid: string) {
+  act(() => {
+    container.querySelector(`[data-testid="${testid}"]`)!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+  });
+  await flush();
+}
+
+describe("useWallet — connect", () => {
+  it("populates address/network and persists the session flag on success", async () => {
+    freighter.isConnected.mockResolvedValue({ isConnected: true });
+    freighter.requestAccess.mockResolvedValue({ address: "GABC1234...WXYZ" });
+    freighter.getNetwork.mockResolvedValue({ network: "TESTNET", networkPassphrase: "Test SDF Network" });
+
+    await render();
+    await click("connect");
+
+    expect(attr("data-address")).toBe("GABC1234...WXYZ");
+    expect(attr("data-network")).toBe("TESTNET");
+    expect(attr("data-wrong-network")).toBe("false");
+    expect(attr("data-connecting")).toBe("false");
+    expect(window.localStorage.getItem(SESSION_KEY)).toBe("true");
+    expect(latestWatcher()).toBeDefined();
+    expect(latestWatcher().stopped).toBe(false);
+  });
+
+  it("flags freighterMissing instead of prompting when the extension isn't installed", async () => {
+    freighter.isConnected.mockResolvedValue({ isConnected: false });
+
+    await render();
+    await click("connect");
+
+    expect(attr("data-freighter-missing")).toBe("true");
+    expect(attr("data-address")).toBe("");
+    expect(freighter.requestAccess).not.toHaveBeenCalled();
+  });
+
+  it("surfaces an error when the user declines the access request", async () => {
+    freighter.isConnected.mockResolvedValue({ isConnected: true });
+    freighter.requestAccess.mockResolvedValue({ error: "User declined access" });
+
+    await render();
+    await click("connect");
+
+    expect(attr("data-error")).toBe("User declined access");
+    expect(attr("data-address")).toBe("");
+    expect(window.localStorage.getItem(SESSION_KEY)).toBeNull();
+  });
+
+  it("flags isWrongNetwork when connected to a network other than expected (TESTNET)", async () => {
+    freighter.isConnected.mockResolvedValue({ isConnected: true });
+    freighter.requestAccess.mockResolvedValue({ address: "GPUBLIC..." });
+    freighter.getNetwork.mockResolvedValue({ network: "PUBLIC", networkPassphrase: "Public Global Stellar Network" });
+
+    await render();
+    await click("connect");
+
+    expect(attr("data-network")).toBe("PUBLIC");
+    expect(attr("data-wrong-network")).toBe("true");
+  });
+});
+
+describe("useWallet — session restore", () => {
+  it("silently restores a session that Freighter still recognizes as allowed", async () => {
+    window.localStorage.setItem(SESSION_KEY, "true");
+    freighter.isConnected.mockResolvedValue({ isConnected: true });
+    freighter.isAllowed.mockResolvedValue({ isAllowed: true });
+    freighter.getAddress.mockResolvedValue({ address: "GRESTORED..." });
+    freighter.getNetwork.mockResolvedValue({ network: "TESTNET", networkPassphrase: "Test SDF Network" });
+
+    await render();
+
+    expect(attr("data-address")).toBe("GRESTORED...");
+    expect(attr("data-restoring")).toBe("false");
+    expect(latestWatcher()).toBeDefined();
+  });
+
+  it("clears a stale session flag when Freighter no longer allows this origin", async () => {
+    window.localStorage.setItem(SESSION_KEY, "true");
+    freighter.isConnected.mockResolvedValue({ isConnected: true });
+    freighter.isAllowed.mockResolvedValue({ isAllowed: false });
+
+    await render();
+
+    expect(attr("data-address")).toBe("");
+    expect(window.localStorage.getItem(SESSION_KEY)).toBeNull();
+    expect(freighter.getAddress).not.toHaveBeenCalled();
+  });
+
+  it("clears a stale session flag when the extension is no longer installed", async () => {
+    window.localStorage.setItem(SESSION_KEY, "true");
+    freighter.isConnected.mockResolvedValue({ isConnected: false });
+
+    await render();
+
+    expect(attr("data-address")).toBe("");
+    expect(window.localStorage.getItem(SESSION_KEY)).toBeNull();
+  });
+
+  it("does nothing on mount when no session was ever established", async () => {
+    freighter.isConnected.mockResolvedValue({ isConnected: true });
+
+    await render();
+
+    expect(attr("data-address")).toBe("");
+    expect(freighter.isAllowed).not.toHaveBeenCalled();
+  });
+});
+
+describe("useWallet — live network-switch guard", () => {
+  async function connectOnTestnet() {
+    freighter.isConnected.mockResolvedValue({ isConnected: true });
+    freighter.requestAccess.mockResolvedValue({ address: "GLIVE..." });
+    freighter.getNetwork.mockResolvedValue({ network: "TESTNET", networkPassphrase: "Test SDF Network" });
+    await render();
+    await click("connect");
+  }
+
+  it("flips isWrongNetwork live when the watcher reports a network change", async () => {
+    await connectOnTestnet();
+    expect(attr("data-wrong-network")).toBe("false");
+
+    await act(async () => {
+      latestWatcher().cb?.({ address: "GLIVE...", network: "PUBLIC", networkPassphrase: "Public Global Stellar Network" });
+    });
+
+    expect(attr("data-network")).toBe("PUBLIC");
+    expect(attr("data-wrong-network")).toBe("true");
+
+    // Switching back clears the guard without a reload or reconnect.
+    await act(async () => {
+      latestWatcher().cb?.({ address: "GLIVE...", network: "TESTNET", networkPassphrase: "Test SDF Network" });
+    });
+    expect(attr("data-wrong-network")).toBe("false");
+  });
+
+  it("disconnects and clears the session when the watcher reports revoked access", async () => {
+    await connectOnTestnet();
+    const watcher = latestWatcher();
+
+    await act(async () => {
+      watcher.cb?.({ address: "", network: "", networkPassphrase: "", error: "access revoked" });
+    });
+
+    expect(attr("data-address")).toBe("");
+    expect(window.localStorage.getItem(SESSION_KEY)).toBeNull();
+    expect(watcher.stopped).toBe(true);
+  });
+
+  it("recheckNetwork() re-verifies immediately, without waiting for the watcher", async () => {
+    await connectOnTestnet();
+    expect(attr("data-wrong-network")).toBe("false");
+
+    freighter.getNetwork.mockResolvedValue({ network: "PUBLIC", networkPassphrase: "Public Global Stellar Network" });
+    await click("recheck");
+
+    expect(attr("data-network")).toBe("PUBLIC");
+    expect(attr("data-wrong-network")).toBe("true");
+  });
+});
+
+describe("useWallet — disconnect", () => {
+  it("stops the watcher and clears all state", async () => {
+    freighter.isConnected.mockResolvedValue({ isConnected: true });
+    freighter.requestAccess.mockResolvedValue({ address: "GBYE..." });
+    freighter.getNetwork.mockResolvedValue({ network: "TESTNET", networkPassphrase: "Test SDF Network" });
+
+    await render();
+    await click("connect");
+    const watcher = latestWatcher();
+
+    await click("disconnect");
+
+    expect(attr("data-address")).toBe("");
+    expect(window.localStorage.getItem(SESSION_KEY)).toBeNull();
+    expect(watcher.stopped).toBe(true);
+  });
+});
diff --git a/src/lib/wallet.ts b/src/lib/wallet.ts
index 7cdaf23..00fb98b 100644
--- a/src/lib/wallet.ts
+++ b/src/lib/wallet.ts
@@ -1,14 +1,51 @@
+/**
+ * Wallet connection layer — session restore, and a live network-switch
+ * guard, on top of `@stellar/freighter-api`.
+ *
+ * WHY isAllowed() INSTEAD OF TRUSTING THE SESSION FLAG ALONE
+ * The original implementation restored a session purely from a localStorage
+ * flag: if it was set, it assumed Freighter would hand back an address. That
+ * breaks the moment access is revoked from inside the extension (or the flag
+ * survives a browser profile that never granted it) — the UI would sit
+ * "connecting" against a wallet that will never answer. `isAllowed()` asks
+ * Freighter directly whether this origin currently holds a grant, so a
+ * revoked/missing grant is detected up front and the stale flag is cleared
+ * instead of leaving the app in limbo.
+ *
+ * WHY A LIVE WATCHER INSTEAD OF ONE-SHOT RESTORE
+ * Freighter has no API to switch the network on a dApp's behalf (that's a
+ * deliberate security boundary — only the user, inside the extension, can do
+ * it), so "guided switching" here means detecting the change the user makes
+ * themselves and reacting to it, not driving it. `WatchWalletChanges` polls
+ * Freighter for the active address/network and reports a callback whenever
+ * either changes. Running it for the lifetime of a connected session is what
+ * lets `NetworkGuard` (see `src/components/wallet/NetworkGuard.tsx`) clear
+ * itself the moment the user switches networks inside the extension, and
+ * what catches an account switch or an access revocation without requiring a
+ * reload.
+ */
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import {
   isConnected as freighterIsConnected,
+  isAllowed as freighterIsAllowed,
   getAddress as freighterGetAddress,
   requestAccess as freighterRequestAccess,
   getNetwork as freighterGetNetwork,
+  WatchWalletChanges,
 } from "@stellar/freighter-api";
+import { EXPECTED_STELLAR_NETWORK } from "@/lib/config";
 
 const SESSION_KEY = "gw_wallet_connected";
+/** How often the live watcher polls Freighter for address/network changes. */
+const WATCH_INTERVAL_MS = 3000;
+
+export const NETWORK_LABELS: Record<string, string> = {
+  PUBLIC: "Mainnet",
+  TESTNET: "Testnet",
+  FUTURENET: "Futurenet",
+};
 
 export function truncateAddress(address: string) {
   return `${address.slice(0, 4)}...${address.slice(-4)}`;
@@ -18,32 +55,99 @@ interface WalletState {
   address: string | null;
   network: string | null;
   connecting: boolean;
+  /** True only while a previously-authorized session is being re-verified
+      on mount — distinct from `connecting`, which is a user-initiated
+      request-access flow that can prompt the extension's UI. */
+  restoring: boolean;
   error: string | null;
   freighterMissing: boolean;
 }
 
+const initialState: WalletState = {
+  address: null,
+  network: null,
+  connecting: false,
+  restoring: false,
+  error: null,
+  freighterMissing: false,
+};
+
 export function useWallet() {
-  const [state, setState] = useState<WalletState>({
-    address: null,
-    network: null,
-    connecting: false,
-    error: null,
-    freighterMissing: false,
-  });
+  const [state, setState] = useState<WalletState>(initialState);
+  const watcherRef = useRef<WatchWalletChanges | null>(null);
 
+  const stopWatching = useCallback(() => {
+    watcherRef.current?.stop();
+    watcherRef.current = null;
+  }, []);
+
+  const startWatching = useCallback(() => {
+    stopWatching();
+    const watcher = new WatchWalletChanges(WATCH_INTERVAL_MS);
+    watcherRef.current = watcher;
+    watcher.watch(({ address, network, error }) => {
+      if (error || !address) {
+        // Access was revoked (or the extension locked) since we last
+        // checked — fall back to disconnected rather than show a session
+        // that no longer exists on Freighter's side.
+        localStorage.removeItem(SESSION_KEY);
+        stopWatching();
+        setState(initialState);
+        return;
+      }
+      setState((s) => ({ ...s, address, network: network || s.network }));
+    });
+  }, [stopWatching]);
+
+  useEffect(() => stopWatching, [stopWatching]);
+
+  // Restore a previously-authorized session on mount (page load / reload).
   useEffect(() => {
     if (localStorage.getItem(SESSION_KEY) !== "true") return;
 
-    freighterIsConnected().then(({ isConnected, error }) => {
-      if (error || !isConnected) return;
-      freighterGetAddress().then(({ address, error: addrError }) => {
-        if (addrError || !address) return;
-        setState((s) => ({ ...s, address }));
-        freighterGetNetwork().then(({ network }) => {
-          setState((s) => ({ ...s, network: network ?? null }));
-        });
-      });
-    });
+    let cancelled = false;
+    setState((s) => ({ ...s, restoring: true }));
+
+    (async () => {
+      const { isConnected } = await freighterIsConnected();
+      if (!isConnected) {
+        if (!cancelled) {
+          localStorage.removeItem(SESSION_KEY);
+          setState((s) => ({ ...s, restoring: false }));
+        }
+        return;
+      }
+
+      const { isAllowed } = await freighterIsAllowed();
+      if (!isAllowed) {
+        if (!cancelled) {
+          localStorage.removeItem(SESSION_KEY);
+          setState((s) => ({ ...s, restoring: false }));
+        }
+        return;
+      }
+
+      const [{ address, error: addrError }, { network }] = await Promise.all([
+        freighterGetAddress(),
+        freighterGetNetwork(),
+      ]);
+      if (cancelled) return;
+
+      if (addrError || !address) {
+        localStorage.removeItem(SESSION_KEY);
+        setState((s) => ({ ...s, restoring: false }));
+        return;
+      }
+
+      setState((s) => ({ ...s, address, network: network || null, restoring: false }));
+      startWatching();
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+    // Restore runs once on mount; startWatching/stopWatching are stable refs.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
   const connect = useCallback(async () => {
@@ -71,15 +175,36 @@ export function useWallet() {
       address,
       network: network ?? null,
       connecting: false,
+      restoring: false,
       error: null,
       freighterMissing: false,
     });
-  }, []);
+    startWatching();
+  }, [startWatching]);
 
   const disconnect = useCallback(() => {
+    stopWatching();
     localStorage.removeItem(SESSION_KEY);
-    setState({ address: null, network: null, connecting: false, error: null, freighterMissing: false });
+    setState(initialState);
+  }, [stopWatching]);
+
+  /** Re-checks the active network immediately, rather than waiting for the
+      watcher's next poll — used by NetworkGuard's "check again" action so
+      switching inside Freighter feels instant. */
+  const recheckNetwork = useCallback(async () => {
+    const { network } = await freighterGetNetwork();
+    if (network) setState((s) => ({ ...s, network }));
   }, []);
 
-  return { ...state, connect, disconnect };
+  const isWrongNetwork =
+    state.address !== null && state.network !== null && state.network !== EXPECTED_STELLAR_NETWORK;
+
+  return {
+    ...state,
+    isWrongNetwork,
+    expectedNetwork: EXPECTED_STELLAR_NETWORK,
+    connect,
+    disconnect,
+    recheckNetwork,
+  };
 }

From 18c7a3ef9d9978784fc9c19bd85ce74a1fbcbd31 Mon Sep 17 00:00:00 2001
From: libby-coder <libbyharper89@gmail.com>
Date: Sat, 22 Aug 2026 19:49:01 +0100
Subject: [PATCH 2/2] fix: share a single wallet instance via context and
 address review feedback

Fixes a real bug the review surfaced: useWallet() previously ran a fully
independent instance (session restore + its own WatchWalletChanges poller)
per call site, so the navbar's desktop/mobile WalletButton and NetworkGuard
were each polling Freighter separately and could drift out of sync. Renamed
the engine to useWalletState() and added WalletProvider (mirroring
ThemeProvider's existing pattern) so the whole app shares one instance.

Also: NetworkGuard moves focus to itself and gives its recheck action an
explicit aria-label; WalletButton's collapsed trigger gets an aria-label
covering the wrong-network state and decorative icons are aria-hidden;
expectedNetwork is now typed as StellarNetwork instead of string; documented
NEXT_PUBLIC_STELLAR_NETWORK's valid values and security implications in
.env.example/README; added a regression test proving WalletProvider shares
one instance/poller across consumers and an explicit
extension-uninstalled-mid-session test.
---
 .env.example                                  |  10 +-
 README.md                                     |   6 +-
 src/app/layout.tsx                            |  14 +-
 src/components/WalletButton.tsx               |  18 +-
 src/components/escrow/EscrowFundingWizard.tsx |   2 +-
 .../escrow/steps/ConnectWalletStep.tsx        |   4 +-
 src/components/wallet/NetworkGuard.tsx        |  42 ++++-
 src/components/wallet/WalletProvider.tsx      |  28 ++++
 src/components/wallet/index.ts                |   5 +
 src/lib/test/wallet.test.tsx                  |  44 ++++-
 src/lib/test/walletProvider.test.tsx          | 155 ++++++++++++++++++
 src/lib/wallet.ts                             |  26 ++-
 12 files changed, 319 insertions(+), 35 deletions(-)
 create mode 100644 src/components/wallet/WalletProvider.tsx
 create mode 100644 src/lib/test/walletProvider.test.tsx

diff --git a/.env.example b/.env.example
index 8e6538b..c9f714a 100644
--- a/.env.example
+++ b/.env.example
@@ -5,6 +5,12 @@
 NEXT_PUBLIC_API_BASE_URL=http://localhost:8080
 
 # Stellar network the wallet-connection layer expects Freighter to be on.
-# One of PUBLIC | TESTNET | FUTURENET. Defaults to TESTNET if unset, matching
-# the Soroban contracts' current deployment target.
+# Valid values: PUBLIC (mainnet), TESTNET, FUTURENET. Defaults to TESTNET if
+# unset, matching the Soroban contracts' current deployment target.
+# This is a security-relevant setting, not just a label: it's what
+# NetworkGuard (src/components/wallet/NetworkGuard.tsx) and the escrow
+# funding wizard check the connected wallet against before allowing funds to
+# move. Setting it to PUBLIC before the backend/contract integration is
+# actually deployed to mainnet would let a wallet connected to real funds
+# pass the guard — only change it once that deployment exists.
 NEXT_PUBLIC_STELLAR_NETWORK=TESTNET
diff --git a/README.md b/README.md
index 2f7e276..29aaefa 100644
--- a/README.md
+++ b/README.md
@@ -227,7 +227,11 @@ frontend currently does two honest things:
      progress** past that step while on the wrong network, since funding
      escrow there isn't recoverable after the fact.
    - The expected network is configurable via `NEXT_PUBLIC_STELLAR_NETWORK`
-     (defaults to `TESTNET` — see `.env.example`).
+     — one of `PUBLIC` (mainnet) / `TESTNET` / `FUTURENET`, defaults to
+     `TESTNET` (see `.env.example`). This is security-relevant, not just a
+     label: it's what the guard checks a connected wallet against before
+     letting funds move, so it should only be pointed at `PUBLIC` once the
+     backend/contract integration is actually deployed there.
 
    No new dependencies were added — `WatchWalletChanges` and `isAllowed()`
    are both part of the `@stellar/freighter-api` version already in
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 80c1163..5b435da 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -7,7 +7,7 @@ import Footer from "@/components/Footer";
 import { ThemeProvider } from "@/components/theme";
 import { NotificationProvider } from "@/components/notifications/useNotifications";
 import NotificationToast from "@/components/notifications/NotificationToast";
-import { NetworkGuard } from "@/components/wallet";
+import { NetworkGuard, WalletProvider } from "@/components/wallet";
 import { themeScript } from "@/lib/theme";
 
 const inter = Inter({
@@ -42,11 +42,13 @@ export default function RootLayout({
       <body className="min-h-full flex flex-col bg-sand text-ink">
         <ThemeProvider>
           <NotificationProvider>
-            <Navbar />
-            <NetworkGuard />
-            <main className="flex-1">{children}</main>
-            <Footer />
-            <NotificationToast />
+            <WalletProvider>
+              <Navbar />
+              <NetworkGuard />
+              <main className="flex-1">{children}</main>
+              <Footer />
+              <NotificationToast />
+            </WalletProvider>
           </NotificationProvider>
         </ThemeProvider>
       </body>
diff --git a/src/components/WalletButton.tsx b/src/components/WalletButton.tsx
index 3574d40..dcd480f 100644
--- a/src/components/WalletButton.tsx
+++ b/src/components/WalletButton.tsx
@@ -2,7 +2,8 @@
 
 import { useEffect, useRef, useState } from "react";
 import { HiLink, HiChevronDown, HiLogout } from "react-icons/hi";
-import { NETWORK_LABELS, truncateAddress, useWallet } from "@/lib/wallet";
+import { NETWORK_LABELS, truncateAddress } from "@/lib/wallet";
+import { useWallet } from "@/components/wallet";
 
 interface WalletButtonProps {
   variant?: "navbar" | "mobile";
@@ -41,11 +42,18 @@ export default function WalletButton({ variant = "navbar" }: WalletButtonProps)
       <div ref={rootRef} className={`relative ${variant === "mobile" ? "w-full" : ""}`}>
         <button
           onClick={() => setOpen((o) => !o)}
+          aria-expanded={open}
+          aria-label={`Wallet connected: ${truncateAddress(address)}${
+            isWrongNetwork ? " — wrong network, action needed" : ""
+          }`}
           className={`${baseButton} ${variant === "mobile" ? "w-full justify-between" : ""}`}
         >
-          <span className={`h-2 w-2 rounded-full shrink-0 ${isWrongNetwork ? "bg-gold-deep" : "bg-ok"}`} />
+          <span
+            aria-hidden
+            className={`h-2 w-2 rounded-full shrink-0 ${isWrongNetwork ? "bg-gold-deep" : "bg-ok"}`}
+          />
           {truncateAddress(address)}
-          <HiChevronDown className={`transition-transform ${open ? "rotate-180" : ""}`} />
+          <HiChevronDown aria-hidden className={`transition-transform ${open ? "rotate-180" : ""}`} />
         </button>
         {open && (
           <div className="absolute right-0 mt-2 w-56 rounded-xl bg-surface text-ink shadow-lg border border-line overflow-hidden z-50">
@@ -66,7 +74,7 @@ export default function WalletButton({ variant = "navbar" }: WalletButtonProps)
               }}
               className="w-full flex items-center gap-2 px-4 py-2.5 text-sm text-err hover:bg-err/5"
             >
-              <HiLogout /> Disconnect
+              <HiLogout aria-hidden /> Disconnect
             </button>
           </div>
         )}
@@ -81,7 +89,7 @@ export default function WalletButton({ variant = "navbar" }: WalletButtonProps)
         disabled={connecting}
         className={`${baseButton} ${variant === "mobile" ? "w-full justify-center" : ""} disabled:opacity-60`}
       >
-        <HiLink />
+        <HiLink aria-hidden />
         {connecting ? "Connecting..." : "Connect Wallet"}
       </button>
       {freighterMissing && (
diff --git a/src/components/escrow/EscrowFundingWizard.tsx b/src/components/escrow/EscrowFundingWizard.tsx
index be11e7c..2d8972a 100644
--- a/src/components/escrow/EscrowFundingWizard.tsx
+++ b/src/components/escrow/EscrowFundingWizard.tsx
@@ -3,7 +3,7 @@
 import { useEffect, useRef, useState } from "react";
 import Button from "@/components/ui/Button";
 import Card from "@/components/ui/Card";
-import { useWallet } from "@/lib/wallet";
+import { useWallet } from "@/components/wallet";
 import EscrowStepper from "./EscrowStepper";
 import ReviewStep from "./steps/ReviewStep";
 import ConnectWalletStep from "./steps/ConnectWalletStep";
diff --git a/src/components/escrow/steps/ConnectWalletStep.tsx b/src/components/escrow/steps/ConnectWalletStep.tsx
index 17d9a51..e84d167 100644
--- a/src/components/escrow/steps/ConnectWalletStep.tsx
+++ b/src/components/escrow/steps/ConnectWalletStep.tsx
@@ -1,6 +1,6 @@
 import { FaWallet } from "react-icons/fa6";
 import Button from "@/components/ui/Button";
-import { NETWORK_LABELS, truncateAddress } from "@/lib/wallet";
+import { NETWORK_LABELS, truncateAddress, type StellarNetwork } from "@/lib/wallet";
 
 interface ConnectWalletStepProps {
   address: string | null;
@@ -9,7 +9,7 @@ interface ConnectWalletStepProps {
   error: string | null;
   isWrongNetwork: boolean;
   network: string | null;
-  expectedNetwork: string;
+  expectedNetwork: StellarNetwork;
   onConnect: () => void;
 }
 
diff --git a/src/components/wallet/NetworkGuard.tsx b/src/components/wallet/NetworkGuard.tsx
index 0d2ab2c..00c450d 100644
--- a/src/components/wallet/NetworkGuard.tsx
+++ b/src/components/wallet/NetworkGuard.tsx
@@ -1,9 +1,10 @@
 "use client";
 
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { HiExclamationCircle } from "react-icons/hi";
 import Button from "@/components/ui/Button";
-import { NETWORK_LABELS, useWallet } from "@/lib/wallet";
+import { NETWORK_LABELS, truncateAddress } from "@/lib/wallet";
+import { useWallet } from "./WalletProvider";
 
 /**
  * App-wide banner that appears whenever a connected wallet is on the wrong
@@ -16,6 +17,17 @@ import { NETWORK_LABELS, useWallet } from "@/lib/wallet";
 export default function NetworkGuard() {
   const { address, network, isWrongNetwork, expectedNetwork, recheckNetwork } = useWallet();
   const [checking, setChecking] = useState(false);
+  const bannerRef = useRef<HTMLDivElement>(null);
+
+  // Move focus to the banner the moment it appears — a sighted keyboard
+  // user or screen-reader user acting elsewhere on the page otherwise has
+  // no reason to notice a `role="alert"` region that materialized outside
+  // their current focus.
+  useEffect(() => {
+    if (address && isWrongNetwork) {
+      bannerRef.current?.focus();
+    }
+  }, [address, isWrongNetwork]);
 
   if (!address || !isWrongNetwork) return null;
 
@@ -29,18 +41,32 @@ export default function NetworkGuard() {
   }
 
   return (
-    <div role="alert" className="sticky top-16 z-40 border-b border-gold-deep/30 bg-gold/15">
+    <div
+      ref={bannerRef}
+      role="alert"
+      tabIndex={-1}
+      className="sticky top-16 z-40 border-b border-gold-deep/30 bg-gold/15 outline-none"
+    >
       <div className="mx-auto flex max-w-6xl flex-col gap-3 px-5 py-3 text-sm text-ink sm:flex-row sm:items-center sm:justify-between md:px-10">
         <div className="flex items-start gap-2">
           <HiExclamationCircle className="mt-0.5 shrink-0 text-lg text-gold-deep" aria-hidden />
           <p>
-            <span className="font-semibold">Wrong network —</span> your wallet is connected to{" "}
-            <span className="font-semibold">{currentLabel}</span>, but GuildWorkman runs on{" "}
-            <span className="font-semibold">{expectedLabel}</span>. Open the Freighter extension and switch its
-            network to {expectedLabel}; this banner clears itself once it detects the change.
+            <span className="font-semibold">Wrong network —</span> your wallet (
+            {truncateAddress(address)}) is connected to <span className="font-semibold">{currentLabel}</span>, but
+            GuildWorkman runs on <span className="font-semibold">{expectedLabel}</span>. Open the Freighter
+            extension and switch its network to {expectedLabel}; this banner clears itself once it detects the
+            change.
           </p>
         </div>
-        <Button type="button" variant="outline" size="sm" onClick={handleRecheck} disabled={checking} className="shrink-0">
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          onClick={handleRecheck}
+          disabled={checking}
+          aria-label={`Recheck the connected wallet's network${checking ? " — checking now" : ""}`}
+          className="shrink-0"
+        >
           {checking ? "Checking…" : "I've switched — check again"}
         </Button>
       </div>
diff --git a/src/components/wallet/WalletProvider.tsx b/src/components/wallet/WalletProvider.tsx
new file mode 100644
index 0000000..438a2b7
--- /dev/null
+++ b/src/components/wallet/WalletProvider.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+import { useWalletState, type WalletContextValue } from "@/lib/wallet";
+
+const WalletContext = createContext<WalletContextValue | null>(null);
+
+/**
+ * Owns the single `useWalletState()` instance for the whole app — session
+ * restore and the live network-switch watcher both run real side effects
+ * (Freighter calls, a polling interval), so every consumer sharing one
+ * instance through context is what keeps that to one poller and one source
+ * of truth, rather than each `WalletButton`/`NetworkGuard` mount running
+ * its own independent copy. See the WHY comment above `useWalletState` in
+ * `src/lib/wallet.ts` for the failure mode this avoids.
+ */
+export function WalletProvider({ children }: { children: ReactNode }) {
+  const wallet = useWalletState();
+  return <WalletContext.Provider value={wallet}>{children}</WalletContext.Provider>;
+}
+
+export function useWallet(): WalletContextValue {
+  const ctx = useContext(WalletContext);
+  if (!ctx) {
+    throw new Error("useWallet must be used within a <WalletProvider>");
+  }
+  return ctx;
+}
diff --git a/src/components/wallet/index.ts b/src/components/wallet/index.ts
index a93cb3f..61c1f21 100644
--- a/src/components/wallet/index.ts
+++ b/src/components/wallet/index.ts
@@ -1 +1,6 @@
+// Barrel for the wallet system (same pattern as theme/index.ts,
+// notifications/index.ts). WalletProvider/NetworkGuard only import from
+// "@/lib/wallet" and "./WalletProvider" directly — nothing here imports
+// back through this barrel — so re-exporting creates no circular-import risk.
 export { default as NetworkGuard } from "./NetworkGuard";
+export { WalletProvider, useWallet } from "./WalletProvider";
diff --git a/src/lib/test/wallet.test.tsx b/src/lib/test/wallet.test.tsx
index 3d791de..281f184 100644
--- a/src/lib/test/wallet.test.tsx
+++ b/src/lib/test/wallet.test.tsx
@@ -4,8 +4,11 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 /** `@stellar/freighter-api` talks to a real browser extension over
     postMessage — nothing jsdom can answer. Mocked here (via `vi.hoisted` so
-    the factory below can reference it) so `useWallet` is driven purely
-    through controllable promises and a fake `WatchWalletChanges`. */
+    the factory below can reference it) so `useWalletState` is driven purely
+    through controllable promises and a fake `WatchWalletChanges` whose
+    callback we invoke by hand — there's no `setTimeout`/polling in the fake
+    at all, so nothing here depends on real time or fake timers to be
+    deterministic. */
 const freighter = vi.hoisted(() => {
   type WatchCallback = (params: {
     address: string;
@@ -49,7 +52,7 @@ vi.mock("@stellar/freighter-api", () => ({
   WatchWalletChanges: freighter.FakeWatchWalletChanges,
 }));
 
-import { useWallet } from "../wallet";
+import { useWalletState } from "../wallet";
 
 const SESSION_KEY = "gw_wallet_connected";
 
@@ -60,7 +63,7 @@ function latestWatcher() {
 
 /** Minimal consumer exposing the hook's values through DOM attributes. */
 function WalletConsumer() {
-  const wallet = useWallet();
+  const wallet = useWalletState();
   return (
     <div
       data-address={wallet.address ?? ""}
@@ -135,7 +138,7 @@ async function click(testid: string) {
   await flush();
 }
 
-describe("useWallet — connect", () => {
+describe("useWalletState — connect", () => {
   it("populates address/network and persists the session flag on success", async () => {
     freighter.isConnected.mockResolvedValue({ isConnected: true });
     freighter.requestAccess.mockResolvedValue({ address: "GABC1234...WXYZ" });
@@ -189,7 +192,7 @@ describe("useWallet — connect", () => {
   });
 });
 
-describe("useWallet — session restore", () => {
+describe("useWalletState — session restore", () => {
   it("silently restores a session that Freighter still recognizes as allowed", async () => {
     window.localStorage.setItem(SESSION_KEY, "true");
     freighter.isConnected.mockResolvedValue({ isConnected: true });
@@ -236,7 +239,7 @@ describe("useWallet — session restore", () => {
   });
 });
 
-describe("useWallet — live network-switch guard", () => {
+describe("useWalletState — live network-switch guard", () => {
   async function connectOnTestnet() {
     freighter.isConnected.mockResolvedValue({ isConnected: true });
     freighter.requestAccess.mockResolvedValue({ address: "GLIVE..." });
@@ -276,6 +279,31 @@ describe("useWallet — live network-switch guard", () => {
     expect(watcher.stopped).toBe(true);
   });
 
+  it("disconnects and clears the session when Freighter is uninstalled mid-session", async () => {
+    // Distinct from a revoked grant: the extension itself disappears (e.g.
+    // uninstalled, or disabled) between the watcher's polls. Freighter's own
+    // requestPublicKey/requestNetworkDetails calls fail the same way an
+    // access-revocation does — an error on the watch callback with no
+    // address/network — so this exercises the same handling with a scenario
+    // named for what it actually represents in production.
+    await connectOnTestnet();
+    const watcher = latestWatcher();
+
+    await act(async () => {
+      watcher.cb?.({
+        address: "",
+        network: "",
+        networkPassphrase: "",
+        error: "Freighter extension is not installed",
+      });
+    });
+
+    expect(attr("data-address")).toBe("");
+    expect(attr("data-network")).toBe("");
+    expect(window.localStorage.getItem(SESSION_KEY)).toBeNull();
+    expect(watcher.stopped).toBe(true);
+  });
+
   it("recheckNetwork() re-verifies immediately, without waiting for the watcher", async () => {
     await connectOnTestnet();
     expect(attr("data-wrong-network")).toBe("false");
@@ -288,7 +316,7 @@ describe("useWallet — live network-switch guard", () => {
   });
 });
 
-describe("useWallet — disconnect", () => {
+describe("useWalletState — disconnect", () => {
   it("stops the watcher and clears all state", async () => {
     freighter.isConnected.mockResolvedValue({ isConnected: true });
     freighter.requestAccess.mockResolvedValue({ address: "GBYE..." });
diff --git a/src/lib/test/walletProvider.test.tsx b/src/lib/test/walletProvider.test.tsx
new file mode 100644
index 0000000..b9045a4
--- /dev/null
+++ b/src/lib/test/walletProvider.test.tsx
@@ -0,0 +1,155 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+/** Same fake as wallet.test.tsx — duplicated rather than shared because
+    `vi.mock` factories run per test file and this repo's other test files
+    (e.g. theme.test.ts / themeProvider.test.tsx) already each stub their own
+    externals rather than sharing a __mocks__ module. No real timers: the
+    fake's callback is only ever invoked by hand. */
+const freighter = vi.hoisted(() => {
+  type WatchCallback = (params: {
+    address: string;
+    network: string;
+    networkPassphrase: string;
+    error?: unknown;
+  }) => void;
+
+  class FakeWatchWalletChanges {
+    static instances: FakeWatchWalletChanges[] = [];
+    cb: WatchCallback | null = null;
+    stopped = false;
+    constructor(public timeout: number) {
+      FakeWatchWalletChanges.instances.push(this);
+    }
+    watch(cb: WatchCallback) {
+      this.cb = cb;
+      return {};
+    }
+    stop() {
+      this.stopped = true;
+    }
+  }
+
+  return {
+    isConnected: vi.fn(),
+    isAllowed: vi.fn(),
+    getAddress: vi.fn(),
+    requestAccess: vi.fn(),
+    getNetwork: vi.fn(),
+    FakeWatchWalletChanges,
+  };
+});
+
+vi.mock("@stellar/freighter-api", () => ({
+  isConnected: freighter.isConnected,
+  isAllowed: freighter.isAllowed,
+  getAddress: freighter.getAddress,
+  requestAccess: freighter.requestAccess,
+  getNetwork: freighter.getNetwork,
+  WatchWalletChanges: freighter.FakeWatchWalletChanges,
+}));
+
+import { useWallet, WalletProvider } from "../../components/wallet/WalletProvider";
+
+/** Two independent consumers, as WalletButton (desktop + mobile) and
+    NetworkGuard are in the real navbar/layout — this is the regression
+    test for "every consumer must share one wallet instance". */
+function ConsumerA() {
+  const wallet = useWallet();
+  return (
+    <div>
+      <span data-testid="a-address">{wallet.address ?? ""}</span>
+      <button data-testid="a-connect" onClick={() => wallet.connect()}>
+        connect
+      </button>
+    </div>
+  );
+}
+
+function ConsumerB() {
+  const wallet = useWallet();
+  return <span data-testid="b-address">{wallet.address ?? ""}</span>;
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  window.localStorage.clear();
+  freighter.FakeWatchWalletChanges.instances.length = 0;
+  freighter.isConnected.mockReset();
+  freighter.isAllowed.mockReset();
+  freighter.getAddress.mockReset();
+  freighter.requestAccess.mockReset();
+  freighter.getNetwork.mockReset();
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  vi.restoreAllMocks();
+});
+
+async function flush(times = 6) {
+  for (let i = 0; i < times; i++) {
+    await act(async () => {
+      await Promise.resolve();
+    });
+  }
+}
+
+function text(testid: string) {
+  return container.querySelector(`[data-testid="${testid}"]`)!.textContent;
+}
+
+describe("WalletProvider", () => {
+  it("throws when useWallet() is called outside a WalletProvider", () => {
+    function Bare() {
+      useWallet();
+      return null;
+    }
+    // React logs the thrown error to console during the failed render;
+    // that's expected here and not something this test needs to assert on.
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    expect(() => {
+      act(() => {
+        root.render(<Bare />);
+      });
+    }).toThrow("useWallet must be used within a <WalletProvider>");
+    consoleError.mockRestore();
+  });
+
+  it("shares one wallet instance — and one WatchWalletChanges poller — across every consumer", async () => {
+    freighter.isConnected.mockResolvedValue({ isConnected: true });
+    freighter.requestAccess.mockResolvedValue({ address: "GSHARED..." });
+    freighter.getNetwork.mockResolvedValue({ network: "TESTNET", networkPassphrase: "Test SDF Network" });
+
+    act(() => {
+      root.render(
+        <WalletProvider>
+          <ConsumerA />
+          <ConsumerB />
+        </WalletProvider>
+      );
+    });
+    await flush();
+
+    expect(text("a-address")).toBe("");
+    expect(text("b-address")).toBe("");
+
+    act(() => {
+      container.querySelector('[data-testid="a-connect"]')!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    await flush();
+
+    // Both consumers see the same connected address from one shared state...
+    expect(text("a-address")).toBe("GSHARED...");
+    expect(text("b-address")).toBe("GSHARED...");
+    // ...backed by exactly one poller, not one per consumer.
+    expect(freighter.FakeWatchWalletChanges.instances).toHaveLength(1);
+  });
+});
diff --git a/src/lib/wallet.ts b/src/lib/wallet.ts
index 00fb98b..711c162 100644
--- a/src/lib/wallet.ts
+++ b/src/lib/wallet.ts
@@ -23,6 +23,18 @@
  * itself the moment the user switches networks inside the extension, and
  * what catches an account switch or an access revocation without requiring a
  * reload.
+ *
+ * WHY THIS HOOK IS WRAPPED IN A CONTEXT PROVIDER
+ * `useWalletState` below owns real side effects — a session restore on
+ * mount and, once connected, a live polling watcher. It's exported for
+ * direct unit testing, but app code should never call it more than once:
+ * every call is a fully independent instance with its own poller, so two
+ * components each calling it (e.g. the navbar's desktop and mobile
+ * `WalletButton`, which are both mounted at once — only one is hidden via
+ * CSS) would double the background polling and could see each other's
+ * connect/disconnect drift out of sync. `WalletProvider` (in
+ * `src/components/wallet/WalletProvider.tsx`) runs the one instance the app
+ * uses; components consume it via `useWallet()` from `@/components/wallet`.
  */
 "use client";
 
@@ -35,7 +47,7 @@ import {
   getNetwork as freighterGetNetwork,
   WatchWalletChanges,
 } from "@stellar/freighter-api";
-import { EXPECTED_STELLAR_NETWORK } from "@/lib/config";
+import { EXPECTED_STELLAR_NETWORK, type StellarNetwork } from "@/lib/config";
 
 const SESSION_KEY = "gw_wallet_connected";
 /** How often the live watcher polls Freighter for address/network changes. */
@@ -72,7 +84,11 @@ const initialState: WalletState = {
   freighterMissing: false,
 };
 
-export function useWallet() {
+/** The stateful engine behind wallet connection — see `WalletProvider` doc
+    comment above for why app code should go through that provider's
+    `useWallet()` instead of calling this directly (tests are the
+    exception: they exercise this hook in isolation). */
+export function useWalletState() {
   const [state, setState] = useState<WalletState>(initialState);
   const watcherRef = useRef<WatchWalletChanges | null>(null);
 
@@ -208,3 +224,9 @@ export function useWallet() {
     recheckNetwork,
   };
 }
+
+export type WalletContextValue = ReturnType<typeof useWalletState>;
+
+/** Re-exported so consumers can type `expectedNetwork` precisely without
+    reaching into `@/lib/config` themselves. */
+export type { StellarNetwork };