tapimo 0.7.0 → 0.7.2

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

@@ -1,7 +1,10 @@
+/** @module-tag localnet */
+
 import type * as z from 'zod/mini'
 import { Value as core_Value } from 'ox'
 import { Db, Schema } from 'tapimo'
 import { FxOracle } from 'tapimo/apps'
+import { Addresses } from 'viem/tempo'
 
 import * as TestApp from '../../../../test/App.js'
 import * as Runtime from '../../../../test/runtime.js'
@@ -32,6 +35,50 @@ describe('GET /transfers', () => {
     expect(Transfers.schema.getTransfers.Query.safeParse({ include: 'token' }).success).toBe(false)
   })
 
+  test.runIf(Runtime.get().mode === 'testnet')(
+    'excludes historical non-TIP-20 transfers for affected mainnet accounts',
+    async () => {
+      const client = TestApp.client()
+      const cases = [
+        {
+          address: Schema.Address.parse('0xad511ba481696d73bcf47d411ad9ea4f77023ddc'),
+          blockNumber: '17681311',
+          expectedCount: 1,
+        },
+        {
+          address: Schema.Address.parse('0x5eb391a6c707ae1168989bbc6c5f5db4a0e06837'),
+          blockNumber: '31227810',
+          expectedCount: 0,
+        },
+      ]
+
+      for (const { address, blockNumber, expectedCount } of cases) {
+        const response = await client.v1.transfers.$get(
+          {
+            query: {
+              address,
+              'blockNumber.from': blockNumber,
+              'blockNumber.to': blockNumber,
+              chainId: '4217',
+              include: 'totalCount',
+              limit: '10',
+              page: '1',
+            },
+          },
+          TestApp.auth,
+        )
+        const body = await TestApp.json(response, Transfers.schema.getTransfers.Response)
+
+        expect(response.status).toBe(200)
+        expect(body.data).toHaveLength(expectedCount)
+        expect(body.data.every((entry) => entry.sourceToken.address.startsWith('0x20c0'))).toBe(
+          true,
+        )
+        expect(body.meta?.totalCount).toBe(expectedCount)
+      }
+    },
+  )
+
   test('degrades unavailable verification data to null valuations', async () => {
     const db = () =>
       Db.postgres({
@@ -63,9 +110,9 @@ describe('GET /transfers', () => {
     const unsupportedResponse = await client.v1.transfers.$get(
       {
         query: {
-          denomination: 'JPY',
           limit: '5',
           token: TestApp.tokenWithHolders,
+          'valuation.currency': 'JPY',
         },
       },
       TestApp.auth,
@@ -666,7 +713,7 @@ describe('GET /transfers', () => {
         amount: core_Value.format(BigInt(entry.sourceAmount.baseUnits), 6),
         currency: 'USD',
       })
-    expect(body.meta?.pricing).toBeUndefined()
+    expect(body.meta?.valuation).toBeUndefined()
   })
 
   test('values transfer legs in a requested denomination', async () => {
@@ -676,7 +723,13 @@ describe('GET /transfers', () => {
 
     // Denominations are case-insensitive.
     const response = await client.v1.transfers.$get(
-      { query: { denomination: 'aud', limit: '5', token: TestApp.tokenWithHolders } },
+      {
+        query: {
+          limit: '5',
+          token: TestApp.tokenWithHolders,
+          'valuation.currency': 'aud',
+        },
+      },
       TestApp.auth,
     )
     const body = await TestApp.json(response, Transfers.schema.getTransfers.Response)
@@ -689,7 +742,7 @@ describe('GET /transfers', () => {
         amount: core_Value.format((BigInt(entry.sourceAmount.baseUnits) * 16n) / 10n, 6),
         currency: 'AUD',
       })
-    expect(body.meta?.pricing).toMatchInlineSnapshot(`
+    expect(body.meta?.valuation).toMatchInlineSnapshot(`
       {
         "asOf": "2026-01-01T00:00:00.000Z",
         "basis": "nominal",
@@ -751,3 +804,112 @@ describe('GET /transfers', () => {
     `)
   })
 })
+
+describe('collate', () => {
+  /** A minimal transfer row at a `(block, log index)` position. */
+  const row = (block: number, logIndex: number) => ({
+    block_num: block,
+    log_idx: logIndex,
+    tx_hash: `0x${'cc'.repeat(32)}`,
+  })
+
+  test('passes a lone engine-paged stream through untouched', () => {
+    const rows = [row(40, 4), row(20, 2)]
+    expect(
+      Transfers.collate([{ rows, sample: false }], { limit: 3, offset: 0, order: 'desc' }),
+    ).toEqual({
+      capped: false,
+      rows,
+    })
+  })
+
+  test('merges split streams: dedupes, orders globally, applies the window', () => {
+    const shared = row(30, 3)
+    const { capped, rows } = Transfers.collate(
+      [
+        { rows: [row(40, 4), shared], sample: false },
+        { rows: [{ ...shared }, row(10, 1)], sample: false },
+      ],
+      { limit: 2, offset: 1, order: 'desc' },
+    )
+    expect(capped).toBe(false)
+    expect(rows.map((entry) => entry['block_num'])).toEqual([30, 10])
+  })
+
+  test('orders and pages a below-cap fallback sample', () => {
+    const { capped, rows } = Transfers.collate([{ rows: [row(10, 1), row(30, 3)], sample: true }], {
+      limit: 2,
+      offset: 0,
+      order: 'desc',
+    })
+    expect(capped).toBe(false)
+    expect(rows.map((entry) => entry['block_num'])).toEqual([30, 10])
+  })
+
+  test('flags a fallback sample that hit the cap', () => {
+    const sample = Array.from({ length: Schema.countCap }, (_, index) => row(index + 1, index))
+    const { capped, rows } = Transfers.collate(
+      [
+        { rows: [row(40_000, 20_000)], sample: false },
+        { rows: sample, sample: true },
+      ],
+      { limit: 3, offset: 0, order: 'desc' },
+    )
+    expect(capped).toBe(true)
+    expect(rows.map((entry) => entry['block_num'])).toEqual([40_000, 10_000, 9_999])
+  })
+})
+
+describe('foldCount', () => {
+  const swapper = `0x${'11'.repeat(20)}`
+  const recipient = `0x${'22'.repeat(20)}`
+  const sourceToken = '0x20c0000000000000000000000000000000000001'
+  const destinationToken = '0x20c0000000000000000000000000000000000002'
+  /** One `Transfer` leg row within a transaction. */
+  const leg = (txHash: string, logIndex: number, from: string, to: string, token: string) => ({
+    address: token,
+    from,
+    log_idx: logIndex,
+    to,
+    tx_hash: txHash,
+    value: '100',
+  })
+  const plain = leg(`0x${'ee'.repeat(32)}`, 0, swapper, recipient, sourceToken)
+
+  test('subtracts classified bundle legs', () => {
+    const txHash = `0x${'dd'.repeat(32)}`
+    // The account server's approve+swap+forward multicall: source into the
+    // DEX, swapped token back, delivery to the recipient, plus the fee leg.
+    const rows = [
+      leg(txHash, 0, swapper, Addresses.stablecoinDex, sourceToken),
+      leg(txHash, 1, Addresses.stablecoinDex, swapper, destinationToken),
+      leg(txHash, 2, swapper, recipient, destinationToken),
+      leg(txHash, 3, swapper, Addresses.feeManager, sourceToken),
+      plain,
+    ]
+    expect(Transfers.foldCount(rows, { capped: false })).toEqual({
+      totalCount: 2,
+      totalCountCapped: false,
+    })
+  })
+
+  test('keeps a cap-truncated sample conservative', () => {
+    const txHash = `0x${'dd'.repeat(32)}`
+    // A partial bundle: the DEX return leg fell outside the cap, defeating
+    // classification. The conservative pass still suppresses the plumbing.
+    const rows = [
+      leg(txHash, 0, swapper, Addresses.stablecoinDex, sourceToken),
+      leg(txHash, 2, swapper, recipient, destinationToken),
+      leg(txHash, 3, swapper, Addresses.feeManager, sourceToken),
+      plain,
+    ]
+    expect(Transfers.foldCount(rows, { capped: false })).toEqual({
+      totalCount: 4,
+      totalCountCapped: false,
+    })
+    expect(Transfers.foldCount(rows, { capped: true })).toEqual({
+      totalCount: 2,
+      totalCountCapped: true,
+    })
+  })
+})

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

@@ -12,7 +12,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'
@@ -26,6 +26,13 @@ import * as Valuation from './valuation.js'
 // the indexer SQL.
 export const signature = 'event Transfer(address indexed from, address indexed to, uint256 value)'
 
+// TIP-20 contracts occupy the deterministic `0x20c0…` range. Full-width
+// bounds compare correctly as PostgreSQL bytea and ClickHouse hex strings.
+const tip20AddressRange = [
+  '0x20c0000000000000000000000000000000000000',
+  '0x20c1000000000000000000000000000000000000',
+] as const
+
 // A memo'd TIP-20 transfer emits `TransferWithMemo` alongside the plain
 // `Transfer`; the two rows match on `(tx_hash, from, to, amount, token)`. A
 // text memo is decoded into `memo`; an MPP attribution fingerprint memo is
@@ -96,7 +103,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.',
         ),
       ),
@@ -169,13 +176,13 @@ export namespace schema {
         'blockNumber.to': Schema.blockNumberBound('transfers', 'to'),
         chainId: Schema.ChainIdQuery,
         cursor: Schema.Cursor,
-        denomination: Schema.Denomination,
         include: includeQuery,
         limit: Schema.Limit,
         order: Schema.Order,
         page: Schema.Page,
         'timestamp.from': Schema.timestampBound('transfers', 'from'),
         'timestamp.to': Schema.timestampBound('transfers', 'to'),
+        'valuation.currency': Schema.Denomination,
       })
       .check(
         z.refine((query) => !(query.address && (query.sender || query.recipient)), {
@@ -281,7 +288,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(
@@ -343,7 +350,7 @@ export function transfers(options: transfers.Options = {}) {
     }),
     Cache.response<App.Environment>({
       cacheControl: Cache.policies.feed,
-      name: 'tempo-api:transfers:v2',
+      name: 'tempo-api:transfers:v3',
       key: (c) => Cache.urlKey(c, schema.getTransfers.Query),
     }),
     async (c) => {
@@ -356,7 +363,7 @@ export function transfers(options: transfers.Options = {}) {
 
       const options = c.req.valid('query')
       const chainId = options.chainId ?? c.get('chainId')
-      const denomination = options.denomination ?? 'USD'
+      const denomination = options['valuation.currency'] ?? 'USD'
 
       // Cursor pages carry current valuations and curated verification data.
       if (options.cursor !== undefined) Cache.setPolicy(c, Cache.policies.metadata)
@@ -569,9 +576,16 @@ export function transfers(options: transfers.Options = {}) {
           },
         )
 
-        const counts = countPromise ? await countPromise : undefined
+        // Wait at most 2.5s more for a still-pending count (cold indexer
+        // reads have stalled 20s+); a timed-out count omits `meta` counts.
+        const counts = countPromise
+          ? await Promise.race([
+              countPromise,
+              new Promise<undefined>((resolve) => setTimeout(() => resolve(undefined), 2_500)),
+            ])
+          : undefined
         const meta = {
-          ...(rates ? { pricing: Valuation.pricing(rates, oracle) } : {}),
+          ...(rates ? { valuation: Valuation.pricing(rates, oracle) } : {}),
           ...counts,
         }
 
@@ -630,7 +644,7 @@ export function query(c: Context<App.Environment>, options: query.Options) {
         }
       },
       {
-        key: `transfers:v1:${chainId}:${options.order}:${options.token ?? ''}:${options.eitherSide ?? ''}:${options.sender ?? ''}:${options.recipient ?? ''}:${options.fromBlock ?? ''}:${options.toBlock ?? ''}:${options.fromTimestamp ?? ''}:${options.toTimestamp ?? ''}:${cursor ? `cursor:${cursor[0]}:${cursor[1]}` : options.page !== undefined && options.page > 1 ? `page:${options.page}` : 'head'}:${options.limit}`,
+        key: `transfers:v2:${chainId}:${options.order}:${options.token ?? ''}:${options.eitherSide ?? ''}:${options.sender ?? ''}:${options.recipient ?? ''}:${options.fromBlock ?? ''}:${options.toBlock ?? ''}:${options.fromTimestamp ?? ''}:${options.toTimestamp ?? ''}:${cursor ? `cursor:${cursor[0]}:${cursor[1]}` : options.page !== undefined && options.page > 1 ? `page:${options.page}` : 'head'}:${options.limit}`,
         store,
         ttl: Ttl.seconds(15),
       },
@@ -713,35 +727,56 @@ export async function scan(deps: scan.Deps, options: scan.Options): Promise<scan
     )
   const addressScoped = address !== undefined
   const window = addressScoped ? (offset ?? 0) + limit + 1 : limit + 1
+  // Only one-sided `"from"`/`"to"` equality shapes hit the planner's
+  // deterministic top-N kill, so only they take the capped fallback.
+  const sideFiltered =
+    addressScoped || options.sender !== undefined || options.recipient !== undefined
   const fetchRows = async (side?: 'from' | 'to') => {
     const sideFilters =
       side !== undefined && address !== undefined
         ? [`"${side}" = '${address}'`, ...filters]
         : filters
     const where = sideFilters.length > 0 ? `WHERE ${sideFilters.join(' AND ')}` : ''
-    const result = await tidx.fetch({
-      chainId,
-      ...(tokenScoped ? { engine: 'clickhouse' } : { signatures: [signature] }),
-      query: `
-        SELECT "from", "to", ${tokenScoped ? 'token AS address, amount AS value' : 'address, value'}, tx_hash, block_num, log_idx, block_timestamp
-        FROM ${tokenScoped ? 'token_transfers' : 'Transfer'}
-        ${where}
-        ORDER BY block_num ${direction}, log_idx ${direction}
-        LIMIT ${window}${!addressScoped && offset !== undefined ? ` OFFSET ${offset}` : ''}
-      ` as string,
-    })
-    return result.rows
+    const select = `"from", "to", ${tokenScoped ? 'token AS address, amount AS value' : 'address, value'}, tx_hash, block_num, log_idx, block_timestamp`
+    const table = tokenScoped ? 'token_transfers' : 'Transfer'
+    try {
+      const result = await tidx.fetch({
+        chainId,
+        ...(tokenScoped ? { engine: 'clickhouse' } : { signatures: [signature] }),
+        query: `
+          SELECT ${select}
+          FROM ${table}
+          ${where}
+          ORDER BY block_num ${direction}, log_idx ${direction}
+          LIMIT ${window}${!addressScoped && offset !== undefined ? ` OFFSET ${offset}` : ''}
+        ` as string,
+      })
+      return { rows: result.rows, sample: false }
+    } catch (error) {
+      // The planner kills a one-sided top-N walk when its matches sit far
+      // from head (422 `db error`). Retry as a plain capped scan, returning
+      // the whole sample so truncation stays detectable.
+      if (!sideFiltered || !Tidx.isDeterministicError(error)) throw error
+      const result = await tidx.fetch({
+        chainId,
+        ...(tokenScoped ? { engine: 'clickhouse' } : { signatures: [signature] }),
+        query: `
+          SELECT ${select}
+          FROM ${table}
+          ${where}
+          LIMIT ${Schema.countCap}
+        ` as string,
+      })
+      return { rows: result.rows, sample: true }
+    }
   }
 
   // TIDX cannot plan `(from = X OR to = X)` over the decoded Transfer table.
-  // Merge two bounded, server-filtered streams while preserving global order.
-  const rows = addressScoped
-    ? mergeTransferRows((await Promise.all([fetchRows('from'), fetchRows('to')])).flat(), {
-        limit: limit + 1,
-        offset: offset ?? 0,
-        order,
-      })
-    : await fetchRows()
+  // Fetch one bounded, server-filtered stream per side and collate app-side.
+  const fetched = addressScoped
+    ? await Promise.all([fetchRows('from'), fetchRows('to')])
+    : [await fetchRows()]
+  const { capped, rows } = collate(fetched, { limit: limit + 1, offset: offset ?? 0, order })
 
   // The next page anchors below the last fetched row's `(block, log_idx)`.
   const page = Cursor.paginate({
@@ -789,13 +824,69 @@ export async function scan(deps: scan.Deps, options: scan.Options): Promise<scan
       })
   }
 
-  return { hasMore: page.hasMore, items, limit, nextCursor: page.nextCursor }
+  // A truncated sample cannot anchor keyset pagination without silently
+  // skipping unseen matches, so the page ends the list instead.
+  return {
+    capped,
+    hasMore: capped ? false : page.hasMore,
+    items,
+    limit,
+    nextCursor: capped ? null : page.nextCursor,
+  }
+}
+
+/**
+ * Collates per-side transfer streams into one ordered page window: split and
+ * sampled streams are deduped, globally ordered, and paged app-side, while a
+ * lone engine-paged stream passes through. `capped` marks a fallback sample
+ * that hit `Schema.countCap`: an arbitrary subset of that side's matches,
+ * unfit to anchor pagination or exact counts.
+ */
+export function collate(
+  fetched: readonly collate.Stream[],
+  options: collate.Options,
+): collate.Result {
+  const capped = fetched.some(({ rows, sample }) => sample && rows.length >= Schema.countCap)
+  const rows =
+    fetched.length > 1 || fetched.some(({ sample }) => sample)
+      ? mergeTransferRows(
+          fetched.flatMap(({ rows }) => rows),
+          options,
+        )
+      : (fetched[0]?.rows ?? [])
+  return { capped, rows }
+}
+
+export declare namespace collate {
+  /** One fetched transfer stream. */
+  type Stream = {
+    /** Raw TIDX rows. */
+    rows: readonly Record<string, unknown>[]
+    /** Whether the rows are an unordered, unpaged capped fallback sample. */
+    sample: boolean
+  }
+  /** The page window applied to the merged stream. */
+  type Options = {
+    /** Maximum merged rows to return. */
+    limit: number
+    /** Number of globally ordered rows to skip. */
+    offset: number
+    /** Global transfer ordering. */
+    order: 'asc' | 'desc'
+  }
+  /** The collated page window. */
+  type Result = {
+    /** Whether any fallback sample hit `Schema.countCap`. */
+    capped: boolean
+    /** The ordered page window rows. */
+    rows: readonly Record<string, unknown>[]
+  }
 }
 
 /** Deduplicates and globally orders bounded `from`/`to` transfer streams. */
 function mergeTransferRows(
   rows: readonly Record<string, unknown>[],
-  options: mergeTransferRows.Options,
+  options: collate.Options,
 ): Record<string, unknown>[] {
   const positioned: mergeTransferRows.PositionedRow[] = []
   const seen = new Set<string>()
@@ -817,14 +908,6 @@ function mergeTransferRows(
 }
 
 declare namespace mergeTransferRows {
-  type Options = {
-    /** Maximum merged rows to return. */
-    limit: number
-    /** Number of globally ordered rows to skip. */
-    offset: number
-    /** Global transfer ordering. */
-    order: 'asc' | 'desc'
-  }
   type PositionedRow = {
     /** Transfer block number. */
     blockNumber: number
@@ -852,6 +935,8 @@ export declare namespace scan {
   }
   /** A page of scanned `Transfer` rows. */
   type Page = {
+    /** Whether the page came from a cap-truncated fallback sample; such a page must not advance a poller cursor. */
+    capped: boolean
     hasMore: boolean
     items: readonly Item[]
     limit: number
@@ -860,13 +945,15 @@ export declare namespace scan {
 }
 
 /**
- * Builds shared transfer filters. A token predicate targets `token_transfers`'s
- * physical `token` column; unscoped queries omit it and use the `Transfer` CTE.
+ * Builds shared transfer filters. Token-scoped queries target `token_transfers`;
+ * unscoped queries constrain the decoded `Transfer` emitter to TIP-20 contracts.
  */
 function filterClauses(options: filterClauses.Options): string[] {
   const { fromBlock, fromTimestamp, recipient, sender, toBlock, toTimestamp, token } = options
-  const filters: string[] = []
-  if (token !== undefined) filters.push(`token = '${token}'`)
+  const filters =
+    token === undefined
+      ? [`address >= '${tip20AddressRange[0]}'`, `address < '${tip20AddressRange[1]}'`]
+      : [`token = '${token}'`]
   if (sender !== undefined) filters.push(`"from" = '${sender}'`)
   if (recipient !== undefined) filters.push(`"to" = '${recipient}'`)
   if (fromBlock !== undefined) filters.push(`block_num >= ${fromBlock}`)
@@ -897,7 +984,7 @@ export function count(c: Context<App.Environment>, options: count.Options): Prom
 
   return Timing.time(c, timing, () =>
     Store.memoize(() => countScan({ tidx }, { chainId, ...rest }), {
-      key: `transfers:count:v1:${chainId}:${rest.crossToken ? 'fold' : 'raw'}:${rest.token ?? ''}:${rest.eitherSide ?? ''}:${rest.sender ?? ''}:${rest.recipient ?? ''}:${rest.fromBlock ?? ''}:${rest.toBlock ?? ''}:${rest.fromTimestamp ?? ''}:${rest.toTimestamp ?? ''}`,
+      key: `transfers:count:v2:${chainId}:${rest.crossToken ? 'fold' : 'raw'}:${rest.token ?? ''}:${rest.eitherSide ?? ''}:${rest.sender ?? ''}:${rest.recipient ?? ''}:${rest.fromBlock ?? ''}:${rest.toBlock ?? ''}:${rest.fromTimestamp ?? ''}:${rest.toTimestamp ?? ''}`,
       store,
       ttl: Ttl.seconds(15),
     }),
@@ -946,40 +1033,54 @@ export async function countScan(
   // rows, classify each transaction, and subtract the folded-away legs. Bounded
   // by `countCap` like the raw count, so it stays within the indexer's budget.
   if (options.crossToken) {
+    // Only one-sided `"from"`/`"to"` equality shapes hit the planner's
+    // deterministic top-N kill, so only they take the capped fallback.
+    const sideFiltered =
+      address !== undefined || options.sender !== undefined || options.recipient !== undefined
     const fetchRows = async (side?: 'from' | 'to') => {
       const sideFilters =
         side !== undefined && address !== undefined
           ? [`"${side}" = '${address}'`, ...filters]
           : filters
       const sideWhere = sideFilters.length > 0 ? `WHERE ${sideFilters.join(' AND ')}` : ''
-      const result = await tidx.fetch({
-        chainId,
-        ...(tokenScoped ? { engine: 'clickhouse' } : { signatures: [signature] }),
-        query: `
-          SELECT tx_hash, block_num, log_idx, "from", "to", ${tokenScoped ? 'token AS address, amount AS value' : 'address, value'}
-          FROM ${tokenScoped ? 'token_transfers' : 'Transfer'}
-          ${sideWhere}
-          ORDER BY block_num, log_idx
-          LIMIT ${Schema.countCap}
-        ` as string,
-      })
-      return result.rows
+      const select = `tx_hash, block_num, log_idx, "from", "to", ${tokenScoped ? 'token AS address, amount AS value' : 'address, value'}`
+      const table = tokenScoped ? 'token_transfers' : 'Transfer'
+      try {
+        const result = await tidx.fetch({
+          chainId,
+          ...(tokenScoped ? { engine: 'clickhouse' } : { signatures: [signature] }),
+          query: `
+            SELECT ${select}
+            FROM ${table}
+            ${sideWhere}
+            ORDER BY block_num, log_idx
+            LIMIT ${Schema.countCap}
+          ` as string,
+        })
+        return { rows: result.rows, sample: false }
+      } catch (error) {
+        // Same planner kill as the page's side scan; the folded count is
+        // already capped, so a plain capped scan keeps its semantics.
+        if (!sideFiltered || !Tidx.isDeterministicError(error)) throw error
+        const result = await tidx.fetch({
+          chainId,
+          ...(tokenScoped ? { engine: 'clickhouse' } : { signatures: [signature] }),
+          query: `
+            SELECT ${select}
+            FROM ${table}
+            ${sideWhere}
+            LIMIT ${Schema.countCap}
+          ` as string,
+        })
+        return { rows: result.rows, sample: true }
+      }
     }
-    const rows =
+    const fetched =
       address !== undefined
-        ? mergeTransferRows((await Promise.all([fetchRows('from'), fetchRows('to')])).flat(), {
-            limit: Schema.countCap,
-            offset: 0,
-            order: 'asc',
-          })
-        : await fetchRows()
-    const rawCount = rows.length
-    let suppressed = 0
-    for (const legs of legsByTransaction(rows).values()) {
-      const bundle = classifyCrossToken(legs)
-      if (bundle) suppressed += bundle.suppressLogIndexes.length
-    }
-    return { totalCountCapped: rawCount >= Schema.countCap, totalCount: rawCount - suppressed }
+        ? await Promise.all([fetchRows('from'), fetchRows('to')])
+        : [await fetchRows()]
+    const { capped, rows } = collate(fetched, { limit: Schema.countCap, offset: 0, order: 'asc' })
+    return foldCount(rows, { capped })
   }
 
   const countRows = async (additionalFilters: readonly string[] = []) => {
@@ -991,7 +1092,7 @@ export async function countScan(
       query: `
         SELECT count(*) AS total
         FROM (
-          SELECT 1
+          SELECT DISTINCT tx_hash, log_idx
           FROM ${tokenScoped ? 'token_transfers' : 'Transfer'}
           ${countWhere}
           LIMIT ${Schema.countCap}
@@ -1028,6 +1129,40 @@ export declare namespace countScan {
     }
 }
 
+/**
+ * Folds a capped `Transfer` scan into the cross-token count. Classified
+ * bundles subtract their folded-away legs; a cap-truncated sample can hold
+ * partial bundles that defeat classification, so it subtracts every DEX and
+ * fee leg instead, keeping the reported lower bound from overcounting.
+ */
+export function foldCount(
+  rows: readonly Record<string, unknown>[],
+  options: foldCount.Options,
+): count.Result {
+  const { capped } = options
+  let suppressed = 0
+  for (const legs of legsByTransaction(rows).values()) {
+    if (capped) {
+      suppressed += legs.filter(isBundleLeg).length
+      continue
+    }
+    const bundle = classifyCrossToken(legs)
+    if (bundle) suppressed += bundle.suppressLogIndexes.length
+  }
+  return {
+    totalCount: rows.length - suppressed,
+    totalCountCapped: capped || rows.length >= Schema.countCap,
+  }
+}
+
+export declare namespace foldCount {
+  /** Options for {@link foldCount}. */
+  type Options = {
+    /** Whether the rows include a cap-truncated fallback sample. */
+    capped: boolean
+  }
+}
+
 /** `'tx1', 'tx2', …` SQL `IN` list of the page's distinct transaction hashes. */
 function txInList(rows: memoMap.Options['rows']): string {
   return [...new Set(rows.map((row) => row.transactionHash.toLowerCase()))]
@@ -1118,6 +1253,15 @@ type Leg = {
   to: z.output<typeof Schema.Address>
 }
 
+/** Whether a leg is cross-token bundle plumbing: a DEX leg or the fee leg. */
+function isBundleLeg(leg: Leg): boolean {
+  return (
+    Address.isEqual(leg.to, Addresses.stablecoinDex) ||
+    Address.isEqual(leg.from, Addresses.stablecoinDex) ||
+    Address.isEqual(leg.to, Addresses.feeManager)
+  )
+}
+
 /** The folded shape of a detected cross-token transfer, anchored on its delivery leg. */
 type CrossTokenBundle = {
   /** Log index of the delivery leg the transfer folds onto. */
@@ -1161,13 +1305,7 @@ function classifyCrossToken(legs: readonly Leg[]): CrossTokenBundle | undefined
   // Require a token change so plain same-token DEX activity is not folded.
   if (!delivery || Address.isEqual(toDex.address, delivery.address)) return undefined
   const suppressLogIndexes = legs
-    .filter(
-      (leg) =>
-        leg.logIndex !== delivery.logIndex &&
-        (Address.isEqual(leg.to, Addresses.stablecoinDex) ||
-          Address.isEqual(leg.from, Addresses.stablecoinDex) ||
-          Address.isEqual(leg.to, Addresses.feeManager)),
-    )
+    .filter((leg) => leg.logIndex !== delivery.logIndex && isBundleLeg(leg))
     .map((leg) => leg.logIndex)
   return {
     deliveryLogIndex: delivery.logIndex,