feat: implement accounts balance route with ledger-derived token balances

Author: K1NGD4VID

src/__tests__/routes/accounts.test.ts

@@ -0,0 +1,52 @@
+import request from "supertest";
+import { createApp } from "../../api";
+import { queryBalances } from "../../db";
+
+// Mock the DB module
+jest.mock("../../db", () => ({
+  ...jest.requireActual("../../db"),
+  queryBalances: jest.fn(),
+  prisma: { $queryRaw: jest.fn() },
+}));
+
+const mockQueryBalances = queryBalances as jest.MockedFunction<typeof queryBalances>;
+
+describe("Accounts route handlers", () => {
+  const app = createApp();
+
+  describe("GET /accounts/:address/balance", () => {
+    const ALICE = "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF";
+    const CONTRACT_A = "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM";
+
+    it("returns per-token derived balance for a known address", async () => {
+      mockQueryBalances.mockResolvedValue([
+        { 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"
+      });
+      expect(res.body.derived_from_ledger).toBe(true);
+    });
+
+    it("returns empty balances array for unknown address", async () => {
+      mockQueryBalances.mockResolvedValue([]);
+
+      const res = await request(app).get(`/accounts/GUNKNOWN/balance`);
+
+      expect(res.status).toBe(200);
+      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);
+    });
+  });
+});

src/api.ts

@@ -9,6 +9,7 @@ import { createAccountsRouter } from "./api/accounts";
 import { createWebhooksRouter } from "./api/webhooks";
 import { getAllCachedTokens } from "./tokenCache";
 import { register, priceRequestsTotal } from "./metrics";
+import accountsRouter from "./routes/accounts";
 
 // ── Rate limiting ─────────────────────────────────────────────────────────────
 const limiter = rateLimit({
@@ -143,6 +144,9 @@ export function createApp(): express.Application {
     res.json({ ok: true, uptime: process.uptime() });
   });
 
+  // ── GET /accounts/:address/balance ──────────────────────────────────────────
+  app.use("/accounts", accountsRouter);
+
   // ── GET /readyz — K8s/Render readiness probe ─────────────────────────────────
   /**
    * Returns 200 only when:

src/db.ts

@@ -506,21 +506,9 @@ export async function getNftOwner(
 
 // ─── Account summary helpers ──────────────────────────────────────────────────
 
-/**
- * Incrementally update materialized aggregates for every address touched by
- * `records`. Called inside the same logical write as upsertTransfers so the
- * two tables never diverge.
- *
- * Strategy:
- *   1. Accumulate per-(address, contractId) deltas in memory.
- *   2. Emit one raw UPSERT per unique pair — O(unique addresses) DB round-trips.
- *
- * Using raw SQL because Prisma cannot do arithmetic on string-typed NUMERIC columns.
- */
 export async function upsertAccountSummaries(records: TransferRecord[]): Promise<void> {
   if (records.length === 0) return;
 
-  // Accumulate deltas keyed by "address|contractId"
   const deltas = new Map<
     string,
     { address: string; contractId: string; sent: bigint; received: bigint; count: number; lastAt: Date }
@@ -567,10 +555,6 @@ export async function upsertAccountSummaries(records: TransferRecord[]): Promise
   }
 }
 
-/**
- * Return all asset rows for a given address, optionally filtered to one contract.
- * O(1) — reads directly from the materialized AccountSummary table.
- */
 export async function getAccountSummary(address: string, contractId?: string) {
   return prisma.accountSummary.findMany({
     where: {
@@ -653,6 +637,36 @@ export async function queryAccountSummaries(params: AccountSummaryQueryParams) {
   };
 }
 
+// ─── Balance aggregate query ──────────────────────────────────────────────────
+export type BalanceRow = {
+  contractId: string;
+  balance: string;
+};
+
+export async function queryBalances(address: string): Promise<BalanceRow[]> {
+  const end = dbQueryDurationSeconds.startTimer({ operation: "queryBalances" });
+
+  const rows = await 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 "TokenTransfer"
+    WHERE "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"
+  `;
+
+  end();
+  return rows;
+}
+
 // ─── Combined address query ───────────────────────────────────────────────────
 export type AllTransfersQueryParams = {
   address: string;

src/routes/accounts.ts

@@ -0,0 +1,32 @@
+import { Router, Request, Response, NextFunction } from "express";
+import { queryBalances } from "../db";
+import { toDisplayAmount } from "../api";
+
+const router = Router();
+
+/**
+ * GET /accounts/:address/balance
+ * Returns per-token derived balances for an address by summing incoming
+ * transfers and subtracting outgoing ones from the indexed history.
+ */
+router.get("/:address/balance", async (req: Request, res: Response, next: NextFunction) => {
+  try {
+    const { address } = req.params;
+    const rows = await queryBalances(address);
+
+    const balances = rows.map((row) => ({
+      token: row.contractId,
+      balance: toDisplayAmount(row.balance),
+    }));
+
+    res.json({
+      balances,
+      derived_from_ledger: true,
+      note: "This balance is derived from indexed token transfers and may not include pre-indexer history.",
+    });
+  } catch (err) {
+    next(err);
+  }
+});
+
+export default router;