V48 Gate 1: Add live on-chain BTC balance to the Wallet pane

geraldarthurdavis · claude · geraldarthurdavis · commit ebe249063b75 · 2026-06-12T18:37:45.000-03:00
Nothing in the codebase ever fetched a chain balance - btcFeeBalance was
only read from profile fields nothing writes, so the 'BTC in wallet' card
showed 'Binding pending' and the nav chip rendered null as 0 BTC.

- New session-scoped GET /api/wallet/btc-balance derives the bound
  addresses server-side from the profile wallet binding (no client-trusted
  address), queries mempool.space, and returns confirmed/pending sats+BTC.
  The ambiguous 'testnet' binding label tries testnet4 first, then
  testnet3, so fauceted coins surface wherever they landed.
- Wallet pane 'BTC in wallet' card now shows the live balance with network
  and pending-confirmation detail, falling back to posture text when the
  source is unavailable.
- Ledger documents testnet4 faucets (coinfaucet.eu, altquick.com) and the
  mempool.space testnet4 explorer patterns.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/BITCODE_V48_QA.md b/BITCODE_V48_QA.md
@@ -7,6 +7,13 @@
 - Posture: interactive local experiential QA of the first live commercial (testnet) experience; app runs locally (`pnpm -C uapi dev:remote`) against the staging Supabase project; wallet network testnet4
 - Source-safety posture: source-safe evidence only; no secrets, protected source, provider payloads, wallet material, service-role keys, database credentials, or raw private prompts are serialized here.
 
+## Testnet BTC resources
+
+- Faucet (testnet4): https://coinfaucet.eu/en/btc-testnet4/
+- Faucet/exchange (testnet coins): https://altquick.com/exchange/
+- Explorer (testnet4): https://mempool.space/testnet4 — tx view at `…/testnet4/tx/<txid>`, address view at `…/testnet4/address/<address>`
+- The in-app "BTC in wallet" card reads the bound address via `/api/wallet/btc-balance` (mempool.space, testnet4-first with testnet3 fallback for the ambiguous `testnet` binding label).
+
 ## QA scripts (committed at `supabase/queries/v48_qa_*.sql`)
 
 Run in the Supabase SQL editor; all auto-target the most recent `custom:bitcode-bitcoin` user (purge-proof, no UUID editing). Run-after map:
@@ -135,7 +142,7 @@ Track 2-4 scripts (deposit activity, BTD ledger, settlement, pack journaling) ge
 - [~] Profile pane readback (optional email binding) — deferred by decision 2026-06-12: wallet (plus GitHub) is the root of identity; email is optional contact only and not required for Track 1 closure. The "Add Email" repair CTA routing was fixed regardless (contract repair routes → `/packs`). The `signInWithOtp` contact-binding semantics check moves to the F4 legacy-auth eradication gate, where the email path gets disambiguated from authentication wholesale.
 - [x] Externals: GitHub App connect + repository inventory — verified 2026-06-12: installation `139922918` (`engineeredsoftware`, repository_selection `all`), provider readiness "succeeded" with source-safe token posture, 46 repositories synced into `vcs_repositories` with full metadata. Post-connect redirect retargeted from the legacy `/terminal` overlay to `/packs?auxillary-open-to=externals`. Connected Scope pill list was hard-capped at 8 (`repositories.slice(0, 8)`) — now renders all in a scrollable wrap.
 - QA evidence hygiene note: ad-hoc `user_connections` dumps that select `connection_data` wholesale expose the GitHub installation `access_token` (short-lived, 1h expiry — the one pasted on 2026-06-12 expired 21:08Z; no rotation needed). Use `v48_qa_03_user_connections_token_safe.sql` instead; never paste raw `connection_data`.
