tapimo 0.7.0 → 0.7.2

package/src/apps/data/routes/activities.ts

@@ -1,3 +1,5 @@
+// TODO(tidx-v1): Restore `queryOutbound` from commit `de87725` after TIDX v1 ships. Remove the receipt-side merge and bounded follow-up lookup.
+
 import { Hono, type Context } from 'hono'
 import { Address, Hex } from 'ox'
 import { type Log, parseEventLogs, zeroAddress } from 'viem'
@@ -14,7 +16,7 @@ import * as OpenApi from '../../../internal/OpenApi.js'
 import * as Response from '../../../internal/Response.js'
 import * as Schema from '../../../internal/Schema.js'
 import * as Store from '../../../internal/Store.js'
-import type * as Tidx from '../../../internal/Tidx.js'
+import * as Tidx from '../../../internal/Tidx.js'
 import * as Timing from '../../../internal/Timing.js'
 import * as Ttl from '../../../internal/Ttl.js'
 import * as Value from '../../../internal/Value.js'
@@ -54,7 +56,7 @@ export namespace schema {
       .optional(z.nullable(Valuation.schema.Value))
       .check(
         z.describe(
-          'The amount’s nominal value in the requested `denomination`. `null` when the token is ' +
+          'The amount’s nominal value in the requested `valuation.currency`. `null` when the token is ' +
             'unverified, its display currency has no rate, or rates were unavailable.',
         ),
       ),
@@ -74,7 +76,7 @@ export namespace schema {
   /** Page-level resources: valuation rate provenance. */
   export const Meta = z
     .object({
-      pricing: z
+      valuation: z
         .optional(Valuation.schema.Pricing)
         .check(
           z.describe(
@@ -1408,7 +1410,6 @@ export namespace schema {
       .strictObject({
         chainId: Schema.ChainIdQuery,
         cursor: Schema.Cursor,
-        denomination: Schema.Denomination,
         // Folding is opt-in: by default every item is returned at the root.
         group: z
           ._default(Schema.booleanQuery(), false)
@@ -1430,6 +1431,7 @@ export namespace schema {
             ),
             z.meta({ examples: [true] }),
           ),
+        'valuation.currency': Schema.Denomination,
       })
       .check(
         z.describe(
@@ -1471,7 +1473,6 @@ export namespace schema {
     export const Query = z
       .strictObject({
         chainId: Schema.ChainIdQuery,
-        denomination: Schema.Denomination,
         include: includeQuery,
         // Raw-log capture is opt-in: it can add a large `events` array to every
         // item, so the default response stays lean.
@@ -1483,6 +1484,7 @@ export namespace schema {
             ),
             z.meta({ examples: [true] }),
           ),
+        'valuation.currency': Schema.Denomination,
       })
       .check(z.describe('Query parameters for the transaction activity request.'))
 
@@ -1736,7 +1738,7 @@ function baseFor(options: {
 }
 
 /**
- * A normalized provider row. Mirrors the TIDX `receipts ⋈ logs` join
+ * A normalized provider row. Mirrors the bounded receipt/log lookups
  * (`source: 'q1'`, full log columns) and the decoded `Transfer` projection
  * (`source: 'q2'`, transfer columns), so the classification pipeline does not
  * care which query produced the row.
@@ -1789,8 +1791,8 @@ type TxGroup = {
  * Creates address-scoped activity handlers, mounted under the `/addresses`
  * composer. Exposes `GET /:address/activities`.
  *
- * Runs the full activity classification pipeline: three TIDX sub-queries
- * (outbound `receipts ⋈ logs`, inbound transfers, outbound transfers) merged
+ * Runs the full activity classification pipeline: outbound receipt/log
+ * lookups plus inbound and outbound transfer queries, merged
  * and decoded into typed items (`transfer`/`mint`/`burn`/`swap`/
  * `approval`/`session-closed`/`access-key-created`/`access-key-revoked`/
  * `token-created`/`burn-blocked`/`channel-opened`/`channel-funded`/
@@ -1882,7 +1884,7 @@ export function addresses(options: addresses.Options = {}) {
         // Build immutable token and structured amount copies from RPC metadata.
         const { items, rates } = await enrichTokens(c, {
           chainId,
-          denomination: query.denomination ?? 'USD',
+          denomination: query['valuation.currency'] ?? 'USD',
           include: query.include,
           items: unenrichedItems,
           oracle,
@@ -1895,7 +1897,7 @@ export function addresses(options: addresses.Options = {}) {
         return c.json(
           Response.validated(schema.getAddressActivities.Response, {
             data,
-            ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
+            ...(rates ? { meta: { valuation: Valuation.pricing(rates, oracle) } } : {}),
             nextCursor,
           }),
           200,
@@ -2016,7 +2018,7 @@ export function transactions(options: transactions.Options = {}) {
         // Build immutable token and structured amount copies from RPC metadata.
         const { items, rates } = await enrichTokens(c, {
           chainId,
-          denomination: query.denomination ?? 'USD',
+          denomination: query['valuation.currency'] ?? 'USD',
           include: query.include,
           items: unenrichedItems,
           oracle,
@@ -2025,7 +2027,7 @@ export function transactions(options: transactions.Options = {}) {
         return c.json(
           Response.validated(schema.getTransactionActivities.Response, {
             data: items,
-            ...(rates ? { meta: { pricing: Valuation.pricing(rates, oracle) } } : {}),
+            ...(rates ? { meta: { valuation: Valuation.pricing(rates, oracle) } } : {}),
           }),
           200,
         )
@@ -2217,8 +2219,8 @@ export declare namespace list {
 /**
  * Creates a TIDX-backed {@link Provider} that runs three sub-queries in
  * parallel and merges them:
- * - Q1 (outbound): `receipts ⋈ logs` for txs where the address is `from` or
- *   `fee_payer`, yielding full log rows.
+ * - Q1 (outbound): page receipts where the address is `from` or `fee_payer`,
+ *   then fetch the selected transactions' logs with a bounded lookup.
  * - Q2 (inbound): decoded `Transfer` events to the address.
  * - Q3 (outbound transfers): decoded `Transfer` events from the address
  *   (catches access-key-signed sends where `tx.from` differs from the address).
@@ -2236,16 +2238,8 @@ export function tidx(deps: tidx.Deps): Provider {
   }
 
   /**
-   * Q1: every log of each transaction the address sent or paid the fee for,
-   * via a single `receipts ⋈ logs` join filtered on `from OR fee_payer`.
-   *
-   * The cursor uses a two-predicate keyset (`block_num <= N` AND `(block_num <
-   * N OR tx_idx < M)`) rather than a plain `block_num < N`: the `<= N` upper
-   * bound lets the ClickHouse planner seek to the cursor block on the
-   * `(block_num, tx_idx)` primary key instead of scanning from the tip, which
-   * is what avoids planner 422s on busy addresses. Over-fetch `limit * 4`
-   * (never `OFFSET`) because one tx fans out into many log rows that
-   * `groupByTx` collapses back into a single group.
+   * Q1 pages outbound receipts, then fetches their logs by bounded block range
+   * and transaction hash. The cursor preserves block and transaction index order.
    */
   async function queryOutbound(options: {
     address: Address.Address
@@ -2254,50 +2248,90 @@ export function tidx(deps: tidx.Deps): Provider {
   }): Promise<Row[]> {
     const { address, cursor, limit } = options
     const keyset = cursor
-      ? `AND receipts.block_num <= ${cursor.blockNum} AND (receipts.block_num < ${cursor.blockNum} OR receipts.tx_idx < ${cursor.txIdx})`
+      ? `AND block_num <= ${cursor.blockNum} AND (block_num < ${cursor.blockNum} OR tx_idx < ${cursor.txIdx})`
       : ''
-    // Raw-table join (no signature-decoded CTE), so inline SQL is cast to `string`.
-    const result = await tidxClient.fetch({
+    const queryLimit = limit + 1
+    const fetchReceipts = (side: 'fee_payer' | 'from') =>
+      tidxClient.fetch({
+        chainId,
+        // Raw-table query (no signature-decoded CTE), so the inline SQL is cast
+        // to `string`.
+        query: `
+          SELECT tx_hash, block_num, block_timestamp, tx_idx, "from", fee_payer
+          FROM receipts
+          WHERE "${side}" = '${address}' ${keyset}
+          ORDER BY block_num DESC, tx_idx DESC
+          LIMIT ${queryLimit}
+        ` as string,
+      })
+
+    // Fetching `limit + 1` from each side is sufficient to form the newest
+    // `limit + 1` transactions after the two ordered sets are merged.
+    const [paid, sent] = await Promise.all([fetchReceipts('fee_payer'), fetchReceipts('from')])
+    const seen = new Set<string>()
+    const receipts = [...paid.rows, ...sent.rows]
+      .map((r) => ({
+        blockNum: Number(Value.toNumber(r['block_num'])),
+        blockTimestamp: Number(Value.toNumber(r['block_timestamp'])),
+        feePayer: lowerOrNull(r['fee_payer']),
+        txHash: lowerHash(r['tx_hash']),
+        txIdx: Number(Value.toNumber(r['tx_idx'])),
+        txSender: lowerOrNull(r['from']),
+      }))
+      .filter((receipt) => {
+        if (seen.has(receipt.txHash)) return false
+        seen.add(receipt.txHash)
+        return true
+      })
+      .sort((a, b) => {
+        if (a.blockNum !== b.blockNum) return b.blockNum - a.blockNum
+        return b.txIdx - a.txIdx
+      })
+      .slice(0, queryLimit)
+    if (receipts.length === 0) return []
+
+    const blocks = receipts.map((receipt) => receipt.blockNum)
+    const receiptByHash = new Map(receipts.map((receipt) => [receipt.txHash, receipt]))
+    const txHashes = receipts.map((receipt) => `'${receipt.txHash}'`).join(', ')
+
+    // `logs` is not keyed by transaction hash, so pair the bounded hash list
+    // with the selected receipts' block range to avoid a full archive scan.
+    const logs = await tidxClient.fetch({
       chainId,
+      // Raw-table query (no signature-decoded CTE), so the inline SQL is cast
+      // to `string`.
       query: `
-        SELECT
-          receipts.tx_hash AS tx_hash,
-          receipts.block_num AS block_num,
-          receipts.block_timestamp AS block_timestamp,
-          receipts.tx_idx AS tx_idx,
-          receipts."from" AS tx_sender,
-          receipts.fee_payer AS fee_payer,
-          logs.address AS log_address,
-          logs.selector AS selector,
-          logs.topic1 AS topic1,
-          logs.topic2 AS topic2,
-          logs.topic3 AS topic3,
-          logs.data AS data,
-          logs.log_idx AS log_idx
-        FROM receipts
-        INNER JOIN logs ON logs.tx_hash = receipts.tx_hash
-        WHERE (receipts."from" = '${address}' OR receipts.fee_payer = '${address}') ${keyset}
-        ORDER BY receipts.block_num DESC, receipts.tx_idx DESC
-        LIMIT ${limit * 4}
+        SELECT tx_hash, block_num, tx_idx, log_idx, address, selector, topic1, topic2, topic3, data
+        FROM logs
+        WHERE block_num BETWEEN ${Math.min(...blocks)} AND ${Math.max(...blocks)}
+          AND tx_hash IN (${txHashes})
+        ORDER BY block_num DESC, tx_idx DESC, log_idx ASC
       ` as string,
     })
 
-    return result.rows.map((r) => ({
-      blockNum: Number(Value.toNumber(r['block_num'])),
-      blockTimestamp: Number(Value.toNumber(r['block_timestamp'])),
-      data: Value.toText(r['data']) ?? null,
-      feePayer: lowerOrNull(r['fee_payer']),
-      logAddress: lower(r['log_address']),
-      logIdx: Number(Value.toNumber(r['log_idx'])),
-      selector: Value.toText(r['selector']) ?? null,
-      source: 'q1' as const,
-      topic1: Value.toText(r['topic1']) ?? null,
-      topic2: Value.toText(r['topic2']) ?? null,
-      topic3: Value.toText(r['topic3']) ?? null,
-      txHash: lowerHash(r['tx_hash']),
-      txIdx: Number(Value.toNumber(r['tx_idx'])),
-      txSender: lowerOrNull(r['tx_sender']),
-    }))
+    const rows = logs.rows.flatMap((r) => {
+      const receipt = receiptByHash.get(lowerHash(r['tx_hash']))
+      if (!receipt) return []
+      return [
+        {
+          blockNum: receipt.blockNum,
+          blockTimestamp: receipt.blockTimestamp,
+          data: Value.toText(r['data']) ?? null,
+          feePayer: receipt.feePayer,
+          logAddress: lower(r['address']),
+          logIdx: Number(Value.toNumber(r['log_idx'])),
+          selector: Value.toText(r['selector']) ?? null,
+          source: 'q1' as const,
+          topic1: Value.toText(r['topic1']) ?? null,
+          topic2: Value.toText(r['topic2']) ?? null,
+          topic3: Value.toText(r['topic3']) ?? null,
+          txHash: receipt.txHash,
+          txIdx: receipt.txIdx,
+          txSender: receipt.txSender,
+        },
+      ]
+    })
+    return mergeAndSort(rows, [], [])
   }
 
   /** Q2/Q3: decoded `Transfer` events on one side of the address. */
@@ -2313,18 +2347,43 @@ export function tidx(deps: tidx.Deps): Provider {
         ? `"to" = '${address}' AND "from" != '${address}'`
         : `"from" = '${address}' AND "to" != '${address}'`
     const keyset = cursor ? `AND block_num < ${cursor.blockNum}` : ''
-    const result = await tidxClient.fetch({
-      chainId,
-      query: `
+    const query = (blockKey?: string) => `
         SELECT "from", "to", address, value, tx_hash, block_num, block_timestamp, log_idx, tx_idx
         FROM Transfer
         WHERE ${where} ${keyset}
-        ORDER BY block_num DESC, tx_idx DESC
-        LIMIT ${limit * 4}
-      `,
-      signatures: [transferSignature],
-    })
-    return result.rows.map((r) => ({
+        ${blockKey ? `ORDER BY ${blockKey} DESC, tx_idx DESC` : ''}
+        LIMIT ${blockKey ? limit * 4 : Schema.countCap}
+      `
+    const result = await (async () => {
+      try {
+        return await tidxClient.fetch({
+          chainId,
+          query: query('block_num'),
+          signatures: [transferSignature],
+        })
+      } catch (error) {
+        if (!Tidx.isDeterministicError(error)) throw error
+        try {
+          // The expression blocks a mis-selected block-ordered top-N walk.
+          return await tidxClient.fetch({
+            chainId,
+            query: query('block_num + 0'),
+            signatures: [transferSignature],
+          })
+        } catch (fallbackError) {
+          if (!Tidx.isDeterministicError(fallbackError)) throw fallbackError
+          const result = await tidxClient.fetch({
+            chainId,
+            query: query(),
+            signatures: [transferSignature],
+          })
+          // An unordered sample cannot safely produce an activity cursor.
+          if (result.rows.length >= Schema.countCap) throw fallbackError
+          return result
+        }
+      }
+    })()
+    const rows = result.rows.map((r) => ({
       blockNum: Number(Value.toNumber(r['block_num'])),
       blockTimestamp: Number(Value.toNumber(r['block_timestamp'])),
       data: null,
@@ -2344,6 +2403,7 @@ export function tidx(deps: tidx.Deps): Provider {
       txIdx: Number(Value.toNumber(r['tx_idx'])),
       txSender: null,
     }))
+    return mergeAndSort([], rows, []).slice(0, limit * 4)
   }
 
   return {

package/src/apps/data/routes/balances.test.ts

@@ -1,3 +1,5 @@
+/** @module-tag localnet */
+
 import { Schema } from 'tapimo'
 import { FxOracle } from 'tapimo/apps'
 import { Value as core_Value } from 'ox'
@@ -5,9 +7,10 @@ import { Actions } from 'viem/tempo'
 
 import * as TestApp from '../../../../test/App.js'
 import * as Runtime from '../../../../test/runtime.js'
+import * as Tempo from '../../../../test/Tempo.js'
 import * as TestViem from '../../../../test/Viem.js'
+import * as Tidx from '../../../internal/Tidx.js'
 import * as Balances from './balances.js'
-import * as Tokens from './tokens.js'
 
 // Deterministic EUR-based rate set so conversion math is exact in assertions.
 const fixed = FxOracle.from({
@@ -31,19 +34,37 @@ function app(options: TestApp.create.Options = {}) {
   return TestApp.client({ db, ...options })
 }
 
-async function holderWithBalance(client: ReturnType<typeof app>) {
+const holderWithBalance = (async () => {
   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
-}
+  const address = Tempo.accounts[1]!.address.toLowerCase() as `0x${string}`
+  const tidx = Tidx.getClient({
+    chainId: runtime.chainId,
+    tidx: { auth: process.env.TIDX_AUTH, baseUrl: runtime.tidxUrl },
+  })
+  const rpc = TestViem.getClient()
+  // Global setup funds this ephemeral account once. Wait for TIDX to index its
+  // faucet delta so discovery exercises a stable, low-activity holder.
+  for (let attempt = 0; attempt < 30; attempt++) {
+    const [balance, indexed] = await Promise.all([
+      Actions.token.getBalance(rpc, { account: address, token: TestApp.tokenWithHolders }),
+      tidx.fetch({
+        chainId: runtime.chainId,
+        engine: 'clickhouse',
+        // Raw-table query, so the inline SQL is cast to `string`.
+        query: `
+          SELECT token
+          FROM address_holder_deltas
+          WHERE holder = '${address}' AND token = '${TestApp.tokenWithHolders}'
+          LIMIT 1
+        ` as string,
+      }),
+    ])
+    if (balance.amount > 0n && indexed.rows.length > 0) return address
+    if (attempt < 29) await new Promise((resolve) => setTimeout(resolve, 500))
+  }
+  throw new Error('expected funded test account to reach TIDX')
+})()
 
 describe('GET /addresses/:address/balances', () => {
   test('parses the total count include', () => {
@@ -63,7 +84,7 @@ 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)
+    const holder = await holderWithBalance
     expect(holder).toMatch(/^0x[0-9a-f]{40}$/)
 
     const response = await client.v1.addresses[':address'].balances.$get(
@@ -147,7 +168,7 @@ describe('GET /addresses/:address/balances', () => {
 
   test('embeds an exact balance total on demand via include=totalCount', async () => {
     const client = app()
-    const holder = await holderWithBalance(client)
+    const holder = await holderWithBalance
 
     const response = await client.v1.addresses[':address'].balances.$get(
       { param: { address: holder }, query: { include: 'totalCount', limit: '5' } },
@@ -204,7 +225,7 @@ describe('GET /addresses/:address/balances', () => {
 
   test('surfaces a 502 when RPC correction is unavailable', async () => {
     const client = app({ rpc: { url: () => 'http://127.0.0.1:1' } })
-    const holder = await holderWithBalance(client)
+    const holder = await holderWithBalance
     const response = await client.v1.addresses[':address'].balances.$get(
       { param: { address: holder }, query: {} },
       TestApp.auth,
@@ -281,7 +302,7 @@ describe('GET /addresses/:address/balances', () => {
       ],
     })
     const client = app({ db: logoDb })
-    const holder = await holderWithBalance(client)
+    const holder = await holderWithBalance
     expect(holder).toMatch(/^0x[0-9a-f]{40}$/)
 
     // The seeded holder is a holder of a verified token, so the verified
@@ -306,7 +327,7 @@ describe('GET /addresses/:address/balances', () => {
 
   test('narrows balances by currency and retains verification', async () => {
     const client = app()
-    const holder = await holderWithBalance(client)
+    const holder = await holderWithBalance
     expect(holder).toMatch(/^0x[0-9a-f]{40}$/)
 
     const response = await client.v1.addresses[':address'].balances.$get(
@@ -322,11 +343,9 @@ describe('GET /addresses/:address/balances', () => {
     }
   })
 
-  test('flags fee-usable holdings with feeEligible', async () => {
+  test('includes feeEligible on balance rows', 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 holder = await holderWithBalance
 
     const response = await client.v1.addresses[':address'].balances.$get(
       { param: { address: holder }, query: { limit: '20' } },
@@ -336,20 +355,14 @@ describe('GET /addresses/:address/balances', () => {
     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).
+    expect(body.data.length).toBeGreaterThan(0)
     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('values each verified holding in the default denomination', async () => {
     await TestApp.verifiedSeed(db, runtime.chainId)
     const client = app()
-    const holder = await holderWithBalance(client)
+    const holder = await holderWithBalance
 
     const response = await client.v1.addresses[':address'].balances.$get(
       { param: { address: holder }, query: { limit: '50' } },
@@ -368,11 +381,11 @@ describe('GET /addresses/:address/balances', () => {
   test('values holdings in a requested denomination', async () => {
     await TestApp.verifiedSeed(db, runtime.chainId)
     const client = app({ fx: { oracle: fixed } })
-    const holder = await holderWithBalance(client)
+    const holder = await holderWithBalance
 
     // Denominations are case-insensitive.
     const response = await client.v1.addresses[':address'].balances.$get(
-      { param: { address: holder }, query: { denomination: 'aud', limit: '50' } },
+      { param: { address: holder }, query: { limit: '50', 'valuation.currency': 'aud' } },
       TestApp.auth,
     )
     const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
@@ -383,7 +396,7 @@ describe('GET /addresses/:address/balances', () => {
     const expected = core_Value.format((core_Value.from(pathUsd!.formatted, 6) * 16n) / 10n, 6)
     expect(pathUsd?.valuation).toEqual({ amount: expected, currency: 'AUD' })
     // Consulted rates surface their provenance response-wide.
-    expect(body.meta?.pricing).toMatchInlineSnapshot(`
+    expect(body.meta?.valuation).toMatchInlineSnapshot(`
       {
         "asOf": "2026-01-01T00:00:00.000Z",
         "basis": "nominal",
@@ -395,10 +408,10 @@ describe('GET /addresses/:address/balances', () => {
   test('nulls valuations when rates are unavailable', async () => {
     await TestApp.verifiedSeed(db, runtime.chainId)
     const client = app({ fx: { oracle: FxOracle.ecb({ url: 'http://127.0.0.1:1' }) } })
-    const holder = await holderWithBalance(client)
+    const holder = await holderWithBalance
 
     const response = await client.v1.addresses[':address'].balances.$get(
-      { param: { address: holder }, query: { denomination: 'AUD', limit: '50' } },
+      { param: { address: holder }, query: { limit: '50', 'valuation.currency': 'AUD' } },
       TestApp.auth,
     )
     const body = await TestApp.json(response, Balances.schema.getAddressBalances.Response)
@@ -408,7 +421,7 @@ describe('GET /addresses/:address/balances', () => {
     expect(response.status).toBe(200)
     expect(body.data.length).toBeGreaterThan(0)
     for (const entry of body.data) expect(entry.valuation).toBeNull()
-    expect(body.meta?.pricing).toBeUndefined()
+    expect(body.meta?.valuation).toBeUndefined()
   })
 
   test('rejects denominations the oracle does not price', async () => {
@@ -418,7 +431,7 @@ describe('GET /addresses/:address/balances', () => {
     const response = await client.v1.addresses[':address'].balances.$get(
       {
         param: { address: `0x${'11'.repeat(20)}` },
-        query: { currency: 'JPY', denomination: 'JPY' },
+        query: { currency: 'JPY', 'valuation.currency': 'JPY' },
       },
       TestApp.auth,
     )
@@ -432,7 +445,7 @@ describe('GET /addresses/:address/balances', () => {
 
   test('restricts the page to fee tokens when feeEligible=true', async () => {
     const client = app()
-    const holder = await holderWithBalance(client)
+    const holder = await holderWithBalance
 
     const response = await client.v1.addresses[':address'].balances.$get(
       {

package/src/apps/data/routes/balances.ts

@@ -52,7 +52,6 @@ export namespace schema {
             ),
           ),
         cursor: Schema.Cursor,
-        denomination: Schema.Denomination,
         feeEligible: z
           .optional(Schema.booleanQuery())
           .check(
@@ -67,6 +66,7 @@ export namespace schema {
         include: Schema.totalCountInclude,
         limit: Schema.Limit,
         page: Schema.Page,
+        'valuation.currency': Schema.Denomination,
         verified: z
           .optional(Schema.booleanQuery())
           .check(
@@ -144,7 +144,7 @@ export namespace schema {
           .nullable(Valuation.schema.Value)
           .check(
             z.describe(
-              'The holding’s nominal value in the requested `denomination`, or `null` when the ' +
+              'The holding’s nominal value in the requested `valuation.currency`, or `null` when the ' +
                 'token is unverified, its display currency has no rate, or rates were unavailable.',
             ),
           ),
@@ -155,7 +155,7 @@ export namespace schema {
     /** Page-level resources: opt-in counts plus valuation rate provenance. */
     export const Meta = z
       .object({
-        pricing: z
+        valuation: z
           .optional(Valuation.schema.Pricing)
           .check(
             z.describe(
@@ -259,7 +259,7 @@ export function addresses(options: addresses.Options = {}) {
           chainId,
           currency: query.currency,
           cursor: query.cursor,
-          denomination: query.denomination ?? 'USD',
+          denomination: query['valuation.currency'] ?? 'USD',
           feeEligible,
           feeTokens,
           includeTotalCount: query.include.includes('totalCount'),
@@ -468,7 +468,7 @@ async function getAddressBalances(
   }
 
   const meta = {
-    ...(rates ? { pricing: Valuation.pricing(rates, oracle) } : {}),
+    ...(rates ? { valuation: Valuation.pricing(rates, oracle) } : {}),
     ...(includeTotalCount ? { totalCount: corrected.length, totalCountCapped: false } : {}),
   }
   return {

package/src/apps/data/routes/blocks.test.ts

@@ -1,3 +1,5 @@
+/** @module-tag localnet */
+
 import { Schema } from 'tapimo'
 import { Hex } from 'ox'
 import { zeroHash } from 'viem'

package/src/apps/data/routes/coingecko.test.ts

@@ -1,4 +1,5 @@
 import { Address, Hash } from 'ox'
+import { Schema } from 'tapimo'
 
 import * as TestApp from '../../../../test/App.js'
 import * as Runtime from '../../../../test/runtime.js'
@@ -59,6 +60,20 @@ describe('GET /gecko/:chainId/assets/:address', () => {
     )
     expect(response.status).toBe(400)
   })
+
+  test('returns 404 for an address that is not a TIP-20 token', async () => {
+    const client = TestApp.client()
+    const response = await client.gecko[':chainId'].assets[':address'].$get(
+      // A syntactically valid address that is not a registered TIP-20: the
+      // metadata read reverts, which must surface as a `404`, not a `502`.
+      { param: { chainId, address: '0xc97613eb1c39b0b57267739b5400ab08f8c4c285' } },
+      TestApp.auth,
+    )
+    const body = await TestApp.json(response, Schema.ErrorResponse)
+
+    expect(response.status).toBe(404)
+    expect(body.error.code).toBe('not_found')
+  })
 })
 
 describe('GET /gecko/:chainId/pairs', () => {
@@ -66,6 +81,7 @@ describe('GET /gecko/:chainId/pairs', () => {
     const client = TestApp.client()
     const response = await client.gecko[':chainId'].pairs.$get({ param: { chainId } }, TestApp.auth)
     expect(response.status).toBe(200)
+    expect(response.headers.get('server-timing')?.includes('coingecko_metadata;dur=')).toBe(true)
     const body = await TestApp.json(response, Coingecko.schema.PairsResponse)
     expect(body.pairs.length).toBeGreaterThan(0)
     const pair = body.pairs[0]!
@@ -169,6 +185,12 @@ describe('GET /gecko/:chainId/events', () => {
     )
     expect(response.status).toBe(200)
     const body = await TestApp.json(response, Coingecko.schema.EventsResponse)
+    // The fan-out segments only emit once the window contains fills.
+    if (body.events.length > 0) {
+      const timing = response.headers.get('server-timing')
+      expect(timing?.includes('coingecko_pair_index;dur=')).toBe(true)
+      expect(timing?.includes('coingecko_metadata;dur=')).toBe(true)
+    }
     for (const event of body.events) {
       expect(event.eventType).toBe('swap')
       expect(Hash.validate(event.pairId)).toBe(true)