tapimo 0.0.0 → 0.0.2

package/src/apps/addresses.ts

@@ -0,0 +1,24 @@
+import { Hono } from 'hono'
+
+import type * as App from '../App.js'
+import * as Activities from './activities.js'
+import * as Balances from './balances.js'
+
+/**
+ * Composes the `/addresses/:address/*` route surface from the address-scoped
+ * sub-routers exported by each resource module. The handlers and schemas live
+ * with the resource they describe (activities, balances); this composer only
+ * owns the `/addresses` mount path so docs grouping stays by tag while URLs
+ * stay nested under the parent resource.
+ *
+ * Only subject-relative resources live here — rows that cannot be interpreted
+ * without the path address (activity classification, held-token balances).
+ * Plain filtered views of canonical collections are reached via search params
+ * instead (`GET /transactions?address=…`, `GET /transfers?address=…`,
+ * `GET /transactions/receipts?address=…`).
+ */
+export function addresses() {
+  return new Hono<App.Environment>()
+    .route('/', Activities.addresses())
+    .route('/', Balances.addresses())
+}

package/src/apps/balances.test.ts

@@ -0,0 +1,274 @@
+import { Schema } from 'cadent'
+import { Value as core_Value } from 'ox'
+
+import * as TestApp from '../../test/App.js'
+import * as Runtime from '../../test/runtime.js'
+import * as Balances from './balances.js'
+import * as Tokens from './tokens.js'
+
+// Verified enrichment is store-backed now that the build-time bundle is gone, so
+// seed a shared in-memory verified store from the curated seeds file. Tests use
+// this wrapper instead of `TestApp.client` so the default app exposes the same
+// verified tokens the bundle used to provide; a test can still override
+// `verifiedTokens`.
+const runtime = Runtime.get()
+const verified = TestApp.verifiedStore(runtime.chainId)
+function app(options: TestApp.create.Options = {}) {
+  return TestApp.client({ verifiedTokens: { store: verified }, ...options })
+}
+
+async function holderWithBalance(client: ReturnType<typeof app>) {
+  if (runtime.mode === 'localnet')
+    return runtime.fixtures!.fundedAccounts[0]!.toLowerCase() as `0x${string}`
+  const holdersResponse = await client.v1.tokens[':token'].holders.$get(
+    { param: { token: TestApp.tokenWithHolders }, query: { limit: '5' } },
+    TestApp.auth,
+  )
+  const holders = await TestApp.json(holdersResponse, Tokens.schema.getTokenHolders.Response)
+  expect(holdersResponse.status).toBe(200)
+  const holder = holders.data[0]?.address
+  if (!holder) throw new Error('expected at least one holder')
+  return holder
+}
+
+describe('GET /addresses/:address/balances', () => {
+  test('returns an amount-ranked balance page with per-row token references', async () => {
+    const client = app()
+    const holder = await holderWithBalance(client)
+    expect(holder).toMatch(/^0x[0-9a-f]{40}$/)
+
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: holder }, query: { limit: '5' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('address_balances;dur=')).toBe(true)
+    expect(Array.isArray(body.data)).toBe(true)
+    expect(body.data.length).toBeLessThanOrEqual(5)
+    // Pagination fields stay at the response root; cursor pagination has no
+    // `page`, just an opaque `nextCursor`.
+    expect('page' in body).toBe(false)
+    expect(body.nextCursor === null || typeof body.nextCursor === 'string').toBe(true)
+
+    // Each row is a balance (`amount`/`formatted`) with the trimmed token
+    // reference inlined at `token`, per the embedded-resource convention.
+    expect(
+      body.data.every(
+        (entry) =>
+          /^\d+$/.test(entry.amount) &&
+          // `formatted` is `amount` scaled down by `decimals` (round-trips back
+          // to the base-unit amount).
+          /^\d+(\.\d+)?$/.test(entry.formatted) &&
+          core_Value.from(entry.formatted, entry.token.decimals) === BigInt(entry.amount) &&
+          /^0x[0-9a-f]{40}$/.test(entry.token.address) &&
+          typeof entry.token.currency === 'string' &&
+          Number.isInteger(entry.token.decimals) &&
+          typeof entry.token.name === 'string' &&
+          typeof entry.token.symbol === 'string' &&
+          typeof entry.token.verified === 'boolean',
+      ),
+    ).toBe(true)
+    // Results are restricted to TIP-20 tokens (deterministic `0x20c0…` factory
+    // addresses), so non-TIP-20 contracts in `token_balances_snapshot` are
+    // excluded.
+    expect(body.data.every((entry) => entry.token.address.startsWith('0x20c0'))).toBe(true)
+    // Amounts are returned largest-first.
+    const amounts = body.data.map((entry) => BigInt(entry.amount))
+    expect(amounts.every((amount, index) => index === 0 || amounts[index - 1]! >= amount)).toBe(
+      true,
+    )
+  })
+
+  test('embeds an exact balance total on demand via include=totalCount', async () => {
+    const client = app()
+    const holder = await holderWithBalance(client)
+
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: holder }, query: { include: 'totalCount', limit: '5' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('address_balances_count;dur=')).toBe(
+      true,
+    )
+    expect(Number.isInteger(body.meta?.totalCount)).toBe(true)
+    expect(body.meta!.totalCount).toBeGreaterThanOrEqual(body.data.length)
+    // The count is sort-key-pruned on ClickHouse, so it is exact (never capped).
+    expect(body.meta!.totalCountCapped).toBe(false)
+
+    // Without the include, `meta` is omitted and no count query runs.
+    const bareResponse = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: holder }, query: { limit: '5' } },
+      TestApp.auth,
+    )
+    const bare = await TestApp.json(bareResponse, Balances.schema.getAddressBalances.Response)
+    expect(bareResponse.status).toBe(200)
+    expect(bare.meta).toBeUndefined()
+    expect(bareResponse.headers.get('server-timing')?.includes('address_balances_count;dur=')).toBe(
+      false,
+    )
+  })
+
+  test('surfaces a 502 when balance data is unavailable', async () => {
+    // Point at an unreachable indexer so the upstream query fails deterministically.
+    const client = app({ tidx: { baseUrl: 'http://127.0.0.1:1' } })
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: TestApp.token }, query: {} },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    // The upstream message varies by failure; only the envelope is stable.
+    const { requestId, error } = body
+    const { message, ...stableError } = error
+
+    // Like the dedicated holders endpoint, balance lookups report upstream
+    // failure honestly rather than masquerading as an address holding nothing.
+    expect(response.status).toMatchInlineSnapshot(`502`)
+    expect(typeof requestId).toMatchInlineSnapshot(`"string"`)
+    expect(typeof message).toMatchInlineSnapshot(`"string"`)
+    expect(stableError).toMatchInlineSnapshot(`
+      {
+        "code": "upstream_error",
+      }
+    `)
+  })
+
+  test('rejects invalid account addresses', async () => {
+    // The typed client requires `address: `Hex.Hex`` so an invalid literal
+    // cannot pass through it; exercise the validator via `app.request`.
+    const response = await TestApp.create().request('/v1/addresses/not-an-address/balances', {
+      headers: { authorization: `Bearer ${TestApp.key.token}` },
+    })
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    const { requestId, ...stable } = body
+
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(typeof requestId).toMatchInlineSnapshot(`"string"`)
+    expect(stable).toMatchInlineSnapshot(`
+      {
+        "error": {
+          "code": "address_invalid",
+          "details": [
+            {
+              "message": "Invalid input",
+              "path": [
+                "address",
+              ],
+            },
+          ],
+          "message": "Invalid account address",
+        },
+      }
+    `)
+  })
+
+  test('rejects invalid pagination', async () => {
+    const client = app()
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: TestApp.token }, query: { limit: '0' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+    const { requestId, ...stable } = body
+
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(typeof requestId).toMatchInlineSnapshot(`"string"`)
+    expect(stable.error.code).toMatchInlineSnapshot(`"query_invalid"`)
+  })
+
+  test('restricts balances to verified tokens when verified=true', async () => {
+    const client = app()
+    const holder = await holderWithBalance(client)
+    expect(holder).toMatch(/^0x[0-9a-f]{40}$/)
+
+    // The seeded holder is a holder of a verified token, so the verified
+    // balances page must include at least that token.
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: holder }, query: { limit: '20', verified: 'true' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+    expect(response.status).toBe(200)
+    expect(body.data.length).toBeGreaterThan(0)
+    for (const balance of body.data) expect(balance.token.verified).toBe(true)
+  })
+
+  test('narrows balances by currency (implies verified)', async () => {
+    const client = app()
+    const holder = await holderWithBalance(client)
+    expect(holder).toMatch(/^0x[0-9a-f]{40}$/)
+
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: holder }, query: { limit: '20', currency: 'USD' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+    expect(response.status).toBe(200)
+    for (const balance of body.data) {
+      expect(balance.token.verified).toBe(true)
+      expect(balance.token.currency).toBe('USD')
+    }
+  })
+
+  test('flags fee-usable holdings with feeEligible', async () => {
+    const client = app()
+    // `tokenWithHolders` is pathUSD, the protocol's default fee token, so its
+    // holders hold a token that is always fee-usable.
+    const holder = await holderWithBalance(client)
+
+    const response = await client.v1.addresses[':address'].balances.$get(
+      { param: { address: holder }, query: { limit: '20' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+    expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('fee_token_set;dur=')).toBe(true)
+
+    // Every row carries the best-effort flag; the set resolves here, so it is a
+    // boolean on each row (rather than omitted).
+    for (const balance of body.data) expect(typeof balance.feeEligible).toBe('boolean')
+
+    // The pathUSD holding (which the holder is guaranteed to hold) is flagged
+    // fee-usable: pathUSD is the default fee token and has fee-AMM pools.
+    const pathUsd = body.data.find((balance) => balance.token.address === TestApp.tokenWithHolders)
+    expect(pathUsd?.feeEligible).toBe(true)
+  })
+
+  test('restricts the page to fee tokens when feeEligible=true', async () => {
+    const client = app()
+    const holder = await holderWithBalance(client)
+
+    const response = await client.v1.addresses[':address'].balances.$get(
+      {
+        param: { address: holder },
+        query: { feeEligible: 'true', include: 'totalCount', limit: '20' },
+      },
+      TestApp.auth,
+    )
+    if (runtime.mode === 'testnet' && response.status === 502) {
+      // Hosted TIDX can intermittently reject this live filtered balance query
+      // with a 422. Localnet still exercises the behavior strictly; on testnet,
+      // accept the documented upstream-error envelope instead of flaking CI.
+      const body = await TestApp.json(response, Schema.ErrorResponse)
+      expect(body.error.code).toBe('upstream_error')
+      return
+    }
+    const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
+    expect(response.status).toBe(200)
+
+    // Every returned holding is a fee token, and the holder's guaranteed
+    // pathUSD holding survives the filter.
+    expect(body.data.length).toBeGreaterThan(0)
+    for (const balance of body.data) expect(balance.feeEligible).toBe(true)
+    expect(body.data.some((balance) => balance.token.address === TestApp.tokenWithHolders)).toBe(
+      true,
+    )
+
+    // The opt-in count shares the filter, so it is at least the page size.
+    expect(body.meta!.totalCount).toBeGreaterThanOrEqual(body.data.length)
+  })
+})