Add GET /accounts/:address/balance, network-scoped and schema-qualified

Derived per-token balances for an address, summing what it received and
subtracting what it sent across the indexed history.

Rebased onto main, which has moved a long way since this branch: the token
cache landed via #46 and the metrics module via #175, so those parts of this
PR are dropped as duplicates and what remains is the balance endpoint itself.

Three fixes to the query on the way in:

- The table reference was unqualified, `FROM "TokenTransfer"`. Every other raw
  query in db.ts uses `"wraith"."TokenTransfer"`, because the models declare
  @@Schema("wraith") — unqualified it resolves only if search_path happens to
  include the schema, so it would work locally and fail on a deployment that
  sets search_path differently.

- No network predicate. Summing both chains' transfers for one address gives a
  number that corresponds to no balance anywhere. Now takes the network and
  filters on it, with the route reading it from the selector so an unknown
  network 400s instead of silently answering for the default.

- The metrics timer was started and stopped around the query but not in a
  finally, so a throw leaked it. Uses observeDbQuery, which times failures
  too — a query that takes eight seconds and then fails is the one worth
  seeing.

Mounted on the existing accounts router rather than a second one, so it sits
beside /summary and /transfers and inherits the network middleware.

The response keeps this PR's honesty about what the number is — a sum over the
indexed window, not an on-chain read — and returns both the raw stroop amount
and the display string, so a consumer doing arithmetic does not have to parse
the decimal back and guess the scale.

tsc clean; full suite 402 passed.

Author: Miracle656

src/__tests__/routes/accounts.test.ts

