tapimo 0.5.3 → 0.7.0

package/dist/apps/data/routes/transfers.js

@@ -14,7 +14,9 @@ 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 FxOracle from '../FxOracle.js';
 import * as Tokens from './tokens.js';
+import * as Valuation from './valuation.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.
@@ -24,52 +26,44 @@ export const signature = 'event Transfer(address indexed from, address indexed t
 // 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)';
+const tokenFields = ['token.logoUri', 'token.verified'];
 /** Zod schemas owned by the transfer handlers. */
 export var schema;
 (function (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. */
     schema.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.'), 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.'), 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({
+        logoUri: z.optional(z.string()).check(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',
             ],
         })),
         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'] })),
         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('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`.'));
+        .check(z.describe('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`
@@ -99,15 +93,14 @@ export var schema;
     (function (getTransfers) {
         /** Optional related resources that callers opt into via `include`. */
         getTransfers.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.
          */
-        getTransfers.includeQuery = Schema.includeQuery(getTransfers.Include, 'Comma-separated related resources to include, such as `token,memo,crossToken,totalCount`.');
+        getTransfers.includeQuery = Schema.includeQuery(getTransfers.Include, 'Comma-separated related resources to include, such as `token.logoUri,token.verified,memo,crossToken,totalCount`.');
         /**
          * Query parameters for top-level transfer list requests. `address` is a
          * convenience for "either side" — passing it alongside an explicit
@@ -127,6 +120,7 @@ export var schema;
             'blockNumber.to': Schema.blockNumberBound('transfers', 'to'),
             chainId: Schema.ChainIdQuery,
             cursor: Schema.Cursor,
+            denomination: Schema.Denomination,
             include: getTransfers.includeQuery,
             limit: Schema.Limit,
             order: Schema.Order,
@@ -152,9 +146,12 @@ export var schema;
             blockNumber: z
                 .number()
                 .check(z.int(), z.nonnegative(), 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`.')),
+                .check(z.describe('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(z.describe('A stable resource ID for this transfer, built from `${transactionHash}-${logIndex}`.'), z.meta({
                 examples: ['0x515801d7f9a5ac705e793e85904c9c69b3f1694b465cc8fb6ba3f0298dc82665-0'],
             })),
@@ -166,30 +163,46 @@ export var schema;
                 .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.')),
+            sourceAmount: ValuedAmount.check(z.describe('Amount associated with `sourceToken`.')),
+            sourceToken: schema.SourceToken.check(z.describe('The token 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.'));
+            .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.'));
+        /** Page-level resources: opt-in counts plus valuation rate provenance. */
+        getTransfers.Meta = z
+            .object({
+            pricing: z
+                .optional(Valuation.schema.Pricing)
+                .check(z.describe('Rate provenance for leg valuations. Present when conversion rates were ' +
+                'consulted; absent when every value was identity-valued or rates were unavailable.')),
+            totalCount: z.optional(Schema.TotalCount),
+            totalCountCapped: z.optional(Schema.TotalCountCapped),
+        })
+            .check(z.describe('Page-level resources attached to this response.'));
         /** Page of TIP-20 token transfers across the chain, ordered by block then log index. */
         getTransfers.Response = z
             .object({
             data: z.array(getTransfers.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.
+            // (`include=totalCount`) and valuation rate provenance; 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`.')),
+                .optional(getTransfers.Meta)
+                .check(z.describe('Page-level resources: opt-in counts and valuation rate provenance.')),
             nextCursor: Schema.NextCursor,
         })
             .check(z.describe('A page of TIP-20 token transfer events across the chain.'));
     })(getTransfers = schema.getTransfers || (schema.getTransfers = {}));
 })(schema || (schema = {}));
 /** Creates transfer handlers. */
-export function transfers() {
+export function transfers(options = {}) {
+    const oracle = options.fx?.oracle ?? FxOracle.ecb();
     return new Hono().get('/v1/transfers', Auth.policy({ apiKey: { scopes: ['data:read'] }, mpp: true, public: true }), OpenApi.validate('query', schema.getTransfers.Query, {
         code: 'query_invalid',
         message: 'Invalid query parameters',
@@ -197,7 +210,7 @@ export function transfers() {
         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,
@@ -207,7 +220,7 @@ export function transfers() {
         tags: ['Transfers'],
     }), Cache.response({
         cacheControl: Cache.policies.feed,
-        name: 'tempo-api:transfers:v1',
+        name: 'tempo-api:transfers:v2',
         key: (c) => Cache.urlKey(c, schema.getTransfers.Query),
     }), async (c) => {
         if (Auth.narrowAccess)
@@ -219,11 +232,10 @@ export function transfers() {
             });
         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.
+        const denomination = options.denomination ?? 'USD';
+        // Cursor pages carry current valuations and curated verification data.
         if (options.cursor !== undefined)
-            Cache.setPolicy(c, Cache.policies.immutable);
+            Cache.setPolicy(c, Cache.policies.metadata);
         // Filters shared by the page query and the opt-in total count, so the
         // count always matches the page it annotates.
         const predicates = {
@@ -257,11 +269,6 @@ export function transfers() {
                 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 = page.data.map((row) => ({
                 blockNumber: row.blockNumber,
                 id: `${row.transactionHash}-${row.logIndex}`,
@@ -315,55 +322,124 @@ export function transfers() {
                     return suppress.has(key) ? [] : [transfer];
                 });
             }
-            if (options.include.includes('token') && data.length > 0) {
-                const uniqueTokens = Array.from(new Set(data.flatMap((transfer) => [
+            // Verification is ancillary to the feed. Skip empty pages and degrade
+            // cold snapshot failures to null valuations.
+            const snapshot = data.length > 0
+                ? await VerifiedTokens.snapshot(c, chainId).catch(() => undefined)
+                : undefined;
+            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(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,
+                    },
+                ];
+            }))));
+            // Value each leg via its curated display currency, in the requested
+            // denomination.
+            const rates = await Valuation.ratesFor(c, {
+                currencies: 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])
-                    .catch(() => [token, undefined]))));
-                const tokensByAddress = new Map(resolved);
-                const withToken = (entry) => {
-                    const token = tokensByAddress.get(entry.address);
-                    return token ? { ...entry, ...token } : entry;
+                ].flatMap((address) => {
+                    const held = snapshot?.byAddress.get(address.toLowerCase())?.currency;
+                    return held === undefined ? [] : [held];
+                })),
+                denomination,
+                oracle,
+            });
+            const enrich = (leg) => {
+                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()) }
+                            : {}),
+                    },
                 };
