tapimo 0.0.0 → 0.0.2

package/src/apps/transfers.ts

@@ -0,0 +1,1116 @@
+import { Hono, type Context } from 'hono'
+import { Address, Hex } from 'ox'
+import { Addresses } from 'viem/tempo'
+import * as z from 'zod/mini'
+
+import type * as App from '../App.js'
+import * as Auth from '../internal/Auth.js'
+import * as Cache from '../internal/Cache.js'
+import * as Cursor from '../internal/Cursor.js'
+import * as Mpp from '../internal/Mpp.js'
+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 Timing from '../internal/Timing.js'
+import * as Ttl from '../internal/Ttl.js'
+import * as Value from '../internal/Value.js'
+import * as VerifiedTokens from '../internal/VerifiedTokens.js'
+import * as Tokens from './tokens.js'
+
+// TIP-20 tokens emit the standard ERC-20 Transfer event. Supplying the
+// signature exposes a decoded `Transfer` CTE (with `from`/`to`/`value`) to
+// the indexer SQL.
+export const signature = 'event Transfer(address indexed from, address indexed to, uint256 value)'
+
+// 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
+// resolved into `attribution` instead.
+const memoSignature =
+  'event TransferWithMemo(address indexed from, address indexed to, uint256 amount, bytes32 indexed memo)'
+
+/** 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.
+   */
+  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())
+        .check(
+          z.describe(
+            'The currency label for this token, such as `USD` for USD-denominated stablecoins.',
+          ),
+          z.meta({ examples: ['USD'] }),
+        ),
+      decimals: z
+        .optional(z.number().check(z.int(), z.nonnegative()))
+        .check(
+          z.describe(
+            'The number of decimal places the token uses; Tempo stablecoins typically use 6.',
+          ),
+          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.meta({
+          examples: [
+            'https://api.tempo.xyz/data/4217/icons/0x20c0000000000000000000008f5425160ebe5525.svg',
+          ],
+        }),
+      ),
+      name: z
+        .optional(z.string())
+        .check(z.describe('The token’s human-readable name.'), z.meta({ examples: ['USD Coin'] })),
+      symbol: z
+        .optional(z.string())
+        .check(
+          z.describe('The short ticker symbol wallets and apps show for this token.'),
+          z.meta({ examples: ['USDC'] }),
+        ),
+      verified: z
+        .optional(z.boolean())
+        .check(
+          z.describe('Whether this token is in Tempo’s curated verified token list.'),
+          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`.',
+      ),
+    )
+
+  /**
+   * Filter predicates shared verbatim by the `GET /transfers` list query
+   * ({@link getTransfers.Query}, which spreads `Predicates.shape`) and `transfer`
+   * webhook subscriptions (`Webhooks.schema.TransferFilters`), so the two never
+   * drift. Read-only concerns (pagination, windowing, ordering, `include`,
+   * `chainId`) are *not* here — they live only on the list query and have no
+   * meaning for an open-ended subscription. Consumers that need different
+   * per-field docs (e.g. the list query's mutually-exclusive `address`) override
+   * that one field.
+   */
+  export const Predicates = z.object({
+    address: z
+      .optional(Schema.Address)
+      .check(
+        z.describe('Match transfers where this account is either the sender or the recipient.'),
+      ),
+    recipient: z
+      .optional(Schema.Address)
+      .check(z.describe('Match transfers sent to this recipient address (`to`).')),
+    sender: z
+      .optional(Schema.Address)
+      .check(z.describe('Match transfers sent from this sender address (`from`).')),
+    token: z
+      .optional(Schema.TokenAddress)
+      .check(z.describe('Match transfers for this TIP-20 token contract address.')),
+  })
+
+  /** Schemas for the getTransfers (list) operation. */
+  export namespace getTransfers {
+    /** Optional related resources that callers opt into via `include`. */
+    export const Include = z
+      .enum(['crossToken', 'memo', 'token', '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.
+     */
+    export const includeQuery = Schema.includeQuery(
+      Include,
+      'Comma-separated related resources to include, such as `token,memo,crossToken,totalCount`.',
+    )
+
+    /**
+     * Query parameters for top-level transfer list requests. `address` is a
+     * convenience for "either side" — passing it alongside an explicit
+     * `sender` or `recipient` is rejected as ambiguous (the helper would have
+     * to AND/OR them in a non-obvious way).
+     */
+    export const Query = z
+      .strictObject({
+        // Predicate fields (`address`, `recipient`, `sender`, `token`) are shared
+        // verbatim with `transfer` webhook filters via `schema.Predicates`;
+        // `address` is overridden below for its list-only mutual-exclusion note.
+        ...schema.Predicates.shape,
+        address: z
+          .optional(Schema.Address)
+          .check(
+            z.describe(
+              'Only include transfers where this account is the sender or recipient. Use this shortcut by itself, not with `sender` or `recipient`.',
+            ),
+          ),
+        'blockNumber.from': Schema.blockNumberBound('transfers', 'from'),
+        'blockNumber.to': Schema.blockNumberBound('transfers', 'to'),
+        chainId: Schema.ChainIdQuery,
+        cursor: Schema.Cursor,
+        include: includeQuery,
+        limit: Schema.Limit,
+        order: Schema.Order,
+        page: Schema.Page,
+        'timestamp.from': Schema.timestampBound('transfers', 'from'),
+        'timestamp.to': Schema.timestampBound('transfers', 'to'),
+      })
+      .check(
+        z.refine((query) => !(query.address && (query.sender || query.recipient)), {
+          error:
+            '`address` is a shortcut for `sender` or `recipient`; pass either `address` or one explicit side, not both.',
+          path: ['address'],
+        }),
+        ...Schema.pageChecks(),
+      )
+      .check(z.describe('Query parameters for listing token transfer events.'))
+
+    /**
+     * A single transfer row. The token contract is carried per-row via
+     * `sourceToken.address` because `/transfers` is unscoped and rows can span
+     * multiple contracts.
+     */
+    export const Transfer = z
+      .object({
+        attribution: z
+          .optional(z.string())
+          .check(
+            z.describe(
+              'The resolved MPP service name, when the transfer memo matches a known service fingerprint. Returned when you request `include=memo`.',
+            ),
+            z.meta({ examples: ['example-service'] }),
+          ),
+        blockNumber: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('The block number where this transfer was recorded.'),
+            z.meta({ examples: [23456789] }),
+          ),
+        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`.',
+            ),
+          ),
+        id: z.string().check(
+          z.describe(
+            'A stable resource ID for this transfer, built from `${transactionHash}-${logIndex}`.',
+          ),
+          z.meta({
+            examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-0'],
+          }),
+        ),
+        logIndex: z
+          .number()
+          .check(
+            z.int(),
+            z.nonnegative(),
+            z.describe('The transfer event’s log index within the block.'),
+            z.meta({ examples: [0] }),
+          ),
+        memo: z
+          .optional(z.string())
+          .check(
+            z.describe(
+              'The decoded text memo from the matching `TransferWithMemo` event, when one is present. Returned when you request `include=memo`.',
+            ),
+            z.meta({ examples: ['Payment for invoice 123'] }),
+          ),
+        recipient: Schema.Address.check(
+          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.')),
+        timestamp: z.iso
+          .datetime()
+          .check(
+            z.describe('The block timestamp when this transfer was recorded.'),
+            z.meta({ examples: ['2024-01-01T00:00:00Z'] }),
+          ),
+        transactionHash: Schema.Hash.check(
+          z.describe('The hash of the transaction that emitted this transfer event.'),
+        ),
+      })
+      .check(
+        z.describe(
+          'One TIP-20 token transfer event, optionally including a payment memo for reconciliation or invoices.',
+        ),
+      )
+
+    /** Page of TIP-20 token transfers across the chain, ordered by block then log index. */
+    export const Response = z
+      .object({
+        data: z.array(Transfer).check(z.describe('The transfers in this page.')),
+        // Response-wide `meta` carries the opt-in capped total count
+        // (`include=totalCount`); per-row embeds (`memo`, `token`) attach to
+        // each `data` item, not here.
+        meta: z
+          .optional(Schema.CountMeta)
+          .check(z.describe('Page-level resources you requested with `include`.')),
+        nextCursor: Schema.NextCursor,
+      })
+      .check(z.describe('A page of TIP-20 token transfer events across the chain.'))
+  }
+}
+
+/** Creates transfer handlers. */
+export function transfers() {
+  return new Hono<App.Environment>().get(
+    '/',
+    Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }),
+    OpenApi.validate('query', schema.getTransfers.Query, {
+      code: 'query_invalid',
+      message: 'Invalid query parameters',
+    }),
+    OpenApi.describeRoute({
+      description: 'List token transfer events across Tempo.',
+      operationId: 'getTransfers',
+      responses: OpenApi.responses({
+        errors: { 502: 'The upstream indexer could not serve this request.' },
+        success: {
+          description: 'A page of token transfer events.',
+          schema: schema.getTransfers.Response,
+        },
+      }),
+      summary: 'List transfers',
+      tags: ['Transfers'],
+    }),
+    Cache.response<App.Environment>({
+      cacheControl: Cache.policies.feed,
+      name: 'tempo-api:transfers:v1',
+      key: (c) => Cache.urlKey(c, schema.getTransfers.Query),
+    }),
+    async (c) => {
+      if (Auth.narrowAccess) return Auth.paidAccessError(c)
+      if (OpenApi.narrowValidation)
+        return OpenApi.validationError(c, {
+          code: 'query_invalid',
+          message: 'Invalid query parameters',
+        })
+
+      const options = c.req.valid('query')
+      const chainId = options.chainId ?? c.get('chainId')
+
+      // Cursor pages are anchored below the head and effectively immutable,
+      // so cache them aggressively; the head page keeps the route's short
+      // `feed` default.
+      if (options.cursor !== undefined) Cache.setPolicy(c, Cache.policies.immutable)
+
+      // Filters shared by the page query and the opt-in total count, so the
+      // count always matches the page it annotates.
+      const predicates = {
+        chainId,
+        eitherSide: options.address,
+        fromBlock: options['blockNumber.from'],
+        fromTimestamp: options['timestamp.from'],
+        recipient: options.recipient,
+        sender: options.sender,
+        toBlock: options['blockNumber.to'],
+        toTimestamp: options['timestamp.to'],
+        token: options.token,
+      }
+
+      try {
+        // `totalCount` is opt-in and independent of the page rows, so kick it
+        // off concurrently with the page query. It is best-effort: a count
+        // failure (e.g. upstream timeout) omits `meta` rather than failing the
+        // whole page.
+        const countPromise = options.include.includes('totalCount')
+          ? count(c, {
+              ...predicates,
+              crossToken: options.include.includes('crossToken'),
+              timing: 'transfers_count',
+            }).catch(() => undefined)
+          : undefined
+
+        const page = await query(c, {
+          ...predicates,
+          cursor: options.cursor,
+          limit: options.limit,
+          order: options.order,
+          page: options.page,
+          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) => ({
+          blockNumber: row.blockNumber,
+          id: `${row.transactionHash}-${row.logIndex}`,
+          logIndex: row.logIndex,
+          recipient: row.recipient,
+          sender: row.sender,
+          sourceToken: { address: row.address, amount: row.amount },
+          timestamp: row.timestamp,
+          transactionHash: row.transactionHash,
+        }))
+
+        // Memo/attribution are opt-in: one `TransferWithMemo` lookup bounded
+        // to the page's transactions resolves both — the decoded text `memo`,
+        // and `attribution` when the memo is a known MPP service fingerprint.
+        if (options.include.includes('memo') && data.length > 0) {
+          const memoByRow = await memoMap(c, { chainId, rows: data })
+          data = data.map((transfer) => {
+            const entry = memoByRow.get(
+              transferKey(
+                transfer.transactionHash,
+                transfer.sender,
+                transfer.recipient,
+                transfer.sourceToken.amount,
+                transfer.sourceToken.address,
+              ),
+            )
+            if (!entry) return transfer
+            return {
+              ...transfer,
+              ...(entry.attribution ? { attribution: entry.attribution } : {}),
+              ...(entry.memo ? { memo: entry.memo } : {}),
+            }
+          })
+        }
+        // Cross-token routing is opt-in. One `Transfer` lookup bounded to the
+        // page's transactions folds the account server's approve+swap+forward
+        // multicall into a single row on the delivery leg: `sourceToken` becomes
+        // the token swapped into the DEX and `destinationToken` the token
+        // delivered to the recipient. The intermediate DEX legs and the fee leg
+        // are dropped from the page. Folding anchors on the delivery leg (whose
+        // own event token is the delivered token), so a `token=` filter matches
+        // cross-token rows by their destination token, and each transfer still
+        // appears exactly once across pages.
+        if (options.include.includes('crossToken') && data.length > 0) {
+          const { fold, suppress } = await crossTokenMap(c, { chainId, rows: data })
+          data = data.flatMap((transfer) => {
+            const key = eventKey(transfer.transactionHash, transfer.logIndex)
+            const folded = fold.get(key)
+            if (folded)
+              return [
+                {
+                  ...transfer,
+                  destinationToken: folded.destinationToken,
+                  recipient: folded.recipient,
+                  sender: folded.sender,
+                  sourceToken: folded.sourceToken,
+                },
+              ]
+            return suppress.has(key) ? [] : [transfer]
+          })
+        }
+        if (options.include.includes('token') && data.length > 0) {
+          const uniqueTokens = Array.from(
+            new Set(
+              data.flatMap((transfer) => [
+                transfer.sourceToken.address,
+                ...(transfer.destinationToken ? [transfer.destinationToken.address] : []),
+              ]),
+            ),
+          )
+          const snapshot = await VerifiedTokens.snapshot(c, chainId)
+          const resolved = 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),
+              ),
+            ),
+          )
+          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) }
+              : {}),
+          }))
+        }
+
+        const meta = countPromise ? await countPromise : undefined
+
+        return c.json(
+          Response.validated(schema.getTransfers.Response, {
+            data,
+            ...(meta ? { meta } : {}),
+            nextCursor: page.nextCursor,
+          }),
+          200,
+        )
+      } catch (cause) {
+        return Response.upstream(c, cause)
+      }
+    },
+  )
+}
+
+/**
+ * Shared TIP-20 `Transfer` page query. Used by `GET /transfers` and the
+ * webhook poller. Builds the signature-decoded `Transfer` CTE query, 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.
+ *
+ * Memoization lives inside the helper under one canonical `transfers:v1:…`
+ * key derived from every filter — so equivalent filter combinations share a
+ * single cache entry. Callers supply only a `timing` label for Server-Timing.
+ */
+export function query(c: Context<App.Environment>, options: query.Options) {
+  const { chainId, timing, ...rest } = options
+  const store = c.get('store')
+  const tidx = c.get('getTidx')(chainId)
+  const cursor = options.cursor ? Cursor.decode(options.cursor, ['int', 'int']) : undefined
+
+  return Timing.time(c, timing, () =>
+    Store.memoize(
+      async () => {
+        const page = await scan({ tidx }, { chainId, ...rest })
+        return {
+          data: page.items.map((item) => item.data),
+          nextCursor: page.nextCursor,
+        }
+      },
+      {
+        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}`,
+        store,
+        ttl: Ttl.seconds(15),
+      },
+    ),
+  )
+}
+
+export declare namespace query {
+  /** Options for the shared TIP-20 `Transfer` page query. */
+  type Options = {
+    chainId: z.output<typeof Schema.ChainId>
+    /** Opaque keyset cursor anchoring the page; omit for the head page. */
+    cursor?: string | undefined
+    /** Restrict to rows where this address appears on either side. */
+    eitherSide?: z.output<typeof Schema.Address> | undefined
+    fromBlock?: number | undefined
+    fromTimestamp?: string | undefined
+    limit: number
+    /** 1-indexed page number (positional pagination; exclusive with `cursor`). */
+    page?: number | undefined
+    order: 'asc' | 'desc'
+    recipient?: z.output<typeof Schema.Address> | undefined
+    sender?: z.output<typeof Schema.Address> | undefined
+    /** Server-Timing label for the caller's surface. */
+    timing: string
+    toBlock?: number | undefined
+    toTimestamp?: string | undefined
+    /** Restrict to a single TIP-20 token contract. */
+    token?: z.output<typeof Schema.Address> | undefined
+  }
+  /** A decoded `Transfer` row before per-surface shaping. */
+  type Row = {
+    /** Token contract that emitted the event. */
+    address: z.output<typeof Schema.Address>
+    amount: string
+    blockNumber: number
+    logIndex: number
+    recipient: z.output<typeof Schema.Address>
+    sender: z.output<typeof Schema.Address>
+    timestamp: string
+    transactionHash: z.output<typeof Schema.Hash>
+  }
+  type Page = {
+    data: readonly Row[]
+    nextCursor: string | null
+  }
+}
+
+/**
+ * Context-free core of {@link query}: builds the signature-decoded `Transfer`
+ * CTE query, applies keyset pagination on `(block_num, log_idx)`, and decodes
+ * rows. Used by the Hono routes (via {@link query}, which adds Server-Timing +
+ * memoization) and by the webhook poller (uncached, ascending, per-row cursors).
+ */
+export async function scan(deps: scan.Deps, options: scan.Options): Promise<scan.Page> {
+  const { chainId, limit, order } = options
+  const { tidx } = deps
+  const direction = order === 'asc' ? 'ASC' : 'DESC'
+  // Keyset pagination: anchor the page below the previous row's `(block, log_idx)`
+  // position instead of a numeric offset, so rows arriving at the head can't
+  // shift items across pages. A malformed cursor falls back to the head page.
+  const cursor = options.cursor ? Cursor.decode(options.cursor, ['int', 'int']) : undefined
+  // Bounded positional lane (exclusive with `cursor` at the schema): page 1 is
+  // the head page, so it shares the head's SQL and cache entries; deeper pages
+  // translate to a SQL OFFSET of `(page - 1) * limit` rows.
+  const offset =
+    options.page !== undefined && options.page > 1 ? (options.page - 1) * limit : undefined
+
+  // 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.
+  const filters = filterClauses(options)
+  if (cursor !== undefined)
+    filters.push(
+      Cursor.keyset([
+        { literal: Cursor.literal(cursor[0]!, 'int'), name: 'block_num', order },
+        { 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. The
+  // global minimum page size (`Schema.minLimit`) keeps this at or above the
+  // indexer's floor for signature-decoded `Transfer` queries.
+  const result = await tidx.fetch({
+    chainId,
+    query: `
+      SELECT "from", "to", address, value, tx_hash, block_num, log_idx, block_timestamp
+      FROM Transfer
+      ${where}
+      ORDER BY block_num ${direction}, log_idx ${direction}
+      LIMIT ${limit + 1}${offset !== undefined ? ` OFFSET ${offset}` : ''}
+    `,
+    signatures: [signature],
+  })
+
+  // The next page anchors below the last fetched row's `(block, log_idx)`.
+  const page = Cursor.paginate({
+    rows: result.rows,
+    limit,
+    key: (row) => {
+      const block = Value.toNumber(row['block_num'])
+      const index = Value.toNumber(row['log_idx'])
+      return block !== undefined && index !== undefined ? [block, index] : undefined
+    },
+  })
+
+  const items: scan.Item[] = []
+  for (const row of page.rows) {
+    const tokenAddress = Schema.Address.safeParse(row['address'])
+    const from = Schema.Address.safeParse(row['from'])
+    const to = Schema.Address.safeParse(row['to'])
+    const transactionHash = Schema.Hash.safeParse(row['tx_hash'])
+    const amount = Value.toIntegerString(row['value'])
+    const blockNumber = Value.toNumber(row['block_num'])
+    const logIndex = Value.toNumber(row['log_idx'])
+    const timestamp = Value.toIsoDateTime(row['block_timestamp'])
+    if (
+      tokenAddress.success &&
+      from.success &&
+      to.success &&
+      transactionHash.success &&
+      amount !== undefined &&
+      blockNumber !== undefined &&
+      logIndex !== undefined &&
+      timestamp !== undefined
+    )
+      items.push({
+        cursor: [blockNumber, logIndex],
+        data: {
+          address: tokenAddress.data,
+          amount,
+          blockNumber,
+          logIndex,
+          recipient: to.data,
+          sender: from.data,
+          timestamp,
+          transactionHash: transactionHash.data,
+        },
+      })
+  }
+
+  return { hasMore: page.hasMore, items, limit, nextCursor: page.nextCursor }
+}
+
+export declare namespace scan {
+  /** Dependencies for {@link scan}. */
+  type Deps = {
+    /** TIDX query client for the target chain. */
+    tidx: Tidx.Client
+  }
+  /** Options for {@link scan} (everything {@link query.Options} has except `timing`). */
+  type Options = Omit<query.Options, 'timing'>
+  /** A decoded `Transfer` row plus its `(block_num, log_idx)` cursor. */
+  type Item = {
+    /** Keyset position of the row. */
+    cursor: readonly [blockNumber: number, logIndex: number]
+    /** The decoded row before per-surface shaping. */
+    data: query.Row
+  }
+  /** A page of scanned `Transfer` rows. */
+  type Page = {
+    hasMore: boolean
+    items: readonly Item[]
+    limit: number
+    nextCursor: string | null
+  }
+}
+
+/**
+ * Builds the shared `WHERE` filter clauses for the `Transfer` feed: contract /
+ * subject / sender / recipient / block / timestamp predicates. Shared verbatim
+ * by the page query ({@link scan}) and the capped count ({@link countScan}) so a
+ * `totalCount` always matches the page it annotates; the keyset cursor clause is
+ * page-only and added by {@link scan} on top of these.
+ */
+function filterClauses(options: filterClauses.Options): string[] {
+  const { eitherSide, fromBlock, fromTimestamp, recipient, sender, toBlock, toTimestamp, token } =
+    options
+  const filters: string[] = []
+  if (token !== undefined) filters.push(`address = '${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}`)
+  if (toBlock !== undefined) filters.push(`block_num <= ${toBlock}`)
+  if (fromTimestamp !== undefined) filters.push(`block_timestamp >= '${fromTimestamp}'`)
+  if (toTimestamp !== undefined) filters.push(`block_timestamp <= '${toTimestamp}'`)
+  return filters
+}
+
+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'
+  >
+}
+
+/**
+ * Capped total-row count for the `Transfer` feed, sharing {@link query}'s
+ * filters (minus pagination) so the count matches the page it annotates. Timed
+ * and memoized like {@link query}; the result feeds `meta.totalCount`/`totalCountCapped`
+ * when a caller opts in via `include=totalCount`.
+ */
+export function count(c: Context<App.Environment>, options: count.Options): Promise<count.Result> {
+  const { chainId, timing, ...rest } = options
+  const store = c.get('store')
+  const tidx = c.get('getTidx')(chainId)
+
+  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 ?? ''}`,
+      store,
+      ttl: Ttl.seconds(15),
+    }),
+  )
+}
+
+export declare namespace count {
+  /** Options for the capped `Transfer` count: {@link query}'s filters plus `timing`. */
+  type Options = Pick<
+    query.Options,
+    | 'chainId'
+    | 'eitherSide'
+    | 'fromBlock'
+    | 'fromTimestamp'
+    | 'recipient'
+    | 'sender'
+    | 'timing'
+    | 'toBlock'
+    | 'toTimestamp'
+    | 'token'
+  > & {
+    /** Count folded cross-token transfers instead of raw `Transfer` logs. */
+    crossToken?: boolean | undefined
+  }
+  /** A capped count result: `totalCountCapped` is `true` when the count hit `Schema.countCap`. */
+  type Result = { totalCountCapped: boolean; totalCount: number }
+}
+
+/**
+ * Context-free core of {@link count}: runs a capped `count(*)` over the
+ * signature-decoded `Transfer` CTE under the shared {@link filterClauses}. The
+ * inner `LIMIT Schema.countCap` bounds the scan so the aggregate can't exceed
+ * the indexer's execution budget on the 10⁹-plus row table (an unbounded count
+ * there blows the 5s `max_execution_time`); a result equal to the cap is a
+ * lower bound, surfaced as `totalCountCapped: true`.
+ */
+export async function countScan(
+  deps: scan.Deps,
+  options: countScan.Options,
+): Promise<count.Result> {
+  const { chainId } = options
+  const { tidx } = deps
+  const filters = filterClauses(options)
+  const where = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : ''
+
+  // 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 result = await tidx.fetch({
+      chainId,
+      query: `
+        SELECT tx_hash, log_idx, "from", "to", address, value
+        FROM Transfer
+        ${where}
+        ORDER BY block_num, log_idx
+        LIMIT ${Schema.countCap}
+      `,
+      signatures: [signature],
+    })
+    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 }
+  }
+
+  const result = await tidx.fetch({
+    chainId,
+    query: `
+      SELECT count(*) AS total
+      FROM (
+        SELECT 1
+        FROM Transfer
+        ${where}
+        LIMIT ${Schema.countCap}
+      ) AS capped
+    `,
+    signatures: [signature],
+  })
+
+  const totalCount = Value.toNumber(result.rows[0]?.['total']) ?? 0
+  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'> & {
+      /** Count folded cross-token transfers instead of raw `Transfer` logs. */
+      crossToken?: boolean | undefined
+    }
+}
+
+/** `'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()))]
+    .map((hash) => `'${hash}'`)
+    .join(', ')
+}
+
+/**
+ * `block_num BETWEEN min AND max` bound covering the page's rows. Event-CTE
+ * predicates on `tx_hash` cannot prune `logs` (sorted by block position), so
+ * a bare `tx_hash IN (…)` scans to genesis; pairing it with the page's block
+ * range keeps the lookup a bounded range read. Callers only invoke the memo
+ * lookup for non-empty pages.
+ */
+function blockBound(rows: memoMap.Options['rows']): string {
+  const blocks = rows.map((row) => row.blockNumber)
+  return `block_num BETWEEN ${Math.min(...blocks)} AND ${Math.max(...blocks)}`
+}
+
+/**
+ * Resolves the memo of each of a page's transfers from their matching
+ * `TransferWithMemo` events, matched back to rows by {@link transferKey}: the
+ * decoded text `memo`, and `attribution` (the resolved MPP service name) when
+ * the memo is a known service fingerprint. The fingerprint directory is
+ * best-effort: a fetch failure leaves a memo unattributed rather than failing
+ * the page.
+ */
+function memoMap(
+  c: Context<App.Environment>,
+  options: memoMap.Options,
+): Promise<Map<string, { attribution?: string | undefined; memo?: string | undefined }>> {
+  const { chainId, rows } = options
+  const tidx = c.get('getTidx')(chainId)
+
+  return Timing.time(c, 'transfers_memo', async () => {
+    const [memos, fingerprintMap] = await Promise.all([
+      tidx.fetch({
+        chainId,
+        query: `
+          SELECT tx_hash, "from", "to", amount, address, memo
+          FROM TransferWithMemo
+          WHERE ${blockBound(rows)} AND tx_hash IN (${txInList(rows)})
+        `,
+        signatures: [memoSignature],
+      }),
+      Mpp.fingerprintMap({ store: c.get('store') }).catch(() => ({})),
+    ])
+
+    const memoByRow = new Map<
+      string,
+      { attribution?: string | undefined; memo?: string | undefined }
+    >()
+    for (const row of memos.rows) {
+      const rawMemo = Value.toText(row['memo']) as Hex.Hex
+      const attribution = Mpp.resolve({ fingerprintMap, memo: rawMemo })
+      const memo = memoToString(rawMemo)
+      const amount = Value.toIntegerString(row['amount'])
+      const txHash = Value.toText(row['tx_hash'])
+      const from = Value.toText(row['from'])
+      const to = Value.toText(row['to'])
+      const token = Value.toText(row['address'])
+      if ((attribution || memo) && amount && txHash && from && to && token)
+        memoByRow.set(transferKey(txHash, from, to, amount, token), { attribution, memo })
+    }
+    return memoByRow
+  })
+}
+
+declare namespace memoMap {
+  /** Options for the per-page memo lookup. */
+  type Options = {
+    /** Source chain id. */
+    chainId: z.output<typeof Schema.ChainId>
+    /** The page rows; only their `transactionHash` and `blockNumber` are read. */
+    rows: readonly { blockNumber: number; transactionHash: string }[]
+  }
+}
+
+/** A token's contract address and moved amount, matching `SourceToken`'s core. */
+type CrossToken = { address: z.output<typeof Schema.Address>; amount: string }
+
+/** A decoded `Transfer` leg used for cross-token classification. */
+type Leg = {
+  address: z.output<typeof Schema.Address>
+  amount: string
+  from: z.output<typeof Schema.Address>
+  logIndex: number
+  to: z.output<typeof Schema.Address>
+}
+
+/** 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. */
+  deliveryLogIndex: number
+  /** The delivered token and amount (the delivery leg's own event token). */
+  destinationToken: CrossToken
+  /** The recipient the swapped-out token was forwarded to. */
+  recipient: z.output<typeof Schema.Address>
+  /** The swapper that funded the transfer through the DEX. */
+  sender: z.output<typeof Schema.Address>
+  /** The token and amount swapped into the DEX. */
+  sourceToken: CrossToken
+  /** Log indexes of the legs folded away (the two DEX legs and any fee leg). */
+  suppressLogIndexes: number[]
+}
+
+/**
+ * Classifies a single transaction's `Transfer` legs as a cross-token transfer,
+ * or returns `undefined`. A cross-token transfer is the account server's
+ * approve+swap+forward multicall: the source token is sent into the DEX, the
+ * swapped token comes back to the swapper, and that swapped token is forwarded
+ * to a different recipient in the same transaction. The transfer folds onto the
+ * delivery (forwarding) leg; the two DEX legs and any fee leg fold away. A swap
+ * whose output stays with the swapper (no onward leg) is not a cross-token
+ * transfer and is left untouched.
+ */
+function classifyCrossToken(legs: readonly Leg[]): CrossTokenBundle | undefined {
+  const toDex = legs.find((leg) => Address.isEqual(leg.to, Addresses.stablecoinDex))
+  const fromDex = legs.find((leg) => Address.isEqual(leg.from, Addresses.stablecoinDex))
+  if (!toDex || !fromDex) return undefined
+  const swapper = fromDex.to
+  const destTokenAddress = fromDex.address
+  const delivery = legs.find(
+    (leg) =>
+      Address.isEqual(leg.address, destTokenAddress) &&
+      Address.isEqual(leg.from, swapper) &&
+      !Address.isEqual(leg.to, Addresses.stablecoinDex) &&
+      !Address.isEqual(leg.to, swapper) &&
+      !Address.isEqual(leg.to, Addresses.feeManager),
+  )
+  // 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)),
+    )
+    .map((leg) => leg.logIndex)
+  return {
+    deliveryLogIndex: delivery.logIndex,
+    destinationToken: { address: delivery.address, amount: delivery.amount },
+    recipient: delivery.to,
+    sender: swapper,
+    sourceToken: { address: toDex.address, amount: toDex.amount },
+    suppressLogIndexes,
+  }
+}
+
+/** Groups decoded `Transfer` rows by lowercased transaction hash. */
+function legsByTransaction(rows: readonly Record<string, unknown>[]): Map<string, Leg[]> {
+  const legsByTx = new Map<string, Leg[]>()
+  for (const row of rows) {
+    const txHash = Value.toText(row['tx_hash'])
+    const from = Schema.Address.safeParse(row['from'])
+    const to = Schema.Address.safeParse(row['to'])
+    const address = Schema.Address.safeParse(row['address'])
+    const amount = Value.toIntegerString(row['value'])
+    const logIndex = Value.toNumber(row['log_idx'])
+    if (
+      txHash &&
+      from.success &&
+      to.success &&
+      address.success &&
+      amount !== undefined &&
+      logIndex !== undefined
+    ) {
+      const legs = legsByTx.get(txHash.toLowerCase()) ?? []
+      legs.push({ address: address.data, amount, from: from.data, logIndex, to: to.data })
+      legsByTx.set(txHash.toLowerCase(), legs)
+    }
+  }
+  return legsByTx
+}
+
+/**
+ * Detects cross-token transfers among a page's transactions and returns the
+ * folding plan: `fold` maps each delivery leg (by `${txHash}-${logIndex}`) to
+ * its folded row (swapper, recipient, swapped-in `sourceToken`, delivered
+ * `destinationToken`), and `suppress` is the set of the other bundle legs (the
+ * two DEX legs and any fee leg) to drop from the page.
+ *
+ * Bounded to the page's transactions and block range like {@link memoMap}, so it
+ * discovers the sibling DEX legs even when they fall outside the current page.
+ *
+ * TODO(https://tips.sh/1072): once TIP-1072 lands, cross-token conversions emit
+ * a single self-describing `Convert(user, sourceToken, destinationToken,
+ * backingToken, amount)` event. Replace this extra `Transfer` lookup and the
+ * multi-leg {@link classifyCrossToken} heuristic with a direct `Convert` decode
+ * (and drop the folded-count scan in {@link countScan}).
+ */
+function crossTokenMap(
+  c: Context<App.Environment>,
+  options: memoMap.Options,
+): Promise<{
+  fold: Map<
+    string,
+    {
+      destinationToken: CrossToken
+      recipient: z.output<typeof Schema.Address>
+      sender: z.output<typeof Schema.Address>
+      sourceToken: CrossToken
+    }
+  >
+  suppress: Set<string>
+}> {
+  const { chainId, rows } = options
+  const tidx = c.get('getTidx')(chainId)
+
+  return Timing.time(c, 'transfers_cross_token', async () => {
+    const result = await tidx.fetch({
+      chainId,
+      query: `
+        SELECT tx_hash, log_idx, "from", "to", address, value
+        FROM Transfer
+        WHERE ${blockBound(rows)} AND tx_hash IN (${txInList(rows)})
+        ORDER BY tx_hash, log_idx
+      `,
+      signatures: [signature],
+    })
+
+    const fold = new Map<
+      string,
+      {
+        destinationToken: CrossToken
+        recipient: z.output<typeof Schema.Address>
+        sender: z.output<typeof Schema.Address>
+        sourceToken: CrossToken
+      }
+    >()
+    const suppress = new Set<string>()
+    for (const [txHash, legs] of legsByTransaction(result.rows)) {
+      const bundle = classifyCrossToken(legs)
+      if (!bundle) continue
+      fold.set(eventKey(txHash, bundle.deliveryLogIndex), {
+        destinationToken: bundle.destinationToken,
+        recipient: bundle.recipient,
+        sender: bundle.sender,
+        sourceToken: bundle.sourceToken,
+      })
+      for (const logIndex of bundle.suppressLogIndexes) suppress.add(eventKey(txHash, logIndex))
+    }
+    return { fold, suppress }
+  })
+}
+
+/** Composite `${transactionHash}-${logIndex}` key for a single transfer event. */
+function eventKey(transactionHash: string, logIndex: number): string {
+  return `${transactionHash}-${logIndex}`.toLowerCase()
+}
+
+/**
+ * Attempts to decode a bytes32 memo into a human-readable string. MPP
+ * attribution memos encode a service fingerprint, not text — they are
+ * suppressed from the display memo (and resolved to `attribution` instead).
+ * Shared with the activity feed's transfer entries.
+ */
+export function memoToString(memo: Hex.Hex): string | undefined {
+  if (Mpp.isAttributionMemo(memo)) return undefined
+  try {
+    const trimmed = Hex.trimLeft(memo)
+    if (trimmed === '0x' || trimmed === '0x0') return undefined
+    return Hex.toString(trimmed)
+  } catch {
+    return undefined
+  }
+}
+
+/** Composite match key shared by the `Transfer` row and its `TransferWithMemo`. */
+function transferKey(
+  txHash: string,
+  from: string,
+  to: string,
+  amount: string,
+  token: string,
+): string {
+  return `${txHash}:${from}:${to}:${amount}:${token}`.toLowerCase()
+}