tapimo 0.6.0 → 0.7.0

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

@@ -33,37 +33,16 @@ export const signature = 'event Transfer(address indexed from, address indexed t
 const memoSignature =
   'event TransferWithMemo(address indexed from, address indexed to, uint256 amount, bytes32 indexed memo)'
 
+const tokenFields = ['token.logoUri', 'token.verified'] as const
+
 /** Zod schemas owned by the transfer handlers. */
 export namespace schema {
-  /**
-   * The token moved by a transfer: its contract address and the transferred
-   * amount, plus the trimmed token reference spread in when requested via
-   * `include=token`. Reference fields are absent on the base (no-`include`)
-   * response and best-effort when requested (a row whose metadata is
-   * unavailable keeps just `address`/`amount`). Shared by every per-row
-   * transfer response across the API.
-   *
-   * The optional metadata fields are inlined here (rather than spread from
-   * `Tokens.schema.Token` via `z.partial`) so this module avoids referencing
-   * the `tokens` schema namespace at module-init time — `transfers` and
-   * `tokens` import each other for runtime helpers (`Transfers.query`,
-   * `Tokens.resolveToken`), and the schema-evaluation back-edge would
-   * otherwise deadlock the namespace.
-   */
+  /** A transfer token reference with RPC metadata. Inlined to avoid the `transfers`/`tokens` module cycle. */
   export const SourceToken = z
     .object({
       address: Schema.TokenAddress.check(z.describe('The TIP-20 token contract address on Tempo.')),
-      amount: z
-        .string()
-        .check(
-          z.regex(/^\d+$/),
-          z.describe(
-            'A non-negative whole number, given as a decimal string so very large token amounts keep full precision. Expressed in the smallest unit of the token.',
-          ),
-          z.meta({ examples: ['1000000'] }),
-        ),
       currency: z
-        .optional(z.string())
+        .string()
         .check(
           z.describe(
             'The currency label for this token, such as `USD` for USD-denominated stablecoins.',
@@ -71,7 +50,8 @@ export namespace schema {
           z.meta({ examples: ['USD'] }),
         ),
       decimals: z
-        .optional(z.number().check(z.int(), z.nonnegative()))
+        .number()
+        .check(z.int(), z.nonnegative())
         .check(
           z.describe(
             'The number of decimal places the token uses; Tempo stablecoins typically use 6.',
@@ -79,7 +59,7 @@ export namespace schema {
           z.meta({ examples: [6] }),
         ),
       logoUri: z.optional(z.string()).check(
-        z.describe('A URL for the token’s logo image, when one is available.'),
+        z.describe('A URL for the token’s logo image, returned with `include=token.logoUri`.'),
         z.meta({
           examples: [
             'https://api.tempo.xyz/data/4217/icons/0x20c0000000000000000000008f5425160ebe5525.svg',
@@ -87,35 +67,41 @@ export namespace schema {
         }),
       ),
       name: z
-        .optional(z.string())
+        .string()
         .check(z.describe('The token’s human-readable name.'), z.meta({ examples: ['USD Coin'] })),
       symbol: z
-        .optional(z.string())
+        .string()
         .check(
           z.describe('The short ticker symbol wallets and apps show for this token.'),
           z.meta({ examples: ['USDC'] }),
         ),
-      valuation: z
-        .optional(z.nullable(Valuation.schema.Value))
-        .check(
-          z.describe(
-            'The leg’s nominal value in the requested `denomination`. `null` when the token is ' +
-              'unverified, its display currency has no rate, or rates were unavailable.',
-          ),
-        ),
       verified: z
         .optional(z.boolean())
         .check(
-          z.describe('Whether this token is in Tempo’s curated verified token list.'),
+          z.describe(
+            'Whether this token is in Tempo’s curated verified list, returned with `include=token.verified`.',
+          ),
           z.meta({ examples: [true] }),
         ),
     })
     .check(
       z.describe(
-        'The token and amount that moved in this transfer, with token metadata added when you request `include=token`.',
+        'The token that moved in this transfer, with RPC metadata and optional curated fields.',
       ),
     )
 
+  /** A token amount carrying its nominal value in the requested denomination. */
+  const ValuedAmount = z.extend(Schema.TokenAmount, {
+    valuation: z
+      .optional(z.nullable(Valuation.schema.Value))
+      .check(
+        z.describe(
+          'The amount’s nominal value in the requested `denomination`. `null` when the token is ' +
+            'unverified, its display currency has no rate, or rates were unavailable.',
+        ),
+      ),
+  })
+
   /**
    * Filter predicates shared verbatim by the `GET /transfers` list query
    * ({@link getTransfers.Query}, which spreads `Predicates.shape`) and `transfer`
@@ -147,18 +133,17 @@ export namespace schema {
   export namespace getTransfers {
     /** Optional related resources that callers opt into via `include`. */
     export const Include = z
-      .enum(['crossToken', 'memo', 'token', 'totalCount'])
+      .enum(['crossToken', 'memo', ...tokenFields, 'totalCount'])
       .check(z.describe('Related resources to include only when you request them with `include`.'))
 
     /**
      * Parses a comma-separated `include` query value into a list of optional
-     * resources to embed. Extra lookups (token metadata, the `TransferWithMemo`
-     * memo/attribution decode, the capped total count) each run only when their
-     * resource is requested, keeping the base transfer page fast.
+     * resources to embed. Extra lookups run only when their resource is
+     * requested, keeping the base transfer page fast.
      */
     export const includeQuery = Schema.includeQuery(
       Include,
-      'Comma-separated related resources to include, such as `token,memo,crossToken,totalCount`.',
+      'Comma-separated related resources to include, such as `token.logoUri,token.verified,memo,crossToken,totalCount`.',
     )
 
     /**
@@ -225,11 +210,18 @@ export namespace schema {
             z.describe('The block number where this transfer was recorded.'),
             z.meta({ examples: [23456789] }),
           ),
+        destinationAmount: z
+          .optional(ValuedAmount)
+          .check(
+            z.describe(
+              'Amount delivered to the recipient for a cross-token transfer. Omitted with `destinationToken` for a same-token transfer.',
+            ),
+          ),
         destinationToken: z
           .optional(schema.SourceToken)
           .check(
             z.describe(
-              'The token and amount delivered to the recipient when it differs from `sourceToken` — a cross-token transfer routed through the DEX, where `sourceToken` is the token swapped in. Omitted for same-token transfers, and only returned when you request `include=crossToken`.',
+              'The token delivered to the recipient when it differs from `sourceToken`. Omitted for same-token transfers and returned only with `include=crossToken`.',
             ),
           ),
         id: z.string().check(
@@ -260,7 +252,8 @@ export namespace schema {
           z.describe('The account address that received the tokens.'),
         ),
         sender: Schema.Address.check(z.describe('The account address that sent the tokens.')),
-        sourceToken: schema.SourceToken.check(z.describe('The token and amount that moved.')),
+        sourceAmount: ValuedAmount.check(z.describe('Amount associated with `sourceToken`.')),
+        sourceToken: schema.SourceToken.check(z.describe('The token that moved.')),
         timestamp: z.iso
           .datetime()
           .check(
@@ -272,6 +265,14 @@ export namespace schema {
         ),
       })
       .check(
+        z.refine(
+          (data) =>
+            (data.destinationToken === undefined) === (data.destinationAmount === undefined),
+          {
+            error: '`destinationAmount` and `destinationToken` must be returned together.',
+            path: ['destinationAmount'],
+          },
+        ),
         z.describe(
           'One TIP-20 token transfer event, optionally including a payment memo for reconciliation or invoices.',
         ),
@@ -309,6 +310,14 @@ export namespace schema {
   }
 }
 
+type UnenrichedTransfer = Omit<
+  z.output<typeof schema.getTransfers.Transfer>,
+  'destinationAmount' | 'destinationToken' | 'sourceAmount' | 'sourceToken'
+> & {
+  destinationToken?: CrossToken | undefined
+  sourceToken: CrossToken
+}
+
 /** Creates transfer handlers. */
 export function transfers(options: transfers.Options = {}) {
   const oracle = options.fx?.oracle ?? FxOracle.ecb()
@@ -323,7 +332,7 @@ export function transfers(options: transfers.Options = {}) {
       description: 'List token transfer events across Tempo.',
       operationId: 'getTransfers',
       responses: OpenApi.responses({
-        errors: { 502: 'The upstream indexer could not serve this request.' },
+        errors: { 502: 'The indexer or Tempo RPC could not serve this request.' },
         success: {
           description: 'A page of token transfer events.',
           schema: schema.getTransfers.Response,
@@ -334,7 +343,7 @@ export function transfers(options: transfers.Options = {}) {
     }),
     Cache.response<App.Environment>({
       cacheControl: Cache.policies.feed,
-      name: 'tempo-api:transfers:v1',
+      name: 'tempo-api:transfers:v2',
       key: (c) => Cache.urlKey(c, schema.getTransfers.Query),
     }),
     async (c) => {
@@ -388,12 +397,7 @@ export function transfers(options: transfers.Options = {}) {
           timing: 'transfers',
         })
 
-        // Token metadata is opt-in. When requested, resolve each page token's
-        // metadata concurrently (sharing one verified-token fetch) and spread
-        // it into the row's `sourceToken`. Resolution is best-effort: a token
-        // whose metadata is unavailable keeps `sourceToken` as just
-        // `address`/`amount` on that row rather than failing the whole page.
-        let data: z.output<typeof schema.getTransfers.Transfer>[] = page.data.map((row) => ({
+        let data: UnenrichedTransfer[] = page.data.map((row) => ({
           blockNumber: row.blockNumber,
           id: `${row.transactionHash}-${row.logIndex}`,
           logIndex: row.logIndex,
@@ -460,43 +464,45 @@ export function transfers(options: transfers.Options = {}) {
           data.length > 0
             ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
             : undefined
-        if (options.include.includes('token') && data.length > 0 && snapshot) {
-          const uniqueTokens = Array.from(
-            new Set(
-              data.flatMap((transfer) => [
-                transfer.sourceToken.address,
-                ...(transfer.destinationToken ? [transfer.destinationToken.address] : []),
-              ]),
-            ),
-          )
-          const resolved = await Timing.time(c, 'tokens', () =>
+        const includeLogoUri = options.include.includes('token.logoUri')
+        const includeVerified = options.include.includes('token.verified')
+        const uniqueTokens = Array.from(
+          new Set(
+            data.flatMap((transfer) => [
+              transfer.sourceToken.address,
+              ...(transfer.destinationToken ? [transfer.destinationToken.address] : []),
+            ]),
+          ),
+        )
+        const tokensByAddress = new Map(
+          await Timing.time(c, 'tokens', () =>
             Promise.all(
-              uniqueTokens.map((token) =>
-                Tokens.resolveToken(c, {
-                  address: token,
-                  chainId,
-                  snapshot,
-                })
-                  .then((metadata) => [token, metadata] as const)
-                  .catch(() => [token, undefined] as const),
-              ),
+              uniqueTokens.map(async (token) => {
+                const [logoUri, metadata] = await Promise.all([
+                  includeLogoUri
+                    ? Timing.time(c, 'token_logo', () =>
+                        Tokens.getTokenLogo(c, { address: token, chainId }),
+                      ).catch(() => undefined)
+                    : undefined,
+                  Timing.time(c, 'token_metadata', () =>
+                    Tokens.getTokenMetadata(c, { address: token, chainId }),
+                  ),
+                ])
+                return [
+                  token.toLowerCase(),
+                  {
+                    ...metadata,
+                    logoUri: includeLogoUri
+                      ? (logoUri ??
+                        snapshot?.byAddress.get(token.toLowerCase())?.logoUri ??
+                        metadata.logoUri)
+                      : undefined,
+                  },
+                ] as const
+              }),
             ),
-          )
-          const tokensByAddress = new Map(resolved)
-          const withToken = <T extends { address: z.output<typeof Schema.TokenAddress> }>(
-            entry: T,
-          ) => {
-            const token = tokensByAddress.get(entry.address)
-            return token ? { ...entry, ...token } : entry
-          }
-          data = data.map((transfer) => ({
-            ...transfer,
-            sourceToken: withToken(transfer.sourceToken),
-            ...(transfer.destinationToken
-              ? { destinationToken: withToken(transfer.destinationToken) }
-              : {}),
-          }))
-        }
+          ),
+        )
 
         // Value each leg via its curated display currency, in the requested
         // denomination.
@@ -513,22 +519,55 @@ export function transfers(options: transfers.Options = {}) {
           denomination,
           oracle,
         })
-        const valued = <leg extends { address: string; amount: string }>(leg: leg) => ({
-          ...leg,
-          valuation: Valuation.valuationFor({
-            amount: BigInt(leg.amount),
-            denomination,
-            rates,
-            token: snapshot?.byAddress.get(leg.address.toLowerCase()),
-          }),
-        })
-        data = data.map((transfer) => ({
-          ...transfer,
-          sourceToken: valued(transfer.sourceToken),
-          ...(transfer.destinationToken
-            ? { destinationToken: valued(transfer.destinationToken) }
-            : {}),
-        }))
+        const enrich = (leg: CrossToken) => {
+          const metadata = tokensByAddress.get(leg.address.toLowerCase())
+          if (!metadata) throw new Error(`Token metadata unavailable for ${leg.address}`)
+          return {
+            amount: {
+              ...Value.tokenAmount({
+                baseUnits: leg.amount,
+                currency: metadata.currency,
+                decimals: metadata.decimals,
+              }),
+              valuation: Valuation.valuationFor({
+                amount: BigInt(leg.amount),
+                denomination,
+                rates,
+                token: snapshot?.byAddress.get(leg.address.toLowerCase()),
+              }),
+            },
+            token: {
+              address: leg.address,
+              currency: metadata.currency,
+              decimals: metadata.decimals,
+              ...(metadata.logoUri !== undefined ? { logoUri: metadata.logoUri } : {}),
+              name: metadata.name,
+              symbol: metadata.symbol,
+              ...(includeVerified && snapshot
+                ? { verified: snapshot.byAddress.has(leg.address.toLowerCase()) }
+                : {}),
+            },
+          }
+        }
+        const responseData: z.output<typeof schema.getTransfers.Transfer>[] = data.map(
+          ({ destinationToken, sourceToken, ...transfer }) => {
+            const source = enrich(sourceToken)
+            if (!destinationToken)
+              return {
+                ...transfer,
+                sourceAmount: source.amount,
+                sourceToken: source.token,
+              }
+            const destination = enrich(destinationToken)
+            return {
+              ...transfer,
+              destinationAmount: destination.amount,
+              destinationToken: destination.token,
+              sourceAmount: source.amount,
+              sourceToken: source.token,
+            }
+          },
+        )
 
         const counts = countPromise ? await countPromise : undefined
         const meta = {
@@ -538,7 +577,7 @@ export function transfers(options: transfers.Options = {}) {
 
         return c.json(
           Response.validated(schema.getTransfers.Response, {
-            data,
+            data: responseData,
             ...(Object.keys(meta).length > 0 ? { meta } : {}),
             nextCursor: page.nextCursor,
           }),
@@ -563,15 +602,13 @@ export declare namespace transfers {
 
 /**
  * Shared TIP-20 `Transfer` page query. Used by `GET /transfers` and the
- * webhook poller. Builds the signature-decoded `Transfer` CTE query, applies
+ * webhook poller. Builds signature-decoded `Transfer` CTE queries, applies
  * opaque keyset pagination on `(block_num, log_idx)`, and decodes rows into a
  * strongly-typed intermediate shape that each caller maps to its own public
  * response.
  *
- * `eitherSide` (the subject address must appear on _either_ side of the
- * transfer) is exposed alongside the one-sided `sender`/`recipient` filters
- * because composing it with the keyset cursor pre-WHERE in SQL is awkward at
- * the call site; the helper takes the knob directly.
+ * `eitherSide` is exposed alongside one-sided `sender`/`recipient` filters
+ * because it requires two upstream scans. The helper owns their ordered merge.
  *
  * Memoization lives inside the helper under one canonical `transfers:v1:…`
  * key derived from every filter — so equivalent filter combinations share a
@@ -661,11 +698,11 @@ export async function scan(deps: scan.Deps, options: scan.Options): Promise<scan
   // translate to a SQL OFFSET of `(page - 1) * limit` rows.
   const offset =
     options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : undefined
+  const address = options.eitherSide
 
-  // Transfer events filtered by any combination of contract / subject /
-  // sender / recipient / block / timestamp. Ordered by block then log
-  // index so transfers within a block stay stable. The keyset cursor clause is
-  // page-only and added on top of the shared filters below.
+  // Transfer events filtered by any combination of contract / sender /
+  // recipient / block / timestamp. The address shortcut is split below so
+  // each upstream query can use one indexed side.
   const filters = filterClauses(options)
   if (cursor !== undefined)
     filters.push(
@@ -674,24 +711,41 @@ export async function scan(deps: scan.Deps, options: scan.Options): Promise<scan
         { literal: Cursor.literal(cursor[1]!, 'int'), name: 'log_idx', order },
       ]),
     )
-  const where = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : ''
-
-  // Fetch one extra row to detect `hasMore` without a separate count query.
-  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 ${limit + 1}${offset !== undefined ? ` OFFSET ${offset}` : ''}
-    ` as string,
-  })
+  const addressScoped = address !== undefined
+  const window = addressScoped ? (offset ?? 0) + limit + 1 : limit + 1
+  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
+  }
+
+  // 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()
 
   // The next page anchors below the last fetched row's `(block, log_idx)`.
   const page = Cursor.paginate({
-    rows: result.rows,
+    rows,
     limit,
     key: (row) => {
       const block = Value.toNumber(row['block_num'])
@@ -738,6 +792,49 @@ export async function scan(deps: scan.Deps, options: scan.Options): Promise<scan
   return { hasMore: page.hasMore, items, limit, nextCursor: page.nextCursor }
 }
 
+/** Deduplicates and globally orders bounded `from`/`to` transfer streams. */
+function mergeTransferRows(
+  rows: readonly Record<string, unknown>[],
+  options: mergeTransferRows.Options,
+): Record<string, unknown>[] {
+  const positioned: mergeTransferRows.PositionedRow[] = []
+  const seen = new Set<string>()
+  for (const row of rows) {
+    const blockNumber = Value.toNumber(row['block_num'])
+    const logIndex = Value.toNumber(row['log_idx'])
+    const transactionHash = Value.toText(row['tx_hash'])
+    if (blockNumber === undefined || logIndex === undefined || !transactionHash) continue
+    const key = eventKey(transactionHash, logIndex)
+    if (seen.has(key)) continue
+    seen.add(key)
+    positioned.push({ blockNumber, logIndex, row })
+  }
+  positioned.sort((a, b) => {
+    const comparison = a.blockNumber - b.blockNumber || a.logIndex - b.logIndex
+    return options.order === 'asc' ? comparison : -comparison
+  })
+  return positioned.slice(options.offset, options.offset + options.limit).map(({ row }) => row)
+}
+
+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
+    /** Transfer log index. */
+    logIndex: number
+    /** Raw TIDX row. */
+    row: Record<string, unknown>
+  }
+}
+
 export declare namespace scan {
   /** Dependencies for {@link scan}. */
   type Deps = {
@@ -767,11 +864,9 @@ export declare namespace scan {
  * physical `token` column; unscoped queries omit it and use the `Transfer` CTE.
  */
 function filterClauses(options: filterClauses.Options): string[] {
-  const { eitherSide, fromBlock, fromTimestamp, recipient, sender, toBlock, toTimestamp, token } =
-    options
+  const { fromBlock, fromTimestamp, recipient, sender, toBlock, toTimestamp, token } = options
   const filters: string[] = []
   if (token !== undefined) filters.push(`token = '${token}'`)
-  if (eitherSide !== undefined) filters.push(`("from" = '${eitherSide}' OR "to" = '${eitherSide}')`)
   if (sender !== undefined) filters.push(`"from" = '${sender}'`)
   if (recipient !== undefined) filters.push(`"to" = '${recipient}'`)
   if (fromBlock !== undefined) filters.push(`block_num >= ${fromBlock}`)
@@ -785,14 +880,7 @@ declare namespace filterClauses {
   /** The non-pagination filter fields of {@link scan.Options}. */
   type Options = Pick<
     scan.Options,
-    | 'eitherSide'
-    | 'fromBlock'
-    | 'fromTimestamp'
-    | 'recipient'
-    | 'sender'
-    | 'toBlock'
-    | 'toTimestamp'
-    | 'token'
+    'fromBlock' | 'fromTimestamp' | 'recipient' | 'sender' | 'toBlock' | 'toTimestamp' | 'token'
   >
 }
 
@@ -841,7 +929,7 @@ export declare namespace count {
 /**
  * Context-free core of {@link count}: counts token-scoped rows from
  * `token_transfers`, otherwise the decoded `Transfer` CTE. The capped inner
- * scan bounds work; the SQL aggregate runs on ClickHouse.
+ * scan bounds work while preserving each source's established query engine.
  */
 export async function countScan(
   deps: scan.Deps,
@@ -851,56 +939,90 @@ export async function countScan(
   const { tidx } = deps
   const filters = filterClauses(options)
   const tokenScoped = options.token !== undefined
-  const where = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : ''
+  const address = options.eitherSide
 
   // Folded count: cross-token transfers collapse several `Transfer` legs into
   // one row, so a raw `count(*)` would overcount. Scan the capped `Transfer`
   // 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) {
+    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 rows =
+      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 }
+  }
+
+  const countRows = async (additionalFilters: readonly string[] = []) => {
+    const countFilters = [...additionalFilters, ...filters]
+    const countWhere = countFilters.length > 0 ? `WHERE ${countFilters.join(' AND ')}` : ''
     const result = await tidx.fetch({
       chainId,
       ...(tokenScoped ? { engine: 'clickhouse' } : { signatures: [signature] }),
       query: `
-        SELECT tx_hash, log_idx, "from", "to", ${tokenScoped ? 'token AS address, amount AS value' : 'address, value'}
-        FROM ${tokenScoped ? 'token_transfers' : 'Transfer'}
-        ${where}
-        ORDER BY block_num, log_idx
-        LIMIT ${Schema.countCap}
+        SELECT count(*) AS total
+        FROM (
+          SELECT 1
+          FROM ${tokenScoped ? 'token_transfers' : 'Transfer'}
+          ${countWhere}
+          LIMIT ${Schema.countCap}
+        ) AS capped
       ` as string,
     })
-    const rawCount = result.rows.length
-    let suppressed = 0
-    for (const legs of legsByTransaction(result.rows).values()) {
-      const bundle = classifyCrossToken(legs)
-      if (bundle) suppressed += bundle.suppressLogIndexes.length
-    }
-    return { totalCountCapped: rawCount >= Schema.countCap, totalCount: rawCount - suppressed }
+    return Value.toNumber(result.rows[0]?.['total']) ?? 0
   }
 
-  const result = await tidx.fetch({
-    chainId,
-    engine: 'clickhouse',
-    ...(tokenScoped ? {} : { signatures: [signature] }),
-    query: `
-      SELECT count(*) AS total
-      FROM (
-        SELECT 1
-        FROM ${tokenScoped ? 'token_transfers' : 'Transfer'}
-        ${where}
-        LIMIT ${Schema.countCap}
-      ) AS capped
-    ` as string,
-  })
+  if (address !== undefined) {
+    // Keep branches disjoint so self-transfers count once.
+    const [sent, received] = await Promise.all([
+      countRows([`"from" = '${address}'`]),
+      countRows([`"to" = '${address}'`, `"from" != '${address}'`]),
+    ])
+    const rawCount = sent + received
+    return {
+      totalCount: Math.min(rawCount, Schema.countCap),
+      totalCountCapped:
+        sent >= Schema.countCap || received >= Schema.countCap || rawCount >= Schema.countCap,
+    }
+  }
 
-  const totalCount = Value.toNumber(result.rows[0]?.['total']) ?? 0
+  const totalCount = await countRows()
   return { totalCountCapped: totalCount >= Schema.countCap, totalCount }
 }
 
 export declare namespace countScan {
   /** Options for {@link countScan}: the shared filters plus the target chain. */
   type Options = filterClauses.Options &
-    Pick<scan.Options, 'chainId'> & {
+    Pick<scan.Options, 'chainId' | 'eitherSide'> & {
       /** Count folded cross-token transfers instead of raw `Transfer` logs. */
       crossToken?: boolean | undefined
     }
@@ -984,7 +1106,7 @@ declare namespace memoMap {
   }
 }
 
-/** A token's contract address and moved amount, matching `SourceToken`'s core. */
+/** A transfer leg before amount and token metadata are separated. */
 type CrossToken = { address: z.output<typeof Schema.Address>; amount: string }
 
 /** A decoded `Transfer` leg used for cross-token classification. */