-                data = data.map((transfer) => ({
+            };
+            const responseData = 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,
-                    sourceToken: withToken(transfer.sourceToken),
-                    ...(transfer.destinationToken
-                        ? { destinationToken: withToken(transfer.destinationToken) }
-                        : {}),
-                }));
-            }
-            const meta = countPromise ? await countPromise : undefined;
+                    destinationAmount: destination.amount,
+                    destinationToken: destination.token,
+                    sourceAmount: source.amount,
+                    sourceToken: source.token,
+                };
+            });
+            const counts = countPromise ? await countPromise : undefined;
+            const meta = {
+                ...(rates ? { pricing: Valuation.pricing(rates, oracle) } : {}),
+                ...counts,
+            };
             return c.json(Response.validated(schema.getTransfers.Response, {
-                data,
-                ...(meta ? { meta } : {}),
+                data: responseData,
+                ...(Object.keys(meta).length > 0 ? { meta } : {}),
                 nextCursor: page.nextCursor,
             }), 200);
         }
         catch (cause) {
+            if (cause instanceof Valuation.UnsupportedDenominationError)
+                return Response.error(c, { code: 'query_invalid', message: cause.message, status: 400 });
             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
+ * 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
@@ -404,32 +480,48 @@ export async function scan(deps, options) {
     // 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 address = options.eitherSide;
+    // 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(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.
-    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}` : ''}
-    `,
-    });
+    const addressScoped = address !== undefined;
+    const window = addressScoped ? (offset ?? 0) + limit + 1 : limit + 1;
+    const fetchRows = async (side) => {
+        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}` : ''}
+      `,
+        });
+        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']);
@@ -471,17 +563,37 @@ export async function scan(deps, options) {
     }
     return { hasMore: page.hasMore, items, limit, nextCursor: page.nextCursor };
 }
+/** Deduplicates and globally orders bounded `from`/`to` transfer streams. */
+function mergeTransferRows(rows, options) {
+    const positioned = [];
+    const seen = new Set();
+    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);
+}
 /**
  * Builds shared transfer filters. A token predicate targets `token_transfers`'s
  * physical `token` column; unscoped queries omit it and use the `Transfer` CTE.
  */
 function filterClauses(options) {
-    const { eitherSide, fromBlock, fromTimestamp, recipient, sender, toBlock, toTimestamp, token } = options;
+    const { fromBlock, fromTimestamp, recipient, sender, toBlock, toTimestamp, token } = options;
     const filters = [];
     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)
@@ -515,54 +627,84 @@ export function count(c, options) {
 /**
  * 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, options) {
     const { chainId } = options;
     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 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}
-      `,
-        });
-        const rawCount = result.rows.length;
+        const fetchRows = async (side) => {
+            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}
+        `,
+            });
+            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(result.rows).values()) {
+        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 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
-    `,
-    });
-    const totalCount = Value.toNumber(result.rows[0]?.['total']) ?? 0;
+    const countRows = async (additionalFilters = []) => {
+        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 count(*) AS total
+        FROM (
+          SELECT 1
+          FROM ${tokenScoped ? 'token_transfers' : 'Transfer'}
+          ${countWhere}
+          LIMIT ${Schema.countCap}
+        ) AS capped
+      `,
+        });
+        return Value.toNumber(result.rows[0]?.['total']) ?? 0;
+    };
+    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 = await countRows();
     return { totalCountCapped: totalCount >= Schema.countCap, totalCount };
 }
 /** `'tx1', 'tx2', …` SQL `IN` list of the page's distinct transaction hashes. */