tapimo 0.7.0 → 0.7.2

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

@@ -1,6 +1,7 @@
 import { Hono, type Context } from 'hono'
 import { AbiEvent, AbiParameters } from 'ox'
 import { type Address, ContractFunctionExecutionError } from 'viem'
+import { Abis } from 'viem/tempo'
 import * as z from 'zod/mini'
 
 import type * as App from '../../../App.js'
@@ -1176,6 +1177,148 @@ export declare namespace resolveToken {
   type Options = getToken.Options
 }
 
+/** Resolves unique token addresses with RPC metadata and requested curated fields. */
+export async function resolveTokens(
+  c: Context<App.Environment>,
+  options: resolveTokens.Options,
+): Promise<resolveTokens.ReturnType> {
+  const { chainId } = options
+  const addresses = Array.from(
+    new Set(options.addresses.map((address) => Schema.Address.parse(address.toLowerCase()))),
+  )
+  if (addresses.length === 0) return new Map()
+
+  const includeLogoUri = options.include.includes('token.logoUri')
+  const includeVerified = options.include.includes('token.verified')
+  const resolveMetadata = () =>
+    Promise.all(
+      addresses.map(async (address) => {
+        const metadata = options.metadata?.get(address)
+        if (metadata) return [address, metadata] as const
+        try {
+          return [address, await getTokenMetadata(c, { address, chainId })] as const
+        } catch {
+          return [address, undefined] as const
+        }
+      }),
+    )
+  const [snapshot, metadataByAddress, logoByAddress] = await Promise.all([
+    options.snapshot ??
+      (includeLogoUri || includeVerified
+        ? VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
+        : undefined),
+    addresses.every((address) => options.metadata?.has(address))
+      ? resolveMetadata()
+      : Timing.time(c, 'token_metadata', resolveMetadata),
+    includeLogoUri
+      ? Timing.time(c, 'token_logo', () =>
+          Promise.all(
+            addresses.map(
+              async (address) =>
+                [
+                  address,
+                  await getTokenLogo(c, { address, chainId }).catch(() => undefined),
+                ] as const,
+            ),
+          ),
+        )
+      : [],
+  ])
+
+  const logos = new Map(logoByAddress)
+  const metadataMap = new Map(metadataByAddress)
+  const onchainLogos = new Map(
+    includeLogoUri
+      ? await Timing.time(c, 'token_logo_uri', () =>
+          Promise.all(
+            addresses
+              .filter(
+                (address) =>
+                  !logos.get(address) &&
+                  !snapshot?.byAddress.get(address)?.logoUri &&
+                  !metadataMap.get(address)?.logoUri,
+              )
+              .map(
+                async (address) =>
+                  [
+                    address,
+                    await getTokenLogoUri(c, { address, chainId }).catch(() => undefined),
+                  ] as const,
+              ),
+          ),
+        )
+      : [],
+  )
+  const tokens: resolveTokens.ReturnType = new Map()
+  for (const [address, metadata] of metadataByAddress) {
+    if (!metadata) continue
+    tokens.set(address, {
+      address,
+      currency: metadata.currency,
+      decimals: metadata.decimals,
+      id: address,
+      logoUri: includeLogoUri
+        ? (logos.get(address) ??
+          snapshot?.byAddress.get(address)?.logoUri ??
+          metadata.logoUri ??
+          onchainLogos.get(address))
+        : undefined,
+      name: metadata.name,
+      symbol: metadata.symbol,
+      verified: includeVerified ? snapshot?.byAddress.has(address) : undefined,
+    })
+  }
+  return tokens
+}
+
+export declare namespace resolveTokens {
+  /** Options for resolving page token metadata. */
+  export type Options = {
+    /** Token addresses to resolve. */
+    addresses: readonly z.output<typeof Schema.Address>[]
+    /** Tempo chain id. */
+    chainId: z.output<typeof Schema.ChainId>
+    /** Curated token fields to include. */
+    include: readonly ('token.logoUri' | 'token.verified')[]
+    /** Token metadata already resolved by the enclosing resource. */
+    metadata?: ReadonlyMap<z.output<typeof Schema.Address>, Metadata> | undefined
+    /** Preloaded verified-token state. */
+    snapshot?: VerifiedTokens.Snapshot | undefined
+  }
+
+  /** Token metadata required by compact references. */
+  export type Metadata = Pick<
+    z.output<typeof schema.Token>,
+    'currency' | 'decimals' | 'logoUri' | 'name' | 'symbol'
+  >
+
+  /** Token metadata keyed by lowercase address. */
+  export type ReturnType = Map<z.output<typeof Schema.Address>, Token>
+
+  /** Token metadata with opt-in curated fields. */
+  export type Token = Omit<z.output<typeof schema.Token>, 'verified'> & {
+    /** Whether the token is curated, when requested. */
+    verified?: boolean | undefined
+  }
+}
+
+function getTokenLogoUri(c: Context<App.Environment>, options: getTokenMetadata.Options) {
+  const { address, chainId } = options
+  return Store.memoize(
+    async () =>
+      (await c.get('getClient')(chainId).readContract({
+        abi: Abis.tip20,
+        address,
+        functionName: 'logoURI',
+      })) || null,
+    {
+      key: `token:v1:${chainId}:${address}:logo-uri`,
+      store: c.get('store'),
+      ttl: Ttl.minutes(1),
+    },
+  ).then((logoUri) => logoUri ?? undefined)
+}
+
 /**
  * Resolves a token's on-chain metadata (`name`/`symbol`/`decimals`/`currency`/
  * `totalSupply`) via a single `token.getMetadata` RPC, memoized under the shared
@@ -1190,7 +1333,6 @@ export function getTokenMetadata(c: Context<App.Environment>, options: getTokenM
 
   return Store.memoize(
     async () => {
-      // TODO(viem): Flatten concurrent metadata multicalls before encoding aggregate3 calldata.
       const fresh = await getClient(chainId).token.getMetadata({ token: address as Address })
       return {
         currency: fresh.currency,
@@ -1319,7 +1461,10 @@ async function fetchExternalLogo(uri: string): Promise<fetchTokenLogo.Logo | und
   if (!url) return undefined
   if (url.protocol !== 'http:' && url.protocol !== 'https:' && url.protocol !== 'data:')
     return undefined
-  if ((url.protocol === 'http:' || url.protocol === 'https:') && isBlockedHost(url.hostname))
+  if (
+    (url.protocol === 'http:' || url.protocol === 'https:') &&
+    ExternalLogo.isBlockedHost(url.hostname)
+  )
     return undefined
 
   const response = await fetch(url, {
@@ -1378,26 +1523,28 @@ async function readBodyWithLimit(
   return buffer
 }
 
-// Blocks hosts that resolve to loopback/private/link-local space, including the
-// cloud metadata IP. Hostnames that are not literal IPs are allowed (we cannot
-// resolve DNS here); the `redirect: 'manual'` policy in `fetchExternalLogo`
-// prevents a public host from bouncing us into private space.
-function isBlockedHost(hostname: string): boolean {
-  const host = hostname.toLowerCase().replace(/^\[|\]$/g, '')
-  if (host === '' || host === 'localhost' || host.endsWith('.localhost')) return true
-  if (host === '::1' || host === '::') return true
-  if (host.startsWith('fc') || host.startsWith('fd') || host.startsWith('fe80:')) return true
-  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host)
-  if (ipv4) {
-    const a = Number(ipv4[1])
-    const b = Number(ipv4[2])
-    if (a === 0 || a === 10 || a === 127) return true
-    if (a === 169 && b === 254) return true
-    if (a === 172 && b >= 16 && b <= 31) return true
-    if (a === 192 && b === 168) return true
-    if (a === 100 && b >= 64 && b <= 127) return true
+namespace ExternalLogo {
+  // Blocks hosts that resolve to loopback/private/link-local space, including the
+  // cloud metadata IP. Hostnames that are not literal IPs are allowed (we cannot
+  // resolve DNS here); `redirect: 'manual'` prevents a public host from bouncing
+  // into private space.
+  export function isBlockedHost(hostname: string): boolean {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, '')
+    if (host === '' || host === 'localhost' || host.endsWith('.localhost')) return true
+    if (host === '::1' || host === '::') return true
+    if (host.startsWith('fc') || host.startsWith('fd') || host.startsWith('fe80:')) return true
+    const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host)
+    if (ipv4) {
+      const a = Number(ipv4[1])
+      const b = Number(ipv4[2])
+      if (a === 0 || a === 10 || a === 127) return true
+      if (a === 169 && b === 254) return true
+      if (a === 172 && b >= 16 && b <= 31) return true
+      if (a === 192 && b === 168) return true
+      if (a === 100 && b >= 64 && b <= 127) return true
+    }
+    return false
   }
-  return false
 }
 
 async function getTokenLogosByAddress(
@@ -1565,46 +1712,48 @@ function getTransferStats(c: Context<App.Environment>, options: getTransferStats
   const store = c.get('store')
   const tidx = c.get('getTidx')(chainId)
 
-  return Store.memoize<getTransferStats.Stats | null>(
+  return Store.memoize<getTransferStats.Stats>(
     async () => {
-      try {
-        // Lifetime `Transfer` statistics for the token, aggregated over the
-        // raw `logs` event stream by emitting contract. The inline query is
-        // cast to `string` so TIDX treats it as a dynamic ClickHouse query
-        // that needs no event signature for the `logs` table.
-        const result = await tidx.fetch({
-          chainId,
-          engine: 'clickhouse',
-          query: `
-            SELECT count() AS transfer_count, min(block_timestamp) AS first_at, max(block_timestamp) AS last_at
-            FROM logs
-            WHERE address = '${address}' AND selector = '${transferTopic}'
-          ` as string,
-        })
-        const row = result.rows[0]
-        // Persist `null` (not `undefined`) so "no transfer data" survives the
-        // cache round-trip without being mistaken for a miss.
-        const count = Value.toNumber(row?.['transfer_count'])
-        if (count === undefined) return null
-        // A zero count comes back with ClickHouse epoch-default (1970)
-        // `min`/`max` aggregates; report explicit nulls instead.
-        if (count === 0) return { count: 0, firstAt: null, lastAt: null }
-        // ClickHouse formats timestamps as naive-UTC `YYYY-MM-DD HH:MM:SS.sss`;
-        // `Value.toIsoDateTime` normalizes them to strict ISO 8601 UTC.
-        return {
-          count,
-          firstAt: Value.toIsoDateTime(row?.['first_at']) ?? null,
-          lastAt: Value.toIsoDateTime(row?.['last_at']) ?? null,
-        }
-      } catch {
-        // Degrade gracefully when transfer data is unavailable (e.g. the
-        // indexer cannot answer the aggregation, or the request is rate
-        // limited) so token metadata still resolves.
-        return null
+      // Lifetime `Transfer` statistics as three primary-key probes instead of
+      // one full aggregation: `count()` is index-counted and first/last read
+      // in `block_num` order, keeping high-volume tokens under the indexer's
+      // execution cap. The inline query is cast to `string` so TIDX treats it
+      // as a dynamic ClickHouse query that needs no event signature for the
+      // `logs` table.
+      const result = await tidx.fetch({
+        chainId,
+        engine: 'clickhouse',
+        query: `
+          SELECT
+            (SELECT count() FROM logs WHERE address = '${address}' AND selector = '${transferTopic}') AS transfer_count,
+            (SELECT block_timestamp FROM logs WHERE address = '${address}' AND selector = '${transferTopic}' ORDER BY block_num ASC LIMIT 1) AS first_at,
+            (SELECT block_timestamp FROM logs WHERE address = '${address}' AND selector = '${transferTopic}' ORDER BY block_num DESC LIMIT 1) AS last_at
+        ` as string,
+      })
+      const row = result.rows[0]
+      const count = Value.toNumber(row?.['transfer_count'])
+      // A malformed row is an upstream failure; degrade like any other error
+      // rather than caching a bogus value.
+      if (count === undefined) throw new Error('malformed transfer stats row')
+      // Empty first/last probes can render as epoch defaults depending on
+      // engine settings; pin the documented shape for zero-transfer tokens.
+      if (count === 0) return { count: 0, firstAt: null, lastAt: null }
+      // ClickHouse formats timestamps as naive-UTC `YYYY-MM-DD HH:MM:SS.sss`;
+      // `Value.toIsoDateTime` normalizes them to strict ISO 8601 UTC.
+      return {
+        count,
+        firstAt: Value.toIsoDateTime(row?.['first_at']) ?? null,
+        lastAt: Value.toIsoDateTime(row?.['last_at']) ?? null,
       }
     },
     { key: `token:v1:${chainId}:${address}:transfer_stats`, store, ttl: Ttl.minutes(5) },
-  )
+  ).catch(() => {
+    // Degrade gracefully so token metadata still resolves. Failures are not
+    // memoized and the degraded response stays out of the response cache, so
+    // the next request retries instead of seeing a blank field for the TTL.
+    Cache.setPolicy(c, Cache.policies.noStore)
+    return null
+  })
 }
 
 declare namespace getTransferStats {
@@ -1628,46 +1777,68 @@ async function getTransferStatsByAddress(
 
   if (addresses.length === 0) return {}
 
-  return Store.memoize(
+  return Store.memoize<Record<string, getTransferStats.Stats>>(
     async () => {
-      try {
-        // Batched form of `getTransferStats` for a page of tokens: one grouped
-        // aggregation over the raw `logs` stream instead of N per-token scans.
-        // Tokens with no `Transfer` events emit no group and are omitted.
-        const result = await tidx.fetch({
-          chainId: options.chainId,
-          engine: 'clickhouse',
-          query: `
-            SELECT address, count() AS transfer_count, min(block_timestamp) AS first_at, max(block_timestamp) AS last_at
-            FROM logs
-            WHERE selector = '${transferTopic}' AND address IN (${addresses.map((address) => `'${address}'`).join(', ')})
-            GROUP BY address
-          ` as string,
-        })
-
-        const statsByAddress: Record<string, getTransferStats.Stats> = {}
-        for (const row of result.rows) {
+      // Batched form of `getTransferStats`: the same three primary-key probes
+      // per token, stitched with UNION ALL in chunks of three (the TIDX proxy
+      // rejects deeper subquery nesting). Zero-transfer tokens surface
+      // `(0, null, null)` rather than dropping out.
+      const chunks: (typeof addresses)[] = []
+      for (let i = 0; i < addresses.length; i += 3) chunks.push(addresses.slice(i, i + 3))
+
+      const statsByAddress: Record<string, getTransferStats.Stats> = {}
+      // Waves of four chunks in flight: the indexer rejects wide bursts of
+      // concurrent queries, and a 200-token page would otherwise fan out ~67
+      // requests at once.
+      for (let i = 0; i < chunks.length; i += 4) {
+        const results = await Promise.all(
+          chunks.slice(i, i + 4).map((group) =>
+            tidx.fetch({
+              chainId: options.chainId,
+              engine: 'clickhouse',
+              query: group
+                .map(
+                  (address) => `
+            SELECT
+              '${address}' AS address,
+              (SELECT count() FROM logs WHERE address = '${address}' AND selector = '${transferTopic}') AS transfer_count,
+              (SELECT block_timestamp FROM logs WHERE address = '${address}' AND selector = '${transferTopic}' ORDER BY block_num ASC LIMIT 1) AS first_at,
+              (SELECT block_timestamp FROM logs WHERE address = '${address}' AND selector = '${transferTopic}' ORDER BY block_num DESC LIMIT 1) AS last_at`,
+                )
+                .join('\n            UNION ALL'),
+            }),
+          ),
+        )
+        for (const row of results.flatMap((result) => result.rows)) {
           const address = Schema.Address.safeParse(row['address'])
           const count = Value.toNumber(row['transfer_count'])
           if (!address.success || count === undefined) continue
-          statsByAddress[address.data] = {
-            count,
-            firstAt: Value.toIsoDateTime(row['first_at']) ?? null,
-            lastAt: Value.toIsoDateTime(row['last_at']) ?? null,
-          }
+          // Empty first/last probes can render as epoch defaults depending on
+          // engine settings; pin the documented shape for zero-transfer tokens.
+          statsByAddress[address.data] =
+            count === 0
+              ? { count: 0, firstAt: null, lastAt: null }
+              : {
+                  count,
+                  firstAt: Value.toIsoDateTime(row['first_at']) ?? null,
+                  lastAt: Value.toIsoDateTime(row['last_at']) ?? null,
+                }
         }
-        return statsByAddress
-      } catch {
-        // Degrade gracefully so the token page still resolves without stats.
-        return {}
       }
+      return statsByAddress
     },
     {
       key: `token:v1:${options.chainId}:transfer_stats:${addresses.join(',')}`,
       store,
       ttl: Ttl.minutes(5),
     },
-  )
+  ).catch(() => {
+    // Degrade gracefully so the token page still resolves without stats.
+    // Failures are not memoized and the degraded response stays out of the
+    // response cache, so the next request retries.
+    Cache.setPolicy(c, Cache.policies.noStore)
+    return {}
+  })
 }
 
 declare namespace getTransferStatsByAddress {
@@ -1821,6 +1992,8 @@ export async function getTokenCreatedAtByAddress(
   try {
     const result = await tidx.fetch({
       chainId: options.chainId,
+      // TODO: Remove the explicit engine after TIDX 1.0 is released.
+      engine: 'clickhouse',
       query: `
         SELECT token, block_timestamp
         FROM tokencreated
@@ -1916,6 +2089,8 @@ async function getTokenCreatedByAddress(
     // needs no event signature for the `logs` table.
     const result = await tidx.fetch({
       chainId: options.chainId,
+      // TODO: Remove the explicit engine after TIDX 1.0 is released.
+      engine: 'clickhouse',
       query: `
         SELECT topic1, data, block_timestamp
         FROM logs
@@ -2300,7 +2475,8 @@ declare namespace getTokens {
   }
 }
 
-function isTokenNotFound(cause: unknown) {
+/** Matches metadata-read failures for addresses that are not TIP-20 tokens. */
+export function isTokenNotFound(cause: unknown) {
   if (cause instanceof ContractFunctionExecutionError) return true
   if (cause instanceof Error && cause.message.includes('invalid tip20 address')) return true
   return false

package/src/apps/data/routes/transactions.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/transactions.ts

@@ -1,3 +1,5 @@
+// TODO(tidx-v1): Restore `scanTransactions` from commit `49ad800` after TIDX v1 ships. Remove the dual fetch, dedupe, sort, and slice.
+
 import { Hono, type Context } from 'hono'
 import { Hex } from 'ox'
 import * as z from 'zod/mini'
@@ -10,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'
@@ -1045,8 +1047,8 @@ export function getTransactions(c: Context<App.Environment>, options: getTransac
 }
 
 /**
- * Context-free core of {@link getTransactions}: builds the `txs` query (with the
- * address-scoped `UNION` planner workaround), applies keyset pagination on
+ * Context-free core of {@link getTransactions}: builds the `txs` query (with
+ * address sides merged in application code), applies keyset pagination on
  * `(block_num, idx)`, and reconstructs each row through the same
  * `toRpcTransaction` → `humanizeTransaction` path the detail endpoint uses. Used
  * by the Hono routes (via {@link getTransactions}, which adds Server-Timing +
@@ -1091,10 +1093,9 @@ export async function scanTransactions(
   // extra row to detect `hasMore` without a separate count query.
   //
   // Build the shared filters once (everything except the address-scope
-  // predicate); the `address` filter is special-cased below because the
-  // TIDX engine errors out on `(from = X OR to = X) ORDER BY ...` for
-  // contracts with non-trivial traffic and an index-friendly `UNION`
-  // over the two sides plans cleanly.
+  // predicate); the `address` filter is special-cased below because TIDX
+  // rejects both `(from = X OR to = X)` and the equivalent ordered `UNION`
+  // for some accounts.
   const filters: string[] = []
   if (sender !== undefined) filters.push(`"from" = '${sender}'`)
   if (recipient !== undefined)
@@ -1122,45 +1123,79 @@ export async function scanTransactions(
       ]),
     )
 
-  // For address-scoped queries, run one branch per side and `UNION` so
-  // each branch can use its own (`from`/`to`) index. The `ORDER BY` and
-  // `LIMIT` must live *inside* each branch — TIDX's planner crashes on
-  // a UNION whose outer query orders by `block_num, idx` for
-  // high-traffic contracts (and on the `(from = X OR to = X) ORDER BY`
-  // form). Pushing the sort+limit down means each branch returns at
-  // most `limit + 1` index-ordered rows, the outer query re-merges,
-  // and plain `UNION` dedupes the self-transfer case where
-  // `from = to = address`.
-  // In the offset lane each branch must over-fetch the full window
-  // (`offset + limit + 1` rows) because the skip applies to the merged set:
-  // the outer query re-sorts the union and discards the first `offset` rows.
-  const sideQuery = (side: 'from' | 'to', addr: string) => {
-    const where = [`"${side}" = '${addr}'`, ...filters].join(' AND ')
-    return `(SELECT ${transactionColumns} FROM txs WHERE ${where} ORDER BY block_num ${sortDirection}, idx ${sortDirection} LIMIT ${(offset ?? 0) + limit + 1})`
+  // Address-scoped queries run each side independently so each request uses one
+  // index and no SQL compound scan. Each side over-fetches the full positional
+  // window because the offset applies after the two result sets are merged.
+  const queryLimit = address === undefined ? limit + 1 : (offset ?? 0) + limit + 1
+  const skip = address === undefined && offset !== undefined ? ` OFFSET ${offset}` : ''
+  const filtered =
+    address !== undefined ||
+    sender !== undefined ||
+    recipient !== undefined ||
+    feePayer !== undefined ||
+    feeToken !== undefined
+  const fetchRows = async (where: readonly string[]) => {
+    try {
+      return await tidx.fetch({
+        chainId,
+        // Raw-table query (no signature-decoded CTE), so the inline SQL is cast
+        // to `string`.
+        query: `
+          SELECT ${transactionColumns}
+          FROM txs
+          ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
+          ORDER BY block_num ${sortDirection}, idx ${sortDirection}
+          LIMIT ${queryLimit}${skip}
+        ` as string,
+      })
+    } catch (error) {
+      // Planner mis-selectivity turns these top-N scans into a block-ordered
+      // walk that times out when matches sit far from the scan boundary;
+      // `block_num + 0` blocks that walk, forcing the filter index plus a sort.
+      if (!filtered || !Tidx.isDeterministicError(error)) throw error
+      return await tidx.fetch({
+        chainId,
+        // Raw-table query (no signature-decoded CTE), so the inline SQL is cast
+        // to `string`.
+        query: `
+          SELECT ${transactionColumns}
+          FROM txs
+          ${where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''}
+          ORDER BY block_num + 0 ${sortDirection}, idx ${sortDirection}
+          LIMIT ${queryLimit}${skip}
+        ` as string,
+      })
+    }
   }
-  const skip = offset !== undefined ? ` OFFSET ${offset}` : ''
-  const query =
-    address !== undefined
-      ? `
-              ${sideQuery('from', address)}
-              UNION
-              ${sideQuery('to', address)}
-              ORDER BY block_num ${sortDirection}, idx ${sortDirection}
-              LIMIT ${limit + 1}${skip}
-            `
-      : `
-              SELECT ${transactionColumns}
-              FROM txs
-              ${filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : ''}
-              ORDER BY block_num ${sortDirection}, idx ${sortDirection}
-              LIMIT ${limit + 1}${skip}
-            `
-
-  const result = await tidx.fetch({ chainId, query: query as string })
+
+  const rows = await (async () => {
+    if (address === undefined) return (await fetchRows(filters)).rows
+
+    const [from, to] = await Promise.all([
+      fetchRows([`"from" = '${address}'`, ...filters]),
+      fetchRows([`"to" = '${address}'`, ...filters]),
+    ])
+    const seen = new Set<string>()
+    return [...from.rows, ...to.rows]
+      .filter((row) => {
+        const hash = Value.toText(row['hash'])?.toLowerCase()
+        if (!hash) return true
+        if (seen.has(hash)) return false
+        seen.add(hash)
+        return true
+      })
+      .sort((a, b) => {
+        const block = (Value.toNumber(a['block_num']) ?? 0) - (Value.toNumber(b['block_num']) ?? 0)
+        const index = (Value.toNumber(a['idx']) ?? 0) - (Value.toNumber(b['idx']) ?? 0)
+        const order = block === 0 ? index : block
+        return sortDirection === 'ASC' ? order : -order
+      })
+      .slice(offset ?? 0, (offset ?? 0) + limit + 1)
+  })()
 
   // The next page anchors below the last fetched row's `(block, idx)`.
   const page = Cursor.paginate({
-    rows: result.rows,
+    rows,
     limit,
     key: (row) => {
       const block = Value.toNumber(row['block_num'])