-- [ ] Wallet pane: binding shows verified, fauceted testnet4 balance visible
+- [ ] Wallet pane: fauceted testnet4 balance visible — live on-chain balance plumbing built 2026-06-12 (`/api/wallet/btc-balance` + "BTC in wallet" card; previously nothing in the codebase ever fetched a chain balance, so the card showed "Binding pending" and the nav chip rendered null as 0). Awaiting visual confirm post-faucet. Binding status stays `pending` by design until signature verification ships (checklist's earlier "verified" wording was aspirational). Nav chip wiring to the live source is a follow-up.
 - [ ] Organization/team + treasury panes render
 
 ## Track 2 — Depositing
diff --git a/uapi/app/api/wallet/btc-balance/route.ts b/uapi/app/api/wallet/btc-balance/route.ts
@@ -0,0 +1,176 @@
+import { NextResponse } from 'next/server';
+
+import { supabaseAdmin } from '@bitcode/supabase';
+import { createClient } from '@bitcode/supabase/ssr/server';
+import {
+  bitcodeServerTelemetry,
+  compactBitcodeServerId,
+} from '@/lib/bitcode-server-telemetry';
+
+export const runtime = 'nodejs';
+
+const SATS_PER_BTC = 100_000_000;
+
+// The OAuth identity sub normalizes the wallet network to "testnet", while the
+// app canon is testnet4 — for the ambiguous label, try testnet4 first and fall
+// back to testnet3 so fauceted coins surface wherever they actually landed.
+const NETWORK_ENDPOINTS: Record<string, Array<{ network: string; baseUrl: string }>> = {
+  mainnet: [{ network: 'mainnet', baseUrl: 'https://mempool.space/api' }],
+  testnet4: [{ network: 'testnet4', baseUrl: 'https://mempool.space/testnet4/api' }],
+  testnet: [
+    { network: 'testnet4', baseUrl: 'https://mempool.space/testnet4/api' },
+    { network: 'testnet3', baseUrl: 'https://mempool.space/testnet/api' },
+  ],
+  signet: [{ network: 'signet', baseUrl: 'https://mempool.space/signet/api' }],
+};
+
+function readNonEmptyString(value: unknown) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function isPlausibleBitcoinAddress(value: unknown) {
+  const address = readNonEmptyString(value);
+  if (!address) return false;
+
+  return (
+    /^(bc1|tb1|bcrt1)[ac-hj-np-z02-9]{8,90}$/i.test(address) ||
+    /^[13mn2][A-HJ-NP-Za-km-z1-9]{25,60}$/.test(address)
+  );
+}
+
+type AddressStats = {
+  address: string;
+  confirmedSats: number;
+  pendingSats: number;
+};
+
+async function readAddressStats(baseUrl: string, address: string): Promise<AddressStats | null> {
+  const response = await fetch(`${baseUrl}/address/${address}`, {
+    cache: 'no-store',
+    headers: { accept: 'application/json' },
+  });
+  if (!response.ok) return null;
+
+  const payload = asRecord(await response.json().catch(() => null));
+  const chain = asRecord(payload?.chain_stats);
+  const mempool = asRecord(payload?.mempool_stats);
+  const readSum = (stats: Record<string, unknown> | null, key: string) =>
+    typeof stats?.[key] === 'number' ? (stats[key] as number) : 0;
+
+  return {
+    address,
+    confirmedSats: readSum(chain, 'funded_txo_sum') - readSum(chain, 'spent_txo_sum'),
+    pendingSats: readSum(mempool, 'funded_txo_sum') - readSum(mempool, 'spent_txo_sum'),
+  };
+}
+
+export async function GET() {
+  const supabase = await createClient();
+  const {
+    data: { user },
+    error: userError,
+  } = await supabase.auth.getUser();
+
+  if (!user || userError) {
+    return NextResponse.json(
+      { error: 'A Bitcode session is required to read wallet BTC posture.', code: 'wallet_session_required' },
+      { status: 401 },
+    );
+  }
+
+  const { data: profile, error: profileError } = await supabaseAdmin
+    .from('user_profiles')
+    .select('settings')
+    .eq('id', user.id)
+    .maybeSingle();
+
+  if (profileError) {
+    return NextResponse.json({ error: profileError.message }, { status: 500 });
+  }
+
+  const binding =
+    asRecord(asRecord(asRecord(profile?.settings)?.bitcodeProfile)?.walletBinding) ??
+    asRecord(asRecord(profile?.settings)?.walletBinding);
+  const addresses = [
+    readNonEmptyString(binding?.authAddress) ?? readNonEmptyString(binding?.address),
+    readNonEmptyString(binding?.paymentAddress),
+  ].filter((value, index, list): value is string =>
+    Boolean(value) && isPlausibleBitcoinAddress(value) && list.indexOf(value) === index,
+  );
+
+  if (!addresses.length) {
+    return NextResponse.json(
+      { error: 'No wallet binding address is attached to this Bitcode profile.', code: 'wallet_binding_missing' },
+      { status: 422 },
+    );
+  }
+
+  const networkLabel = (readNonEmptyString(binding?.network) ?? 'testnet4').toLowerCase();
+  const candidates = NETWORK_ENDPOINTS[networkLabel];
+  if (!candidates) {
+    return NextResponse.json(
+      { error: `Wallet network ${networkLabel} has no public balance source.`, code: 'wallet_network_unsupported' },
+      { status: 422 },
+    );
+  }
+
+  try {
+    let resolved: { network: string; entries: AddressStats[] } | null = null;
+    for (const candidate of candidates) {
+      const entries = (
+        await Promise.all(addresses.map((address) => readAddressStats(candidate.baseUrl, address)))
+      ).filter((entry): entry is AddressStats => entry !== null);
+      if (!entries.length) continue;
+
+      const total = entries.reduce((sum, entry) => sum + entry.confirmedSats + entry.pendingSats, 0);
+      if (!resolved) resolved = { network: candidate.network, entries };
+      if (total > 0) {
+        resolved = { network: candidate.network, entries };
+        break;
+      }
+    }
+
+    if (!resolved) {
+      return NextResponse.json(
+        { error: 'Balance source is unavailable.', code: 'wallet_balance_source_unavailable' },
+        { status: 502 },
+      );
+    }
+
+    const confirmedSats = resolved.entries.reduce((sum, entry) => sum + entry.confirmedSats, 0);
+    const pendingSats = resolved.entries.reduce((sum, entry) => sum + entry.pendingSats, 0);
+
+    bitcodeServerTelemetry('info', 'wallet-btc-balance', 'read', {
+      userId: compactBitcodeServerId(user.id),
+      network: resolved.network,
+      addresses: resolved.entries.map((entry) => compactBitcodeServerId(entry.address)),
+      confirmedSats,
+      pendingSats,
+    });
+
+    return NextResponse.json({
+      ok: true,
+      network: resolved.network,
+      addresses: resolved.entries.map((entry) => entry.address),
+      confirmedSats,
+      pendingSats,
+      confirmedBtc: confirmedSats / SATS_PER_BTC,
+      pendingBtc: pendingSats / SATS_PER_BTC,
+    });
+  } catch (error) {
+    bitcodeServerTelemetry('warn', 'wallet-btc-balance', 'read-failed', {
+      userId: compactBitcodeServerId(user.id),
+      message: error instanceof Error ? error.message : String(error),
+    });
+    return NextResponse.json(
+      { error: 'Balance source is unavailable.', code: 'wallet_balance_source_unavailable' },
+      { status: 502 },
+    );
+  }
+}
diff --git a/uapi/app/auxillaries/components/AuxillariesWalletPane.tsx b/uapi/app/auxillaries/components/AuxillariesWalletPane.tsx
@@ -248,6 +248,33 @@ export default function AuxillariesWalletPane({
   const [selectedActivityId, setSelectedActivityId] = useState<string | null>(
     MASTER_MOCK_MODE ? MOCK_RUNS[0]?.id ?? null : null,
   );
+  const [liveBtcBalance, setLiveBtcBalance] = useState<{
+    confirmedBtc: number;
+    pendingBtc: number;
+    network: string;
+  } | null>(null);
+
+  useEffect(() => {
+    if (!walletBinding?.address) return;
+    let cancelled = false;
+    (async () => {
+      try {
+        const response = await fetch('/api/wallet/btc-balance');
+        const payload = await response.json().catch(() => null);
+        if (cancelled || !response.ok || !payload?.ok) return;
+        setLiveBtcBalance({
+          confirmedBtc: typeof payload.confirmedBtc === 'number' ? payload.confirmedBtc : 0,
+          pendingBtc: typeof payload.pendingBtc === 'number' ? payload.pendingBtc : 0,
+          network: typeof payload.network === 'string' ? payload.network : 'testnet4',
+        });
+      } catch {
+        // Balance source unavailable: the card keeps its posture fallback.
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [walletBinding?.address]);
 
   useEffect(() => {
     if (onCompletionStatusChange && !hasCalledCompletionRef.current) {
@@ -503,8 +530,18 @@ export default function AuxillariesWalletPane({
                     },
                     {
                       label: "BTC in wallet",
-                      value: formatBtcFeeBalance(supportTreasury?.btcFeeBalance ?? btcFeeBalanceSource),
-                      detail: supportTreasury?.organizationTreasurySeparated
+                      value: formatBtcFeeBalance(
+                        liveBtcBalance?.confirmedBtc ??
+                          supportTreasury?.btcFeeBalance ??
+                          btcFeeBalanceSource,
+                      ),
+                      detail: liveBtcBalance
+                        ? `Live on-chain ${liveBtcBalance.network} balance for the bound wallet address${
+                            liveBtcBalance.pendingBtc > 0
+                              ? `; ${liveBtcBalance.pendingBtc.toLocaleString(undefined, { maximumFractionDigits: 8 })} BTC pending confirmation`
+                              : ''
+                          }.`
+                        : supportTreasury?.organizationTreasurySeparated
                         ? "Account treasury posture is source-safe and separate from organization treasury controls and Exchange market state."
                         : hasReadableBtcFeeBalance
                         ? "Live BTC fee-liquidity posture supplied by the connected wallet posture."
diff --git a/uapi/tests/api/walletBtcBalanceRoute.test.ts b/uapi/tests/api/walletBtcBalanceRoute.test.ts
@@ -0,0 +1,132 @@
+/**
+ * @jest-environment node
+ */
+
+jest.mock('@bitcode/supabase/ssr/server', () => ({
+  createClient: jest.fn(),
+}));
+
+jest.mock('@bitcode/supabase', () => ({
+  supabaseAdmin: {
+    from: jest.fn(),
+  },
+}));
+
+import { createClient } from '@bitcode/supabase/ssr/server';
+import { supabaseAdmin } from '@bitcode/supabase';
+import { GET } from '@/app/api/wallet/btc-balance/route';
+
+const QA_ADDRESS = 'tb1p6x70u8ag7hkmgsve58lxhpgk5fhnanxp2vtuhvccv6n54f2m9mrsxe6wc2';
+
+function installSupabaseMocks(options: {
+  user?: { id: string } | null;
+  settings?: Record<string, unknown> | null;
+}) {
+  (createClient as jest.Mock).mockResolvedValue({
+    auth: {
+      getUser: jest.fn().mockResolvedValue({
+        data: { user: Object.prototype.hasOwnProperty.call(options, 'user') ? options.user : { id: 'user-1' } },
+        error: null,
+      }),
+    },
+  });
+
+  const builder = {
+    select: jest.fn(),
+    eq: jest.fn(),
+    maybeSingle: jest.fn().mockResolvedValue({
+      data: options.settings === null ? null : { settings: options.settings },
+      error: null,
+    }),
+  };
+  builder.select.mockReturnValue(builder);
+  builder.eq.mockReturnValue(builder);
+  (supabaseAdmin.from as jest.Mock).mockReturnValue(builder);
+}
+
+function mempoolResponse(confirmed: number, pending = 0) {
+  return {
+    ok: true,
+    json: async () => ({
+      chain_stats: { funded_txo_sum: confirmed, spent_txo_sum: 0 },
+      mempool_stats: { funded_txo_sum: pending, spent_txo_sum: 0 },
+    }),
+  };
+}
+
+describe('GET /api/wallet/btc-balance', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('requires a session', async () => {
+    installSupabaseMocks({ user: null, settings: null });
+
+    const response = await GET();
+    expect(response.status).toBe(401);
+    await expect(response.json()).resolves.toEqual(
+      expect.objectContaining({ code: 'wallet_session_required' }),
+    );
+  });
+
+  it('rejects profiles with no wallet binding address', async () => {
+    installSupabaseMocks({ settings: { bitcodeProfile: { walletBinding: null } } });
+
+    const response = await GET();
+    expect(response.status).toBe(422);
+    await expect(response.json()).resolves.toEqual(
+      expect.objectContaining({ code: 'wallet_binding_missing' }),
+    );
+  });
+
+  it('reads the bound address balance, trying testnet4 first for the ambiguous testnet label', async () => {
+    installSupabaseMocks({
+      settings: {
+        bitcodeProfile: {
+          walletBinding: {
+            address: QA_ADDRESS,
+            authAddress: QA_ADDRESS,
+            paymentAddress: null,
+            network: 'testnet',
+          },
+        },
+      },
+    });
+    global.fetch = jest.fn(async () => mempoolResponse(125_000, 4_000)) as jest.Mock;
+
+    const response = await GET();
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual(
+      expect.objectContaining({
+        ok: true,
+        network: 'testnet4',
+        confirmedSats: 125_000,
+        pendingSats: 4_000,
+        confirmedBtc: 0.00125,
+      }),
+    );
+    expect(global.fetch).toHaveBeenCalledWith(
+      `https://mempool.space/testnet4/api/address/${QA_ADDRESS}`,
+      expect.objectContaining({ cache: 'no-store' }),
+    );
+  });
+
+  it('falls back to testnet3 when testnet4 shows no funds', async () => {
+    installSupabaseMocks({
+      settings: {
+        bitcodeProfile: {
+          walletBinding: { address: QA_ADDRESS, network: 'testnet' },
+        },
+      },
+    });
+    global.fetch = jest.fn(async (url: string) =>
+      url.includes('/testnet4/') ? mempoolResponse(0, 0) : mempoolResponse(99_000, 0),
+    ) as jest.Mock;
+
+    const response = await GET();
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toEqual(
+      expect.objectContaining({ ok: true, network: 'testnet3', confirmedSats: 99_000 }),
+    );
+  });
+});