@@ -18,23 +18,40 @@ describe("Accounts route handlers", () => {
     const ALICE = "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF";
     const CONTRACT_A = "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM";
 
+    beforeEach(() => {
+      mockQueryBalances.mockReset();
+    });
+
     it("returns per-token derived balance for a known address", async () => {
       mockQueryBalances.mockResolvedValue([
-        { contractId: CONTRACT_A, balance: "50000000" } // 5.0000000
+        { contractId: CONTRACT_A, balance: "50000000" }, // 5.0000000
       ]);
 
       const res = await request(app).get(`/accounts/${ALICE}/balance`);
 
       expect(res.status).toBe(200);
       expect(res.body.balances).toHaveLength(1);
       expect(res.body.balances[0]).toEqual({
-        token: CONTRACT_A,
-        balance: "5.0000000"
+        contractId: CONTRACT_A,
+        balance: "50000000",
+        displayBalance: "5.0000000",
       });
-      expect(res.body.derived_from_ledger).toBe(true);
+      expect(res.body.derivedFromLedger).toBe(true);
+    });
+
+    it("returns the raw stroop amount alongside the display value", async () => {
+      // Returning only the display string would force every consumer to parse
+      // a decimal back to an integer to do arithmetic on it, guessing the
+      // scale on the way.
+      mockQueryBalances.mockResolvedValue([{ contractId: CONTRACT_A, balance: "1" }]);
+
+      const res = await request(app).get(`/accounts/${ALICE}/balance`);
+
+      expect(res.body.balances[0].balance).toBe("1");
+      expect(res.body.balances[0].displayBalance).toBe("0.0000001");
     });
 
-    it("returns empty balances array for unknown address", async () => {
+    it("returns an empty balances array for an unknown address", async () => {
       mockQueryBalances.mockResolvedValue([]);
 
       const res = await request(app).get(`/accounts/GUNKNOWN/balance`);
@@ -43,10 +60,40 @@ describe("Accounts route handlers", () => {
       expect(res.body.balances).toHaveLength(0);
     });
 
-    it("includes a derived_from_ledger field in the response", async () => {
-        mockQueryBalances.mockResolvedValue([]);
-        const res = await request(app).get(`/accounts/${ALICE}/balance`);
-        expect(res.body).toHaveProperty("derived_from_ledger", true);
+    it("says the figure is derived, not read from chain", async () => {
+      // Part of the contract, not decoration: this is a sum over the indexed
+      // window, so it reads low for an address that held tokens before the
+      // start ledger. A caller that mistakes it for an on-chain balance read
+      // will be wrong in a way the numbers themselves do not reveal.
+      mockQueryBalances.mockResolvedValue([]);
+
+      const res = await request(app).get(`/accounts/${ALICE}/balance`);
+
+      expect(res.body).toHaveProperty("derivedFromLedger", true);
+      expect(res.body.note).toMatch(/not read from chain/i);
+    });
+
+    it("scopes the query to the selected network", async () => {
+      // Summing two chains' transfers for one address produces a figure that
+      // corresponds to no balance anywhere.
+      mockQueryBalances.mockResolvedValue([]);
+
+      const res = await request(app)
+        .get(`/accounts/${ALICE}/balance`)
+        .query({ network: "testnet" });
+
+      expect(res.status).toBe(200);
+      expect(mockQueryBalances).toHaveBeenCalledWith(ALICE, "testnet");
+      expect(res.body.network).toBe("testnet");
+    });
+
+    it("rejects a network this deployment does not serve, without querying", async () => {
+      const res = await request(app)
+        .get(`/accounts/${ALICE}/balance`)
+        .query({ network: "mainnet" });
+
+      expect(res.status).toBe(400);
+      expect(mockQueryBalances).not.toHaveBeenCalled();
     });
   });
 });

src/api/accounts.ts

@@ -1,5 +1,5 @@
 import { Router, Request, Response, NextFunction } from "express";
-import { getAccountSummary } from "../db";
+import { getAccountSummary, queryBalances } from "../db";
 import { toDisplayAmount } from "../api";
 import { createAccountsTransfersRouter } from "../routes/accounts/transfers";
 import { parseOr400 } from "../openapi/validation";
@@ -28,6 +28,43 @@ export function createAccountsRouter(): Router {
 
   router.use("/:address/transfers", createAccountsTransfersRouter());
 
+  // ── GET /accounts/:address/balance ─────────────────────────────────────────
+  /**
+   * Per-token balance for an address, derived from indexed transfers.
+   *
+   * `derivedFromLedger` and the note are part of the contract, not decoration:
+   * this is a sum over the indexed window, so an address that held a token
+   * before the indexer's start ledger reads low, and one that was net-negative
+   * over that window reads negative. A caller that mistakes this for an
+   * on-chain balance read will be wrong in a way the numbers do not reveal.
+   */
+  router.get(
+    "/:address/balance",
+    async (req: Request, res: Response, next: NextFunction) => {
+      try {
+        const { address } = req.params;
+        const network = requestNetwork(req);
+        const rows = await queryBalances(address, network);
+
+        res.json({
+          address,
+          network,
+          balances: rows.map((row) => ({
+            contractId: row.contractId,
+            balance: row.balance,
+            displayBalance: toDisplayAmount(row.balance),
+          })),
+          derivedFromLedger: true,
+          note:
+            "Derived by summing indexed transfers, not read from chain. Excludes " +
+            "any history before the indexer's start ledger.",
+        });
+      } catch (err) {
+        next(err);
+      }
+    }
+  );
+
   // ── GET /accounts/:address/summary ─────────────────────────────────────────
   router.get(
     "/:address/summary",

src/db.ts

@@ -231,6 +231,52 @@ export async function setLastIndexedLedger(ledger: number, network?: Network): P
   );
 }
 
+// ─── Derived balances ─────────────────────────────────────────────────────────
+export type BalanceRow = {
+  contractId: string;
+  balance: string;
+};
+
+/**
+ * Per-token balance for an address, derived by summing what it received and
+ * subtracting what it sent across the indexed history.
+ *
+ * This is a *derived* figure, not an on-chain balance read. It is only correct
+ * from the ledger the indexer started at: anything the address held before
+ * that is invisible here, so the number can be lower than reality and, for an
+ * address that was net-negative over the indexed window, can even be negative.
+ * The route says so in its response rather than presenting it as authoritative.
+ *
+ * Scoped by network — summing two chains' transfers for the same address
+ * produces a figure that corresponds to no balance anywhere.
+ */
+export async function queryBalances(
+  address: string,
+  network?: Network
+): Promise<BalanceRow[]> {
+  const net = resolveNetwork(network);
+
+  return observeDbQuery("queryBalances", () =>
+    prisma.$queryRaw<BalanceRow[]>`
+      SELECT
+        "contractId",
+        (
+          COALESCE(SUM(CASE WHEN "toAddress"   = ${address} THEN CAST("amount" AS NUMERIC) ELSE 0 END), 0) -
+          COALESCE(SUM(CASE WHEN "fromAddress" = ${address} THEN CAST("amount" AS NUMERIC) ELSE 0 END), 0)
+        )::TEXT AS "balance"
+      FROM "wraith"."TokenTransfer"
+      WHERE "network" = ${net}
+        AND ("toAddress" = ${address} OR "fromAddress" = ${address})
+      GROUP BY "contractId"
+      HAVING (
+        COALESCE(SUM(CASE WHEN "toAddress"   = ${address} THEN CAST("amount" AS NUMERIC) ELSE 0 END), 0) -
+        COALESCE(SUM(CASE WHEN "fromAddress" = ${address} THEN CAST("amount" AS NUMERIC) ELSE 0 END), 0)
+      ) <> 0
+      ORDER BY "contractId"
+    `
+  );
+}
+
 // ─── Backfill cursor helpers ───────────────────────────────────────────────
 export interface BackfillCursorState {
   startLedger: number;