tapimo 0.0.0 → 0.0.2

package/dist/apps/transfers.js

@@ -0,0 +1,769 @@
+import { Hono } from 'hono';
+import { Address, Hex } from 'ox';
+import { Addresses } from 'viem/tempo';
+import * as z from 'zod/mini';
+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 * 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 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.
+     */
+    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())
+            .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.
+     */
+    schema.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. */
+    let getTransfers;
+    (function (getTransfers) {
+        /** Optional related resources that callers opt into via `include`. */
+        getTransfers.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.
+         */
+        getTransfers.includeQuery = Schema.includeQuery(getTransfers.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).
+         */
+        getTransfers.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: getTransfers.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.
+         */
+        getTransfers.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. */
+        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.
+            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.'));
+    })(getTransfers = schema.getTransfers || (schema.getTransfers = {}));
+})(schema || (schema = {}));
+/** Creates transfer handlers. */
+export function transfers() {
+    return new Hono().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({
+        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 = 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])
+                    .catch(() => [token, undefined]))));
+                const tokensByAddress = new Map(resolved);
+                const withToken = (entry) => {
+                    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, 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),
+    }));
+}
+/**
+ * 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, options) {
+    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 = [];
+    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 };
+}
+/**
+ * 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) {
+    const { eitherSide, fromBlock, fromTimestamp, recipient, sender, toBlock, toTimestamp, token } = options;
+    const filters = [];
+    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;
+}
+/**
+ * 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, options) {
+    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),
+    }));
+}
+/**
+ * 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, options) {
+    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 };
+}
+/** `'tx1', 'tx2', …` SQL `IN` list of the page's distinct transaction hashes. */
+function txInList(rows) {
+    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) {
+    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, options) {
+    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();
+        for (const row of memos.rows) {
+            const rawMemo = Value.toText(row['memo']);
+            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;
+    });
+}
+/**
+ * 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) {
+    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) {
+    const legsByTx = new Map();
+    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, options) {
+    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();
+        const suppress = new Set();
+        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, logIndex) {
+    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) {
+    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, from, to, amount, token) {
+    return `${txHash}:${from}:${to}:${amount}:${token}`.toLowerCase();
+}
+//# sourceMappingURL=transfers.js.map